diff options
| author | DongHun Kwak <dh0128.kwak@samsung.com> | 2016-10-06 10:33:54 +0900 |
|---|---|---|
| committer | DongHun Kwak <dh0128.kwak@samsung.com> | 2016-10-06 10:36:09 +0900 |
| commit | d9ec475d945d3035377a0d89ed42e382d8988891 (patch) | |
| tree | 34aff2cee4b209906243ab5499d61f3edee2982f /libs/python | |
| parent | 71d216b90256936a9638f325af9bc69d720e75de (diff) | |
| download | boost-d9ec475d945d3035377a0d89ed42e382d8988891.tar.gz boost-d9ec475d945d3035377a0d89ed42e382d8988891.tar.bz2 boost-d9ec475d945d3035377a0d89ed42e382d8988891.zip | |
Imported Upstream version 1.60.0
Change-Id: Ie709530d6d5841088ceaba025cbe175a4ef43050
Signed-off-by: DongHun Kwak <dh0128.kwak@samsung.com>
Diffstat (limited to 'libs/python')
367 files changed, 34099 insertions, 24381 deletions
diff --git a/libs/python/doc/Jamfile b/libs/python/doc/Jamfile index 9b7c8841aa..d97b9559d2 100644 --- a/libs/python/doc/Jamfile +++ b/libs/python/doc/Jamfile @@ -1,23 +1,49 @@ -# Copyright David Abrahams 2006. Distributed under the Boost -# Software License, Version 1.0. (See accompanying +# Copyright (c) 2006 Joel de Guzman +# Copyright (c) 2015 Stefan Seefeld +# +# Distributed under the Boost Software License, Version 1.0. (See accompanying # file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +path-constant here : . ; +path-constant images : html/images ; + + +project python/doc + : requirements + -<xsl:param>boost.defaults=Boost + <format>html:<xsl:param>boost.defaults=none + <format>html:<xsl:param>toc.max.depth=3 + <format>html:<xsl:param>toc.section.depth=2 + <format>html:<xsl:param>chunk.section.depth=1 + ; + +import boostbook ; +import quickbook ; import docutils ; -import path ; -sources = building.rst ; -bases = $(sources:S=) ; - -# This is a path relative to the html/ subdirectory where the -# generated output will eventually be moved. -stylesheet = "--stylesheet=../../../rst.css" ; - -for local b in $(bases) -{ - html $(b) : $(b).rst : - - <docutils-html>"-gdt --source-url="./$(b).rst" --link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet) - ; -} - -alias htmls : $(bases) ; -stage . : $(bases) ; +boostbook python : python.qbk + : <format>html:<name>$(here)/html + <format>html:<xsl:param>generate.toc="library nop; chapter toc; section toc;" + <format>html:<xsl:param>html.stylesheet=boostbook.css + <format>html:<xsl:param>boost.image.src=images/boost.png + <format>html:<xsl:param>boost.graphics.root=images/ + ; + +boostbook tutorial : tutorial.qbk + : <format>html:<name>$(here)/html/tutorial + <format>html:<xsl:param>html.stylesheet=../boostbook.css + <format>html:<xsl:param>boost.image.src=../images/boost.png + <format>html:<xsl:param>boost.graphics.root=../images/ + ; + +boostbook reference : reference.qbk + : <format>html:<name>$(here)/html/reference + <format>html:<xsl:param>html.stylesheet=../boostbook.css + <format>html:<xsl:param>boost.image.src=../images/boost.png + <format>html:<xsl:param>boost.graphics.root=../images/ + ; + +html article : article.rst + : <location>html + <docutils-html>"--link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript --stylesheet=rst.css" + ; diff --git a/libs/python/doc/PyConDC_2003/bpl.html b/libs/python/doc/PyConDC_2003/bpl.html deleted file mode 100755 index 32b655bd9a..0000000000 --- a/libs/python/doc/PyConDC_2003/bpl.html +++ /dev/null @@ -1,22 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="refresh" content="0; URL=http://www.boost-consulting.com/writing/bpl.html"> - - <title>Loading: “Building Hybrid Systems With Boost.Python”</title> - </head> - - <body> - Loading...; if nothing happens, please go to <a href= "http://www.boost-consulting.com/writing/bpl.html">http://www.boost-consulting.com/writing/bpl.html</a>. - </body> -</html> - diff --git a/libs/python/doc/PyConDC_2003/bpl.pdf b/libs/python/doc/PyConDC_2003/bpl.pdf Binary files differdeleted file mode 100755 index 09827aff02..0000000000 --- a/libs/python/doc/PyConDC_2003/bpl.pdf +++ /dev/null diff --git a/libs/python/doc/PyConDC_2003/bpl.txt b/libs/python/doc/PyConDC_2003/bpl.txt deleted file mode 100644 index d6921b1244..0000000000 --- a/libs/python/doc/PyConDC_2003/bpl.txt +++ /dev/null @@ -1,5 +0,0 @@ -.. Copyright David Abrahams 2006. Distributed under the Boost -.. Software License, Version 1.0. (See accompanying -.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - -This file has been moved to http://www.boost-consulting.com/writing/bpl.txt. diff --git a/libs/python/doc/PyConDC_2003/bpl_mods.txt b/libs/python/doc/PyConDC_2003/bpl_mods.txt deleted file mode 100644 index d42f00f8b1..0000000000 --- a/libs/python/doc/PyConDC_2003/bpl_mods.txt +++ /dev/null @@ -1,911 +0,0 @@ -Copyright David Abrahams 2006. Distributed under the Boost -Software License, Version 1.0. (See accompanying -file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - -.. This is a comment. Note how any initial comments are moved by - transforms to after the document title, subtitle, and docinfo. - -.. Need intro and conclusion -.. Exposing classes - .. Constructors - .. Overloading - .. Properties and data members - .. Inheritance - .. Operators and Special Functions - .. Virtual Functions -.. Call Policies - -++++++++++++++++++++++++++++++++++++++++++++++ - Introducing Boost.Python (Extended Abstract) -++++++++++++++++++++++++++++++++++++++++++++++ - - -.. bibliographic fields (which also require a transform): - -:Author: David Abrahams -:Address: 45 Walnut Street - Somerville, MA 02143 -:Contact: dave@boost-consulting.com -:organization: `Boost Consulting`_ -:status: This is a "work in progress" -:version: 1 -:copyright: Copyright David Abrahams 2002. All rights reserved - -:Dedication: - - For my girlfriend, wife, and partner Luann - -:abstract: - - This paper describes the Boost.Python library, a system for - C++/Python interoperability. - -.. meta:: - :keywords: Boost,python,Boost.Python,C++ - :description lang=en: C++/Python interoperability with Boost.Python - -.. contents:: Table of Contents -.. section-numbering:: - - -.. _`Boost Consulting`: http://www.boost-consulting.com - -============== - Introduction -============== - -Python and C++ are in many ways as different as two languages could -be: while C++ is usually compiled to machine-code, Python is -interpreted. Python's dynamic type system is often cited as the -foundation of its flexibility, while in C++ static typing is the -cornerstone of its efficiency. C++ has an intricate and difficult -meta-language to support compile-time polymorphism, while Python is -a uniform language with convenient runtime polymorphism. - -Yet for many programmers, these very differences mean that Python and -C++ complement one another perfectly. Performance bottlenecks in -Python programs can be rewritten in C++ for maximal speed, and -authors of powerful C++ libraries choose Python as a middleware -language for its flexible system integration capabilities. -Furthermore, the surface differences mask some strong similarities: - -* 'C'-family control structures (if, while, for...) - -* Support for object-orientation, functional programming, and generic - programming (these are both *multi-paradigm* programming languages.) - -* Comprehensive operator overloading facilities, recognizing the - importance of syntactic variability for readability and - expressivity. - -* High-level concepts such as collections and iterators. - -* High-level encapsulation facilities (C++: namespaces, Python: modules) - to support the design of re-usable libraries. - -* Exception-handling for effective management of error conditions. - -* C++ idioms in common use, such as handle/body classes and - reference-counted smart pointers mirror Python reference semantics. - -Python provides a rich 'C' API for writers of 'C' extension modules. -Unfortunately, using this API directly for exposing C++ type and -function interfaces to Python is much more tedious than it should be. -This is mainly due to the limitations of the 'C' language. Compared to -C++ and Python, 'C' has only very rudimentary abstraction facilities. -Support for exception-handling is completely missing. One important -undesirable consequence is that 'C' extension module writers are -required to manually manage Python reference counts. Another unpleasant -consequence is a very high degree of repetition of similar code in 'C' -extension modules. Of course highly redundant code does not only cause -frustration for the module writer, but is also very difficult to -maintain. - -The limitations of the 'C' API have lead to the development of a -variety of wrapping systems. SWIG_ is probably the most popular package -for the integration of C/C++ and Python. A more recent development is -the SIP_ package, which is specifically designed for interfacing Python -with the Qt_ graphical user interface library. Both SWIG and SIP -introduce a new specialized language for defining the inter-language -bindings. Of course being able to use a specialized language has -advantages, but having to deal with three different languages (Python, -C/C++ and the interface language) also introduces practical and mental -difficulties. The CXX_ package demonstrates an interesting alternative. -It shows that at least some parts of Python's 'C' API can be wrapped -and presented through a much more user-friendly C++ interface. However, -unlike SWIG and SIP, CXX does not include support for wrapping C++ -classes as new Python types. CXX is also no longer actively developed. - -In some respects Boost.Python combines ideas from SWIG and SIP with -ideas from CXX. Like SWIG and SIP, Boost.Python is a system for -wrapping C++ classes as new Python "built-in" types, and C/C++ -functions as Python functions. Like CXX, Boost.Python presents Python's -'C' API through a C++ interface. Boost.Python goes beyond the scope of -other systems with the unique support for C++ virtual functions that -are overrideable in Python, support for organizing extensions as Python -packages with a central registry for inter-language type conversions, -and a convenient mechanism for tying into Python's serialization engine -(pickle). Importantly, all this is achieved without introducing a new -syntax. Boost.Python leverages the power of C++ meta-programming -techniques to introspect about the C++ type system, and presents a -simple, IDL-like C++ interface for exposing C/C++ code in extension -modules. Boost.Python is a pure C++ library, the inter-language -bindings are defined in pure C++, and other than a C++ compiler only -Python itself is required to get started with Boost.Python. Last but -not least, Boost.Python is an unrestricted open source library. There -are no strings attached even for commercial applications. - -.. _SWIG: http://www.swig.org/ -.. _SIP: http://www.riverbankcomputing.co.uk/sip/index.php -.. _Qt: http://www.trolltech.com/ -.. _CXX: http://cxx.sourceforge.net/ - -=========================== - Boost.Python Design Goals -=========================== - -The primary goal of Boost.Python is to allow users to expose C++ -classes and functions to Python using nothing more than a C++ -compiler. In broad strokes, the user experience should be one of -directly manipulating C++ objects from Python. - -However, it's also important not to translate all interfaces *too* -literally: the idioms of each language must be respected. For -example, though C++ and Python both have an iterator concept, they are -expressed very differently. Boost.Python has to be able to bridge the -interface gap. - -It must be possible to insulate Python users from crashes resulting -from trivial misuses of C++ interfaces, such as accessing -already-deleted objects. By the same token the library should -insulate C++ users from low-level Python 'C' API, replacing -error-prone 'C' interfaces like manual reference-count management and -raw ``PyObject`` pointers with more-robust alternatives. - -Support for component-based development is crucial, so that C++ types -exposed in one extension module can be passed to functions exposed in -another without loss of crucial information like C++ inheritance -relationships. - -Finally, all wrapping must be *non-intrusive*, without modifying or -even seeing the original C++ source code. Existing C++ libraries have -to be wrappable by third parties who only have access to header files -and binaries. - -========================== - Hello Boost.Python World -========================== - -And now for a preview of Boost.Python, and how it improves on the raw -facilities offered by Python. Here's a function we might want to -expose:: - - char const* greet(unsigned x) - { - static char const* const msgs[] = { "hello", "Boost.Python", "world!" }; - - if (x > 2) - throw std::range_error("greet: index out of range"); - - return msgs[x]; - } - -To wrap this function in standard C++ using the Python 'C' API, we'd -need something like this:: - - extern "C" // all Python interactions use 'C' linkage and calling convention - { - // Wrapper to handle argument/result conversion and checking - PyObject* greet_wrap(PyObject* args, PyObject * keywords) - { - int x; - if (PyArg_ParseTuple(args, "i", &x)) // extract/check arguments - { - char const* result = greet(x); // invoke wrapped function - return PyString_FromString(result); // convert result to Python - } - return 0; // error occurred - } - - // Table of wrapped functions to be exposed by the module - static PyMethodDef methods[] = { - { "greet", greet_wrap, METH_VARARGS, "return one of 3 parts of a greeting" } - , { NULL, NULL, 0, NULL } // sentinel - }; - - // module initialization function - DL_EXPORT init_hello() - { - (void) Py_InitModule("hello", methods); // add the methods to the module - } - } - -Now here's the wrapping code we'd use to expose it with Boost.Python:: - - #include <boost/python.hpp> - using namespace boost::python; - BOOST_PYTHON_MODULE(hello) - { - def("greet", greet, "return one of 3 parts of a greeting"); - } - -and here it is in action:: - - >>> import hello - >>> for x in range(3): - ... print hello.greet(x) - ... - hello - Boost.Python - world! - -Aside from the fact that the 'C' API version is much more verbose than -the BPL one, it's worth noting that it doesn't handle a few things -correctly: - -* The original function accepts an unsigned integer, and the Python - 'C' API only gives us a way of extracting signed integers. The - Boost.Python version will raise a Python exception if we try to pass - a negative number to ``hello.greet``, but the other one will proceed - to do whatever the C++ implementation does when converting an - negative integer to unsigned (usually wrapping to some very large - number), and pass the incorrect translation on to the wrapped - function. - -* That brings us to the second problem: if the C++ ``greet()`` - function is called with a number greater than 2, it will throw an - exception. Typically, if a C++ exception propagates across the - boundary with code generated by a 'C' compiler, it will cause a - crash. As you can see in the first version, there's no C++ - scaffolding there to prevent this from happening. Functions wrapped - by Boost.Python automatically include an exception-handling layer - which protects Python users by translating unhandled C++ exceptions - into a corresponding Python exception. - -* A slightly more-subtle limitation is that the argument conversion - used in the Python 'C' API case can only get that integer ``x`` in - *one way*. PyArg_ParseTuple can't convert Python ``long`` objects - (arbitrary-precision integers) which happen to fit in an ``unsigned - int`` but not in a ``signed long``, nor will it ever handle a - wrapped C++ class with a user-defined implicit ``operator unsigned - int()`` conversion. The BPL's dynamic type conversion registry - allows users to add arbitrary conversion methods. - -================== - Library Overview -================== - -This section outlines some of the library's major features. Except as -necessary to avoid confusion, details of library implementation are -omitted. - -------------------------------------------- - The fundamental type-conversion mechanism -------------------------------------------- - -XXX This needs to be rewritten. - -Every argument of every wrapped function requires some kind of -extraction code to convert it from Python to C++. Likewise, the -function return value has to be converted from C++ to Python. -Appropriate Python exceptions must be raised if the conversion fails. -Argument and return types are part of the function's type, and much of -this tedium can be relieved if the wrapping system can extract that -information through introspection. - -Passing a wrapped C++ derived class instance to a C++ function -accepting a pointer or reference to a base class requires knowledge of -the inheritance relationship and how to translate the address of a base -class into that of a derived class. - ------------------- - Exposing Classes ------------------- - -C++ classes and structs are exposed with a similarly-terse interface. -Given:: - - struct World - { - void set(std::string msg) { this->msg = msg; } - std::string greet() { return msg; } - std::string msg; - }; - -The following code will expose it in our extension module:: - - #include <boost/python.hpp> - BOOST_PYTHON_MODULE(hello) - { - class_<World>("World") - .def("greet", &World::greet) - .def("set", &World::set) - ; - } - -Although this code has a certain pythonic familiarity, people -sometimes find the syntax bit confusing because it doesn't look like -most of the C++ code they're used to. All the same, this is just -standard C++. Because of their flexible syntax and operator -overloading, C++ and Python are great for defining domain-specific -(sub)languages -(DSLs), and that's what we've done in BPL. To break it down:: - - class_<World>("World") - -constructs an unnamed object of type ``class_<World>`` and passes -``"World"`` to its constructor. This creates a new-style Python class -called ``World`` in the extension module, and associates it with the -C++ type ``World`` in the BPL type conversion registry. We might have -also written:: - - class_<World> w("World"); - -but that would've been more verbose, since we'd have to name ``w`` -again to invoke its ``def()`` member function:: - - w.def("greet", &World::greet) - -There's nothing special about the location of the dot for member -access in the original example: C++ allows any amount of whitespace on -either side of a token, and placing the dot at the beginning of each -line allows us to chain as many successive calls to member functions -as we like with a uniform syntax. The other key fact that allows -chaining is that ``class_<>`` member functions all return a reference -to ``*this``. - -So the example is equivalent to:: - - class_<World> w("World"); - w.def("greet", &World::greet); - w.def("set", &World::set); - -It's occasionally useful to be able to break down the components of a -Boost.Python class wrapper in this way, but the rest of this paper -will tend to stick to the terse syntax. - -For completeness, here's the wrapped class in use: - ->>> import hello ->>> planet = hello.World() ->>> planet.set('howdy') ->>> planet.greet() -'howdy' - -Constructors -============ - -Since our ``World`` class is just a plain ``struct``, it has an -implicit no-argument (nullary) constructor. Boost.Python exposes the -nullary constructor by default, which is why we were able to write: - ->>> planet = hello.World() - -However, well-designed classes in any language may require constructor -arguments in order to establish their invariants. Unlike Python, -where ``__init__`` is just a specially-named method, In C++ -constructors cannot be handled like ordinary member functions. In -particular, we can't take their address: ``&World::World`` is an -error. The library provides a different interface for specifying -constructors. Given:: - - struct World - { - World(std::string msg); // added constructor - ... - -we can modify our wrapping code as follows:: - - class_<World>("World", init<std::string>()) - ... - -of course, a C++ class may have additional constructors, and we can -expose those as well by passing more instances of ``init<...>`` to -``def()``:: - - class_<World>("World", init<std::string>()) - .def(init<double, double>()) - ... - -Boost.Python allows wrapped functions, member functions, and -constructors to be overloaded to mirror C++ overloading. - -Data Members and Properties -=========================== - -Any publicly-accessible data members in a C++ class can be easily -exposed as either ``readonly`` or ``readwrite`` attributes:: - - class_<World>("World", init<std::string>()) - .def_readonly("msg", &World::msg) - ... - -and can be used directly in Python: - ->>> planet = hello.World('howdy') ->>> planet.msg -'howdy' - -This does *not* result in adding attributes to the ``World`` instance -``__dict__``, which can result in substantial memory savings when -wrapping large data structures. In fact, no instance ``__dict__`` -will be created at all unless attributes are explicitly added from -Python. BPL owes this capability to the new Python 2.2 type system, -in particular the descriptor interface and ``property`` type. - -In C++, publicly-accessible data members are considered a sign of poor -design because they break encapsulation, and style guides usually -dictate the use of "getter" and "setter" functions instead. In -Python, however, ``__getattr__``, ``__setattr__``, and since 2.2, -``property`` mean that attribute access is just one more -well-encapsulated syntactic tool at the programmer's disposal. BPL -bridges this idiomatic gap by making Python ``property`` creation -directly available to users. So if ``msg`` were private, we could -still expose it as attribute in Python as follows:: - - class_<World>("World", init<std::string>()) - .add_property("msg", &World::greet, &World::set) - ... - -The example above mirrors the familiar usage of properties in Python -2.2+: - ->>> class World(object): -... __init__(self, msg): -... self.__msg = msg -... def greet(self): -... return self.__msg -... def set(self, msg): -... self.__msg = msg -... msg = property(greet, set) - -Operators and Special Functions -=============================== - -The ability to write arithmetic operators for user-defined types that -C++ and Python both allow the definition of has been a major factor in -the popularity of both languages for scientific computing. The -success of packages like NumPy attests to the power of exposing -operators in extension modules. In this example we'll wrap a class -representing a position in a large file:: - - class FilePos { /*...*/ }; - - // Linear offset - FilePos operator+(FilePos, int); - FilePos operator+(int, FilePos); - FilePos operator-(FilePos, int); - - // Distance between two FilePos objects - int operator-(FilePos, FilePos); - - // Offset with assignment - FilePos& operator+=(FilePos&, int); - FilePos& operator-=(FilePos&, int); - - // Comparison - bool operator<(FilePos, FilePos); - -The wrapping code looks like this:: - - class_<FilePos>("FilePos") - .def(self + int()) // __add__ - .def(int() + self) // __radd__ - .def(self - int()) // __sub__ - - .def(self - self) // __sub__ - - .def(self += int()) // __iadd__ - .def(self -= int()) // __isub__ - - .def(self < self); // __lt__ - ; - -The magic is performed using a simplified application of "expression -templates" [VELD1995]_, a technique originally developed by for -optimization of high-performance matrix algebra expressions. The -essence is that instead of performing the computation immediately, -operators are overloaded to construct a type *representing* the -computation. In matrix algebra, dramatic optimizations are often -available when the structure of an entire expression can be taken into -account, rather than processing each operation "greedily". -Boost.Python uses the same technique to build an appropriate Python -callable object based on an expression involving ``self``, which is -then added to the class. - -Inheritance -=========== - -C++ inheritance relationships can be represented to Boost.Python by adding -an optional ``bases<...>`` argument to the ``class_<...>`` template -parameter list as follows:: - - class_<Derived, bases<Base1,Base2> >("Derived") - ... - -This has two effects: - -1. When the ``class_<...>`` is created, Python type objects - corresponding to ``Base1`` and ``Base2`` are looked up in the BPL - registry, and are used as bases for the new Python ``Derived`` type - object [#mi]_, so methods exposed for the Python ``Base1`` and - ``Base2`` types are automatically members of the ``Derived`` type. - Because the registry is global, this works correctly even if - ``Derived`` is exposed in a different module from either of its - bases. - -2. C++ conversions from ``Derived`` to its bases are added to the - Boost.Python registry. Thus wrapped C++ methods expecting (a - pointer or reference to) an object of either base type can be - called with an object wrapping a ``Derived`` instance. Wrapped - member functions of class ``T`` are treated as though they have an - implicit first argument of ``T&``, so these conversions are - necessary to allow the base class methods to be called for derived - objects. - -Of course it's possible to derive new Python classes from wrapped C++ -class instances. Because Boost.Python uses the new-style class -system, that works very much as for the Python built-in types. There -is one significant detail in which it differs: the built-in types -generally establish their invariants in their ``__new__`` function, so -that derived classes do not need to call ``__init__`` on the base -class before invoking its methods : - ->>> class L(list): -... def __init__(self): -... pass -... ->>> L().reverse() ->>> - -Because C++ object construction is a one-step operation, C++ instance -data cannot be constructed until the arguments are available, in the -``__init__`` function: - ->>> class D(SomeBPLClass): -... def __init__(self): -... pass -... ->>> D().some_bpl_method() -Traceback (most recent call last): - File "<stdin>", line 1, in ? -TypeError: bad argument type for built-in operation - -This happened because Boost.Python couldn't find instance data of type -``SomeBPLClass`` within the ``D`` instance; ``D``'s ``__init__`` -function masked construction of the base class. It could be corrected -by either removing ``D``'s ``__init__`` function or having it call -``SomeBPLClass.__init__(...)`` explicitly. - -Virtual Functions -================= - -Deriving new types in Python from extension classes is not very -interesting unless they can be used polymorphically from C++. In -other words, Python method implementations should appear to override -the implementation of C++ virtual functions when called *through base -class pointers/references from C++*. Since the only way to alter the -behavior of a virtual function is to override it in a derived class, -the user must build a special derived class to dispatch a polymorphic -class' virtual functions:: - - // - // interface to wrap: - // - class Base - { - public: - virtual int f(std::string x) { return 42; } - virtual ~Base(); - }; - - int calls_f(Base const& b, std::string x) { return b.f(x); } - - // - // Wrapping Code - // - - // Dispatcher class - struct BaseWrap : Base - { - // Store a pointer to the Python object - BaseWrap(PyObject* self_) : self(self_) {} - PyObject* self; - - // Default implementation, for when f is not overridden - int f_default(std::string x) { return this->Base::f(x); } - // Dispatch implementation - int f(std::string x) { return call_method<int>(self, "f", x); } - }; - - ... - def("calls_f", calls_f); - class_<Base, BaseWrap>("Base") - .def("f", &Base::f, &BaseWrap::f_default) - ; - -Now here's some Python code which demonstrates: - ->>> class Derived(Base): -... def f(self, s): -... return len(s) -... ->>> calls_f(Base(), 'foo') -42 ->>> calls_f(Derived(), 'forty-two') -9 - -Things to notice about the dispatcher class: - -* The key element which allows overriding in Python is the - ``call_method`` invocation, which uses the same global type - conversion registry as the C++ function wrapping does to convert its - arguments from C++ to Python and its return type from Python to C++. - -* Any constructor signatures you wish to wrap must be replicated with - an initial ``PyObject*`` argument - -* The dispatcher must store this argument so that it can be used to - invoke ``call_method`` - -* The ``f_default`` member function is needed when the function being - exposed is not pure virtual; there's no other way ``Base::f`` can be - called on an object of type ``BaseWrap``, since it overrides ``f``. - -Admittedly, this formula is tedious to repeat, especially on a project -with many polymorphic classes; that it is necessary reflects -limitations in C++'s compile-time reflection capabilities. Several -efforts are underway to write front-ends for Boost.Python which can -generate these dispatchers (and other wrapping code) automatically. -If these are successful it will mark a move away from wrapping -everything directly in pure C++ for many of our users. - ---------------- - Serialization ---------------- - -*Serialization* is the process of converting objects in memory to a -form that can be stored on disk or sent over a network connection. The -serialized object (most often a plain string) can be retrieved and -converted back to the original object. A good serialization system will -automatically convert entire object hierarchies. Python's standard -``pickle`` module is such a system. It leverages the language's strong -runtime introspection facilities for serializing practically arbitrary -user-defined objects. With a few simple and unintrusive provisions this -powerful machinery can be extended to also work for wrapped C++ objects. -Here is an example:: - - #include <string> - - struct World - { - World(std::string a_msg) : msg(a_msg) {} - std::string greet() const { return msg; } - std::string msg; - }; - - #include <boost/python.hpp> - using namespace boost::python; - - struct World_picklers : pickle_suite - { - static tuple - getinitargs(World const& w) { return make_tuple(w.greet()); } - }; - - BOOST_PYTHON_MODULE(hello) - { - class_<World>("World", init<std::string>()) - .def("greet", &World::greet) - .def_pickle(World_picklers()) - ; - } - -Now let's create a ``World`` object and put it to rest on disk:: - - >>> import hello - >>> import pickle - >>> a_world = hello.World("howdy") - >>> pickle.dump(a_world, open("my_world", "w")) - -In a potentially *different script* on a potentially *different -computer* with a potentially *different operating system*:: - - >>> import pickle - >>> resurrected_world = pickle.load(open("my_world", "r")) - >>> resurrected_world.greet() - 'howdy' - -Of course the ``cPickle`` module can also be used for faster -processing. - -Boost.Python's ``pickle_suite`` fully supports the ``pickle`` protocol -defined in the standard Python documentation. There is a one-to-one -correspondence between the standard pickling methods (``__getinitargs__``, -``__getstate__``, ``__setstate__``) and the functions defined by the -user in the class derived from ``pickle_suite`` (``getinitargs``, -``getstate``, ``setstate``). The ``class_::def_pickle()`` member function -is used to establish the Python bindings for all user-defined functions -simultaneously. Correct signatures for these functions are enforced at -compile time. Non-sensical combinations of the three pickle functions -are also rejected at compile time. These measures are designed to -help the user in avoiding obvious errors. - -Enabling serialization of more complex C++ objects requires a little -more work than is shown in the example above. Fortunately the -``object`` interface (see next section) greatly helps in keeping the -code manageable. - ------------------- - Object interface ------------------- - -Experienced extension module authors will be familiar with the 'C' view -of Python objects, the ubiquitous ``PyObject*``. Most if not all Python -'C' API functions involve ``PyObject*`` as arguments or return type. A -major complication is the raw reference counting interface presented to -the 'C' programmer. E.g. some API functions return *new references* and -others return *borrowed references*. It is up to the extension module -writer to properly increment and decrement reference counts. This -quickly becomes cumbersome and error prone, especially if there are -multiple execution paths. - -Boost.Python provides a type ``object`` which is essentially a high -level wrapper around ``PyObject*``. ``object`` automates reference -counting as much as possible. It also provides the facilities for -converting arbitrary C++ types to Python objects and vice versa. -This significantly reduces the learning effort for prospective -extension module writers. - -Creating an ``object`` from any other type is extremely simple:: - - object o(3); - -``object`` has templated interactions with all other types, with -automatic to-python conversions. It happens so naturally that it's -easily overlooked. - -The ``extract<T>`` class template can be used to convert Python objects -to C++ types:: - - double x = extract<double>(o); - -All registered user-defined conversions are automatically accessible -through the ``object`` interface. With reference to the ``World`` class -defined in previous examples:: - - object as_python_object(World("howdy")); - World back_as_c_plus_plus_object = extract<World>(as_python_object); - -If a C++ type cannot be converted to a Python object an appropriate -exception is thrown at runtime. Similarly, an appropriate exception is -thrown if a C++ type cannot be extracted from a Python object. -``extract<T>`` provides facilities for avoiding exceptions if this is -desired. - -The ``object::attr()`` member function is available for accessing -and manipulating attributes of Python objects. For example:: - - object planet(World()); - planet.attr("set")("howdy"); - -``planet.attr("set")`` returns a callable ``object``. ``"howdy"`` is -converted to a Python string object which is then passed as an argument -to the ``set`` method. - -The ``object`` type is accompanied by a set of derived types -that mirror the Python built-in types such as ``list``, ``dict``, -``tuple``, etc. as much as possible. This enables convenient -manipulation of these high-level types from C++:: - - dict d; - d["some"] = "thing"; - d["lucky_number"] = 13; - list l = d.keys(); - -This almost looks and works like regular Python code, but it is pure C++. - -================= - Thinking hybrid -================= - -For many applications runtime performance considerations are very -important. This is particularly true for most scientific applications. -Often the performance considerations dictate the use of a compiled -language for the core algorithms. Traditionally the decision to use a -particular programming language is an exclusive one. Because of the -practical and mental difficulties of combining different languages many -systems are written in just one language. This is quite unfortunate -because the price payed for runtime performance is typically a -significant overhead due to static typing. For example, our experience -shows that developing maintainable C++ code is typically much more -time-consuming and requires much more hard-earned working experience -than developing useful Python code. A related observation is that many -compiled packages are augmented by some type of rudimentary scripting -layer. These ad hoc solutions clearly show that many times a compiled -language alone does not get the job done. On the other hand it is also -clear that a pure Python implementation is too slow for numerically -intensive production code. - -Boost.Python enables us to *think hybrid* when developing new -applications. Python can be used for rapidly prototyping a -new application. Python's ease of use and the large pool of standard -libraries give us a head start on the way to a first working system. If -necessary, the working procedure can be used to discover the -rate-limiting algorithms. To maximize performance these can be -reimplemented in C++, together with the Boost.Python bindings needed to -tie them back into the existing higher-level procedure. - -Of course, this *top-down* approach is less attractive if it is clear -from the start that many algorithms will eventually have to be -implemented in a compiled language. Fortunately Boost.Python also -enables us to pursue a *bottom-up* approach. We have used this approach -very successfully in the development of a toolbox for scientific -applications (scitbx) that we will describe elsewhere. The toolbox -started out mainly as a library of C++ classes with Boost.Python -bindings, and for a while the growth was mainly concentrated on the C++ -parts. However, as the toolbox is becoming more complete, more and more -newly added functionality can be implemented in Python. We expect this -trend to continue, as illustrated qualitatively in this figure: - -.. image:: python_cpp_mix.png - -This figure shows the ratio of newly added C++ and Python code over -time as new algorithms are implemented. We expect this ratio to level -out near 70% Python. The increasing ability to solve new problems -mostly with the easy-to-use Python language rather than a necessarily -more arcane statically typed language is the return on the investment -of learning how to use Boost.Python. The ability to solve some problems -entirely using only Python will enable a larger group of people to -participate in the rapid development of new applications. - -============= - Conclusions -============= - -The examples in this paper illustrate that Boost.Python enables -seamless interoperability between C++ and Python. Importantly, this is -achieved without introducing a third syntax: the Python/C++ interface -definitions are written in pure C++. This avoids any problems with -parsing the C++ code to be interfaced to Python, yet the interface -definitions are concise and maintainable. Freed from most of the -development-time penalties of crossing a language boundary, software -designers can take full advantage of two rich and complimentary -language environments. In practice it turns out that some things are -very difficult to do with pure Python/C (e.g. an efficient array -library with an intuitive interface in the compiled language) and -others are very difficult to do with pure C++ (e.g. serialization). -If one has the luxury of being able to design a software system as a -hybrid system from the ground up there are many new ways of avoiding -road blocks in one language or the other. - -.. I'm not ready to give up on all of this quite yet - -.. Perhaps one day we'll have a language with the simplicity and - expressive power of Python and the compile-time muscle of C++. Being - able to take advantage of all of these facilities without paying the - mental and development-time penalties of crossing a language barrier - would bring enormous benefits. Until then, interoperability tools - like Boost.Python can help lower the barrier and make the benefits of - both languages more accessible to both communities. - -=========== - Footnotes -=========== - -.. [#mi] For hard-core new-style class/extension module writers it is - worth noting that the normal requirement that all extension classes - with data form a layout-compatible single-inheritance chain is - lifted for Boost.Python extension classes. Clearly, either - ``Base1`` or ``Base2`` has to occupy a different offset in the - ``Derived`` class instance. This is possible because the wrapped - part of BPL extension class instances is never assumed to have a - fixed offset within the wrapper. - -=========== - Citations -=========== - -.. [VELD1995] T. Veldhuizen, "Expression Templates," C++ Report, - Vol. 7 No. 5 June 1995, pp. 26-31. - http://osl.iu.edu/~tveldhui/papers/Expression-Templates/exprtmpl.html diff --git a/libs/python/doc/PyConDC_2003/default.css b/libs/python/doc/PyConDC_2003/default.css deleted file mode 100644 index f8109bbd33..0000000000 --- a/libs/python/doc/PyConDC_2003/default.css +++ /dev/null @@ -1,188 +0,0 @@ -/* -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:copyright: This stylesheet has been placed in the public domain. - -boostinspect:nolicense - -Default cascading style sheet for the HTML output of Docutils. -*/ - -.first { - margin-top: 0 } - -.last { - margin-bottom: 0 } - -a.toc-backref { - text-decoration: none ; - color: black } - -dd { - margin-bottom: 0.5em } - -div.abstract { - margin: 2em 5em } - -div.abstract p.topic-title { - font-weight: bold ; - text-align: center } - -div.attention, div.caution, div.danger, div.error, div.hint, -div.important, div.note, div.tip, div.warning { - margin: 2em ; - border: medium outset ; - padding: 1em } - -div.attention p.admonition-title, div.caution p.admonition-title, -div.danger p.admonition-title, div.error p.admonition-title, -div.warning p.admonition-title { - color: red ; - font-weight: bold ; - font-family: sans-serif } - -div.hint p.admonition-title, div.important p.admonition-title, -div.note p.admonition-title, div.tip p.admonition-title { - font-weight: bold ; - font-family: sans-serif } - -div.dedication { - margin: 2em 5em ; - text-align: center ; - font-style: italic } - -div.dedication p.topic-title { - font-weight: bold ; - font-style: normal } - -div.figure { - margin-left: 2em } - -div.footer, div.header { - font-size: smaller } - -div.system-messages { - margin: 5em } - -div.system-messages h1 { - color: red } - -div.system-message { - border: medium outset ; - padding: 1em } - -div.system-message p.system-message-title { - color: red ; - font-weight: bold } - -div.topic { - margin: 2em } - -h1.title { - text-align: center } - -h2.subtitle { - text-align: center } - -hr { - width: 75% } - -ol.simple, ul.simple { - margin-bottom: 1em } - -ol.arabic { - list-style: decimal } - -ol.loweralpha { - list-style: lower-alpha } - -ol.upperalpha { - list-style: upper-alpha } - -ol.lowerroman { - list-style: lower-roman } - -ol.upperroman { - list-style: upper-roman } - -p.caption { - font-style: italic } - -p.credits { - font-style: italic ; - font-size: smaller } - -p.label { - white-space: nowrap } - -p.topic-title { - font-weight: bold } - -pre.address { - margin-bottom: 0 ; - margin-top: 0 ; - font-family: serif ; - font-size: 100% } - -pre.line-block { - font-family: serif ; - font-size: 100% } - -pre.literal-block, pre.doctest-block { - margin-left: 2em ; - margin-right: 2em ; - background-color: #eeeeee } - -span.classifier { - font-family: sans-serif ; - font-style: oblique } - -span.classifier-delimiter { - font-family: sans-serif ; - font-weight: bold } - -span.interpreted { - font-family: sans-serif } - -span.option-argument { - font-style: italic } - -span.pre { - white-space: pre } - -span.problematic { - color: red } - -table { - margin-top: 0.5em ; - margin-bottom: 0.5em } - -table.citation { - border-left: solid thin gray ; - padding-left: 0.5ex } - -table.docinfo { - margin: 2em 4em } - -table.footnote { - border-left: solid thin black ; - padding-left: 0.5ex } - -td, th { - padding-left: 0.5em ; - padding-right: 0.5em ; - vertical-align: top } - -th.docinfo-name, th.field-name { - font-weight: bold ; - text-align: left ; - white-space: nowrap } - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - font-size: 100% } - -tt { - background-color: #eeeeee } - -ul.auto-toc { - list-style-type: none } diff --git a/libs/python/doc/PyConDC_2003/python_cpp_mix.jpg b/libs/python/doc/PyConDC_2003/python_cpp_mix.jpg Binary files differdeleted file mode 100755 index 755a9605b8..0000000000 --- a/libs/python/doc/PyConDC_2003/python_cpp_mix.jpg +++ /dev/null diff --git a/libs/python/doc/article.rst b/libs/python/doc/article.rst new file mode 100644 index 0000000000..521f04f4f4 --- /dev/null +++ b/libs/python/doc/article.rst @@ -0,0 +1,947 @@ ++++++++++++++++++++++++++++++++++++++++++++ + Building Hybrid Systems with Boost.Python ++++++++++++++++++++++++++++++++++++++++++++ + +:Author: David Abrahams +:Contact: dave@boost-consulting.com +:organization: `Boost Consulting`_ +:date: 2003-05-14 + +:Author: Ralf W. Grosse-Kunstleve + +:copyright: Copyright David Abrahams and Ralf W. Grosse-Kunstleve 2003. All rights reserved + +.. contents:: Table of Contents + +.. _`Boost Consulting`: http://www.boost-consulting.com + +========== + Abstract +========== + +Boost.Python is an open source C++ library which provides a concise +IDL-like interface for binding C++ classes and functions to +Python. Leveraging the full power of C++ compile-time introspection +and of recently developed metaprogramming techniques, this is achieved +entirely in pure C++, without introducing a new syntax. +Boost.Python's rich set of features and high-level interface make it +possible to engineer packages from the ground up as hybrid systems, +giving programmers easy and coherent access to both the efficient +compile-time polymorphism of C++ and the extremely convenient run-time +polymorphism of Python. + +============== + Introduction +============== + +Python and C++ are in many ways as different as two languages could +be: while C++ is usually compiled to machine-code, Python is +interpreted. Python's dynamic type system is often cited as the +foundation of its flexibility, while in C++ static typing is the +cornerstone of its efficiency. C++ has an intricate and difficult +compile-time meta-language, while in Python, practically everything +happens at runtime. + +Yet for many programmers, these very differences mean that Python and +C++ complement one another perfectly. Performance bottlenecks in +Python programs can be rewritten in C++ for maximal speed, and +authors of powerful C++ libraries choose Python as a middleware +language for its flexible system integration capabilities. +Furthermore, the surface differences mask some strong similarities: + +* 'C'-family control structures (if, while, for...) + +* Support for object-orientation, functional programming, and generic + programming (these are both *multi-paradigm* programming languages.) + +* Comprehensive operator overloading facilities, recognizing the + importance of syntactic variability for readability and + expressivity. + +* High-level concepts such as collections and iterators. + +* High-level encapsulation facilities (C++: namespaces, Python: modules) + to support the design of re-usable libraries. + +* Exception-handling for effective management of error conditions. + +* C++ idioms in common use, such as handle/body classes and + reference-counted smart pointers mirror Python reference semantics. + +Given Python's rich 'C' interoperability API, it should in principle +be possible to expose C++ type and function interfaces to Python with +an analogous interface to their C++ counterparts. However, the +facilities provided by Python alone for integration with C++ are +relatively meager. Compared to C++ and Python, 'C' has only very +rudimentary abstraction facilities, and support for exception-handling +is completely missing. 'C' extension module writers are required to +manually manage Python reference counts, which is both annoyingly +tedious and extremely error-prone. Traditional extension modules also +tend to contain a great deal of boilerplate code repetition which +makes them difficult to maintain, especially when wrapping an evolving +API. + +These limitations have lead to the development of a variety of wrapping +systems. SWIG_ is probably the most popular package for the +integration of C/C++ and Python. A more recent development is SIP_, +which was specifically designed for interfacing Python with the Qt_ +graphical user interface library. Both SWIG and SIP introduce their +own specialized languages for customizing inter-language bindings. +This has certain advantages, but having to deal with three different +languages (Python, C/C++ and the interface language) also introduces +practical and mental difficulties. The CXX_ package demonstrates an +interesting alternative. It shows that at least some parts of +Python's 'C' API can be wrapped and presented through a much more +user-friendly C++ interface. However, unlike SWIG and SIP, CXX does +not include support for wrapping C++ classes as new Python types. + +The features and goals of Boost.Python_ overlap significantly with +many of these other systems. That said, Boost.Python attempts to +maximize convenience and flexibility without introducing a separate +wrapping language. Instead, it presents the user with a high-level +C++ interface for wrapping C++ classes and functions, managing much of +the complexity behind-the-scenes with static metaprogramming. +Boost.Python also goes beyond the scope of earlier systems by +providing: + +* Support for C++ virtual functions that can be overridden in Python. + +* Comprehensive lifetime management facilities for low-level C++ + pointers and references. + +* Support for organizing extensions as Python packages, + with a central registry for inter-language type conversions. + +* A safe and convenient mechanism for tying into Python's powerful + serialization engine (pickle). + +* Coherence with the rules for handling C++ lvalues and rvalues that + can only come from a deep understanding of both the Python and C++ + type systems. + +The key insight that sparked the development of Boost.Python is that +much of the boilerplate code in traditional extension modules could be +eliminated using C++ compile-time introspection. Each argument of a +wrapped C++ function must be extracted from a Python object using a +procedure that depends on the argument type. Similarly the function's +return type determines how the return value will be converted from C++ +to Python. Of course argument and return types are part of each +function's type, and this is exactly the source from which +Boost.Python deduces most of the information required. + +This approach leads to *user guided wrapping*: as much information is +extracted directly from the source code to be wrapped as is possible +within the framework of pure C++, and some additional information is +supplied explicitly by the user. Mostly the guidance is mechanical +and little real intervention is required. Because the interface +specification is written in the same full-featured language as the +code being exposed, the user has unprecedented power available when +she does need to take control. + +.. _Python: http://www.python.org/ +.. _SWIG: http://www.swig.org/ +.. _SIP: http://www.riverbankcomputing.co.uk/sip/index.php +.. _Qt: http://www.trolltech.com/ +.. _CXX: http://cxx.sourceforge.net/ +.. _Boost.Python: http://www.boost.org/libs/python/doc + +=========================== + Boost.Python Design Goals +=========================== + +The primary goal of Boost.Python is to allow users to expose C++ +classes and functions to Python using nothing more than a C++ +compiler. In broad strokes, the user experience should be one of +directly manipulating C++ objects from Python. + +However, it's also important not to translate all interfaces *too* +literally: the idioms of each language must be respected. For +example, though C++ and Python both have an iterator concept, they are +expressed very differently. Boost.Python has to be able to bridge the +interface gap. + +It must be possible to insulate Python users from crashes resulting +from trivial misuses of C++ interfaces, such as accessing +already-deleted objects. By the same token the library should +insulate C++ users from low-level Python 'C' API, replacing +error-prone 'C' interfaces like manual reference-count management and +raw ``PyObject`` pointers with more-robust alternatives. + +Support for component-based development is crucial, so that C++ types +exposed in one extension module can be passed to functions exposed in +another without loss of crucial information like C++ inheritance +relationships. + +Finally, all wrapping must be *non-intrusive*, without modifying or +even seeing the original C++ source code. Existing C++ libraries have +to be wrappable by third parties who only have access to header files +and binaries. + +========================== + Hello Boost.Python World +========================== + +And now for a preview of Boost.Python, and how it improves on the raw +facilities offered by Python. Here's a function we might want to +expose:: + + char const* greet(unsigned x) + { + static char const* const msgs[] = { "hello", "Boost.Python", "world!" }; + + if (x > 2) + throw std::range_error("greet: index out of range"); + + return msgs[x]; + } + +To wrap this function in standard C++ using the Python 'C' API, we'd +need something like this:: + + extern "C" // all Python interactions use 'C' linkage and calling convention + { + // Wrapper to handle argument/result conversion and checking + PyObject* greet_wrap(PyObject* args, PyObject * keywords) + { + int x; + if (PyArg_ParseTuple(args, "i", &x)) // extract/check arguments + { + char const* result = greet(x); // invoke wrapped function + return PyString_FromString(result); // convert result to Python + } + return 0; // error occurred + } + + // Table of wrapped functions to be exposed by the module + static PyMethodDef methods[] = { + { "greet", greet_wrap, METH_VARARGS, "return one of 3 parts of a greeting" } + , { NULL, NULL, 0, NULL } // sentinel + }; + + // module initialization function + DL_EXPORT init_hello() + { + (void) Py_InitModule("hello", methods); // add the methods to the module + } + } + +Now here's the wrapping code we'd use to expose it with Boost.Python:: + + #include <boost/python.hpp> + using namespace boost::python; + BOOST_PYTHON_MODULE(hello) + { + def("greet", greet, "return one of 3 parts of a greeting"); + } + +and here it is in action:: + + >>> import hello + >>> for x in range(3): + ... print hello.greet(x) + ... + hello + Boost.Python + world! + +Aside from the fact that the 'C' API version is much more verbose, +it's worth noting a few things that it doesn't handle correctly: + +* The original function accepts an unsigned integer, and the Python + 'C' API only gives us a way of extracting signed integers. The + Boost.Python version will raise a Python exception if we try to pass + a negative number to ``hello.greet``, but the other one will proceed + to do whatever the C++ implementation does when converting an + negative integer to unsigned (usually wrapping to some very large + number), and pass the incorrect translation on to the wrapped + function. + +* That brings us to the second problem: if the C++ ``greet()`` + function is called with a number greater than 2, it will throw an + exception. Typically, if a C++ exception propagates across the + boundary with code generated by a 'C' compiler, it will cause a + crash. As you can see in the first version, there's no C++ + scaffolding there to prevent this from happening. Functions wrapped + by Boost.Python automatically include an exception-handling layer + which protects Python users by translating unhandled C++ exceptions + into a corresponding Python exception. + +* A slightly more-subtle limitation is that the argument conversion + used in the Python 'C' API case can only get that integer ``x`` in + *one way*. PyArg_ParseTuple can't convert Python ``long`` objects + (arbitrary-precision integers) which happen to fit in an ``unsigned + int`` but not in a ``signed long``, nor will it ever handle a + wrapped C++ class with a user-defined implicit ``operator unsigned + int()`` conversion. Boost.Python's dynamic type conversion + registry allows users to add arbitrary conversion methods. + +================== + Library Overview +================== + +This section outlines some of the library's major features. Except as +neccessary to avoid confusion, details of library implementation are +omitted. + +------------------ + Exposing Classes +------------------ + +C++ classes and structs are exposed with a similarly-terse interface. +Given:: + + struct World + { + void set(std::string msg) { this->msg = msg; } + std::string greet() { return msg; } + std::string msg; + }; + +The following code will expose it in our extension module:: + + #include <boost/python.hpp> + BOOST_PYTHON_MODULE(hello) + { + class_<World>("World") + .def("greet", &World::greet) + .def("set", &World::set) + ; + } + +Although this code has a certain pythonic familiarity, people +sometimes find the syntax bit confusing because it doesn't look like +most of the C++ code they're used to. All the same, this is just +standard C++. Because of their flexible syntax and operator +overloading, C++ and Python are great for defining domain-specific +(sub)languages +(DSLs), and that's what we've done in Boost.Python. To break it down:: + + class_<World>("World") + +constructs an unnamed object of type ``class_<World>`` and passes +``"World"`` to its constructor. This creates a new-style Python class +called ``World`` in the extension module, and associates it with the +C++ type ``World`` in the Boost.Python type conversion registry. We +might have also written:: + + class_<World> w("World"); + +but that would've been more verbose, since we'd have to name ``w`` +again to invoke its ``def()`` member function:: + + w.def("greet", &World::greet) + +There's nothing special about the location of the dot for member +access in the original example: C++ allows any amount of whitespace on +either side of a token, and placing the dot at the beginning of each +line allows us to chain as many successive calls to member functions +as we like with a uniform syntax. The other key fact that allows +chaining is that ``class_<>`` member functions all return a reference +to ``*this``. + +So the example is equivalent to:: + + class_<World> w("World"); + w.def("greet", &World::greet); + w.def("set", &World::set); + +It's occasionally useful to be able to break down the components of a +Boost.Python class wrapper in this way, but the rest of this article +will stick to the terse syntax. + +For completeness, here's the wrapped class in use: :: + + >>> import hello + >>> planet = hello.World() + >>> planet.set('howdy') + >>> planet.greet() + 'howdy' + +Constructors +============ + +Since our ``World`` class is just a plain ``struct``, it has an +implicit no-argument (nullary) constructor. Boost.Python exposes the +nullary constructor by default, which is why we were able to write: :: + + >>> planet = hello.World() + +However, well-designed classes in any language may require constructor +arguments in order to establish their invariants. Unlike Python, +where ``__init__`` is just a specially-named method, In C++ +constructors cannot be handled like ordinary member functions. In +particular, we can't take their address: ``&World::World`` is an +error. The library provides a different interface for specifying +constructors. Given:: + + struct World + { + World(std::string msg); // added constructor + ... + +we can modify our wrapping code as follows:: + + class_<World>("World", init<std::string>()) + ... + +of course, a C++ class may have additional constructors, and we can +expose those as well by passing more instances of ``init<...>`` to +``def()``:: + + class_<World>("World", init<std::string>()) + .def(init<double, double>()) + ... + +Boost.Python allows wrapped functions, member functions, and +constructors to be overloaded to mirror C++ overloading. + +Data Members and Properties +=========================== + +Any publicly-accessible data members in a C++ class can be easily +exposed as either ``readonly`` or ``readwrite`` attributes:: + + class_<World>("World", init<std::string>()) + .def_readonly("msg", &World::msg) + ... + +and can be used directly in Python: :: + + >>> planet = hello.World('howdy') + >>> planet.msg + 'howdy' + +This does *not* result in adding attributes to the ``World`` instance +``__dict__``, which can result in substantial memory savings when +wrapping large data structures. In fact, no instance ``__dict__`` +will be created at all unless attributes are explicitly added from +Python. Boost.Python owes this capability to the new Python 2.2 type +system, in particular the descriptor interface and ``property`` type. + +In C++, publicly-accessible data members are considered a sign of poor +design because they break encapsulation, and style guides usually +dictate the use of "getter" and "setter" functions instead. In +Python, however, ``__getattr__``, ``__setattr__``, and since 2.2, +``property`` mean that attribute access is just one more +well-encapsulated syntactic tool at the programmer's disposal. +Boost.Python bridges this idiomatic gap by making Python ``property`` +creation directly available to users. If ``msg`` were private, we +could still expose it as attribute in Python as follows:: + + class_<World>("World", init<std::string>()) + .add_property("msg", &World::greet, &World::set) + ... + +The example above mirrors the familiar usage of properties in Python +2.2+: :: + + >>> class World(object): + ... __init__(self, msg): + ... self.__msg = msg + ... def greet(self): + ... return self.__msg + ... def set(self, msg): + ... self.__msg = msg + ... msg = property(greet, set) + +Operator Overloading +==================== + +The ability to write arithmetic operators for user-defined types has +been a major factor in the success of both languages for numerical +computation, and the success of packages like NumPy_ attests to the +power of exposing operators in extension modules. Boost.Python +provides a concise mechanism for wrapping operator overloads. The +example below shows a fragment from a wrapper for the Boost rational +number library:: + + class_<rational<int> >("rational_int") + .def(init<int, int>()) // constructor, e.g. rational_int(3,4) + .def("numerator", &rational<int>::numerator) + .def("denominator", &rational<int>::denominator) + .def(-self) // __neg__ (unary minus) + .def(self + self) // __add__ (homogeneous) + .def(self * self) // __mul__ + .def(self + int()) // __add__ (heterogenous) + .def(int() + self) // __radd__ + ... + +The magic is performed using a simplified application of "expression +templates" [VELD1995]_, a technique originally developed for +optimization of high-performance matrix algebra expressions. The +essence is that instead of performing the computation immediately, +operators are overloaded to construct a type *representing* the +computation. In matrix algebra, dramatic optimizations are often +available when the structure of an entire expression can be taken into +account, rather than evaluating each operation "greedily". +Boost.Python uses the same technique to build an appropriate Python +method object based on expressions involving ``self``. + +.. _NumPy: http://www.pfdubois.com/numpy/ + +Inheritance +=========== + +C++ inheritance relationships can be represented to Boost.Python by adding +an optional ``bases<...>`` argument to the ``class_<...>`` template +parameter list as follows:: + + class_<Derived, bases<Base1,Base2> >("Derived") + ... + +This has two effects: + +1. When the ``class_<...>`` is created, Python type objects + corresponding to ``Base1`` and ``Base2`` are looked up in + Boost.Python's registry, and are used as bases for the new Python + ``Derived`` type object, so methods exposed for the Python ``Base1`` + and ``Base2`` types are automatically members of the ``Derived`` + type. Because the registry is global, this works correctly even if + ``Derived`` is exposed in a different module from either of its + bases. + +2. C++ conversions from ``Derived`` to its bases are added to the + Boost.Python registry. Thus wrapped C++ methods expecting (a + pointer or reference to) an object of either base type can be + called with an object wrapping a ``Derived`` instance. Wrapped + member functions of class ``T`` are treated as though they have an + implicit first argument of ``T&``, so these conversions are + neccessary to allow the base class methods to be called for derived + objects. + +Of course it's possible to derive new Python classes from wrapped C++ +class instances. Because Boost.Python uses the new-style class +system, that works very much as for the Python built-in types. There +is one significant detail in which it differs: the built-in types +generally establish their invariants in their ``__new__`` function, so +that derived classes do not need to call ``__init__`` on the base +class before invoking its methods : :: + + >>> class L(list): + ... def __init__(self): + ... pass + ... + >>> L().reverse() + >>> + +Because C++ object construction is a one-step operation, C++ instance +data cannot be constructed until the arguments are available, in the +``__init__`` function: :: + + >>> class D(SomeBoostPythonClass): + ... def __init__(self): + ... pass + ... + >>> D().some_boost_python_method() + Traceback (most recent call last): + File "<stdin>", line 1, in ? + TypeError: bad argument type for built-in operation + +This happened because Boost.Python couldn't find instance data of type +``SomeBoostPythonClass`` within the ``D`` instance; ``D``'s ``__init__`` +function masked construction of the base class. It could be corrected +by either removing ``D``'s ``__init__`` function or having it call +``SomeBoostPythonClass.__init__(...)`` explicitly. + +Virtual Functions +================= + +Deriving new types in Python from extension classes is not very +interesting unless they can be used polymorphically from C++. In +other words, Python method implementations should appear to override +the implementation of C++ virtual functions when called *through base +class pointers/references from C++*. Since the only way to alter the +behavior of a virtual function is to override it in a derived class, +the user must build a special derived class to dispatch a polymorphic +class' virtual functions:: + + // + // interface to wrap: + // + class Base + { + public: + virtual int f(std::string x) { return 42; } + virtual ~Base(); + }; + + int calls_f(Base const& b, std::string x) { return b.f(x); } + + // + // Wrapping Code + // + + // Dispatcher class + struct BaseWrap : Base + { + // Store a pointer to the Python object + BaseWrap(PyObject* self_) : self(self_) {} + PyObject* self; + + // Default implementation, for when f is not overridden + int f_default(std::string x) { return this->Base::f(x); } + // Dispatch implementation + int f(std::string x) { return call_method<int>(self, "f", x); } + }; + + ... + def("calls_f", calls_f); + class_<Base, BaseWrap>("Base") + .def("f", &Base::f, &BaseWrap::f_default) + ; + +Now here's some Python code which demonstrates: :: + + >>> class Derived(Base): + ... def f(self, s): + ... return len(s) + ... + >>> calls_f(Base(), 'foo') + 42 + >>> calls_f(Derived(), 'forty-two') + 9 + +Things to notice about the dispatcher class: + +* The key element which allows overriding in Python is the + ``call_method`` invocation, which uses the same global type + conversion registry as the C++ function wrapping does to convert its + arguments from C++ to Python and its return type from Python to C++. + +* Any constructor signatures you wish to wrap must be replicated with + an initial ``PyObject*`` argument + +* The dispatcher must store this argument so that it can be used to + invoke ``call_method`` + +* The ``f_default`` member function is needed when the function being + exposed is not pure virtual; there's no other way ``Base::f`` can be + called on an object of type ``BaseWrap``, since it overrides ``f``. + +Deeper Reflection on the Horizon? +================================= + +Admittedly, this formula is tedious to repeat, especially on a project +with many polymorphic classes. That it is neccessary reflects some +limitations in C++'s compile-time introspection capabilities: there's +no way to enumerate the members of a class and find out which are +virtual functions. At least one very promising project has been +started to write a front-end which can generate these dispatchers (and +other wrapping code) automatically from C++ headers. + +Pyste_ is being developed by Bruno da Silva de Oliveira. It builds on +GCC_XML_, which generates an XML version of GCC's internal program +representation. Since GCC is a highly-conformant C++ compiler, this +ensures correct handling of the most-sophisticated template code and +full access to the underlying type system. In keeping with the +Boost.Python philosophy, a Pyste interface description is neither +intrusive on the code being wrapped, nor expressed in some unfamiliar +language: instead it is a 100% pure Python script. If Pyste is +successful it will mark a move away from wrapping everything directly +in C++ for many of our users. It will also allow us the choice to +shift some of the metaprogram code from C++ to Python. We expect that +soon, not only our users but the Boost.Python developers themselves +will be "thinking hybrid" about their own code. + +.. _`GCC_XML`: http://www.gccxml.org/HTML/Index.html +.. _`Pyste`: http://www.boost.org/libs/python/pyste + +--------------- + Serialization +--------------- + +*Serialization* is the process of converting objects in memory to a +form that can be stored on disk or sent over a network connection. The +serialized object (most often a plain string) can be retrieved and +converted back to the original object. A good serialization system will +automatically convert entire object hierarchies. Python's standard +``pickle`` module is just such a system. It leverages the language's strong +runtime introspection facilities for serializing practically arbitrary +user-defined objects. With a few simple and unintrusive provisions this +powerful machinery can be extended to also work for wrapped C++ objects. +Here is an example:: + + #include <string> + + struct World + { + World(std::string a_msg) : msg(a_msg) {} + std::string greet() const { return msg; } + std::string msg; + }; + + #include <boost/python.hpp> + using namespace boost::python; + + struct World_picklers : pickle_suite + { + static tuple + getinitargs(World const& w) { return make_tuple(w.greet()); } + }; + + BOOST_PYTHON_MODULE(hello) + { + class_<World>("World", init<std::string>()) + .def("greet", &World::greet) + .def_pickle(World_picklers()) + ; + } + +Now let's create a ``World`` object and put it to rest on disk:: + + >>> import hello + >>> import pickle + >>> a_world = hello.World("howdy") + >>> pickle.dump(a_world, open("my_world", "w")) + +In a potentially *different script* on a potentially *different +computer* with a potentially *different operating system*:: + + >>> import pickle + >>> resurrected_world = pickle.load(open("my_world", "r")) + >>> resurrected_world.greet() + 'howdy' + +Of course the ``cPickle`` module can also be used for faster +processing. + +Boost.Python's ``pickle_suite`` fully supports the ``pickle`` protocol +defined in the standard Python documentation. Like a __getinitargs__ +function in Python, the pickle_suite's getinitargs() is responsible for +creating the argument tuple that will be use to reconstruct the pickled +object. The other elements of the Python pickling protocol, +__getstate__ and __setstate__ can be optionally provided via C++ +getstate and setstate functions. C++'s static type system allows the +library to ensure at compile-time that nonsensical combinations of +functions (e.g. getstate without setstate) are not used. + +Enabling serialization of more complex C++ objects requires a little +more work than is shown in the example above. Fortunately the +``object`` interface (see next section) greatly helps in keeping the +code manageable. + +------------------ + Object interface +------------------ + +Experienced 'C' language extension module authors will be familiar +with the ubiquitous ``PyObject*``, manual reference-counting, and the +need to remember which API calls return "new" (owned) references or +"borrowed" (raw) references. These constraints are not just +cumbersome but also a major source of errors, especially in the +presence of exceptions. + +Boost.Python provides a class ``object`` which automates reference +counting and provides conversion to Python from C++ objects of +arbitrary type. This significantly reduces the learning effort for +prospective extension module writers. + +Creating an ``object`` from any other type is extremely simple:: + + object s("hello, world"); // s manages a Python string + +``object`` has templated interactions with all other types, with +automatic to-python conversions. It happens so naturally that it's +easily overlooked:: + + object ten_Os = 10 * s[4]; // -> "oooooooooo" + +In the example above, ``4`` and ``10`` are converted to Python objects +before the indexing and multiplication operations are invoked. + +The ``extract<T>`` class template can be used to convert Python objects +to C++ types:: + + double x = extract<double>(o); + +If a conversion in either direction cannot be performed, an +appropriate exception is thrown at runtime. + +The ``object`` type is accompanied by a set of derived types +that mirror the Python built-in types such as ``list``, ``dict``, +``tuple``, etc. as much as possible. This enables convenient +manipulation of these high-level types from C++:: + + dict d; + d["some"] = "thing"; + d["lucky_number"] = 13; + list l = d.keys(); + +This almost looks and works like regular Python code, but it is pure +C++. Of course we can wrap C++ functions which accept or return +``object`` instances. + +================= + Thinking hybrid +================= + +Because of the practical and mental difficulties of combining +programming languages, it is common to settle a single language at the +outset of any development effort. For many applications, performance +considerations dictate the use of a compiled language for the core +algorithms. Unfortunately, due to the complexity of the static type +system, the price we pay for runtime performance is often a +significant increase in development time. Experience shows that +writing maintainable C++ code usually takes longer and requires *far* +more hard-earned working experience than developing comparable Python +code. Even when developers are comfortable working exclusively in +compiled languages, they often augment their systems by some type of +ad hoc scripting layer for the benefit of their users without ever +availing themselves of the same advantages. + +Boost.Python enables us to *think hybrid*. Python can be used for +rapidly prototyping a new application; its ease of use and the large +pool of standard libraries give us a head start on the way to a +working system. If necessary, the working code can be used to +discover rate-limiting hotspots. To maximize performance these can +be reimplemented in C++, together with the Boost.Python bindings +needed to tie them back into the existing higher-level procedure. + +Of course, this *top-down* approach is less attractive if it is clear +from the start that many algorithms will eventually have to be +implemented in C++. Fortunately Boost.Python also enables us to +pursue a *bottom-up* approach. We have used this approach very +successfully in the development of a toolbox for scientific +applications. The toolbox started out mainly as a library of C++ +classes with Boost.Python bindings, and for a while the growth was +mainly concentrated on the C++ parts. However, as the toolbox is +becoming more complete, more and more newly added functionality can be +implemented in Python. + +.. image:: images/python_cpp_mix.png + +This figure shows the estimated ratio of newly added C++ and Python +code over time as new algorithms are implemented. We expect this +ratio to level out near 70% Python. Being able to solve new problems +mostly in Python rather than a more difficult statically typed +language is the return on our investment in Boost.Python. The ability +to access all of our code from Python allows a broader group of +developers to use it in the rapid development of new applications. + +===================== + Development history +===================== + +The first version of Boost.Python was developed in 2000 by Dave +Abrahams at Dragon Systems, where he was privileged to have Tim Peters +as a guide to "The Zen of Python". One of Dave's jobs was to develop +a Python-based natural language processing system. Since it was +eventually going to be targeting embedded hardware, it was always +assumed that the compute-intensive core would be rewritten in C++ to +optimize speed and memory footprint [#proto]_. The project also wanted to +test all of its C++ code using Python test scripts [#test]_. The only +tool we knew of for binding C++ and Python was SWIG_, and at the time +its handling of C++ was weak. It would be false to claim any deep +insight into the possible advantages of Boost.Python's approach at +this point. Dave's interest and expertise in fancy C++ template +tricks had just reached the point where he could do some real damage, +and Boost.Python emerged as it did because it filled a need and +because it seemed like a cool thing to try. + +This early version was aimed at many of the same basic goals we've +described in this paper, differing most-noticeably by having a +slightly more cumbersome syntax and by lack of special support for +operator overloading, pickling, and component-based development. +These last three features were quickly added by Ullrich Koethe and +Ralf Grosse-Kunstleve [#feature]_, and other enthusiastic contributors arrived +on the scene to contribute enhancements like support for nested +modules and static member functions. + +By early 2001 development had stabilized and few new features were +being added, however a disturbing new fact came to light: Ralf had +begun testing Boost.Python on pre-release versions of a compiler using +the EDG_ front-end, and the mechanism at the core of Boost.Python +responsible for handling conversions between Python and C++ types was +failing to compile. As it turned out, we had been exploiting a very +common bug in the implementation of all the C++ compilers we had +tested. We knew that as C++ compilers rapidly became more +standards-compliant, the library would begin failing on more +platforms. Unfortunately, because the mechanism was so central to the +functioning of the library, fixing the problem looked very difficult. + +Fortunately, later that year Lawrence Berkeley and later Lawrence +Livermore National labs contracted with `Boost Consulting`_ for support +and development of Boost.Python, and there was a new opportunity to +address fundamental issues and ensure a future for the library. A +redesign effort began with the low level type conversion architecture, +building in standards-compliance and support for component-based +development (in contrast to version 1 where conversions had to be +explicitly imported and exported across module boundaries). A new +analysis of the relationship between the Python and C++ objects was +done, resulting in more intuitive handling for C++ lvalues and +rvalues. + +The emergence of a powerful new type system in Python 2.2 made the +choice of whether to maintain compatibility with Python 1.5.2 easy: +the opportunity to throw away a great deal of elaborate code for +emulating classic Python classes alone was too good to pass up. In +addition, Python iterators and descriptors provided crucial and +elegant tools for representing similar C++ constructs. The +development of the generalized ``object`` interface allowed us to +further shield C++ programmers from the dangers and syntactic burdens +of the Python 'C' API. A great number of other features including C++ +exception translation, improved support for overloaded functions, and +most significantly, CallPolicies for handling pointers and +references, were added during this period. + +In October 2002, version 2 of Boost.Python was released. Development +since then has concentrated on improved support for C++ runtime +polymorphism and smart pointers. Peter Dimov's ingenious +``boost::shared_ptr`` design in particular has allowed us to give the +hybrid developer a consistent interface for moving objects back and +forth across the language barrier without loss of information. At +first, we were concerned that the sophistication and complexity of the +Boost.Python v2 implementation might discourage contributors, but the +emergence of Pyste_ and several other significant feature +contributions have laid those fears to rest. Daily questions on the +Python C++-sig and a backlog of desired improvements show that the +library is getting used. To us, the future looks bright. + +.. _`EDG`: http://www.edg.com + +============= + Conclusions +============= + +Boost.Python achieves seamless interoperability between two rich and +complimentary language environments. Because it leverages template +metaprogramming to introspect about types and functions, the user +never has to learn a third syntax: the interface definitions are +written in concise and maintainable C++. Also, the wrapping system +doesn't have to parse C++ headers or represent the type system: the +compiler does that work for us. + +Computationally intensive tasks play to the strengths of C++ and are +often impossible to implement efficiently in pure Python, while jobs +like serialization that are trivial in Python can be very difficult in +pure C++. Given the luxury of building a hybrid software system from +the ground up, we can approach design with new confidence and power. + +=========== + Citations +=========== + +.. [VELD1995] T. Veldhuizen, "Expression Templates," C++ Report, + Vol. 7 No. 5 June 1995, pp. 26-31. + http://osl.iu.edu/~tveldhui/papers/Expression-Templates/exprtmpl.html + +=========== + Footnotes +=========== + +.. [#proto] In retrospect, it seems that "thinking hybrid" from the + ground up might have been better for the NLP system: the + natural component boundaries defined by the pure python + prototype turned out to be inappropriate for getting the + desired performance and memory footprint out of the C++ core, + which eventually caused some redesign overhead on the Python + side when the core was moved to C++. + +.. [#test] We also have some reservations about driving all C++ + testing through a Python interface, unless that's the only way + it will be ultimately used. Any transition across language + boundaries with such different object models can inevitably + mask bugs. + +.. [#feature] These features were expressed very differently in v1 of + Boost.Python diff --git a/libs/python/doc/boost.css b/libs/python/doc/boost.css deleted file mode 100644 index 6c3e9808ea..0000000000 --- a/libs/python/doc/boost.css +++ /dev/null @@ -1,63 +0,0 @@ -/* Copyright David Abrahams 2006. Distributed under the Boost - Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -*/ -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; - FONT-SIZE: 80%; - BACKGROUND-COLOR: #dfffff -} -CODE -{ - FONT-SIZE: 95%; - 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/libs/python/doc/building.html b/libs/python/doc/building.html deleted file mode 100644 index e2c48847f1..0000000000 --- a/libs/python/doc/building.html +++ /dev/null @@ -1,636 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> -<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" /> -<title>Boost C++ Libraries: Boost.Python Build and Test HOWTO</title> -<link rel="stylesheet" href="../../../rst.css" type="text/css" /> -</head> -<body> -<div class="document" id="logo-boost-python-build-and-test-howto"> -<h1 class="title"><a class="reference external" href="../index.html"><img alt="Boost C++ Libraries:" class="boost-logo" src="../../../boost.png" /></a> Boost.Python Build and Test HOWTO</h1> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at --> -<!-- http://www.boost.org/LICENSE_1_0.txt) --> -<div class="contents sidebar small topic" id="contents"> -<p class="topic-title first">Contents</p> -<ul class="auto-toc simple"> -<li><a class="reference internal" href="#requirements" id="id25">1 Requirements</a></li> -<li><a class="reference internal" href="#background" id="id26">2 Background</a></li> -<li><a class="reference internal" href="#no-install-quickstart" id="id27">3 No-Install Quickstart</a><ul class="auto-toc"> -<li><a class="reference internal" href="#basic-procedure" id="id28">3.1 Basic Procedure</a></li> -<li><a class="reference internal" href="#in-case-of-trouble" id="id29">3.2 In Case of Trouble</a></li> -<li><a class="reference internal" href="#in-case-everything-seemed-to-work" id="id30">3.3 In Case Everything Seemed to Work</a></li> -<li><a class="reference internal" href="#modifying-the-example-project" id="id31">3.4 Modifying the Example Project</a></li> -</ul> -</li> -<li><a class="reference internal" href="#installing-boost-python-on-your-system" id="id32">4 Installing Boost.Python on your System</a></li> -<li><a class="reference internal" href="#configuring-boost-build" id="id33">5 Configuring Boost.Build</a><ul class="auto-toc"> -<li><a class="reference internal" href="#python-configuration-parameters" id="id34">5.1 Python Configuration Parameters</a></li> -<li><a class="reference internal" href="#examples" id="id35">5.2 Examples</a></li> -</ul> -</li> -<li><a class="reference internal" href="#choosing-a-boost-python-library-binary" id="id36">6 Choosing a Boost.Python Library Binary</a><ul class="auto-toc"> -<li><a class="reference internal" href="#the-dynamic-binary" id="id37">6.1 The Dynamic Binary</a></li> -<li><a class="reference internal" href="#the-static-binary" id="id38">6.2 The Static Binary</a></li> -</ul> -</li> -<li><a class="reference internal" href="#include-issues" id="id39">7 <tt class="docutils literal"><span class="pre">#include</span></tt> Issues</a></li> -<li><a class="reference internal" href="#python-debugging-builds" id="id40">8 Python Debugging Builds</a></li> -<li><a class="reference internal" href="#testing-boost-python" id="id41">9 Testing Boost.Python</a></li> -<li><a class="reference internal" href="#notes-for-mingw-and-cygwin-with-mno-cygwin-gcc-users" id="id42">10 Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users</a></li> -</ul> -</div> -<div class="section" id="requirements"> -<h1><a class="toc-backref" href="#id25">1 Requirements</a></h1> -<p>Boost.Python requires <a class="reference external" href="http://www.python.org/2.2">Python 2.2</a><a class="footnote-reference" href="#id22" id="id2"><sup>1</sup></a> <em>or</em> <a class="reference external" href="http://www.python.org"><em>newer</em></a>.</p> -</div> -<div class="section" id="background"> -<h1><a class="toc-backref" href="#id26">2 Background</a></h1> -<p>There are two basic models for combining C++ and Python:</p> -<ul class="simple"> -<li><a class="reference external" href="http://www.python.org/doc/current/ext/intro.html">extending</a>, in which the end-user launches the Python interpreter -executable and imports Python “extension modules†written in C++. -Think of taking a library written in C++ and giving it a Python -interface so Python programmers can use it. From Python, these -modules look just like regular Python modules.</li> -<li><a class="reference external" href="http://www.python.org/doc/current/ext/embedding.html">embedding</a>, in which the end-user launches a program written -in C++ that in turn invokes the Python interpreter as a library -subroutine. Think of adding scriptability to an existing -application.</li> -</ul> -<p>The key distinction between extending and embedding is the location -of the C++ <tt class="docutils literal"><span class="pre">main()</span></tt> function: in the Python interpreter executable, -or in some other program, respectively. Note that even when -embedding Python in another program, <a class="reference external" href="http://www.python.org/doc/current/ext/extending-with-embedding.html">extension modules are often -the best way to make C/C++ functionality accessible to Python -code</a>, so the use of extension modules is really at the heart of -both models.</p> -<p>Except in rare cases, extension modules are built as -dynamically-loaded libraries with a single entry point, which means -you can change them without rebuilding either the other extension -modules or the executable containing <tt class="docutils literal"><span class="pre">main()</span></tt>.</p> -</div> -<div class="section" id="no-install-quickstart"> -<span id="quickstart"></span><h1><a class="toc-backref" href="#id27">3 No-Install Quickstart</a></h1> -<p>There is no need to “install Boost†in order to get started using -Boost.Python. These instructions use <a class="reference external" href="../../../tools/build/index.html">Boost.Build</a> projects, -which will build those binaries as soon as they're needed. Your -first tests may take a little longer while you wait for -Boost.Python to build, but doing things this way will save you from -worrying about build intricacies like which library binaries to use -for a specific compiler configuration and figuring out the right -compiler options to use yourself.</p> -<!-- .. raw:: html - -<div style="width:50%"> --> -<div class="note"> -<p class="first admonition-title">Note</p> -<p>Of course it's possible to use other build systems to -build Boost.Python and its extensions, but they are not -officially supported by Boost. Moreover <strong>99% of all “I can't -build Boost.Python†problems come from trying to use another -build system</strong> without first following these instructions.</p> -<p>If you want to use another system anyway, we suggest that you -follow these instructions, and then invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> with the</p> -<pre class="literal-block"> -<tt class="docutils literal"><span class="pre">-a</span> <span class="pre">-o</span></tt><em>filename</em> -</pre> -<p class="last">options to dump the build commands it executes to a file, so -you can see what your alternate build system needs to do.</p> -</div> -<!-- .. raw:: html - -</div> --> -<div class="section" id="basic-procedure"> -<h2><a class="toc-backref" href="#id28">3.1 Basic Procedure</a></h2> -<ol class="arabic"> -<li><p class="first">Get Boost; see sections 1 and 2 [<a class="reference external" href="../../../more/getting_started/unix-variants.html#get-boost">Unix/Linux</a>, <a class="reference external" href="../../../more/getting_started/windows.html#get-boost">Windows</a>] of the -Boost <a class="reference external" href="../../../more/getting_started/index.html">Getting Started Guide</a>.</p> -</li> -<li><p class="first">Get the <tt class="docutils literal"><span class="pre">bjam</span></tt> build driver. See section 5 [<a class="reference external" href="../../../more/getting_started/unix-variants.html#prepare-to-use-a-boost-library-binary">Unix/Linux</a>, -<a class="reference external" href="../../../more/getting_started/windows.html#prepare-to-use-a-boost-library-binary">Windows</a>] of the Boost <a class="reference external" href="../../../more/getting_started/index.html">Getting Started Guide</a>.</p> -</li> -<li><p class="first">cd into the <tt class="docutils literal"><span class="pre">libs/python/example/quickstart/</span></tt> directory of your -Boost installation, which contains a small example project.</p> -</li> -<li><p class="first">Invoke <tt class="docutils literal"><span class="pre">bjam</span></tt>. Replace the “<tt class="docutils literal"><span class="pre">stage</span></tt>“ argument from the -example invocation from section 5 of the <a class="reference external" href="../../../more/getting_started/index.html">Getting Started -Guide</a> with “<tt class="docutils literal"><span class="pre">test</span></tt>,“ to build all the test targets. Also add -the argument “<tt class="docutils literal"><span class="pre">--verbose-test</span></tt>†to see the output generated by -the tests when they are run.</p> -<p>On Windows, your <tt class="docutils literal"><span class="pre">bjam</span></tt> invocation might look something like:</p> -<pre class="literal-block"> -C:\boost_1_34_0\…\quickstart> <strong>bjam toolset=msvc --verbose-test test</strong> -</pre> -<p>and on Unix variants, perhaps,</p> -<pre class="literal-block"> -~/boost_1_34_0/…/quickstart$ <strong>bjam toolset=gcc --verbose-test test</strong> -</pre> -</li> -</ol> -<div class="admonition-note-to-windows-users admonition"> -<p class="first admonition-title">Note to Windows Users</p> -<p class="last">For the sake of concision, the rest of this guide will use -unix-style forward slashes in pathnames instead of the -backslashes with which you may be more familiar. The forward -slashes should work everywhere except in <a class="reference external" href="../../../more/getting_started/windows.html#command-prompt">Command Prompt</a> -windows, where you should use backslashes.</p> -</div> -<p>If you followed this procedure successfully, you will have built an -extension module called <tt class="docutils literal"><span class="pre">extending</span></tt> and tested it by running a -Python script called <tt class="docutils literal"><span class="pre">test_extending.py</span></tt>. You will also have -built and run a simple application called <tt class="docutils literal"><span class="pre">embedding</span></tt> that embeds -python.</p> -</div> -<div class="section" id="in-case-of-trouble"> -<h2><a class="toc-backref" href="#id29">3.2 In Case of Trouble</a></h2> -<p>If you're seeing lots of compiler and/or linker error messages, -it's probably because Boost.Build is having trouble finding your -Python installation. You might want to pass the -<tt class="docutils literal"><span class="pre">--debug-configuration</span></tt> option to <tt class="docutils literal"><span class="pre">bjam</span></tt> the first few times -you invoke it, to make sure that Boost.Build is correctly locating -all the parts of your Python installation. If it isn't, consider -<a class="reference internal" href="#configuring-boost-build">Configuring Boost.Build</a> as detailed below.</p> -<p>If you're still having trouble, Someone on one of the following -mailing lists may be able to help:</p> -<ul class="simple"> -<li>The <a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#jamboost">Boost.Build mailing list</a> for issues related to Boost.Build</li> -<li>The Python <a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#cplussig">C++ Sig</a> for issues specifically related to Boost.Python</li> -</ul> -</div> -<div class="section" id="in-case-everything-seemed-to-work"> -<h2><a class="toc-backref" href="#id30">3.3 In Case Everything Seemed to Work</a></h2> -<p>Rejoice! If you're new to Boost.Python, at this point it might be -a good idea to ignore build issues for a while and concentrate on -learning the library by going through the <a class="reference external" href="tutorial/index.html">tutorial</a> and perhaps -some of the <a class="reference external" href="v2/reference.html">reference documentation</a>, trying out what you've -learned about the API by modifying the quickstart project.</p> -</div> -<div class="section" id="modifying-the-example-project"> -<h2><a class="toc-backref" href="#id31">3.4 Modifying the Example Project</a></h2> -<p>If you're content to keep your extension module forever in one -source file called <a class="reference external" href="../example/quickstart/extending.cpp"><tt class="docutils literal"><span class="pre">extending.cpp</span></tt></a>, inside your Boost -distribution, and import it forever as <tt class="docutils literal"><span class="pre">extending</span></tt>, then you can -stop here. However, it's likely that you will want to make a few -changes. There are a few things you can do without having to learn -<a class="reference external" href="../../../tools/build/index.html">Boost.Build</a> in depth.</p> -<p>The project you just built is specified in two files in the current -directory: <a class="reference external" href="../example/quickstart/boost-build.jam"><tt class="docutils literal"><span class="pre">boost-build.jam</span></tt></a>, which tells <tt class="docutils literal"><span class="pre">bjam</span></tt> where it can -find the interpreted code of the Boost build system, and -<a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>, which describes the targets you just built. These -files are heavily commented, so they should be easy to modify. -Take care, however, to preserve whitespace. Punctuation such as -<tt class="docutils literal"><span class="pre">;</span></tt> will not be recognized as intended by <tt class="docutils literal"><span class="pre">bjam</span></tt> if it is not -surrounded by whitespace.</p> -<div class="section" id="relocate-the-project"> -<h3>Relocate the Project</h3> -<p>You'll probably want to copy this project elsewhere so you can -change it without modifying your Boost distribution. To do that, -simply</p> -<ol class="loweralpha simple"> -<li>copy the entire <tt class="docutils literal"><span class="pre">libs/python/example/quickstart/</span></tt> directory -into a new directory.</li> -<li>In the new copies of <a class="reference external" href="../example/quickstart/boost-build.jam"><tt class="docutils literal"><span class="pre">boost-build.jam</span></tt></a> and <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>, locate -the relative path near the top of the file that is clearly -marked by a comment, and edit that path so that it refers to the -same directory your Boost distribution as it referred to when -the file was in its original location in the -<tt class="docutils literal"><span class="pre">libs/python/example/quickstart/</span></tt> directory.</li> -</ol> -<p>For example, if you moved the project from -<tt class="docutils literal"><span class="pre">/home/dave/boost_1_34_0/libs/python/example/quickstart</span></tt> to -<tt class="docutils literal"><span class="pre">/home/dave/my-project</span></tt>, you could change the first path in -<a class="reference external" href="../example/quickstart/boost-build.jam"><tt class="docutils literal"><span class="pre">boost-build.jam</span></tt></a> from</p> -<pre class="literal-block"> -<strong>../../../..</strong>/tools/build/v2 -</pre> -<p>to</p> -<pre class="literal-block"> -<strong>/home/dave/boost_1_34_0</strong>/tools/build/v2 -</pre> -<p>and change the first path in <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a> from</p> -<pre class="literal-block"> -<strong>../../../..</strong> -</pre> -<p>to</p> -<pre class="literal-block"> -<strong>/home/dave/boost_1_34_0</strong> -</pre> -</div> -<div class="section" id="add-new-or-change-names-of-existing-source-files"> -<h3>Add New or Change Names of Existing Source Files</h3> -<p>The names of additional source files involved in building your -extension module or embedding application can be listed in -<a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a> right alongside <tt class="docutils literal"><span class="pre">extending.cpp</span></tt> or <tt class="docutils literal"><span class="pre">embedding.cpp</span></tt> -respectively. Just be sure to leave whitespace around each -filename:</p> -<pre class="literal-block"> -… file1.cpp file2.cpp file3.cpp … -</pre> -<p>Naturally, if you want to change the name of a source file you can -tell Boost.Build about it by editing the name in <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>.</p> -</div> -<div class="section" id="change-the-name-of-your-extension-module"> -<h3>Change the Name of your Extension Module</h3> -<p>The name of the extension module is determined by two things:</p> -<ol class="arabic simple"> -<li>the name in <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a> immediately following <tt class="docutils literal"><span class="pre">python-extension</span></tt>, and</li> -<li>the name passed to <tt class="docutils literal"><span class="pre">BOOST_PYTHON_MODULE</span></tt> in <a class="reference external" href="../example/quickstart/extending.cpp"><tt class="docutils literal"><span class="pre">extending.cpp</span></tt></a>.</li> -</ol> -<p>To change the name of the extension module from <tt class="docutils literal"><span class="pre">extending</span></tt> to -<tt class="docutils literal"><span class="pre">hello</span></tt>, you'd edit <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>, changing</p> -<pre class="literal-block"> -python-extension <strong>extending</strong> : extending.cpp ; -</pre> -<p>to</p> -<pre class="literal-block"> -python-extension <strong>hello</strong> : extending.cpp ; -</pre> -<p>and you'd edit extending.cpp, changing</p> -<pre class="literal-block"> -BOOST_PYTHON_MODULE(<strong>extending</strong>) -</pre> -<p>to</p> -<pre class="literal-block"> -BOOST_PYTHON_MODULE(<strong>hello</strong>) -</pre> -</div> -</div> -</div> -<div class="section" id="installing-boost-python-on-your-system"> -<h1><a class="toc-backref" href="#id32">4 Installing Boost.Python on your System</a></h1> -<p>Since Boost.Python is a separately-compiled (as opposed to -<a class="reference external" href="../../../more/getting_started/windows.html#header-only-libraries">header-only</a>) library, its user relies on the services of a -Boost.Python library binary.</p> -<p>If you need a regular installation of the Boost.Python library -binaries on your system, the Boost <a class="reference external" href="../../../more/getting_started/index.html">Getting Started Guide</a> will -walk you through the steps of creating one. If building binaries -from source, you might want to supply the <tt class="docutils literal"><span class="pre">--with-python</span></tt> -argument to <tt class="docutils literal"><span class="pre">bjam</span></tt> (or the <tt class="docutils literal"><span class="pre">--with-libraries=python</span></tt> argument -to <tt class="docutils literal"><span class="pre">configure</span></tt>), so only the Boost.Python binary will be built, -rather than all the Boost binaries.</p> -</div> -<div class="section" id="configuring-boost-build"> -<h1><a class="toc-backref" href="#id33">5 Configuring Boost.Build</a></h1> -<p>As described in the <a class="reference external" href="http://www.boost.orgdoc/html/bbv2/advanced.html#bbv2.advanced.configuration">Boost.Build reference manual</a>, a file called -<tt class="docutils literal"><span class="pre">user-config.jam</span></tt> in your home directory<a class="footnote-reference" href="#home-dir" id="id11"><sup>6</sup></a> is used to -specify the tools and libraries available to the build system. You -may need to create or edit <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> to tell Boost.Build -how to invoke Python, <tt class="docutils literal"><span class="pre">#include</span></tt> its headers, and link with its -libraries.</p> -<div class="admonition-users-of-unix-variant-oses admonition"> -<p class="first admonition-title">Users of Unix-Variant OSes</p> -<p class="last">If you are using a unix-variant OS and you ran Boost's -<tt class="docutils literal"><span class="pre">configure</span></tt> script, it may have generated a -<tt class="docutils literal"><span class="pre">user-config.jam</span></tt> for you.<a class="footnote-reference" href="#overwrite" id="id13"><sup>4</sup></a> If your <tt class="docutils literal"><span class="pre">configure</span></tt>/<tt class="docutils literal"><span class="pre">make</span></tt> sequence was successful and Boost.Python binaries -were built, your <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file is probably already -correct.</p> -</div> -<p>If you have one fairly “standard†python installation for your -platform, you might not need to do anything special to describe it. If -you haven't configured python in <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> (and you don't -specify <tt class="docutils literal"><span class="pre">--without-python</span></tt> on the Boost.Build command line), -Boost.Build will automatically execute the equivalent of</p> -<pre class="literal-block"> -import toolset : using ; -using python ; -</pre> -<p>which automatically looks for Python in the most likely places. -However, that only happens when using the Boost.Python project file -(e.g. when referred to by another project as in the <a class="reference internal" href="#quickstart">quickstart</a> -method). If instead you are linking against separately-compiled -Boost.Python binaries, you should set up a <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file -with at least the minimal incantation above.</p> -<div class="section" id="python-configuration-parameters"> -<h2><a class="toc-backref" href="#id34">5.1 Python Configuration Parameters</a></h2> -<p>If you have several versions of Python installed, or Python is -installed in an unusual way, you may want to supply any or all of -the following optional parameters to <tt class="docutils literal"><span class="pre">using</span> <span class="pre">python</span></tt>.</p> -<dl class="docutils"> -<dt>version</dt> -<dd>the version of Python to use. Should be in Major.Minor -format, for example, <tt class="docutils literal"><span class="pre">2.3</span></tt>. Do not include the subminor -version (i.e. <em>not</em> <tt class="docutils literal"><span class="pre">2.5.1</span></tt>). If you have multiple Python -versions installed, the version will usually be the only -configuration argument required.</dd> -<dt>cmd-or-prefix</dt> -<dd>preferably, a command that invokes a Python interpreter. -Alternatively, the installation prefix for Python libraries and -header files. Only use the alternative formulation if there is -no appropriate Python executable available.</dd> -<dt>includes</dt> -<dd>the <tt class="docutils literal"><span class="pre">#include</span></tt> paths for Python headers. Normally the correct -path(s) will be automatically deduced from <tt class="docutils literal"><span class="pre">version</span></tt> and/or -<tt class="docutils literal"><span class="pre">cmd-or-prefix</span></tt>.</dd> -<dt>libraries</dt> -<dd>the path to Python library binaries. On MacOS/Darwin, -you can also pass the path of the Python framework. Normally the -correct path(s) will be automatically deduced from <tt class="docutils literal"><span class="pre">version</span></tt> -and/or <tt class="docutils literal"><span class="pre">cmd-or-prefix</span></tt>.</dd> -<dt>condition</dt> -<dd>if specified, should be a set of Boost.Build -properties that are matched against the build configuration when -Boost.Build selects a Python configuration to use. See examples -below for details.</dd> -<dt>extension-suffix</dt> -<dd>A string to append to the name of extension -modules before the true filename extension. You almost certainly -don't need to use this. Usually this suffix is only used when -targeting a Windows debug build of Python, and will be set -automatically for you based on the value of the -<a class="reference internal" href="#python-debugging"><tt class="docutils literal"><span class="pre"><python-debugging></span></tt></a> feature. However, at least one Linux -distribution (Ubuntu Feisty Fawn) has a specially configured -<a class="reference external" href="https://wiki.ubuntu.com/PyDbgBuilds">python-dbg</a> package that claims to use such a suffix.</dd> -</dl> -</div> -<div class="section" id="examples"> -<h2><a class="toc-backref" href="#id35">5.2 Examples</a></h2> -<p>Note that in the examples below, case and <em>especially whitespace</em> are -significant.</p> -<ul> -<li><p class="first">If you have both python 2.5 and python 2.4 installed, -<tt class="docutils literal"><span class="pre">user-config.jam</span></tt> might contain:</p> -<pre class="literal-block"> -using python : 2.5 ; # Make both versions of Python available - -using python : 2.4 ; # To build with python 2.4, add python=2.4 - # to your command line. -</pre> -<p>The first version configured (2.5) becomes the default. To build -against python 2.4, add <tt class="docutils literal"><span class="pre">python=2.4</span></tt> to the <tt class="docutils literal"><span class="pre">bjam</span></tt> command line.</p> -</li> -<li><p class="first">If you have python installed in an unusual location, you might -supply the path to the interpreter in the <tt class="docutils literal"><span class="pre">cmd-or-prefix</span></tt> -parameter:</p> -<pre class="literal-block"> -using python : : /usr/local/python-2.6-beta/bin/python ; -</pre> -</li> -<li><p class="first">If you have a separate build of Python for use with a particular -toolset, you might supply that toolset in the <tt class="docutils literal"><span class="pre">condition</span></tt> -parameter:</p> -<pre class="literal-block"> -using python ; # use for most toolsets - -# Use with Intel C++ toolset -using python - : # version - : c:\\Devel\\Python-2.5-IntelBuild\\PCBuild\\python # cmd-or-prefix - : # includes - : # libraries - : <toolset>intel # condition - ; -</pre> -</li> -<li><p class="first">If you have downloaded the Python sources and built both the -normal and the “<a class="reference internal" href="#id19">python debugging</a>†builds from source on -Windows, you might see:</p> -<pre class="literal-block"> -using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python ; -using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python_d - : # includes - : # libs - : <python-debugging>on ; -</pre> -</li> -<li><p class="first">You can set up your user-config.jam so a bjam built under Windows -can build/test both Windows and <a class="reference external" href="http://cygwin.com">Cygwin</a> python extensions. Just pass -<tt class="docutils literal"><span class="pre"><target-os>cygwin</span></tt> in the <tt class="docutils literal"><span class="pre">condition</span></tt> parameter -for the cygwin python installation:</p> -<pre class="literal-block"> -# windows installation -using python ; - -# cygwin installation -using python : : c:\\cygwin\\bin\\python2.5 : : : <target-os>cygwin ; -</pre> -<p>when you put target-os=cygwin in your build request, it should build -with the cygwin version of python:<a class="footnote-reference" href="#flavor" id="id15"><sup>5</sup></a></p> -<blockquote> -<p>bjam target-os=cygwin toolset=gcc</p> -</blockquote> -<p>This is supposed to work the other way, too (targeting windows -python with a <a class="reference external" href="http://cygwin.com">Cygwin</a> bjam) but it seems as though the support in -Boost.Build's toolsets for building that way is broken at the -time of this writing.</p> -</li> -<li><p class="first">Note that because of <a class="reference external" href="http://zigzag.cs.msu.su/boost.build/wiki/AlternativeSelection">the way Boost.Build currently selects target -alternatives</a>, you might have be very explicit in your build -requests. For example, given:</p> -<pre class="literal-block"> -using python : 2.5 ; # a regular windows build -using python : 2.4 : : : : <target-os>cygwin ; -</pre> -<p>building with</p> -<pre class="literal-block"> -bjam target-os=cygwin -</pre> -<p>will yield an error. Instead, you'll need to write:</p> -<pre class="literal-block"> -bjam target-os=cygwin/python=2.4 -</pre> -</li> -</ul> -</div> -</div> -<div class="section" id="choosing-a-boost-python-library-binary"> -<h1><a class="toc-backref" href="#id36">6 Choosing a Boost.Python Library Binary</a></h1> -<p>If—instead of letting Boost.Build construct and link with the right -libraries automatically—you choose to use a pre-built Boost.Python -library, you'll need to think about which one to link with. The -Boost.Python binary comes in both static and dynamic flavors. Take -care to choose the right flavor for your application.<a class="footnote-reference" href="#naming" id="id17"><sup>2</sup></a></p> -<div class="section" id="the-dynamic-binary"> -<h2><a class="toc-backref" href="#id37">6.1 The Dynamic Binary</a></h2> -<p>The dynamic library is the safest and most-versatile choice:</p> -<ul class="simple"> -<li>A single copy of the library code is used by all extension -modules built with a given toolset.<a class="footnote-reference" href="#toolset-specific" id="id18"><sup>3</sup></a></li> -<li>The library contains a type conversion registry. Because one -registry is shared among all extension modules, instances of a -class exposed to Python in one dynamically-loaded extension -module can be passed to functions exposed in another such module.</li> -</ul> -</div> -<div class="section" id="the-static-binary"> -<h2><a class="toc-backref" href="#id38">6.2 The Static Binary</a></h2> -<p>It might be appropriate to use the static Boost.Python library in -any of the following cases:</p> -<ul class="simple"> -<li>You are <a class="reference external" href="http://www.python.org/doc/current/ext/intro.html">extending</a> python and the types exposed in your -dynamically-loaded extension module don't need to be used by any -other Boost.Python extension modules, and you don't care if the -core library code is duplicated among them.</li> -<li>You are <a class="reference external" href="http://www.python.org/doc/current/ext/embedding.html">embedding</a> python in your application and either:<ul> -<li>You are targeting a Unix variant OS other than MacOS or AIX, -where the dynamically-loaded extension modules can “see†the -Boost.Python library symbols that are part of the executable.</li> -<li>Or, you have statically linked some Boost.Python extension -modules into your application and you don't care if any -dynamically-loaded Boost.Python extension modules are able to -use the types exposed by your statically-linked extension -modules (and vice-versa).</li> -</ul> -</li> -</ul> -</div> -</div> -<div class="section" id="include-issues"> -<h1><a class="toc-backref" href="#id39">7 <tt class="docutils literal"><span class="pre">#include</span></tt> Issues</a></h1> -<ol class="arabic simple"> -<li>If you should ever have occasion to <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"python.h"</span></tt> -directly in a translation unit of a program using Boost.Python, -use <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"boost/python/detail/wrap_python.hpp"</span></tt> instead. -It handles several issues necessary for use with Boost.Python, -one of which is mentioned in the next section.</li> -<li>Be sure not to <tt class="docutils literal"><span class="pre">#include</span></tt> any system headers before -<tt class="docutils literal"><span class="pre">wrap_python.hpp</span></tt>. This restriction is actually imposed by -Python, or more properly, by Python's interaction with your -operating system. See -<a class="reference external" href="http://docs.python.org/ext/simpleExample.html">http://docs.python.org/ext/simpleExample.html</a> for details.</li> -</ol> -</div> -<div class="section" id="python-debugging-builds"> -<span id="id19"></span><span id="python-debugging"></span><h1><a class="toc-backref" href="#id40">8 Python Debugging Builds</a></h1> -<p>Python can be built in a special “python debugging†configuration -that adds extra checks and instrumentation that can be very useful -for developers of extension modules. The data structures used by -the debugging configuration contain additional members, so <strong>a -Python executable built with python debugging enabled cannot be -used with an extension module or library compiled without it, and -vice-versa.</strong></p> -<p>Since pre-built “python debugging†versions of the Python -executable and libraries are not supplied with most distributions -of Python,<a class="footnote-reference" href="#get-debug-build" id="id20"><sup>7</sup></a> and we didn't want to force our users -to build them, Boost.Build does not automatically enable python -debugging in its <tt class="docutils literal"><span class="pre">debug</span></tt> build variant (which is the default). -Instead there is a special build property called -<tt class="docutils literal"><span class="pre">python-debugging</span></tt> that, when used as a build property, will -define the right preprocessor symbols and select the right -libraries to link with.</p> -<p>On unix-variant platforms, the debugging versions of Python's data -structures will only be used if the symbol <tt class="docutils literal"><span class="pre">Py_DEBUG</span></tt> is defined. -On many windows compilers, when extension modules are built with -the preprocessor symbol <tt class="docutils literal"><span class="pre">_DEBUG</span></tt>, Python defaults to force -linking with a special debugging version of the Python DLL. Since -that symbol is very commonly used even when Python is not present, -Boost.Python temporarily undefines _DEBUG when Python.h -is #included from <tt class="docutils literal"><span class="pre">boost/python/detail/wrap_python.hpp</span></tt> - unless -<tt class="docutils literal"><span class="pre">BOOST_DEBUG_PYTHON</span></tt> is defined. The upshot is that if you want -“python debuggingâ€and you aren't using Boost.Build, you should make -sure <tt class="docutils literal"><span class="pre">BOOST_DEBUG_PYTHON</span></tt> is defined, or python debugging will be -suppressed.</p> -</div> -<div class="section" id="testing-boost-python"> -<h1><a class="toc-backref" href="#id41">9 Testing Boost.Python</a></h1> -<p>To run the full test suite for Boost.Python, invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> in the -<tt class="docutils literal"><span class="pre">libs/python/test</span></tt> subdirectory of your Boost distribution.</p> -</div> -<div class="section" id="notes-for-mingw-and-cygwin-with-mno-cygwin-gcc-users"> -<h1><a class="toc-backref" href="#id42">10 Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users</a></h1> -<p>If you are using a version of Python prior to 2.4.1 with a MinGW -prior to 3.0.0 (with binutils-2.13.90-20030111-1), you will need to -create a MinGW-compatible version of the Python library; the one -shipped with Python will only work with a Microsoft-compatible -linker. Follow the instructions in the “Non-Microsoft†section of -the “Building Extensions: Tips And Tricks†chapter in <a class="reference external" href="http://www.python.org/doc/current/inst/index.html">Installing -Python Modules</a> to create <tt class="docutils literal"><span class="pre">libpythonXX.a</span></tt>, where <tt class="docutils literal"><span class="pre">XX</span></tt> -corresponds to the major and minor version numbers of your Python -installation.</p> -<hr class="docutils" /> -<table class="docutils footnote" frame="void" id="id22" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>Note that although we tested earlier versions of -Boost.Python with Python 2.2, and we don't <em>think</em> we've done -anything to break compatibility, this release of Boost.Python -may not have been tested with versions of Python earlier than -2.4, so we're not 100% sure that python 2.2 and 2.3 are -supported.</td></tr> -</tbody> -</table> -<table class="docutils footnote" frame="void" id="naming" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id17">[2]</a></td><td><p class="first">Information about how to identify the -static and dynamic builds of Boost.Python:</p> -<ul class="simple"> -<li><a class="reference external" href="../../../more/getting_started/windows.html#library-naming">on Windows</a></li> -<li><a class="reference external" href="../../../more/getting_started/unix-variants.html#library-naming">on Unix variants</a></li> -</ul> -</td></tr> -</tbody> -</table> -<table class="docutils footnote" frame="void" id="toolset-specific" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id18">[3]</a></td><td>Because of the way most *nix platforms -share symbols among dynamically-loaded objects, I'm not certain -that extension modules built with different compiler toolsets -will always use different copies of the Boost.Python library -when loaded into the same Python instance. Not using different -libraries could be a good thing if the compilers have compatible -ABIs, because extension modules built with the two libraries -would be interoperable. Otherwise, it could spell disaster, -since an extension module and the Boost.Python library would -have different ideas of such things as class layout. I would -appreciate someone doing the experiment to find out what -happens.</td></tr> -</tbody> -</table> -<table class="docutils footnote" frame="void" id="overwrite" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id13">[4]</a></td><td><tt class="docutils literal"><span class="pre">configure</span></tt> overwrites the existing -<tt class="docutils literal"><span class="pre">user-config.jam</span></tt> in your home directory -(if any) after making a backup of the old version.</td></tr> -</tbody> -</table> -<table class="docutils footnote" frame="void" id="flavor" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id15">[5]</a></td><td>Note that the <tt class="docutils literal"><span class="pre"><target-os>cygwin</span></tt> feature is -different from the <tt class="docutils literal"><span class="pre"><flavor>cygwin</span></tt> subfeature of the <tt class="docutils literal"><span class="pre">gcc</span></tt> -toolset, and you might need handle both explicitly if you also -have a MinGW GCC installed.</td></tr> -</tbody> -</table> -<table class="docutils footnote" frame="void" id="home-dir" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id11">[6]</a></td><td><p class="first">Windows users, your home directory can be -found by typing:</p> -<pre class="literal-block"> -ECHO %HOMEDRIVE%%HOMEPATH% -</pre> -<p class="last">into a <a class="reference external" href="../../../more/getting_started/windows.html#command-prompt">command prompt</a> window.</p> -</td></tr> -</tbody> -</table> -<table class="docutils footnote" frame="void" id="get-debug-build" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id20">[7]</a></td><td>On Unix and similar platforms, a debugging -python and associated libraries are built by adding -<tt class="docutils literal"><span class="pre">--with-pydebug</span></tt> when configuring the Python build. On -Windows, the debugging version of Python is generated by -the "Win32 Debug" target of the Visual Studio project in the -PCBuild subdirectory of a full Python source code distribution. -</td></tr> -</tbody> -</table> -</div> -</div> -<div class="footer"> -<hr class="footer" /> -<a class="reference external" href="./building.rst">View document source</a>. -Generated on: 2007-07-02 13:46 UTC. -Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source. - -</div> -</body> -</html> diff --git a/libs/python/doc/building.qbk b/libs/python/doc/building.qbk new file mode 100644 index 0000000000..c19ba7cfdd --- /dev/null +++ b/libs/python/doc/building.qbk @@ -0,0 +1,566 @@ +[chapter Building and Testing + [quickbook 1.7] + [authors [Abrahams, David]] + [copyright 2002 - 2015 David Abrahams, Stefan Seefeld] + [id building] +] +[/ Copyright David Abrahams 2006. Distributed under the Boost + / Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at + / http://www.boost.org/LICENSE_1_0.txt) + /] + +[section Requirements] + +Boost.Python requires [@http://www.python.org/2.2 Python 2.2] +[footnote Note that although we tested earlier versions of Boost.Python + with Python 2.2, and we don't *think* we've done anything to break + compatibility, this release of Boost.Python may not have been tested + with versions of Python earlier than 2.4, so we're not 100% sure that + python 2.2 and 2.3 are supported.] *or* [@http://www.python.org newer]. + +[endsect] +[section Background] + +There are two basic models for combining C++ and Python: + +* [@http://www.python.org/doc/current/ext/intro.html extending], + in which the end-user launches the Python interpreter + executable and imports Python “extension modules†written in C++. + Think of taking a library written in C++ and giving it a Python + interface so Python programmers can use it. From Python, these + modules look just like regular Python modules. + +* [@http://www.python.org/doc/current/ext/embedding.html embedding], + in which the end-user launches a program written + in C++ that in turn invokes the Python interpreter as a library + subroutine. Think of adding scriptability to an existing + application. + +The key distinction between extending and embedding is the location +of the C++ `main()` function: in the Python interpreter executable, +or in some other program, respectively. Note that even when +embedding Python in another program, [@http://www.python.org/doc/current/ext/extending-with-embedding.html extension modules are often +the best way to make C/C++ functionality accessible to Python +code], so the use of extension modules is really at the heart of +both models. + +Except in rare cases, extension modules are built as +dynamically-loaded libraries with a single entry point, which means +you can change them without rebuilding either the other extension +modules or the executable containing `main()`. + +[endsect] +[section No-Install Quickstart] + +There is no need to “install Boost†in order to get started using +Boost.Python. These instructions use _bb_ projects, +which will build those binaries as soon as they're needed. Your +first tests may take a little longer while you wait for +Boost.Python to build, but doing things this way will save you from +worrying about build intricacies like which library binaries to use +for a specific compiler configuration and figuring out the right +compiler options to use yourself. + +[note Of course it's possible to use other build systems to + build Boost.Python and its extensions, but they are not + officially supported by Boost. Moreover *99% of all “I can't + build Boost.Python†problems come from trying to use another + build system* without first following these instructions. + + If you want to use another system anyway, we suggest that you + follow these instructions, and then invoke `bjam` with the + + `-a -o`\ /filename/ + + options to dump the build commands it executes to a file, so + you can see what your alternate build system needs to do.] + +[section Basic Procedure] + +1. Get Boost; see sections 1 and 2 of the _gsg_. + +2. Get the `bjam` build driver. See section 5 of the _gsg_. + +3. cd into the `example/quickstart/` directory of your + Boost.Python installation, which contains a small example project. + +4. Invoke `bjam`. Replace the “\ `stage`\ “ argument from the + example invocation from section 5 of the _gsg_ with “\ `test`\ ,“ to + build all the test targets. Also add the argument “\ `--verbose-test`\ †+ to see the output generated by the tests when they are run. + On Windows, your `bjam` invocation might look something like: + `` + C:\\...\\quickstart> bjam toolset=msvc --verbose-test test + `` + and on Unix variants, perhaps, + `` + .../quickstart$ bjam toolset=gcc --verbose-test test + `` + +[note For the sake of concision, the rest of this guide will use + unix-style forward slashes in pathnames instead of the + backslashes with which Windows users may be more familiar. The forward + slashes should work everywhere except in + [@http://www.boost.org/more/getting_started/windows.html#command-prompt + Command Prompt] windows, where you should use backslashes.] + +If you followed this procedure successfully, you will have built an +extension module called `extending` and tested it by running a +Python script called `test_extending.py`. You will also have +built and run a simple application called `embedding` that embeds +python. + +[endsect] +[section In Case of Trouble] + +If you're seeing lots of compiler and/or linker error messages, +it's probably because Boost.Build is having trouble finding your +Python installation. You might want to pass the +`--debug-configuration` option to `bjam` the first few times +you invoke it, to make sure that Boost.Build is correctly locating +all the parts of your Python installation. If it isn't, consider +[link building.configuring_boost_build Configuring Boost.Build] +as detailed below. + +If you're still having trouble, Someone on one of the following +mailing lists may be able to help: + +* The _bb_list_ for issues related to Boost.Build +* The _bp_list_ for issues specifically related to Boost.Python + +[endsect] +[section In Case Everything Seemed to Work] + +Rejoice! If you're new to Boost.Python, at this point it might be +a good idea to ignore build issues for a while and concentrate on +learning the library by going through the _tutorial_ and perhaps +some of the _reference_, trying out what you've +learned about the API by modifying the quickstart project. + +[endsect] +[section Modifying the Example Project] + +If you're content to keep your extension module forever in one +source file called `extending.cpp`, inside your Boost.Python +distribution, and import it forever as `extending`, then you can +stop here. However, it's likely that you will want to make a few +changes. There are a few things you can do without having to learn +_bb_ in depth. + +The project you just built is specified in two files in the current +directory: `boost-build.jam`, which tells `bjam` where it can +find the interpreted code of the Boost build system, and +`Jamroot`, which describes the targets you just built. These +files are heavily commented, so they should be easy to modify. +Take care, however, to preserve whitespace. Punctuation such as +`;` will not be recognized as intended by `bjam` if it is not +surrounded by whitespace. + +[section Relocate the Project] + +You'll probably want to copy this project elsewhere so you can +change it without modifying your Boost distribution. To do that, +simply + +a. copy the entire `example/quickstart/` directory + into a new directory. + +b. In the new copies of `boost-build.jam` and `Jamroot`, locate + the relative path near the top of the file that is clearly + marked by a comment, and edit that path so that it refers to the + same directory your Boost distribution as it referred to when + the file was in its original location in the + `example/quickstart/` directory. + +For example, if you moved the project from +`/home/dave/boost_1_34_0/libs/python/example/quickstart` to +`/home/dave/my-project`, you could change the first path in +`boost-build.jam` from +`` + ../../../../tools/build/src +`` +to +`` + /home/dave/boost_1_34_0/tools/build/src +`` +and change the first path in `Jamroot` from +`` + ../../../.. +`` +to +`` + /home/dave/boost_1_34_0 +`` + +[endsect] +[section Add New or Change Names of Existing Source Files] + +The names of additional source files involved in building your +extension module or embedding application can be listed in +`Jamroot` right alongside `extending.cpp` or `embedding.cpp` +respectively. Just be sure to leave whitespace around each +filename: +`` + … file1.cpp file2.cpp file3.cpp … +`` +Naturally, if you want to change the name of a source file you can +tell Boost.Build about it by editing the name in `Jamroot`. + +[endsect] +[section Change the Name of your Extension Module] + +The name of the extension module is determined by two things: + +# the name in `Jamroot` immediately following `python-extension`, and +# the name passed to `BOOST_PYTHON_MODULE` in `extending.cpp`. + +To change the name of the extension module from `extending` to +`hello`, you'd edit `Jamroot`, changing +`` + python-extension extending : extending.cpp ; +`` +to +`` + python-extension hello : extending.cpp ; +`` +and you'd edit extending.cpp, changing + +`` + BOOST_PYTHON_MODULE(extending) +`` +to +`` + BOOST_PYTHON_MODULE(hello) +`` +[endsect] +[endsect] +[endsect] +[section Installing Boost.Python on your System] + +Since Boost.Python is a separately-compiled (as opposed to +`header-only`) library, its user relies on the services of a +Boost.Python library binary. + +If you need a regular installation of the Boost.Python library +binaries on your system, the _gsg_ will +walk you through the steps of creating one. If building binaries +from source, you might want to supply the `--with-python` +argument to `bjam` (or the `--with-libraries=python` argument +to `configure`), so only the Boost.Python binary will be built, +rather than all the Boost binaries. + +[endsect] +[section Configuring Boost.Build] + +As described in the [@http://www.boost.org/build/doc/html/bbv2/overview/configuration.html Boost.Build Reference Manual], a file called +`user-config.jam` in your home directory is used to +specify the tools and libraries available to the build system. You +may need to create or edit `user-config.jam` to tell Boost.Build +how to invoke Python, `#include` its headers, and link with its +libraries. + +[note If you are using a unix-variant OS and you ran Boost's + `configure` script, it may have generated a + `user-config.jam` for you. [footnote `configure` overwrites the existing + `user-config.jam` in your home directory (if any) after making a backup of + the old version.] If your `configure`\ /\ `make` sequence was successful and + Boost.Python binaries were built, your `user-config.jam` file is probably already + correct.] + +If you have one fairly “standard†python installation for your +platform, you might not need to do anything special to describe it. If +you haven't configured python in `user-config.jam` (and you don't +specify `--without-python` on the Boost.Build command line), +Boost.Build will automatically execute the equivalent of + +`` + import toolset : using ; + using python ; +`` +which automatically looks for Python in the most likely places. +However, that only happens when using the Boost.Python project file +(e.g. when referred to by another project as in the quickstart +method). If instead you are linking against separately-compiled +Boost.Python binaries, you should set up a `user-config.jam` file +with at least the minimal incantation above. + +[section Python Configuration Parameters] + +If you have several versions of Python installed, or Python is +installed in an unusual way, you may want to supply any or all of +the following optional parameters to `using python`. + +[variablelist + [[version] + + [the version of Python to use. Should be in Major.Minor + format, for example, `2.3`. Do not include the subminor + version (i.e. *not* `2.5.1`). If you have multiple Python + versions installed, the version will usually be the only + configuration argument required.]] + + [[cmd-or-prefix] + + [preferably, a command that invokes a Python interpreter. + Alternatively, the installation prefix for Python libraries and + header files. Only use the alternative formulation if there is + no appropriate Python executable available.]] + + [[*includes*] + + [the `#include` paths for Python headers. Normally the correct + path(s) will be automatically deduced from `version` and/or + `cmd-or-prefix`.]] + + [[*libraries*] + + [the path to Python library binaries. On MacOS/Darwin, + you can also pass the path of the Python framework. Normally the + correct path(s) will be automatically deduced from `version` + and/or `cmd-or-prefix`.]] + + [[*condition*] + + [if specified, should be a set of Boost.Build + properties that are matched against the build configuration when + Boost.Build selects a Python configuration to use. See examples + below for details.]] + + [[*extension-suffix*] + + [A string to append to the name of extension + modules before the true filename extension. You almost certainly + don't need to use this. Usually this suffix is only used when + targeting a Windows debug build of Python, and will be set + automatically for you based on the value of the + [link building.python_debugging_builds <python-debugging>] feature. + However, at least one Linux distribution (Ubuntu Feisty Fawn) has + a specially configured [@https://wiki.ubuntu.com/PyDbgBuilds <python-dbg>] + package that claims to use such a suffix.]] + ] + +[endsect] +[section Examples] + +Note that in the examples below, case and *especially whitespace* are +significant. + +* If you have both python 2.5 and python 2.4 installed, + `user-config.jam` might contain + + `` + using python : 2.5 ; # Make both versions of Python available + using python : 2.4 ; # To build with python 2.4, add python=2.4 + # to your command line. + `` + The first version configured (2.5) becomes the default. To build + against python 2.4, add `python=2.4` to the `bjam` command line. + +* If you have python installed in an unusual location, you might + supply the path to the interpreter in the `cmd-or-prefix` + parameter: + + `` + using python : : /usr/local/python-2.6-beta/bin/python ; + `` + +* If you have a separate build of Python for use with a particular + toolset, you might supply that toolset in the `condition` + parameter: + + `` + using python ; # use for most toolsets + + # Use with Intel C++ toolset + using python + : # version + : c:\\Devel\\Python-2.5-IntelBuild\\PCBuild\\python # cmd-or-prefix + : # includes + : # libraries + : <toolset>intel # condition + ; + `` + +* If you have downloaded the Python sources and built both the + normal and the [link building.python_debugging_builds "python debugging"] + builds from source on Windows, you might see: + + `` + using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python ; + using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python_d + : # includes + : # libs + : <python-debugging>on ; + `` +* You can set up your user-config.jam so a bjam built under Windows + can build/test both Windows and Cygwin_ python extensions. Just pass + `<target-os>cygwin` in the `condition` parameter + for the cygwin python installation: + + `` + # windows installation + using python ; + + # cygwin installation + using python : : c:\\cygwin\\bin\\python2.5 : : : <target-os>cygwin ; + `` + when you put target-os=cygwin in your build request, it should build + with the cygwin version of python: [#flavor]_ + + `` + bjam target-os=cygwin toolset=gcc + `` + This is supposed to work the other way, too (targeting windows + python with a [@http://cygwin.com Cygwin] bjam) but it seems as though the support in + Boost.Build's toolsets for building that way is broken at the + time of this writing. + +* Note that because of [@http://zigzag.cs.msu.su/boost.build/wiki/AlternativeSelection + the way Boost.Build currently selects target alternatives], you might have be very + explicit in your build requests. For example, given: + + `` + using python : 2.5 ; # a regular windows build + using python : 2.4 : : : : <target-os>cygwin ; + `` + building with + `` + bjam target-os=cygwin + `` + + will yield an error. Instead, you'll need to write + + `` + bjam target-os=cygwin/python=2.4 + `` + +[endsect] +[endsect] +[section Choosing a Boost.Python Library Binary] + +If—instead of letting Boost.Build construct and link with the right +libraries automatically—you choose to use a pre-built Boost.Python +library, you'll need to think about which one to link with. The +Boost.Python binary comes in both static and dynamic flavors. Take +care to choose the right flavor for your application. [footnote +Information about how to identify the static and dynamic builds of Boost.Python on +[@http://boost.org/more/getting_started/windows.html#library-naming Windows] / +[@http://boost.org/more/getting_started/unix-variants.html#library-naming Unix variants]] + +[section The Dynamic Binary] + +The dynamic library is the safest and most-versatile choice: + +* A single copy of the library code is used by all extension + modules built with a given toolset. [footnote Because of the way most \*nix platforms + share symbols among dynamically-loaded objects, I'm not certain + that extension modules built with different compiler toolsets + will always use different copies of the Boost.Python library + when loaded into the same Python instance. Not using different + libraries could be a good thing if the compilers have compatible + ABIs, because extension modules built with the two libraries + would be interoperable. Otherwise, it could spell disaster, + since an extension module and the Boost.Python library would + have different ideas of such things as class layout. I would + appreciate someone doing the experiment to find out what + happens.] + +* The library contains a type conversion registry. Because one + registry is shared among all extension modules, instances of a + class exposed to Python in one dynamically-loaded extension + module can be passed to functions exposed in another such module. + +[endsect] +[section The Static Binary] + +It might be appropriate to use the static Boost.Python library in +any of the following cases: + +* You are _extending_ python and the types exposed in your + dynamically-loaded extension module don't need to be used by any + other Boost.Python extension modules, and you don't care if the + core library code is duplicated among them. + +* You are _embedding_ python in your application and either: + + * You are targeting a Unix variant OS other than MacOS or AIX, + where the dynamically-loaded extension modules can “see†the + Boost.Python library symbols that are part of the executable. + + * Or, you have statically linked some Boost.Python extension + modules into your application and you don't care if any + dynamically-loaded Boost.Python extension modules are able to + use the types exposed by your statically-linked extension + modules (and vice-versa). + +[endsect] +[endsect] +[section `#include` Issues] + +1. If you should ever have occasion to `#include "python.h"` + directly in a translation unit of a program using Boost.Python, + use `#include "boost/python/detail/wrap_python.hpp"` instead. + It handles several issues necessary for use with Boost.Python, + one of which is mentioned in the next section. + +2. Be sure not to `#include` any system headers before + `wrap_python.hpp`. This restriction is actually imposed by + Python, or more properly, by Python's interaction with your + operating system. See + [@http://docs.python.org/ext/simpleExample.html] for details. + +[endsect] +[section Python Debugging Builds] + +Python can be built in a special “python debugging†configuration +that adds extra checks and instrumentation that can be very useful +for developers of extension modules. The data structures used by +the debugging configuration contain additional members, so *a +Python executable built with python debugging enabled cannot be +used with an extension module or library compiled without it, and +vice-versa.* + +Since pre-built “python debugging†versions of the Python +executable and libraries are not supplied with most distributions +of Python, [footnote On Unix and similar platforms, a debugging python and associated libraries are built by adding --with-pydebug when configuring the Python build. On Windows, the debugging version of Python is generated by the "Win32 Debug" target of the Visual Studio project in the PCBuild subdirectory of a full Python source code distribution.] and we didn't want to force our users +to build them, Boost.Build does not automatically enable python +debugging in its `debug` build variant (which is the default). +Instead there is a special build property called +`python-debugging` that, when used as a build property, will +define the right preprocessor symbols and select the right +libraries to link with. + +On unix-variant platforms, the debugging versions of Python's data +structures will only be used if the symbol `Py_DEBUG` is defined. +On many windows compilers, when extension modules are built with +the preprocessor symbol `_DEBUG`, Python defaults to force +linking with a special debugging version of the Python DLL. Since +that symbol is very commonly used even when Python is not present, +Boost.Python temporarily undefines `_DEBUG` when `Python.h` +is #included from `boost/python/detail/wrap_python.hpp` - unless +`BOOST_DEBUG_PYTHON` is defined. The upshot is that if you want +“python debuggingâ€and you aren't using Boost.Build, you should make +sure `BOOST_DEBUG_PYTHON` is defined, or python debugging will be +suppressed. + +[endsect] +[section Testing Boost.Python] + +To run the full test suite for Boost.Python, invoke `bjam` in the +`test` subdirectory of your Boost.Python distribution. + +[endsect] +[section Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users] + +If you are using a version of Python prior to 2.4.1 with a MinGW +prior to 3.0.0 (with binutils-2.13.90-20030111-1), you will need to +create a MinGW-compatible version of the Python library; the one +shipped with Python will only work with a Microsoft-compatible +linker. Follow the instructions in the “Non-Microsoft†section of +the “Building Extensions: Tips And Tricks†chapter in +[@https://docs.python.org/2/install/index.html Installing Python Modules] +to create `libpythonXX.a`, where `XX` corresponds to the major and minor +version numbers of your Python installation. + +[endsect] diff --git a/libs/python/doc/building.rst b/libs/python/doc/building.rst deleted file mode 100644 index 1e2c7d42f2..0000000000 --- a/libs/python/doc/building.rst +++ /dev/null @@ -1,680 +0,0 @@ -.. Copyright David Abrahams 2006. Distributed under the Boost -.. Software License, Version 1.0. (See accompanying -.. file LICENSE_1_0.txt or copy at -.. http://www.boost.org/LICENSE_1_0.txt) - -============================================== - |(logo)|__ Boost.Python Build and Test HOWTO -============================================== - -.. |(logo)| image:: ../../../boost.png - :alt: Boost C++ Libraries: - :class: boost-logo - -__ ../index.html - - -.. section-numbering:: - :depth: 2 - -.. contents:: Contents - :depth: 2 - :class: sidebar small - -.. |newer| replace:: *newer* - -Requirements -============ - -Boost.Python requires `Python 2.2`_ [#2.2]_ *or* |newer|__. - -.. _Python 2.2: http://www.python.org/2.2 -__ http://www.python.org - -Background -========== - -There are two basic models for combining C++ and Python: - -- extending_, in which the end-user launches the Python interpreter - executable and imports Python “extension modules†written in C++. - Think of taking a library written in C++ and giving it a Python - interface so Python programmers can use it. From Python, these - modules look just like regular Python modules. - -- embedding_, in which the end-user launches a program written - in C++ that in turn invokes the Python interpreter as a library - subroutine. Think of adding scriptability to an existing - application. - -.. _extending: http://www.python.org/doc/current/ext/intro.html -.. _embedding: http://www.python.org/doc/current/ext/embedding.html - -The key distinction between extending and embedding is the location -of the C++ ``main()`` function: in the Python interpreter executable, -or in some other program, respectively. Note that even when -embedding Python in another program, `extension modules are often -the best way to make C/C++ functionality accessible to Python -code`__, so the use of extension modules is really at the heart of -both models. - -__ http://www.python.org/doc/current/ext/extending-with-embedding.html - -Except in rare cases, extension modules are built as -dynamically-loaded libraries with a single entry point, which means -you can change them without rebuilding either the other extension -modules or the executable containing ``main()``. - -.. _quickstart: - -No-Install Quickstart -===================== - -There is no need to “install Boost†in order to get started using -Boost.Python. These instructions use Boost.Build_ projects, -which will build those binaries as soon as they're needed. Your -first tests may take a little longer while you wait for -Boost.Python to build, but doing things this way will save you from -worrying about build intricacies like which library binaries to use -for a specific compiler configuration and figuring out the right -compiler options to use yourself. - -.. .. raw:: html - - <div style="width:50%"> - -.. Note:: Of course it's possible to use other build systems to - build Boost.Python and its extensions, but they are not - officially supported by Boost. Moreover **99% of all “I can't - build Boost.Python†problems come from trying to use another - build system** without first following these instructions. - - If you want to use another system anyway, we suggest that you - follow these instructions, and then invoke ``bjam`` with the - - .. parsed-literal:: - - ``-a -o``\ *filename* - - options to dump the build commands it executes to a file, so - you can see what your alternate build system needs to do. - -.. .. raw:: html - - </div> - -.. _Boost.Build: ../../../tools/build/index.html - -Basic Procedure ---------------- - -1. Get Boost; see sections 1 and 2 [`Unix/Linux`__, `Windows`__\ ] of the - Boost `Getting Started Guide`_. - - __ ../../../more/getting_started/unix-variants.html#get-boost - __ ../../../more/getting_started/windows.html#get-boost - -2. Get the ``bjam`` build driver. See section 5 [`Unix/Linux`__, - `Windows`__\ ] of the Boost `Getting Started Guide`_. - - __ ../../../more/getting_started/unix-variants.html#prepare-to-use-a-boost-library-binary - __ ../../../more/getting_started/windows.html#prepare-to-use-a-boost-library-binary - - -3. cd into the ``libs/python/example/quickstart/`` directory of your - Boost installation, which contains a small example project. - -4. Invoke ``bjam``. Replace the “\ ``stage``\ “ argument from the - example invocation from section 5 of the `Getting Started - Guide`_ with “\ ``test``\ ,“ to build all the test targets. Also add - the argument “\ ``--verbose-test``\ †to see the output generated by - the tests when they are run. - - On Windows, your ``bjam`` invocation might look something like: - - .. parsed-literal:: - - C:\\boost_1_34_0\\…\\quickstart> **bjam toolset=msvc --verbose-test test** - - and on Unix variants, perhaps, - - .. parsed-literal:: - - ~/boost_1_34_0/…/quickstart$ **bjam toolset=gcc --verbose-test test** - -.. Admonition:: Note to Windows Users - - For the sake of concision, the rest of this guide will use - unix-style forward slashes in pathnames instead of the - backslashes with which you may be more familiar. The forward - slashes should work everywhere except in `Command Prompt`_ - windows, where you should use backslashes. - - .. _Command Prompt: ../../../more/getting_started/windows.html#command-prompt - -If you followed this procedure successfully, you will have built an -extension module called ``extending`` and tested it by running a -Python script called ``test_extending.py``. You will also have -built and run a simple application called ``embedding`` that embeds -python. - -.. _Getting Started Guide: ../../../more/getting_started/index.html - -In Case of Trouble ------------------- - -If you're seeing lots of compiler and/or linker error messages, -it's probably because Boost.Build is having trouble finding your -Python installation. You might want to pass the -``--debug-configuration`` option to ``bjam`` the first few times -you invoke it, to make sure that Boost.Build is correctly locating -all the parts of your Python installation. If it isn't, consider -`Configuring Boost.Build`_ as detailed below. - -If you're still having trouble, Someone on one of the following -mailing lists may be able to help: - -* The `Boost.Build mailing list`__ for issues related to Boost.Build -* The Python `C++ Sig`__ for issues specifically related to Boost.Python - -__ http://www.boost.org/more/mailing_lists.htm#jamboost -__ http://www.boost.org/more/mailing_lists.htm#cplussig - -In Case Everything Seemed to Work ---------------------------------- - -Rejoice! If you're new to Boost.Python, at this point it might be -a good idea to ignore build issues for a while and concentrate on -learning the library by going through the tutorial_ and perhaps -some of the `reference documentation`_, trying out what you've -learned about the API by modifying the quickstart project. - -.. _reference documentation: v2/reference.html -.. _tutorial: tutorial/index.html - -Modifying the Example Project ------------------------------ - -If you're content to keep your extension module forever in one -source file called |extending.cpp|_, inside your Boost -distribution, and import it forever as ``extending``, then you can -stop here. However, it's likely that you will want to make a few -changes. There are a few things you can do without having to learn -Boost.Build_ in depth. - -The project you just built is specified in two files in the current -directory: |boost-build.jam|_, which tells ``bjam`` where it can -find the interpreted code of the Boost build system, and -|Jamroot|_, which describes the targets you just built. These -files are heavily commented, so they should be easy to modify. -Take care, however, to preserve whitespace. Punctuation such as -``;`` will not be recognized as intended by ``bjam`` if it is not -surrounded by whitespace. - -.. |boost-build.jam| replace:: ``boost-build.jam`` -.. _boost-build.jam: ../example/quickstart/boost-build.jam - -.. |Jamroot| replace:: ``Jamroot`` -.. _Jamroot: ../example/quickstart/Jamroot - -.. |extending.cpp| replace:: ``extending.cpp`` -.. _extending.cpp: ../example/quickstart/extending.cpp - -Relocate the Project -.................... - -You'll probably want to copy this project elsewhere so you can -change it without modifying your Boost distribution. To do that, -simply - -a. copy the entire ``libs/python/example/quickstart/`` directory - into a new directory. - -b. In the new copies of |boost-build.jam|_ and |Jamroot|_, locate - the relative path near the top of the file that is clearly - marked by a comment, and edit that path so that it refers to the - same directory your Boost distribution as it referred to when - the file was in its original location in the - ``libs/python/example/quickstart/`` directory. - -For example, if you moved the project from -``/home/dave/boost_1_34_0/libs/python/example/quickstart`` to -``/home/dave/my-project``, you could change the first path in -|boost-build.jam|_ from - -.. parsed-literal:: - - **../../../..**\ /tools/build/v2 - -to - -.. parsed-literal:: - - **/home/dave/boost_1_34_0**\ /tools/build/v2 - -and change the first path in |Jamroot|_ from - -.. parsed-literal:: - - **../../../..** - -to - -.. parsed-literal:: - - **/home/dave/boost_1_34_0** - -Add New or Change Names of Existing Source Files -................................................ - -The names of additional source files involved in building your -extension module or embedding application can be listed in -|Jamroot|_ right alongside ``extending.cpp`` or ``embedding.cpp`` -respectively. Just be sure to leave whitespace around each -filename:: - - … file1.cpp file2.cpp file3.cpp … - -Naturally, if you want to change the name of a source file you can -tell Boost.Build about it by editing the name in |Jamroot|_. - -Change the Name of your Extension Module -........................................ - -The name of the extension module is determined by two things: - -1. the name in |Jamroot|_ immediately following ``python-extension``, and -2. the name passed to ``BOOST_PYTHON_MODULE`` in |extending.cpp|_. - -To change the name of the extension module from ``extending`` to -``hello``, you'd edit |Jamroot|_, changing - -.. parsed-literal:: - - python-extension **extending** : extending.cpp ; - -to - -.. parsed-literal:: - - python-extension **hello** : extending.cpp ; - -and you'd edit extending.cpp, changing - -.. parsed-literal:: - - BOOST_PYTHON_MODULE(\ **extending**\ ) - -to - -.. parsed-literal:: - - BOOST_PYTHON_MODULE(\ **hello**\ ) - -Installing Boost.Python on your System -====================================== - -Since Boost.Python is a separately-compiled (as opposed to -`header-only`_) library, its user relies on the services of a -Boost.Python library binary. - -.. _header-only: ../../../more/getting_started/windows.html#header-only-libraries - -If you need a regular installation of the Boost.Python library -binaries on your system, the Boost `Getting Started Guide`_ will -walk you through the steps of creating one. If building binaries -from source, you might want to supply the ``--with-python`` -argument to ``bjam`` (or the ``--with-libraries=python`` argument -to ``configure``), so only the Boost.Python binary will be built, -rather than all the Boost binaries. - - -Configuring Boost.Build -======================= - -As described in the `Boost.Build reference manual`__, a file called -``user-config.jam`` in your home directory [#home-dir]_ is used to -specify the tools and libraries available to the build system. You -may need to create or edit ``user-config.jam`` to tell Boost.Build -how to invoke Python, ``#include`` its headers, and link with its -libraries. - -__ http://www.boost.orgdoc/html/bbv2/advanced.html#bbv2.advanced.configuration - -.. Admonition:: Users of Unix-Variant OSes - - If you are using a unix-variant OS and you ran Boost's - ``configure`` script, it may have generated a - ``user-config.jam`` for you. [#overwrite]_ If your ``configure``\ - /\ ``make`` sequence was successful and Boost.Python binaries - were built, your ``user-config.jam`` file is probably already - correct. - -If you have one fairly “standard†python installation for your -platform, you might not need to do anything special to describe it. If -you haven't configured python in ``user-config.jam`` (and you don't -specify ``--without-python`` on the Boost.Build command line), -Boost.Build will automatically execute the equivalent of :: - - import toolset : using ; - using python ; - -which automatically looks for Python in the most likely places. -However, that only happens when using the Boost.Python project file -(e.g. when referred to by another project as in the quickstart_ -method). If instead you are linking against separately-compiled -Boost.Python binaries, you should set up a ``user-config.jam`` file -with at least the minimal incantation above. - -Python Configuration Parameters -------------------------------- - -If you have several versions of Python installed, or Python is -installed in an unusual way, you may want to supply any or all of -the following optional parameters to ``using python``. - -version - the version of Python to use. Should be in Major.Minor - format, for example, ``2.3``. Do not include the subminor - version (i.e. *not* ``2.5.1``). If you have multiple Python - versions installed, the version will usually be the only - configuration argument required. - -cmd-or-prefix - preferably, a command that invokes a Python interpreter. - Alternatively, the installation prefix for Python libraries and - header files. Only use the alternative formulation if there is - no appropriate Python executable available. - -includes - the ``#include`` paths for Python headers. Normally the correct - path(s) will be automatically deduced from ``version`` and/or - ``cmd-or-prefix``. - -libraries - the path to Python library binaries. On MacOS/Darwin, - you can also pass the path of the Python framework. Normally the - correct path(s) will be automatically deduced from ``version`` - and/or ``cmd-or-prefix``. - -condition - if specified, should be a set of Boost.Build - properties that are matched against the build configuration when - Boost.Build selects a Python configuration to use. See examples - below for details. - -extension-suffix - A string to append to the name of extension - modules before the true filename extension. You almost certainly - don't need to use this. Usually this suffix is only used when - targeting a Windows debug build of Python, and will be set - automatically for you based on the value of the - |python-debugging|_ feature. However, at least one Linux - distribution (Ubuntu Feisty Fawn) has a specially configured - `python-dbg`__ package that claims to use such a suffix. - -.. |python-debugging| replace:: ``<python-debugging>`` - -__ https://wiki.ubuntu.com/PyDbgBuilds - - -Examples --------- - -Note that in the examples below, case and *especially whitespace* are -significant. - -- If you have both python 2.5 and python 2.4 installed, - ``user-config.jam`` might contain:: - - using python : 2.5 ; # Make both versions of Python available - - using python : 2.4 ; # To build with python 2.4, add python=2.4 - # to your command line. - - The first version configured (2.5) becomes the default. To build - against python 2.4, add ``python=2.4`` to the ``bjam`` command line. - -- If you have python installed in an unusual location, you might - supply the path to the interpreter in the ``cmd-or-prefix`` - parameter:: - - using python : : /usr/local/python-2.6-beta/bin/python ; - -- If you have a separate build of Python for use with a particular - toolset, you might supply that toolset in the ``condition`` - parameter:: - - using python ; # use for most toolsets - - # Use with Intel C++ toolset - using python - : # version - : c:\\Devel\\Python-2.5-IntelBuild\\PCBuild\\python # cmd-or-prefix - : # includes - : # libraries - : <toolset>intel # condition - ; - - -- If you have downloaded the Python sources and built both the - normal and the “\ `python debugging`_\ †builds from source on - Windows, you might see:: - - using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python ; - using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python_d - : # includes - : # libs - : <python-debugging>on ; - -- You can set up your user-config.jam so a bjam built under Windows - can build/test both Windows and Cygwin_ python extensions. Just pass - ``<target-os>cygwin`` in the ``condition`` parameter - for the cygwin python installation:: - - # windows installation - using python ; - - # cygwin installation - using python : : c:\\cygwin\\bin\\python2.5 : : : <target-os>cygwin ; - - when you put target-os=cygwin in your build request, it should build - with the cygwin version of python: [#flavor]_ - - bjam target-os=cygwin toolset=gcc - - This is supposed to work the other way, too (targeting windows - python with a Cygwin_ bjam) but it seems as though the support in - Boost.Build's toolsets for building that way is broken at the - time of this writing. - -- Note that because of `the way Boost.Build currently selects target - alternatives`__, you might have be very explicit in your build - requests. For example, given:: - - using python : 2.5 ; # a regular windows build - using python : 2.4 : : : : <target-os>cygwin ; - - building with :: - - bjam target-os=cygwin - - will yield an error. Instead, you'll need to write:: - - bjam target-os=cygwin/python=2.4 - -.. _Cygwin: http://cygwin.com - -__ http://zigzag.cs.msu.su/boost.build/wiki/AlternativeSelection - -Choosing a Boost.Python Library Binary -====================================== - -If—instead of letting Boost.Build construct and link with the right -libraries automatically—you choose to use a pre-built Boost.Python -library, you'll need to think about which one to link with. The -Boost.Python binary comes in both static and dynamic flavors. Take -care to choose the right flavor for your application. [#naming]_ - -The Dynamic Binary ------------------- - -The dynamic library is the safest and most-versatile choice: - -- A single copy of the library code is used by all extension - modules built with a given toolset. [#toolset-specific]_ - -- The library contains a type conversion registry. Because one - registry is shared among all extension modules, instances of a - class exposed to Python in one dynamically-loaded extension - module can be passed to functions exposed in another such module. - -The Static Binary ------------------ - -It might be appropriate to use the static Boost.Python library in -any of the following cases: - -- You are extending_ python and the types exposed in your - dynamically-loaded extension module don't need to be used by any - other Boost.Python extension modules, and you don't care if the - core library code is duplicated among them. - -- You are embedding_ python in your application and either: - - - You are targeting a Unix variant OS other than MacOS or AIX, - where the dynamically-loaded extension modules can “see†the - Boost.Python library symbols that are part of the executable. - - - Or, you have statically linked some Boost.Python extension - modules into your application and you don't care if any - dynamically-loaded Boost.Python extension modules are able to - use the types exposed by your statically-linked extension - modules (and vice-versa). - -``#include`` Issues -=================== - -1. If you should ever have occasion to ``#include "python.h"`` - directly in a translation unit of a program using Boost.Python, - use ``#include "boost/python/detail/wrap_python.hpp"`` instead. - It handles several issues necessary for use with Boost.Python, - one of which is mentioned in the next section. - -2. Be sure not to ``#include`` any system headers before - ``wrap_python.hpp``. This restriction is actually imposed by - Python, or more properly, by Python's interaction with your - operating system. See - http://docs.python.org/ext/simpleExample.html for details. - -.. _python-debugging: -.. _python debugging: - -Python Debugging Builds -======================= - -Python can be built in a special “python debugging†configuration -that adds extra checks and instrumentation that can be very useful -for developers of extension modules. The data structures used by -the debugging configuration contain additional members, so **a -Python executable built with python debugging enabled cannot be -used with an extension module or library compiled without it, and -vice-versa.** - -Since pre-built “python debugging†versions of the Python -executable and libraries are not supplied with most distributions -of Python, [#get-debug-build]_ and we didn't want to force our users -to build them, Boost.Build does not automatically enable python -debugging in its ``debug`` build variant (which is the default). -Instead there is a special build property called -``python-debugging`` that, when used as a build property, will -define the right preprocessor symbols and select the right -libraries to link with. - -On unix-variant platforms, the debugging versions of Python's data -structures will only be used if the symbol ``Py_DEBUG`` is defined. -On many windows compilers, when extension modules are built with -the preprocessor symbol ``_DEBUG``, Python defaults to force -linking with a special debugging version of the Python DLL. Since -that symbol is very commonly used even when Python is not present, -Boost.Python temporarily undefines _DEBUG when Python.h -is #included from ``boost/python/detail/wrap_python.hpp`` - unless -``BOOST_DEBUG_PYTHON`` is defined. The upshot is that if you want -“python debuggingâ€and you aren't using Boost.Build, you should make -sure ``BOOST_DEBUG_PYTHON`` is defined, or python debugging will be -suppressed. - -Testing Boost.Python -==================== - -To run the full test suite for Boost.Python, invoke ``bjam`` in the -``libs/python/test`` subdirectory of your Boost distribution. - -Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users -======================================================= - -If you are using a version of Python prior to 2.4.1 with a MinGW -prior to 3.0.0 (with binutils-2.13.90-20030111-1), you will need to -create a MinGW-compatible version of the Python library; the one -shipped with Python will only work with a Microsoft-compatible -linker. Follow the instructions in the “Non-Microsoft†section of -the “Building Extensions: Tips And Tricks†chapter in `Installing -Python Modules`__ to create ``libpythonXX.a``, where ``XX`` -corresponds to the major and minor version numbers of your Python -installation. - -__ http://www.python.org/doc/current/inst/index.html - ------------------------------ - -.. [#2.2] Note that although we tested earlier versions of - Boost.Python with Python 2.2, and we don't *think* we've done - anything to break compatibility, this release of Boost.Python - may not have been tested with versions of Python earlier than - 2.4, so we're not 100% sure that python 2.2 and 2.3 are - supported. - -.. [#naming] Information about how to identify the - static and dynamic builds of Boost.Python: - - * `on Windows`__ - * `on Unix variants`__ - - __ ../../../more/getting_started/windows.html#library-naming - __ ../../../more/getting_started/unix-variants.html#library-naming - -.. [#toolset-specific] Because of the way most \*nix platforms - share symbols among dynamically-loaded objects, I'm not certain - that extension modules built with different compiler toolsets - will always use different copies of the Boost.Python library - when loaded into the same Python instance. Not using different - libraries could be a good thing if the compilers have compatible - ABIs, because extension modules built with the two libraries - would be interoperable. Otherwise, it could spell disaster, - since an extension module and the Boost.Python library would - have different ideas of such things as class layout. I would - appreciate someone doing the experiment to find out what - happens. - -.. [#overwrite] ``configure`` overwrites the existing - ``user-config.jam`` in your home directory - (if any) after making a backup of the old version. - -.. [#flavor] Note that the ``<target-os>cygwin`` feature is - different from the ``<flavor>cygwin`` subfeature of the ``gcc`` - toolset, and you might need handle both explicitly if you also - have a MinGW GCC installed. - -.. [#home-dir] Windows users, your home directory can be - found by typing:: - - ECHO %HOMEDRIVE%%HOMEPATH% - - into a `command prompt`_ window. - -.. [#get-debug-build] On Unix and similar platforms, a debugging - python and associated libraries are built by adding - ``--with-pydebug`` when configuring the Python build. On - Windows, the debugging version of Python is generated by - the "Win32 Debug" target of the Visual Studio project in the - PCBuild subdirectory of a full Python source code distribution. diff --git a/libs/python/doc/configuration.qbk b/libs/python/doc/configuration.qbk new file mode 100644 index 0000000000..49b97de072 --- /dev/null +++ b/libs/python/doc/configuration.qbk @@ -0,0 +1,83 @@ +[chapter Configuration + [quickbook 1.7] + [authors [Abrahams, David]] + [copyright 2002 - 2015 David Abrahams, Stefan Seefeld] + [id configuration] +] + + +[section Configuration] + +[section 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. + +[endsect] +[section Application Defined Macros] + +These are the macros that may be defined by an application using Boost.Python. Note that if you extend a strict interpretation of the C++ standard to cover dynamic libraries, using different values of these macros when compiling different libraries (including extension modules and the Boost.Python library itself) is a violation of the [link odr ODR]. However, we know of no C++ implementations on which this particular violation is detectable or causes any problems. + +[table + [[Macro][Default][Meaning]] + [[BOOST_PYTHON_MAX_ARITY] + [15] + [The maximum arity of any function, member function, + or constructor to be wrapped, invocation of a + Boost.Python function wich is specified as taking + arguments x1, x2,...Xn. This includes, in particular, + callback mechanisms such as object::operator()(...) or call_method<R>(... ).]] + [[BOOST_PYTHON_MAX_BASES][10] + [The maximum number of template arguments to the + `bases<...>` class template, which is used to specify + the bases of a wrapped C++ class..]] + [[BOOST_PYTHON_STATIC_MODULE] + [ /not defined/ ] + [If defined, prevents your module initialization + function from being treated as an exported symbol + on platforms which support that distinction in-code]] + [[BOOST_PYTHON_ENABLE_CDECL] + [ /not defined/ ] + [If defined, allows functions using the `__cdecl` + calling convention to be wrapped.]] + [[BOOST_PYTHON_ENABLE_STDCALL] + [ /not defined/ ] + [If defined, allows functions using the `__stdcall` + calling convention to be wrapped.]] + [[BOOST_PYTHON_ENABLE_FASTCALL] + [ /not defined/ ] + [If defined, allows functions using the `__fastcall` + calling convention to be wrapped.]] +] +[endsect] +[section Library Defined Defined Macros] +These macros are defined by *Boost.Python* and are implementation details of interest only to implementors and those porting to new platforms. +[table + [[Macro][Default][Meaning]] + [[BOOST_PYTHON_TYPE_ID_NAME][ /not defined/ ] + [If defined, this indicates that the type_info comparison across + shared library boundaries does not work on this platform. + In other words, if shared-lib-1 passes `typeid(T)` to a function + in shared-lib-2 which compares it to `typeid(T)`, that comparison + may return `false`. If this macro is #defined, Boost.Python uses + and compares `typeid(T).name()` instead of using and comparing + the `std::type_info` objects directly.]] + [[BOOST_PYTHON_NO_PY_SIGNATURES][ /not defined/ ] + [If defined for a module no pythonic signatures are generated for + the docstrings of the module functions, and no python type is + associated with any of the converters registered by the module. + This also reduces the binary size of the module by about 14% + (gcc compiled). + If defined for the boost_python runtime library, the default for + the `docstring_options.enable_py_signatures()` is set to `false`.]] + [[BOOST_PYTHON_SUPPORTS_PY_SIGNATURES] + [ /defined/ if `BOOST_PYTHON_NO_PY_SIGNATURES` is /undefined/ ] + [This macro is defined to enable a smooth transition from older + Boost.Python versions which do not support pythonic signatures. + For example usage see here.]] + [[BOOST_PYTHON_PY_SIGNATURES_PROPER_INIT_SELF_TYPE][ /not defined/ ] + [If defined the python type of `__init__` method "self" parameters + is properly generated, otherwise object is used. It is undefined by + default because it increases the binary size of the module by about + 14% (gcc compiled).]] +] +[endsect] +[endsect] diff --git a/libs/python/doc/faq.qbk b/libs/python/doc/faq.qbk new file mode 100644 index 0000000000..fce67dce0a --- /dev/null +++ b/libs/python/doc/faq.qbk @@ -0,0 +1,736 @@ +[chapter Frequently Asked Questions (FAQs) + [quickbook 1.7] + [id faq] +] + +[section How can I wrap a function which takes a function pointer as an argument?] + +If what you're trying to do is something like this: +`` + typedef boost::function<void (string s) > funcptr; + + void foo(funcptr fp) + { + fp("hello,world!"); + } + + BOOST_PYTHON_MODULE(test) + { + def("foo",foo); + } +`` + +And then: + +`` +>>> def hello(s): +... print s +... +>>> foo(hello) +hello, world! +`` +The short answer is: "you can't". This is not a +Boost.Python limitation so much as a limitation of C++. The +problem is that a Python function is actually data, and the only +way of associating data with a C++ function pointer is to store it +in a static variable of the function. The problem with that is +that you can only associate one piece of data with every C++ +function, and we have no way of compiling a new C++ function +on-the-fly for every Python function you decide to pass +to `foo`. In other words, this could work if the C++ +function is always going to invoke the /same/ Python +function, but you probably don't want that. + +If you have the luxury of changing the C++ code you're +wrapping, pass it an `object` instead and call that; +the overloaded function call operator will invoke the Python +function you pass it behind the `object`. + +[endsect] +[section I'm getting the "attempt to return dangling reference" error. + What am I doing wrong?] + +That exception is protecting you from causing a nasty crash. It usually +happens in response to some code like this: +`` + period const &get_floating_frequency() const + { + return boost::python::call_method<period const &>( + m_self,"get_floating_frequency"); + } +`` +And you get: +`` + ReferenceError: Attempt to return dangling reference to object of type: + class period +`` + +In this case, the Python method invoked by `call_method` +constructs a new Python object. You're trying to return a reference to a +C++ object (an instance of `class period`) contained within +and owned by that Python object. Because the called method handed back a +brand new object, the only reference to it is held for the duration of +`get_floating_frequency()` above. When the function returns, +the Python object will be destroyed, destroying the instance of +`class period`, and leaving the returned reference dangling. +That's already undefined behavior, and if you try to do anything with +that reference you're likely to cause a crash. Boost.Python detects this +situation at runtime and helpfully throws an exception instead of letting +you do that. + +[endsect] +[section Is `return_internal_reference` efficient?] + +[*Q:] /I have an object composed of 12 doubles. A `const&` to +this object is returned by a member function of another class. From the +viewpoint of using the returned object in Python I do not care if I get +a copy or a reference to the returned object. In Boost.Python I have the +choice of using `copy_const_reference` or `return_internal_reference`. +Are there considerations that would lead me to prefer one over the other, +such as size of generated code or memory overhead?/ + +[*A:] `copy_const_reference` will make an instance with storage +for one of your objects, `size = base_size + 12 * sizeof(double)`. +`return_internal_reference` will make an instance with storage for a +pointer to one of your objects, `size = base_size + sizeof(void*)`. +However, it will also create a weak reference object which goes in the +source object's weakreflist and a special callback object to manage the +lifetime of the internally-referenced object. My guess? +`copy_const_reference` is your friend here, resulting in less overall +memory use and less fragmentation, also probably fewer total +cycles. + +[endsect] +[section How can I wrap functions which take C++ containers as arguments?] + +Ralf W. Grosse-Kunstleve provides these notes: + +# Using the regular `class_<>` wrapper: + `` + class_<std::vector<double> >("std_vector_double") + .def(...) + ... + ; + `` + This can be moved to a template so that several types (`double`, `int`, + `long`, etc.) can be wrapped with the same code. This technique is used + in the file `scitbx/include/scitbx/array_family/boost_python/flex_wrapper.h` + in the "scitbx" package. The file could easily be modified for + wrapping `std::vector<>` instantiations. + This type of C++/Python binding is most suitable for containers + that may contain a large number of elements (>10000). + +# Using custom rvalue converters. Boost.Python "rvalue converters" + match function signatures such as: + `` + void foo(std::vector<double> const &array); // pass by const-reference + void foo(std::vector<double> array); // pass by value + `` + Some custom rvalue converters are implemented in the file + `scitbx/include/scitbx/boost_python/container_conversions.h` + This code can be used to convert from C++ container types such as + `std::vector<>` or `std::list<>` to Python tuples and vice + versa. A few simple examples can be found in the file + `scitbx/array_family/boost_python/regression_test_module.cpp` + Automatic C++ container <-> Python tuple conversions are most + suitable for containers of moderate size. These converters generate + significantly less object code compared to alternative 1 above. + +A disadvantage of using alternative 2 is that operators such as +arithmetic +,-,*,/,% are not available. It would be useful to have custom +rvalue converters that convert to a "math_array" type instead of tuples. +This is currently not implemented but is possible within the framework of +Boost.Python V2 as it will be released in the next couple of weeks. [ed.: +this was posted on 2002/03/10] + +It would also be useful to also have "custom lvalue converters" such +as `std::vector<>` <-> Python list. These converters would +support the modification of the Python list from C++. For example: + +C++: +`` + void foo(std::vector<double> &array) + { + for(std::size_t i=0;i<array.size();i++) { + array[i] *= 2; + } + } +`` +Python: [python] +`` + >>> l = [1, 2, 3] + >>> foo(l) + >>> print l + [2, 4, 6] +`` +Custom lvalue converters require changes to the Boost.Python core library +and are currently not available. + +P.S.: + +The "scitbx" files referenced above are available via anonymous +CVS: +`` + cvs -d:pserver:anonymous@cvs.cctbx.sourceforge.net:/cvsroot/cctbx login + cvs -d:pserver:anonymous@cvs.cctbx.sourceforge.net:/cvsroot/cctbx co scitbx +`` + +[endsect] +[section fatal error C1204:Compiler limit:internal structure overflow] + +[*Q:] /I get this error message when compiling a large source file. What can I do?/ + +[*A:] You have two choices: + +# Upgrade your compiler (preferred) + +# Break your source file up into multiple translation units. + + `my_module.cpp`: [c++] + + `` + ... + void more_of_my_module(); + BOOST_PYTHON_MODULE(my_module) + { + def("foo", foo); + def("bar", bar); + ... + more_of_my_module(); + } + `` + `more_of_my_module.cpp`: + `` + void more_of_my_module() + { + def("baz", baz); + ... + } + `` + If you find that a `class_<...>` declaration + can't fit in a single source file without triggering the error, you + can always pass a reference to the `class_` object to a + function in another source file, and call some of its member + functions (e.g. `.def(...)`) in the auxilliary source + file: + + `more_of_my_class.cpp`: + `` + void more_of_my_class(class<my_class>& x) + { + x + .def("baz", baz) + .add_property("xx", &my_class::get_xx, &my_class::set_xx) + ; + ... + } + `` + +[endsect] +[section How do I debug my Python extensions?] + +Greg Burley gives the following answer for Unix GCC users: + +[:Once you have created a boost python extension for your c++ library or + class, you may need to debug the code. Afterall this is one of the + reasons for wrapping the library in python. An expected side-effect or + benefit of using BPL is that debugging should be isolated to the c++ + library that is under test, given that python code is minimal and + boost::python either works or it doesn't. (ie. While errors can occur + when the wrapping method is invalid, most errors are caught by the + compiler ;-). + + The basic steps required to initiate a gdb session to debug a c++ + library via python are shown here. Note, however that you should start + the gdb session in the directory that contains your BPL my_ext.so + module. + + `` + (gdb) target exec python + (gdb) run + >>> from my_ext import * + >>> [C-c] + (gdb) break MyClass::MyBuggyFunction + (gdb) cont + >>> pyobj = MyClass() + >>> pyobj.MyBuggyFunction() + Breakpoint 1, MyClass::MyBuggyFunction ... + Current language: auto; currently c++ + (gdb) do debugging stuff + `` +] + +Greg's approach works even better using Emacs' "gdb" +command, since it will show you each line of source as you step through it. + +On *Windows*, my favorite debugging solution is the debugger that +comes with Microsoft Visual C++ 7. This debugger seems to work with code +generated by all versions of Microsoft and Metrowerks toolsets; it's rock +solid and "just works" without requiring any special tricks from the +user. + +Raoul Gough has provided the following for gdb on Windows: + +[:gdb support for Windows DLLs has improved lately, so it is + now possible to debug Python extensions using a few + tricks. Firstly, you will need an up-to-date gdb with support + for minimal symbol extraction from a DLL. Any gdb from version 6 + onwards, or Cygwin gdb-20030214-1 and onwards should do. A + suitable release will have a section in the gdb.info file under + Configuration - Native - Cygwin Native - + Non-debug DLL symbols. Refer to that info section for more + details of the procedures outlined here. + + Secondly, it seems necessary to set a breakpoint in the + Python interpreter, rather than using ^C to break execution. A + good place to set this breakpoint is PyOS_Readline, which will + stop execution immediately before reading each interactive + Python command. You have to let Python start once under the + debugger, so that it loads its own DLL, before you can set the + breakpoint: + + `` + $ gdb python + GNU gdb 2003-09-02-cvs (cygwin-special) + [...] + + (gdb) run + Starting program: /cygdrive/c/Python22/python.exe + Python 2.2.2 (#37, Oct 14 2002, 17:02:34) [MSC 32 bit (Intel)] on win32 + Type "help", "copyright", "credits" or "license" for more information. + >>> ^Z + + + Program exited normally. + (gdb) break *&PyOS_Readline + Breakpoint 1 at 0x1e04eff0 + (gdb) run + Starting program: /cygdrive/c/Python22/python.exe + Python 2.2.2 (#37, Oct 14 2002, 17:02:34) [MSC 32 bit (Intel)] on win32 + Type "help", "copyright", "credits" or "license" for more information. + + Breakpoint 1, 0x1e04eff0 in python22!PyOS_Readline () + from /cygdrive/c/WINNT/system32/python22.dll + (gdb) cont + Continuing. + >>> from my_ext import * + + Breakpoint 1, 0x1e04eff0 in python22!PyOS_Readline () + from /cygdrive/c/WINNT/system32/python22.dll + (gdb) # my_ext now loaded (with any debugging symbols it contains) + `` +] + +[h2 Debugging extensions through Boost.Build] + +If you are launching your extension module tests with _bb_ using the +`boost-python-runtest` rule, you can ask it to launch your +debugger for you by adding "--debugger=/debugger/" to your bjam +command-line: +`` + bjam -sTOOLS=vc7.1 "--debugger=devenv /debugexe" test + bjam -sTOOLS=gcc -sPYTHON_LAUNCH=gdb test +`` +It can also be extremely useful to add the `-d+2` option when +you run your test, because Boost.Build will then show you the exact +commands it uses to invoke it. This will invariably involve setting up +PYTHONPATH and other important environment variables such as +LD_LIBRARY_PATH which may be needed by your debugger in order to get +things to work right. + +[endsect] +[section Why doesn't my `*=` operator work?] + +[*Q:] ['I have exported my class to python, with many overloaded +operators. it works fine for me except the `*=` +operator. It always tells me "can't multiply sequence with non int +type". If I use `p1.__imul__(p2)` instead of +`p1 *= p2`, it successfully executes my code. What's +wrong with me?] + +[*A:] There's nothing wrong with you. This is a bug in Python + 2.2. You can see the same effect in Pure Python (you can learn a lot + about what's happening in Boost.Python by playing with new-style + classes in Pure Python). +`` +>>> class X(object): +... def __imul__(self, x): +... print 'imul' +... +>>> x = X() +>>> x *= 1 +`` +To cure this problem, all you need to do is upgrade your Python to +version 2.2.1 or later. + +[endsect] +[section Does Boost.Python work with Mac OS X?] + +It is known to work under 10.2.8 and 10.3 using +Apple's gcc 3.3 compiler: +``gcc (GCC) 3.3 20030304 (Apple Computer, Inc. build 1493)`` +Under 10.2.8 get the August 2003 gcc update (free at [@http://connect.apple.com]). +Under 10.3 get the Xcode Tools v1.0 (also free). + +Python 2.3 is required. The Python that ships with 10.3 is +fine. Under 10.2.8 use these commands to install Python +as a framework: +``./configure --enable-framework +make +make frameworkinstall`` + +The last command requires root privileges because the target +directory is `/Library/Frameworks/Python.framework/Versions/2.3`. +However, the installation does not interfere with the Python +version that ships with 10.2.8. + +It is also crucial to increase the `stacksize` before +starting compilations, e.g.: +``limit stacksize 8192k`` +If the `stacksize` is too small the build might crash with +internal compiler errors. + +Sometimes Apple's compiler exhibits a bug by printing an error +like the following while compiling a +`boost::python::class_<your_type>` +template instantiation: +`` + .../inheritance.hpp:44: error: cannot + dynamic_cast `p' (of type `struct cctbx::boost_python::<unnamed>::add_pair* + ') to type `void*' (source type is not polymorphic) +`` + +We do not know a general workaround, but if the definition of +`your_type` can be modified the following was found +to work in all cases encountered so far: +`` + struct your_type + { + // before defining any member data + #if defined(__MACH__) && defined(__APPLE_CC__) && __APPLE_CC__ == 1493 + bool dummy_; + #endif + // now your member data, e.g. + double x; + int j; + // etc. + }; +`` +[endsect] +[section How can I find the existing PyObject that holds a C++ object?] + +[: "I am wrapping a function that always returns a pointer to an + already-held C++ object."] + +One way to do that is to hijack the mechanisms used for wrapping a class +with virtual functions. If you make a wrapper class with an initial +PyObject* constructor argument and store that PyObject* as "self", you +can get back to it by casting down to that wrapper type in a thin wrapper +function. For example: +`` + class X { X(int); virtual ~X(); ... }; + X* f(); // known to return Xs that are managed by Python objects + + + // wrapping code + + struct X_wrap : X + { + X_wrap(PyObject* self, int v) : self(self), X(v) {} + PyObject* self; + }; + + handle<> f_wrap() + { + X_wrap* xw = dynamic_cast<X_wrap*>(f()); + assert(xw != 0); + return handle<>(borrowed(xw->self)); + } + + ... + + def("f", f_wrap()); + class_<X,X_wrap,boost::noncopyable>("X", init<int>()) + ... + ; +`` + +Of course, if X has no virtual functions you'll have to use +`static_cast` instead of `dynamic_cast` with no +runtime check that it's valid. This approach also only works if the +`X` object was constructed from Python, because +`X`\ s constructed from C++ are of course never +`X_wrap` objects. + +Another approach to this requires you to change your C++ code a bit; +if that's an option for you it might be a better way to go. work we've +been meaning to get to anyway. When a `shared_ptr<X>` is +converted from Python, the shared_ptr actually manages a reference to the +containing Python object. When a shared_ptr<X> is converted back to +Python, the library checks to see if it's one of those "Python object +managers" and if so just returns the original Python object. So you could +just write `object(p)` to get the Python object back. To +exploit this you'd have to be able to change the C++ code you're wrapping +so that it deals with shared_ptr instead of raw pointers. + +There are other approaches too. The functions that receive the Python +object that you eventually want to return could be wrapped with a thin +wrapper that records the correspondence between the object address and +its containing Python object, and you could have your f_wrap function +look in that mapping to get the Python object out. + +[endsect] +[section How can I wrap a function which needs to take ownership of a raw pointer?] + +[*Q:] Part of an API that I'm wrapping goes something like this: + +`` + struct A {}; struct B { void add( A* ); } + where B::add() takes ownership of the pointer passed to it. +`` + +However: + +`` + a = mod.A() + b = mod.B() + b.add( a ) + del a + del b + # python interpreter crashes + # later due to memory corruption. +`` + +Even binding the lifetime of a to b via `with_custodian_and_ward` doesn't prevent +the python object a from ultimately trying to delete the object it's pointing to. +Is there a way to accomplish a 'transfer-of-ownership' of a wrapped C++ object? + +--Bruce Lowery + +Yes: Make sure the C++ object is held by auto_ptr: +`` + class_<A, std::auto_ptr<A> >("A") + ... + ; +`` +Then make a thin wrapper function which takes an auto_ptr parameter: +`` + void b_insert(B &b, std::auto_ptr<A> a) + { + b.insert(a.get()); + a.release(); + } +`` +Wrap that as B.add. Note that pointers returned via `manage_new_object` +will also be held by `auto_ptr`, so this transfer-of-ownership +will also work correctly. + +[endsect] +[section Compilation takes too much time and eats too much memory! + What can I do to make it faster?] + +Please refer to the `Reducing Compiling Time` section in the _tutorial_. + +[endsect] +[section How do I create sub-packages using Boost.Python?] + +Please refer to the `Creating Packages` section in the _tutorial_. + +[endsect] +[section error C2064: term does not evaluate to a function taking 2 arguments] + +/Niall Douglas provides these notes:/ + +If you see Microsoft Visual C++ 7.1 (MS Visual Studio .NET 2003) issue +an error message like the following it is most likely due to a bug +in the compiler: +`` + boost\boost\python\detail\invoke.hpp(76): + error C2064: term does not evaluate to a function taking 2 arguments" +`` +This message is triggered by code like the following: +`` + #include <boost/python.hpp> + + using namespace boost::python; + + class FXThread + { + public: + bool setAutoDelete(bool doso) throw(); + }; + + void Export_FXThread() + { + class_< FXThread >("FXThread") + .def("setAutoDelete", &FXThread::setAutoDelete) + ; + } +`` +The bug is related to the `throw()` modifier. +As a workaround cast off the modifier. E.g.: +`` + .def("setAutoDelete", (bool (FXThread::*)(bool)) &FXThread::setAutoDelete) +`` +(The bug has been reported to Microsoft.) + +[endsect] +[section How can I automatically convert my custom string type to and from a Python string?] + +/Ralf W. Grosse-Kunstleve provides these notes:/ + +Below is a small, self-contained demo extension module that shows +how to do this. Here is the corresponding trivial test: +`` + import custom_string + assert custom_string.hello() == "Hello world." + assert custom_string.size("california") == 10 +`` +If you look at the code you will find: + +* A custom `to_python` converter (easy): + `custom_string_to_python_str` + +*A custom lvalue converter (needs more code): + `custom_string_from_python_str` + +The custom converters are registered in the global Boost.Python +registry near the top of the module initialization function. Once +flow control has passed through the registration code the automatic +conversions from and to Python strings will work in any module +imported in the same process. + +`` + #include <boost/python/module.hpp> + #include <boost/python/def.hpp> + #include <boost/python/to_python_converter.hpp> + + namespace sandbox { namespace { + + class custom_string + { + public: + custom_string() {} + custom_string(std::string const &value) : value_(value) {} + std::string const &value() const { return value_; } + private: + std::string value_; + }; + + struct custom_string_to_python_str + { + static PyObject* convert(custom_string const &s) + { + return boost::python::incref(boost::python::object(s.value()).ptr()); + } + }; + + struct custom_string_from_python_str + { + custom_string_from_python_str() + { + boost::python::converter::registry::push_back( + &convertible, + &construct, + boost::python::type_id<custom_string>()); + } + + static void* convertible(PyObject* obj_ptr) + { + if (!PyString_Check(obj_ptr)) return 0; + return obj_ptr; + } + + static void construct( + PyObject* obj_ptr, + boost::python::converter::rvalue_from_python_stage1_data* data) + { + const char* value = PyString_AsString(obj_ptr); + if (value == 0) boost::python::throw_error_already_set(); + void* storage = ( + (boost::python::converter::rvalue_from_python_storage<custom_string>*) + data)->storage.bytes; + new (storage) custom_string(value); + data->convertible = storage; + } + }; + + custom_string hello() { return custom_string("Hello world."); } + + std::size_t size(custom_string const &s) { return s.value().size(); } + + void init_module() + { + using namespace boost::python; + + boost::python::to_python_converter< + custom_string, + custom_string_to_python_str>(); + + custom_string_from_python_str(); + + def("hello", hello); + def("size", size); + } + + }} // namespace sandbox::<anonymous> + + BOOST_PYTHON_MODULE(custom_string) + { + sandbox::init_module(); + } +`` +[endsect] +[section Why is my automatic to-python conversion not being found?] + +/Niall Douglas provides these notes:/ + +If you define custom converters similar to the ones +shown above the `def_readonly()` and `def_readwrite()` +member functions provided by `boost::python::class_` for +direct access to your member data will not work as expected. +This is because `def_readonly("bar",&foo::bar)` is +equivalent to: + +`` + .add_property("bar", make_getter(&foo::bar, return_internal_reference())) +`` +Similarly, `def_readwrite("bar",&foo::bar)` is +equivalent to: + +`` + .add_property("bar", make_getter(&foo::bar, return_internal_reference()), + make_setter(&foo::bar, return_internal_reference()) +`` +In order to define return value policies compatible with the +custom conversions replace `def_readonly()` and +`def_readwrite()` by `add_property()`. E.g.: + +`` + .add_property("bar", make_getter(&foo::bar, return_value_policy<return_by_value>()), + make_setter(&foo::bar, return_value_policy<return_by_value>())) +`` + +[endsect] +[section Is Boost.Python thread-aware/compatible with multiple interpreters?] + +/Niall Douglas provides these notes:/ + +The quick answer to this is: no. + +The longer answer is that it can be patched to be so, but it's +complex. You will need to add custom lock/unlock wrapping of every +time your code enters Boost.Python (particularly every virtual +function override) plus heavily modify +`boost/python/detail/invoke.hpp` with custom unlock/lock +wrapping of every time Boost.Python enters your code. You must +furthermore take care to /not/ unlock/lock when Boost.Python +is invoking iterator changes via `invoke.hpp`. + +There is a patched `invoke.hpp` posted on the C++-SIG +mailing list archives and you can find a real implementation of all +the machinery necessary to fully implement this in the TnFOX +project at [@http://sourceforge.net/projects/tnfox/ this] +SourceForge project location. + +[endsect]
\ No newline at end of file diff --git a/libs/python/doc/glossary.qbk b/libs/python/doc/glossary.qbk new file mode 100644 index 0000000000..eaea9709f3 --- /dev/null +++ b/libs/python/doc/glossary.qbk @@ -0,0 +1,38 @@ +[chapter Glossary + [quickbook 1.7] + [id glossary] +] + +[variablelist +[[arity [#arity]] + [The number of argumnts accepted by a function or member function. + Unless otherwise specified, the hidden `this` argument to member + functions is not counted when specifying arity.]] +[[ntbs [#ntbs]] + [Null-Terminated Byte String, or 'C'-string. C++ string literals are *ntbs*\ es. + An *ntbs* must never be null.]] +[[raise [#raise]] + [Exceptions in Python are "raised", not "thrown", as they are in C++. + When this documentation says that some Python exception is "raised" in + the context of C++ code, it means that the corresponding Python exception + is set via the [@http://www.python.org/doc/current/api/exceptionHandling.html Python/'C' API], + and `throw_error_already_set()` is called.]] +[[POD [#pod]] + [A technical term from the C++ standard. Short for "Plain Ol'Data": + A POD-struct is an aggregate class that has no non-static data members + of type pointer to member, non-POD-struct, non-POD-union (or array of such + types) or reference, and has no user-defined copy assign- ment operator and + no user-defined destructor. Similarly, a POD-union is an aggregate union that + has no non-static data members of type pointer to member, non-POD-struct, + non-POD-union (or array of such types) or reference, and has no + user-defined copy assignment operator and no user-defined destructor. A + POD class is a class that is either a POD-struct or a POD-union. An + aggregate is an array or a class (clause 9) with no user-declared + constructors (12.1), no private or protected non-static data members + (clause 11), no base classes (clause 10), and no virtual functions + (10.3).]] +[[ODR [#odr]] + [The "One Definition Rule", which says that any entity in a C++ program must have + the same definition in all translation units (object files) which make up a program.]] +] + diff --git a/libs/python/doc/html/article.html b/libs/python/doc/html/article.html new file mode 100644 index 0000000000..2a70bac826 --- /dev/null +++ b/libs/python/doc/html/article.html @@ -0,0 +1,929 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" /> +<title>Building Hybrid Systems with Boost.Python</title> +<meta name="author" content="David Abrahams" /> +<meta name="organization" content="Boost Consulting" /> +<meta name="date" content="2003-05-14" /> +<meta name="author" content="Ralf W. Grosse-Kunstleve" /> +<meta name="copyright" content="Copyright David Abrahams and Ralf W. Grosse-Kunstleve 2003. All rights reserved" /> +<link rel="stylesheet" href="rst.css" type="text/css" /> +</head> +<body> +<div class="document" id="building-hybrid-systems-with-boost-python"> +<h1 class="title">Building Hybrid Systems with Boost.Python</h1> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Author:</th> +<td>David Abrahams</td></tr> +<tr><th class="docinfo-name">Contact:</th> +<td><a class="first last reference external" href="mailto:dave@boost-consulting.com">dave@boost-consulting.com</a></td></tr> +<tr><th class="docinfo-name">Organization:</th> +<td><a class="first last reference external" href="http://www.boost-consulting.com">Boost Consulting</a></td></tr> +<tr><th class="docinfo-name">Date:</th> +<td>2003-05-14</td></tr> +<tr><th class="docinfo-name">Author:</th> +<td>Ralf W. Grosse-Kunstleve</td></tr> +<tr><th class="docinfo-name">Copyright:</th> +<td>Copyright David Abrahams and Ralf W. Grosse-Kunstleve 2003. All rights reserved</td></tr> +</tbody> +</table> +<div class="contents topic" id="table-of-contents"> +<p class="topic-title first">Table of Contents</p> +<ul class="simple"> +<li><a class="reference internal" href="#abstract" id="id5">Abstract</a></li> +<li><a class="reference internal" href="#introduction" id="id6">Introduction</a></li> +<li><a class="reference internal" href="#boost-python-design-goals" id="id7">Boost.Python Design Goals</a></li> +<li><a class="reference internal" href="#hello-boost-python-world" id="id8">Hello Boost.Python World</a></li> +<li><a class="reference internal" href="#library-overview" id="id9">Library Overview</a><ul> +<li><a class="reference internal" href="#exposing-classes" id="id10">Exposing Classes</a><ul> +<li><a class="reference internal" href="#constructors" id="id11">Constructors</a></li> +<li><a class="reference internal" href="#data-members-and-properties" id="id12">Data Members and Properties</a></li> +<li><a class="reference internal" href="#operator-overloading" id="id13">Operator Overloading</a></li> +<li><a class="reference internal" href="#inheritance" id="id14">Inheritance</a></li> +<li><a class="reference internal" href="#virtual-functions" id="id15">Virtual Functions</a></li> +<li><a class="reference internal" href="#deeper-reflection-on-the-horizon" id="id16">Deeper Reflection on the Horizon?</a></li> +</ul> +</li> +<li><a class="reference internal" href="#serialization" id="id17">Serialization</a></li> +<li><a class="reference internal" href="#object-interface" id="id18">Object interface</a></li> +</ul> +</li> +<li><a class="reference internal" href="#thinking-hybrid" id="id19">Thinking hybrid</a></li> +<li><a class="reference internal" href="#development-history" id="id20">Development history</a></li> +<li><a class="reference internal" href="#conclusions" id="id21">Conclusions</a></li> +<li><a class="reference internal" href="#citations" id="id22">Citations</a></li> +<li><a class="reference internal" href="#footnotes" id="id23">Footnotes</a></li> +</ul> +</div> +<div class="section" id="abstract"> +<h1><a class="toc-backref" href="#id5">Abstract</a></h1> +<p>Boost.Python is an open source C++ library which provides a concise +IDL-like interface for binding C++ classes and functions to +Python. Leveraging the full power of C++ compile-time introspection +and of recently developed metaprogramming techniques, this is achieved +entirely in pure C++, without introducing a new syntax. +Boost.Python's rich set of features and high-level interface make it +possible to engineer packages from the ground up as hybrid systems, +giving programmers easy and coherent access to both the efficient +compile-time polymorphism of C++ and the extremely convenient run-time +polymorphism of Python.</p> +</div> +<div class="section" id="introduction"> +<h1><a class="toc-backref" href="#id6">Introduction</a></h1> +<p>Python and C++ are in many ways as different as two languages could +be: while C++ is usually compiled to machine-code, Python is +interpreted. Python's dynamic type system is often cited as the +foundation of its flexibility, while in C++ static typing is the +cornerstone of its efficiency. C++ has an intricate and difficult +compile-time meta-language, while in Python, practically everything +happens at runtime.</p> +<p>Yet for many programmers, these very differences mean that Python and +C++ complement one another perfectly. Performance bottlenecks in +Python programs can be rewritten in C++ for maximal speed, and +authors of powerful C++ libraries choose Python as a middleware +language for its flexible system integration capabilities. +Furthermore, the surface differences mask some strong similarities:</p> +<ul class="simple"> +<li>'C'-family control structures (if, while, for...)</li> +<li>Support for object-orientation, functional programming, and generic +programming (these are both <em>multi-paradigm</em> programming languages.)</li> +<li>Comprehensive operator overloading facilities, recognizing the +importance of syntactic variability for readability and +expressivity.</li> +<li>High-level concepts such as collections and iterators.</li> +<li>High-level encapsulation facilities (C++: namespaces, Python: modules) +to support the design of re-usable libraries.</li> +<li>Exception-handling for effective management of error conditions.</li> +<li>C++ idioms in common use, such as handle/body classes and +reference-counted smart pointers mirror Python reference semantics.</li> +</ul> +<p>Given Python's rich 'C' interoperability API, it should in principle +be possible to expose C++ type and function interfaces to Python with +an analogous interface to their C++ counterparts. However, the +facilities provided by Python alone for integration with C++ are +relatively meager. Compared to C++ and Python, 'C' has only very +rudimentary abstraction facilities, and support for exception-handling +is completely missing. 'C' extension module writers are required to +manually manage Python reference counts, which is both annoyingly +tedious and extremely error-prone. Traditional extension modules also +tend to contain a great deal of boilerplate code repetition which +makes them difficult to maintain, especially when wrapping an evolving +API.</p> +<p>These limitations have lead to the development of a variety of wrapping +systems. <a class="reference external" href="http://www.swig.org/">SWIG</a> is probably the most popular package for the +integration of C/C++ and Python. A more recent development is <a class="reference external" href="http://www.riverbankcomputing.co.uk/sip/index.php">SIP</a>, +which was specifically designed for interfacing Python with the <a class="reference external" href="http://www.trolltech.com/">Qt</a> +graphical user interface library. Both SWIG and SIP introduce their +own specialized languages for customizing inter-language bindings. +This has certain advantages, but having to deal with three different +languages (Python, C/C++ and the interface language) also introduces +practical and mental difficulties. The <a class="reference external" href="http://cxx.sourceforge.net/">CXX</a> package demonstrates an +interesting alternative. It shows that at least some parts of +Python's 'C' API can be wrapped and presented through a much more +user-friendly C++ interface. However, unlike SWIG and SIP, CXX does +not include support for wrapping C++ classes as new Python types.</p> +<p>The features and goals of <a class="reference external" href="http://www.boost.org/libs/python/doc">Boost.Python</a> overlap significantly with +many of these other systems. That said, Boost.Python attempts to +maximize convenience and flexibility without introducing a separate +wrapping language. Instead, it presents the user with a high-level +C++ interface for wrapping C++ classes and functions, managing much of +the complexity behind-the-scenes with static metaprogramming. +Boost.Python also goes beyond the scope of earlier systems by +providing:</p> +<ul class="simple"> +<li>Support for C++ virtual functions that can be overridden in Python.</li> +<li>Comprehensive lifetime management facilities for low-level C++ +pointers and references.</li> +<li>Support for organizing extensions as Python packages, +with a central registry for inter-language type conversions.</li> +<li>A safe and convenient mechanism for tying into Python's powerful +serialization engine (pickle).</li> +<li>Coherence with the rules for handling C++ lvalues and rvalues that +can only come from a deep understanding of both the Python and C++ +type systems.</li> +</ul> +<p>The key insight that sparked the development of Boost.Python is that +much of the boilerplate code in traditional extension modules could be +eliminated using C++ compile-time introspection. Each argument of a +wrapped C++ function must be extracted from a Python object using a +procedure that depends on the argument type. Similarly the function's +return type determines how the return value will be converted from C++ +to Python. Of course argument and return types are part of each +function's type, and this is exactly the source from which +Boost.Python deduces most of the information required.</p> +<p>This approach leads to <em>user guided wrapping</em>: as much information is +extracted directly from the source code to be wrapped as is possible +within the framework of pure C++, and some additional information is +supplied explicitly by the user. Mostly the guidance is mechanical +and little real intervention is required. Because the interface +specification is written in the same full-featured language as the +code being exposed, the user has unprecedented power available when +she does need to take control.</p> +</div> +<div class="section" id="boost-python-design-goals"> +<h1><a class="toc-backref" href="#id7">Boost.Python Design Goals</a></h1> +<p>The primary goal of Boost.Python is to allow users to expose C++ +classes and functions to Python using nothing more than a C++ +compiler. In broad strokes, the user experience should be one of +directly manipulating C++ objects from Python.</p> +<p>However, it's also important not to translate all interfaces <em>too</em> +literally: the idioms of each language must be respected. For +example, though C++ and Python both have an iterator concept, they are +expressed very differently. Boost.Python has to be able to bridge the +interface gap.</p> +<p>It must be possible to insulate Python users from crashes resulting +from trivial misuses of C++ interfaces, such as accessing +already-deleted objects. By the same token the library should +insulate C++ users from low-level Python 'C' API, replacing +error-prone 'C' interfaces like manual reference-count management and +raw <tt class="docutils literal">PyObject</tt> pointers with more-robust alternatives.</p> +<p>Support for component-based development is crucial, so that C++ types +exposed in one extension module can be passed to functions exposed in +another without loss of crucial information like C++ inheritance +relationships.</p> +<p>Finally, all wrapping must be <em>non-intrusive</em>, without modifying or +even seeing the original C++ source code. Existing C++ libraries have +to be wrappable by third parties who only have access to header files +and binaries.</p> +</div> +<div class="section" id="hello-boost-python-world"> +<h1><a class="toc-backref" href="#id8">Hello Boost.Python World</a></h1> +<p>And now for a preview of Boost.Python, and how it improves on the raw +facilities offered by Python. Here's a function we might want to +expose:</p> +<pre class="literal-block"> +char const* greet(unsigned x) +{ + static char const* const msgs[] = { "hello", "Boost.Python", "world!" }; + + if (x > 2) + throw std::range_error("greet: index out of range"); + + return msgs[x]; +} +</pre> +<p>To wrap this function in standard C++ using the Python 'C' API, we'd +need something like this:</p> +<pre class="literal-block"> +extern "C" // all Python interactions use 'C' linkage and calling convention +{ + // Wrapper to handle argument/result conversion and checking + PyObject* greet_wrap(PyObject* args, PyObject * keywords) + { + int x; + if (PyArg_ParseTuple(args, "i", &x)) // extract/check arguments + { + char const* result = greet(x); // invoke wrapped function + return PyString_FromString(result); // convert result to Python + } + return 0; // error occurred + } + + // Table of wrapped functions to be exposed by the module + static PyMethodDef methods[] = { + { "greet", greet_wrap, METH_VARARGS, "return one of 3 parts of a greeting" } + , { NULL, NULL, 0, NULL } // sentinel + }; + + // module initialization function + DL_EXPORT init_hello() + { + (void) Py_InitModule("hello", methods); // add the methods to the module + } +} +</pre> +<p>Now here's the wrapping code we'd use to expose it with Boost.Python:</p> +<pre class="literal-block"> +#include <boost/python.hpp> +using namespace boost::python; +BOOST_PYTHON_MODULE(hello) +{ + def("greet", greet, "return one of 3 parts of a greeting"); +} +</pre> +<p>and here it is in action:</p> +<pre class="literal-block"> +>>> import hello +>>> for x in range(3): +... print hello.greet(x) +... +hello +Boost.Python +world! +</pre> +<p>Aside from the fact that the 'C' API version is much more verbose, +it's worth noting a few things that it doesn't handle correctly:</p> +<ul class="simple"> +<li>The original function accepts an unsigned integer, and the Python +'C' API only gives us a way of extracting signed integers. The +Boost.Python version will raise a Python exception if we try to pass +a negative number to <tt class="docutils literal">hello.greet</tt>, but the other one will proceed +to do whatever the C++ implementation does when converting an +negative integer to unsigned (usually wrapping to some very large +number), and pass the incorrect translation on to the wrapped +function.</li> +<li>That brings us to the second problem: if the C++ <tt class="docutils literal">greet()</tt> +function is called with a number greater than 2, it will throw an +exception. Typically, if a C++ exception propagates across the +boundary with code generated by a 'C' compiler, it will cause a +crash. As you can see in the first version, there's no C++ +scaffolding there to prevent this from happening. Functions wrapped +by Boost.Python automatically include an exception-handling layer +which protects Python users by translating unhandled C++ exceptions +into a corresponding Python exception.</li> +<li>A slightly more-subtle limitation is that the argument conversion +used in the Python 'C' API case can only get that integer <tt class="docutils literal">x</tt> in +<em>one way</em>. PyArg_ParseTuple can't convert Python <tt class="docutils literal">long</tt> objects +(arbitrary-precision integers) which happen to fit in an <tt class="docutils literal">unsigned +int</tt> but not in a <tt class="docutils literal">signed long</tt>, nor will it ever handle a +wrapped C++ class with a user-defined implicit <tt class="docutils literal">operator unsigned +int()</tt> conversion. Boost.Python's dynamic type conversion +registry allows users to add arbitrary conversion methods.</li> +</ul> +</div> +<div class="section" id="library-overview"> +<h1><a class="toc-backref" href="#id9">Library Overview</a></h1> +<p>This section outlines some of the library's major features. Except as +neccessary to avoid confusion, details of library implementation are +omitted.</p> +<div class="section" id="exposing-classes"> +<h2><a class="toc-backref" href="#id10">Exposing Classes</a></h2> +<p>C++ classes and structs are exposed with a similarly-terse interface. +Given:</p> +<pre class="literal-block"> +struct World +{ + void set(std::string msg) { this->msg = msg; } + std::string greet() { return msg; } + std::string msg; +}; +</pre> +<p>The following code will expose it in our extension module:</p> +<pre class="literal-block"> +#include <boost/python.hpp> +BOOST_PYTHON_MODULE(hello) +{ + class_<World>("World") + .def("greet", &World::greet) + .def("set", &World::set) + ; +} +</pre> +<p>Although this code has a certain pythonic familiarity, people +sometimes find the syntax bit confusing because it doesn't look like +most of the C++ code they're used to. All the same, this is just +standard C++. Because of their flexible syntax and operator +overloading, C++ and Python are great for defining domain-specific +(sub)languages +(DSLs), and that's what we've done in Boost.Python. To break it down:</p> +<pre class="literal-block"> +class_<World>("World") +</pre> +<p>constructs an unnamed object of type <tt class="docutils literal">class_<World></tt> and passes +<tt class="docutils literal">"World"</tt> to its constructor. This creates a new-style Python class +called <tt class="docutils literal">World</tt> in the extension module, and associates it with the +C++ type <tt class="docutils literal">World</tt> in the Boost.Python type conversion registry. We +might have also written:</p> +<pre class="literal-block"> +class_<World> w("World"); +</pre> +<p>but that would've been more verbose, since we'd have to name <tt class="docutils literal">w</tt> +again to invoke its <tt class="docutils literal">def()</tt> member function:</p> +<pre class="literal-block"> +w.def("greet", &World::greet) +</pre> +<p>There's nothing special about the location of the dot for member +access in the original example: C++ allows any amount of whitespace on +either side of a token, and placing the dot at the beginning of each +line allows us to chain as many successive calls to member functions +as we like with a uniform syntax. The other key fact that allows +chaining is that <tt class="docutils literal">class_<></tt> member functions all return a reference +to <tt class="docutils literal">*this</tt>.</p> +<p>So the example is equivalent to:</p> +<pre class="literal-block"> +class_<World> w("World"); +w.def("greet", &World::greet); +w.def("set", &World::set); +</pre> +<p>It's occasionally useful to be able to break down the components of a +Boost.Python class wrapper in this way, but the rest of this article +will stick to the terse syntax.</p> +<p>For completeness, here's the wrapped class in use:</p> +<pre class="literal-block"> +>>> import hello +>>> planet = hello.World() +>>> planet.set('howdy') +>>> planet.greet() +'howdy' +</pre> +<div class="section" id="constructors"> +<h3><a class="toc-backref" href="#id11">Constructors</a></h3> +<p>Since our <tt class="docutils literal">World</tt> class is just a plain <tt class="docutils literal">struct</tt>, it has an +implicit no-argument (nullary) constructor. Boost.Python exposes the +nullary constructor by default, which is why we were able to write:</p> +<pre class="literal-block"> +>>> planet = hello.World() +</pre> +<p>However, well-designed classes in any language may require constructor +arguments in order to establish their invariants. Unlike Python, +where <tt class="docutils literal">__init__</tt> is just a specially-named method, In C++ +constructors cannot be handled like ordinary member functions. In +particular, we can't take their address: <tt class="docutils literal"><span class="pre">&World::World</span></tt> is an +error. The library provides a different interface for specifying +constructors. Given:</p> +<pre class="literal-block"> +struct World +{ + World(std::string msg); // added constructor + ... +</pre> +<p>we can modify our wrapping code as follows:</p> +<pre class="literal-block"> +class_<World>("World", init<std::string>()) + ... +</pre> +<p>of course, a C++ class may have additional constructors, and we can +expose those as well by passing more instances of <tt class="docutils literal"><span class="pre">init<...></span></tt> to +<tt class="docutils literal">def()</tt>:</p> +<pre class="literal-block"> +class_<World>("World", init<std::string>()) + .def(init<double, double>()) + ... +</pre> +<p>Boost.Python allows wrapped functions, member functions, and +constructors to be overloaded to mirror C++ overloading.</p> +</div> +<div class="section" id="data-members-and-properties"> +<h3><a class="toc-backref" href="#id12">Data Members and Properties</a></h3> +<p>Any publicly-accessible data members in a C++ class can be easily +exposed as either <tt class="docutils literal">readonly</tt> or <tt class="docutils literal">readwrite</tt> attributes:</p> +<pre class="literal-block"> +class_<World>("World", init<std::string>()) + .def_readonly("msg", &World::msg) + ... +</pre> +<p>and can be used directly in Python:</p> +<pre class="literal-block"> +>>> planet = hello.World('howdy') +>>> planet.msg +'howdy' +</pre> +<p>This does <em>not</em> result in adding attributes to the <tt class="docutils literal">World</tt> instance +<tt class="docutils literal">__dict__</tt>, which can result in substantial memory savings when +wrapping large data structures. In fact, no instance <tt class="docutils literal">__dict__</tt> +will be created at all unless attributes are explicitly added from +Python. Boost.Python owes this capability to the new Python 2.2 type +system, in particular the descriptor interface and <tt class="docutils literal">property</tt> type.</p> +<p>In C++, publicly-accessible data members are considered a sign of poor +design because they break encapsulation, and style guides usually +dictate the use of "getter" and "setter" functions instead. In +Python, however, <tt class="docutils literal">__getattr__</tt>, <tt class="docutils literal">__setattr__</tt>, and since 2.2, +<tt class="docutils literal">property</tt> mean that attribute access is just one more +well-encapsulated syntactic tool at the programmer's disposal. +Boost.Python bridges this idiomatic gap by making Python <tt class="docutils literal">property</tt> +creation directly available to users. If <tt class="docutils literal">msg</tt> were private, we +could still expose it as attribute in Python as follows:</p> +<pre class="literal-block"> +class_<World>("World", init<std::string>()) + .add_property("msg", &World::greet, &World::set) + ... +</pre> +<p>The example above mirrors the familiar usage of properties in Python +2.2+:</p> +<pre class="literal-block"> +>>> class World(object): +... __init__(self, msg): +... self.__msg = msg +... def greet(self): +... return self.__msg +... def set(self, msg): +... self.__msg = msg +... msg = property(greet, set) +</pre> +</div> +<div class="section" id="operator-overloading"> +<h3><a class="toc-backref" href="#id13">Operator Overloading</a></h3> +<p>The ability to write arithmetic operators for user-defined types has +been a major factor in the success of both languages for numerical +computation, and the success of packages like <a class="reference external" href="http://www.pfdubois.com/numpy/">NumPy</a> attests to the +power of exposing operators in extension modules. Boost.Python +provides a concise mechanism for wrapping operator overloads. The +example below shows a fragment from a wrapper for the Boost rational +number library:</p> +<pre class="literal-block"> +class_<rational<int> >("rational_int") + .def(init<int, int>()) // constructor, e.g. rational_int(3,4) + .def("numerator", &rational<int>::numerator) + .def("denominator", &rational<int>::denominator) + .def(-self) // __neg__ (unary minus) + .def(self + self) // __add__ (homogeneous) + .def(self * self) // __mul__ + .def(self + int()) // __add__ (heterogenous) + .def(int() + self) // __radd__ + ... +</pre> +<p>The magic is performed using a simplified application of "expression +templates" <a class="citation-reference" href="#veld1995" id="id1">[VELD1995]</a>, a technique originally developed for +optimization of high-performance matrix algebra expressions. The +essence is that instead of performing the computation immediately, +operators are overloaded to construct a type <em>representing</em> the +computation. In matrix algebra, dramatic optimizations are often +available when the structure of an entire expression can be taken into +account, rather than evaluating each operation "greedily". +Boost.Python uses the same technique to build an appropriate Python +method object based on expressions involving <tt class="docutils literal">self</tt>.</p> +</div> +<div class="section" id="inheritance"> +<h3><a class="toc-backref" href="#id14">Inheritance</a></h3> +<p>C++ inheritance relationships can be represented to Boost.Python by adding +an optional <tt class="docutils literal"><span class="pre">bases<...></span></tt> argument to the <tt class="docutils literal"><span class="pre">class_<...></span></tt> template +parameter list as follows:</p> +<pre class="literal-block"> +class_<Derived, bases<Base1,Base2> >("Derived") + ... +</pre> +<p>This has two effects:</p> +<ol class="arabic simple"> +<li>When the <tt class="docutils literal"><span class="pre">class_<...></span></tt> is created, Python type objects +corresponding to <tt class="docutils literal">Base1</tt> and <tt class="docutils literal">Base2</tt> are looked up in +Boost.Python's registry, and are used as bases for the new Python +<tt class="docutils literal">Derived</tt> type object, so methods exposed for the Python <tt class="docutils literal">Base1</tt> +and <tt class="docutils literal">Base2</tt> types are automatically members of the <tt class="docutils literal">Derived</tt> +type. Because the registry is global, this works correctly even if +<tt class="docutils literal">Derived</tt> is exposed in a different module from either of its +bases.</li> +<li>C++ conversions from <tt class="docutils literal">Derived</tt> to its bases are added to the +Boost.Python registry. Thus wrapped C++ methods expecting (a +pointer or reference to) an object of either base type can be +called with an object wrapping a <tt class="docutils literal">Derived</tt> instance. Wrapped +member functions of class <tt class="docutils literal">T</tt> are treated as though they have an +implicit first argument of <tt class="docutils literal">T&</tt>, so these conversions are +neccessary to allow the base class methods to be called for derived +objects.</li> +</ol> +<p>Of course it's possible to derive new Python classes from wrapped C++ +class instances. Because Boost.Python uses the new-style class +system, that works very much as for the Python built-in types. There +is one significant detail in which it differs: the built-in types +generally establish their invariants in their <tt class="docutils literal">__new__</tt> function, so +that derived classes do not need to call <tt class="docutils literal">__init__</tt> on the base +class before invoking its methods :</p> +<pre class="literal-block"> +>>> class L(list): +... def __init__(self): +... pass +... +>>> L().reverse() +>>> +</pre> +<p>Because C++ object construction is a one-step operation, C++ instance +data cannot be constructed until the arguments are available, in the +<tt class="docutils literal">__init__</tt> function:</p> +<pre class="literal-block"> +>>> class D(SomeBoostPythonClass): +... def __init__(self): +... pass +... +>>> D().some_boost_python_method() +Traceback (most recent call last): + File "<stdin>", line 1, in ? +TypeError: bad argument type for built-in operation +</pre> +<p>This happened because Boost.Python couldn't find instance data of type +<tt class="docutils literal">SomeBoostPythonClass</tt> within the <tt class="docutils literal">D</tt> instance; <tt class="docutils literal">D</tt>'s <tt class="docutils literal">__init__</tt> +function masked construction of the base class. It could be corrected +by either removing <tt class="docutils literal">D</tt>'s <tt class="docutils literal">__init__</tt> function or having it call +<tt class="docutils literal"><span class="pre">SomeBoostPythonClass.__init__(...)</span></tt> explicitly.</p> +</div> +<div class="section" id="virtual-functions"> +<h3><a class="toc-backref" href="#id15">Virtual Functions</a></h3> +<p>Deriving new types in Python from extension classes is not very +interesting unless they can be used polymorphically from C++. In +other words, Python method implementations should appear to override +the implementation of C++ virtual functions when called <em>through base +class pointers/references from C++</em>. Since the only way to alter the +behavior of a virtual function is to override it in a derived class, +the user must build a special derived class to dispatch a polymorphic +class' virtual functions:</p> +<pre class="literal-block"> +// +// interface to wrap: +// +class Base +{ + public: + virtual int f(std::string x) { return 42; } + virtual ~Base(); +}; + +int calls_f(Base const& b, std::string x) { return b.f(x); } + +// +// Wrapping Code +// + +// Dispatcher class +struct BaseWrap : Base +{ + // Store a pointer to the Python object + BaseWrap(PyObject* self_) : self(self_) {} + PyObject* self; + + // Default implementation, for when f is not overridden + int f_default(std::string x) { return this->Base::f(x); } + // Dispatch implementation + int f(std::string x) { return call_method<int>(self, "f", x); } +}; + +... + def("calls_f", calls_f); + class_<Base, BaseWrap>("Base") + .def("f", &Base::f, &BaseWrap::f_default) + ; +</pre> +<p>Now here's some Python code which demonstrates:</p> +<pre class="literal-block"> +>>> class Derived(Base): +... def f(self, s): +... return len(s) +... +>>> calls_f(Base(), 'foo') +42 +>>> calls_f(Derived(), 'forty-two') +9 +</pre> +<p>Things to notice about the dispatcher class:</p> +<ul class="simple"> +<li>The key element which allows overriding in Python is the +<tt class="docutils literal">call_method</tt> invocation, which uses the same global type +conversion registry as the C++ function wrapping does to convert its +arguments from C++ to Python and its return type from Python to C++.</li> +<li>Any constructor signatures you wish to wrap must be replicated with +an initial <tt class="docutils literal">PyObject*</tt> argument</li> +<li>The dispatcher must store this argument so that it can be used to +invoke <tt class="docutils literal">call_method</tt></li> +<li>The <tt class="docutils literal">f_default</tt> member function is needed when the function being +exposed is not pure virtual; there's no other way <tt class="docutils literal"><span class="pre">Base::f</span></tt> can be +called on an object of type <tt class="docutils literal">BaseWrap</tt>, since it overrides <tt class="docutils literal">f</tt>.</li> +</ul> +</div> +<div class="section" id="deeper-reflection-on-the-horizon"> +<h3><a class="toc-backref" href="#id16">Deeper Reflection on the Horizon?</a></h3> +<p>Admittedly, this formula is tedious to repeat, especially on a project +with many polymorphic classes. That it is neccessary reflects some +limitations in C++'s compile-time introspection capabilities: there's +no way to enumerate the members of a class and find out which are +virtual functions. At least one very promising project has been +started to write a front-end which can generate these dispatchers (and +other wrapping code) automatically from C++ headers.</p> +<p><a class="reference external" href="http://www.boost.org/libs/python/pyste">Pyste</a> is being developed by Bruno da Silva de Oliveira. It builds on +<a class="reference external" href="http://www.gccxml.org/HTML/Index.html">GCC_XML</a>, which generates an XML version of GCC's internal program +representation. Since GCC is a highly-conformant C++ compiler, this +ensures correct handling of the most-sophisticated template code and +full access to the underlying type system. In keeping with the +Boost.Python philosophy, a Pyste interface description is neither +intrusive on the code being wrapped, nor expressed in some unfamiliar +language: instead it is a 100% pure Python script. If Pyste is +successful it will mark a move away from wrapping everything directly +in C++ for many of our users. It will also allow us the choice to +shift some of the metaprogram code from C++ to Python. We expect that +soon, not only our users but the Boost.Python developers themselves +will be "thinking hybrid" about their own code.</p> +</div> +</div> +<div class="section" id="serialization"> +<h2><a class="toc-backref" href="#id17">Serialization</a></h2> +<p><em>Serialization</em> is the process of converting objects in memory to a +form that can be stored on disk or sent over a network connection. The +serialized object (most often a plain string) can be retrieved and +converted back to the original object. A good serialization system will +automatically convert entire object hierarchies. Python's standard +<tt class="docutils literal">pickle</tt> module is just such a system. It leverages the language's strong +runtime introspection facilities for serializing practically arbitrary +user-defined objects. With a few simple and unintrusive provisions this +powerful machinery can be extended to also work for wrapped C++ objects. +Here is an example:</p> +<pre class="literal-block"> +#include <string> + +struct World +{ + World(std::string a_msg) : msg(a_msg) {} + std::string greet() const { return msg; } + std::string msg; +}; + +#include <boost/python.hpp> +using namespace boost::python; + +struct World_picklers : pickle_suite +{ + static tuple + getinitargs(World const& w) { return make_tuple(w.greet()); } +}; + +BOOST_PYTHON_MODULE(hello) +{ + class_<World>("World", init<std::string>()) + .def("greet", &World::greet) + .def_pickle(World_picklers()) + ; +} +</pre> +<p>Now let's create a <tt class="docutils literal">World</tt> object and put it to rest on disk:</p> +<pre class="literal-block"> +>>> import hello +>>> import pickle +>>> a_world = hello.World("howdy") +>>> pickle.dump(a_world, open("my_world", "w")) +</pre> +<p>In a potentially <em>different script</em> on a potentially <em>different +computer</em> with a potentially <em>different operating system</em>:</p> +<pre class="literal-block"> +>>> import pickle +>>> resurrected_world = pickle.load(open("my_world", "r")) +>>> resurrected_world.greet() +'howdy' +</pre> +<p>Of course the <tt class="docutils literal">cPickle</tt> module can also be used for faster +processing.</p> +<p>Boost.Python's <tt class="docutils literal">pickle_suite</tt> fully supports the <tt class="docutils literal">pickle</tt> protocol +defined in the standard Python documentation. Like a __getinitargs__ +function in Python, the pickle_suite's getinitargs() is responsible for +creating the argument tuple that will be use to reconstruct the pickled +object. The other elements of the Python pickling protocol, +__getstate__ and __setstate__ can be optionally provided via C++ +getstate and setstate functions. C++'s static type system allows the +library to ensure at compile-time that nonsensical combinations of +functions (e.g. getstate without setstate) are not used.</p> +<p>Enabling serialization of more complex C++ objects requires a little +more work than is shown in the example above. Fortunately the +<tt class="docutils literal">object</tt> interface (see next section) greatly helps in keeping the +code manageable.</p> +</div> +<div class="section" id="object-interface"> +<h2><a class="toc-backref" href="#id18">Object interface</a></h2> +<p>Experienced 'C' language extension module authors will be familiar +with the ubiquitous <tt class="docutils literal">PyObject*</tt>, manual reference-counting, and the +need to remember which API calls return "new" (owned) references or +"borrowed" (raw) references. These constraints are not just +cumbersome but also a major source of errors, especially in the +presence of exceptions.</p> +<p>Boost.Python provides a class <tt class="docutils literal">object</tt> which automates reference +counting and provides conversion to Python from C++ objects of +arbitrary type. This significantly reduces the learning effort for +prospective extension module writers.</p> +<p>Creating an <tt class="docutils literal">object</tt> from any other type is extremely simple:</p> +<pre class="literal-block"> +object s("hello, world"); // s manages a Python string +</pre> +<p><tt class="docutils literal">object</tt> has templated interactions with all other types, with +automatic to-python conversions. It happens so naturally that it's +easily overlooked:</p> +<pre class="literal-block"> +object ten_Os = 10 * s[4]; // -> "oooooooooo" +</pre> +<p>In the example above, <tt class="docutils literal">4</tt> and <tt class="docutils literal">10</tt> are converted to Python objects +before the indexing and multiplication operations are invoked.</p> +<p>The <tt class="docutils literal">extract<T></tt> class template can be used to convert Python objects +to C++ types:</p> +<pre class="literal-block"> +double x = extract<double>(o); +</pre> +<p>If a conversion in either direction cannot be performed, an +appropriate exception is thrown at runtime.</p> +<p>The <tt class="docutils literal">object</tt> type is accompanied by a set of derived types +that mirror the Python built-in types such as <tt class="docutils literal">list</tt>, <tt class="docutils literal">dict</tt>, +<tt class="docutils literal">tuple</tt>, etc. as much as possible. This enables convenient +manipulation of these high-level types from C++:</p> +<pre class="literal-block"> +dict d; +d["some"] = "thing"; +d["lucky_number"] = 13; +list l = d.keys(); +</pre> +<p>This almost looks and works like regular Python code, but it is pure +C++. Of course we can wrap C++ functions which accept or return +<tt class="docutils literal">object</tt> instances.</p> +</div> +</div> +<div class="section" id="thinking-hybrid"> +<h1><a class="toc-backref" href="#id19">Thinking hybrid</a></h1> +<p>Because of the practical and mental difficulties of combining +programming languages, it is common to settle a single language at the +outset of any development effort. For many applications, performance +considerations dictate the use of a compiled language for the core +algorithms. Unfortunately, due to the complexity of the static type +system, the price we pay for runtime performance is often a +significant increase in development time. Experience shows that +writing maintainable C++ code usually takes longer and requires <em>far</em> +more hard-earned working experience than developing comparable Python +code. Even when developers are comfortable working exclusively in +compiled languages, they often augment their systems by some type of +ad hoc scripting layer for the benefit of their users without ever +availing themselves of the same advantages.</p> +<p>Boost.Python enables us to <em>think hybrid</em>. Python can be used for +rapidly prototyping a new application; its ease of use and the large +pool of standard libraries give us a head start on the way to a +working system. If necessary, the working code can be used to +discover rate-limiting hotspots. To maximize performance these can +be reimplemented in C++, together with the Boost.Python bindings +needed to tie them back into the existing higher-level procedure.</p> +<p>Of course, this <em>top-down</em> approach is less attractive if it is clear +from the start that many algorithms will eventually have to be +implemented in C++. Fortunately Boost.Python also enables us to +pursue a <em>bottom-up</em> approach. We have used this approach very +successfully in the development of a toolbox for scientific +applications. The toolbox started out mainly as a library of C++ +classes with Boost.Python bindings, and for a while the growth was +mainly concentrated on the C++ parts. However, as the toolbox is +becoming more complete, more and more newly added functionality can be +implemented in Python.</p> +<img alt="images/python_cpp_mix.png" src="images/python_cpp_mix.png" /> +<p>This figure shows the estimated ratio of newly added C++ and Python +code over time as new algorithms are implemented. We expect this +ratio to level out near 70% Python. Being able to solve new problems +mostly in Python rather than a more difficult statically typed +language is the return on our investment in Boost.Python. The ability +to access all of our code from Python allows a broader group of +developers to use it in the rapid development of new applications.</p> +</div> +<div class="section" id="development-history"> +<h1><a class="toc-backref" href="#id20">Development history</a></h1> +<p>The first version of Boost.Python was developed in 2000 by Dave +Abrahams at Dragon Systems, where he was privileged to have Tim Peters +as a guide to "The Zen of Python". One of Dave's jobs was to develop +a Python-based natural language processing system. Since it was +eventually going to be targeting embedded hardware, it was always +assumed that the compute-intensive core would be rewritten in C++ to +optimize speed and memory footprint<a class="footnote-reference" href="#proto" id="id2"><sup>1</sup></a>. The project also wanted to +test all of its C++ code using Python test scripts<a class="footnote-reference" href="#test" id="id3"><sup>2</sup></a>. The only +tool we knew of for binding C++ and Python was <a class="reference external" href="http://www.swig.org/">SWIG</a>, and at the time +its handling of C++ was weak. It would be false to claim any deep +insight into the possible advantages of Boost.Python's approach at +this point. Dave's interest and expertise in fancy C++ template +tricks had just reached the point where he could do some real damage, +and Boost.Python emerged as it did because it filled a need and +because it seemed like a cool thing to try.</p> +<p>This early version was aimed at many of the same basic goals we've +described in this paper, differing most-noticeably by having a +slightly more cumbersome syntax and by lack of special support for +operator overloading, pickling, and component-based development. +These last three features were quickly added by Ullrich Koethe and +Ralf Grosse-Kunstleve<a class="footnote-reference" href="#feature" id="id4"><sup>3</sup></a>, and other enthusiastic contributors arrived +on the scene to contribute enhancements like support for nested +modules and static member functions.</p> +<p>By early 2001 development had stabilized and few new features were +being added, however a disturbing new fact came to light: Ralf had +begun testing Boost.Python on pre-release versions of a compiler using +the <a class="reference external" href="http://www.edg.com">EDG</a> front-end, and the mechanism at the core of Boost.Python +responsible for handling conversions between Python and C++ types was +failing to compile. As it turned out, we had been exploiting a very +common bug in the implementation of all the C++ compilers we had +tested. We knew that as C++ compilers rapidly became more +standards-compliant, the library would begin failing on more +platforms. Unfortunately, because the mechanism was so central to the +functioning of the library, fixing the problem looked very difficult.</p> +<p>Fortunately, later that year Lawrence Berkeley and later Lawrence +Livermore National labs contracted with <a class="reference external" href="http://www.boost-consulting.com">Boost Consulting</a> for support +and development of Boost.Python, and there was a new opportunity to +address fundamental issues and ensure a future for the library. A +redesign effort began with the low level type conversion architecture, +building in standards-compliance and support for component-based +development (in contrast to version 1 where conversions had to be +explicitly imported and exported across module boundaries). A new +analysis of the relationship between the Python and C++ objects was +done, resulting in more intuitive handling for C++ lvalues and +rvalues.</p> +<p>The emergence of a powerful new type system in Python 2.2 made the +choice of whether to maintain compatibility with Python 1.5.2 easy: +the opportunity to throw away a great deal of elaborate code for +emulating classic Python classes alone was too good to pass up. In +addition, Python iterators and descriptors provided crucial and +elegant tools for representing similar C++ constructs. The +development of the generalized <tt class="docutils literal">object</tt> interface allowed us to +further shield C++ programmers from the dangers and syntactic burdens +of the Python 'C' API. A great number of other features including C++ +exception translation, improved support for overloaded functions, and +most significantly, CallPolicies for handling pointers and +references, were added during this period.</p> +<p>In October 2002, version 2 of Boost.Python was released. Development +since then has concentrated on improved support for C++ runtime +polymorphism and smart pointers. Peter Dimov's ingenious +<tt class="docutils literal"><span class="pre">boost::shared_ptr</span></tt> design in particular has allowed us to give the +hybrid developer a consistent interface for moving objects back and +forth across the language barrier without loss of information. At +first, we were concerned that the sophistication and complexity of the +Boost.Python v2 implementation might discourage contributors, but the +emergence of <a class="reference external" href="http://www.boost.org/libs/python/pyste">Pyste</a> and several other significant feature +contributions have laid those fears to rest. Daily questions on the +Python C++-sig and a backlog of desired improvements show that the +library is getting used. To us, the future looks bright.</p> +</div> +<div class="section" id="conclusions"> +<h1><a class="toc-backref" href="#id21">Conclusions</a></h1> +<p>Boost.Python achieves seamless interoperability between two rich and +complimentary language environments. Because it leverages template +metaprogramming to introspect about types and functions, the user +never has to learn a third syntax: the interface definitions are +written in concise and maintainable C++. Also, the wrapping system +doesn't have to parse C++ headers or represent the type system: the +compiler does that work for us.</p> +<p>Computationally intensive tasks play to the strengths of C++ and are +often impossible to implement efficiently in pure Python, while jobs +like serialization that are trivial in Python can be very difficult in +pure C++. Given the luxury of building a hybrid software system from +the ground up, we can approach design with new confidence and power.</p> +</div> +<div class="section" id="citations"> +<h1><a class="toc-backref" href="#id22">Citations</a></h1> +<table class="docutils citation" frame="void" id="veld1995" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id1">[VELD1995]</a></td><td>T. Veldhuizen, "Expression Templates," C++ Report, +Vol. 7 No. 5 June 1995, pp. 26-31. +<a class="reference external" href="http://osl.iu.edu/~tveldhui/papers/Expression-Templates/exprtmpl.html">http://osl.iu.edu/~tveldhui/papers/Expression-Templates/exprtmpl.html</a></td></tr> +</tbody> +</table> +</div> +<div class="section" id="footnotes"> +<h1><a class="toc-backref" href="#id23">Footnotes</a></h1> +<table class="docutils footnote" frame="void" id="proto" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>In retrospect, it seems that "thinking hybrid" from the +ground up might have been better for the NLP system: the +natural component boundaries defined by the pure python +prototype turned out to be inappropriate for getting the +desired performance and memory footprint out of the C++ core, +which eventually caused some redesign overhead on the Python +side when the core was moved to C++.</td></tr> +</tbody> +</table> +<table class="docutils footnote" frame="void" id="test" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id3">[2]</a></td><td>We also have some reservations about driving all C++ +testing through a Python interface, unless that's the only way +it will be ultimately used. Any transition across language +boundaries with such different object models can inevitably +mask bugs.</td></tr> +</tbody> +</table> +<table class="docutils footnote" frame="void" id="feature" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id4">[3]</a></td><td>These features were expressed very differently in v1 of +Boost.Python</td></tr> +</tbody> +</table> +</div> +</div> +</body> +</html> diff --git a/libs/python/doc/html/boost.css b/libs/python/doc/html/boost.css new file mode 100644 index 0000000000..986c4050fa --- /dev/null +++ b/libs/python/doc/html/boost.css @@ -0,0 +1,66 @@ +/*============================================================================= + Copyright 2002 William E. Kempf + Distributed under the Boost Software License, Version 1.0. (See accompany- + ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +=============================================================================*/ + +H1 +{ + FONT-SIZE: 200%; + COLOR: #00008B; +} +H2 +{ + FONT-SIZE: 150%; +} +H3 +{ + FONT-SIZE: 125%; +} +H4 +{ + FONT-SIZE: 108%; +} +BODY +{ + FONT-SIZE: 100%; + BACKGROUND-COLOR: #ffffff; + COLOR: #000000; +} +PRE +{ + MARGIN-LEFT: 2em; + FONT-FAMILY: Courier, + monospace; +} +CODE +{ + FONT-FAMILY: Courier, + monospace; +} +CODE.as_pre +{ + 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; +}
\ No newline at end of file diff --git a/libs/python/doc/html/boostbook.css b/libs/python/doc/html/boostbook.css new file mode 100644 index 0000000000..d42b3c022f --- /dev/null +++ b/libs/python/doc/html/boostbook.css @@ -0,0 +1,700 @@ + +/*============================================================================= +Copyright (c) 2004 Joel de Guzman +http://spirit.sourceforge.net/ + +Copyright 2013 Niall Douglas additions for colors and alignment. +Copyright 2013 Paul A. Bristow additions for more colors and alignments. + +Distributed under the Boost Software License, Version 1.0. (See accompany- +ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +=============================================================================*/ + +/*============================================================================= +Body defaults +=============================================================================*/ + + body + { + margin: 1em; + font-family: sans-serif; + } + +/*============================================================================= +Paragraphs +=============================================================================*/ + + p + { + text-align: left; + font-size: 10pt; + line-height: 1.15; + } + +/*============================================================================= +Program listings +=============================================================================*/ + + /* Code on paragraphs */ + p tt.computeroutput + { + font-size: 9pt; + } + + pre.synopsis + { + font-size: 9pt; + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; + } + + .programlisting, + .screen + { + font-size: 9pt; + display: block; + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; + } + + /* Program listings in tables don't get borders */ + td .programlisting, + td .screen + { + margin: 0pc 0pc 0pc 0pc; + padding: 0pc 0pc 0pc 0pc; + } + +/*============================================================================= +Headings +=============================================================================*/ + + h1, h2, h3, h4, h5, h6 + { + text-align: left; + margin: 1em 0em 0.5em 0em; + font-weight: bold; + } + + h1 { font-size: 140%; } + h2 { font-weight: bold; font-size: 140%; } + h3 { font-weight: bold; font-size: 130%; } + h4 { font-weight: bold; font-size: 120%; } + h5 { font-weight: normal; font-style: italic; font-size: 110%; } + h6 { font-weight: normal; font-style: italic; font-size: 100%; } + + /* Top page titles */ + title, + h1.title, + h2.title + h3.title, + h4.title, + h5.title, + h6.title, + .refentrytitle + { + font-weight: bold; + margin-bottom: 1pc; + } + + h1.title { font-size: 140% } + h2.title { font-size: 140% } + h3.title { font-size: 130% } + h4.title { font-size: 120% } + h5.title { font-size: 110% } + h6.title { font-size: 100% } + + .section h1 + { + margin: 0em 0em 0.5em 0em; + font-size: 140%; + } + + .section h2 { font-size: 140% } + .section h3 { font-size: 130% } + .section h4 { font-size: 120% } + .section h5 { font-size: 110% } + .section h6 { font-size: 100% } + + /* Code on titles */ + h1 tt.computeroutput { font-size: 140% } + h2 tt.computeroutput { font-size: 140% } + h3 tt.computeroutput { font-size: 130% } + h4 tt.computeroutput { font-size: 130% } + h5 tt.computeroutput { font-size: 130% } + h6 tt.computeroutput { font-size: 130% } + + +/*============================================================================= +Author +=============================================================================*/ + + h3.author + { + font-size: 100% + } + +/*============================================================================= +Lists +=============================================================================*/ + + li + { + font-size: 10pt; + line-height: 1.3; + } + + /* Unordered lists */ + ul + { + text-align: left; + } + + /* Ordered lists */ + ol + { + text-align: left; + } + +/*============================================================================= +Links +=============================================================================*/ + + a + { + text-decoration: none; /* no underline */ + } + + a:hover + { + text-decoration: underline; + } + +/*============================================================================= +Spirit style navigation +=============================================================================*/ + + .spirit-nav + { + text-align: right; + } + + .spirit-nav a + { + color: white; + padding-left: 0.5em; + } + + .spirit-nav img + { + border-width: 0px; + } + +/*============================================================================= +Copyright footer +=============================================================================*/ + .copyright-footer + { + text-align: right; + font-size: 70%; + } + + .copyright-footer p + { + text-align: right; + font-size: 80%; + } + +/*============================================================================= +Table of contents +=============================================================================*/ + + div.toc + { + margin: 1pc 4% 0pc 4%; + padding: 0.1pc 1pc 0.1pc 1pc; + font-size: 80%; + line-height: 1.15; + } + + .boost-toc + { + float: right; + padding: 0.5pc; + } + + /* Code on toc */ + .toc .computeroutput { font-size: 120% } + + /* No margin on nested menus */ + + .toc dl dl { margin: 0; } + +/*============================================================================= +Tables +=============================================================================*/ + + .table-title, + div.table p.title + { + margin-left: 4%; + padding-right: 0.5em; + padding-left: 0.5em; + } + + .informaltable table, + .table table + { + width: 92%; + margin-left: 4%; + margin-right: 4%; + } + + div.informaltable table, + div.table table + { + padding: 4px; + } + + /* Table Cells */ + div.informaltable table tr td, + div.table table tr td + { + padding: 0.5em; + text-align: left; + font-size: 9pt; + } + + div.informaltable table tr th, + div.table table tr th + { + padding: 0.5em 0.5em 0.5em 0.5em; + border: 1pt solid white; + font-size: 80%; + } + + table.simplelist + { + width: auto !important; + margin: 0em !important; + padding: 0em !important; + border: none !important; + } + table.simplelist td + { + margin: 0em !important; + padding: 0em !important; + text-align: left !important; + font-size: 9pt !important; + border: none !important; + } + +/*============================================================================= +Blurbs +=============================================================================*/ + + div.note, + div.tip, + div.important, + div.caution, + div.warning, + p.blurb + { + font-size: 9pt; /* A little bit smaller than the main text */ + line-height: 1.2; + display: block; + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; + } + + p.blurb img + { + padding: 1pt; + } + +/*============================================================================= +Variable Lists +=============================================================================*/ + + div.variablelist + { + margin: 1em 0; + } + + /* Make the terms in definition lists bold */ + div.variablelist dl dt, + span.term + { + font-weight: bold; + font-size: 10pt; + } + + div.variablelist table tbody tr td + { + text-align: left; + vertical-align: top; + padding: 0em 2em 0em 0em; + font-size: 10pt; + margin: 0em 0em 0.5em 0em; + line-height: 1; + } + + div.variablelist dl dt + { + margin-bottom: 0.2em; + } + + div.variablelist dl dd + { + margin: 0em 0em 0.5em 2em; + font-size: 10pt; + } + + div.variablelist table tbody tr td p, + div.variablelist dl dd p + { + margin: 0em 0em 0.5em 0em; + line-height: 1; + } + +/*============================================================================= +Misc +=============================================================================*/ + + /* Title of books and articles in bibliographies */ + span.title + { + font-style: italic; + } + + span.underline + { + text-decoration: underline; + } + + span.strikethrough + { + text-decoration: line-through; + } + + /* Copyright, Legal Notice */ + div div.legalnotice p + { + text-align: left + } + +/*============================================================================= +Colors +=============================================================================*/ + + @media screen + { + body { + background-color: #FFFFFF; + color: #000000; + } + + /* Syntax Highlighting */ + .keyword { color: #0000AA; } + .identifier { color: #000000; } + .special { color: #707070; } + .preprocessor { color: #402080; } + .char { color: teal; } + .comment { color: #800000; } + .string { color: teal; } + .number { color: teal; } + .white_bkd { background-color: #FFFFFF; } + .dk_grey_bkd { background-color: #999999; } + + /* Links */ + a, a .keyword, a .identifier, a .special, a .preprocessor + a .char, a .comment, a .string, a .number + { + color: #005a9c; + } + + a:visited, a:visited .keyword, a:visited .identifier, + a:visited .special, a:visited .preprocessor a:visited .char, + a:visited .comment, a:visited .string, a:visited .number + { + color: #9c5a9c; + } + + h1 a, h2 a, h3 a, h4 a, h5 a, h6 a, + h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, h5 a:hover, h6 a:hover, + h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited + { + text-decoration: none; /* no underline */ + color: #000000; + } + + /* Copyright, Legal Notice */ + .copyright + { + color: #666666; + font-size: small; + } + + div div.legalnotice p + { + color: #666666; + } + + /* Program listing */ + pre.synopsis + { + border: 1px solid #DCDCDC; + } + + .programlisting, + .screen + { + border: 1px solid #DCDCDC; + } + + td .programlisting, + td .screen + { + border: 0px solid #DCDCDC; + } + + /* Blurbs */ + div.note, + div.tip, + div.important, + div.caution, + div.warning, + p.blurb + { + border: 1px solid #DCDCDC; + } + + /* Table of contents */ + div.toc + { + border: 1px solid #DCDCDC; + } + + /* Tables */ + div.informaltable table tr td, + div.table table tr td + { + border: 1px solid #DCDCDC; + } + + div.informaltable table tr th, + div.table table tr th + { + background-color: #F0F0F0; + border: 1px solid #DCDCDC; + } + + .copyright-footer + { + color: #8F8F8F; + } + + /* Misc */ + span.highlight + { + color: #00A000; + } + } + + @media print + { + /* Links */ + a + { + color: black; + } + + a:visited + { + color: black; + } + + .spirit-nav + { + display: none; + } + + /* Program listing */ + pre.synopsis + { + border: 1px solid gray; + } + + .programlisting, + .screen + { + border: 1px solid gray; + } + + td .programlisting, + td .screen + { + border: 0px solid #DCDCDC; + } + + /* Table of contents */ + div.toc + { + border: 1px solid gray; + } + + .informaltable table, + .table table + { + border: 1px solid gray; + border-collapse: collapse; + } + + /* Tables */ + div.informaltable table tr td, + div.table table tr td + { + border: 1px solid gray; + } + + div.informaltable table tr th, + div.table table tr th + { + border: 1px solid gray; + } + + table.simplelist tr td + { + border: none !important; + } + + /* Misc */ + span.highlight + { + font-weight: bold; + } + } + +/*============================================================================= +Images +=============================================================================*/ + + span.inlinemediaobject img + { + vertical-align: middle; + } + +/*============================================================================== +Super and Subscript: style so that line spacing isn't effected, see +http://www.adobe.com/cfusion/communityengine/index.cfm?event=showdetails&productId=1&postId=5341 +==============================================================================*/ + +sup, +sub { +height: 0; +line-height: 1; +vertical-align: baseline; +position: relative; + +} + +/* For internet explorer: */ + +* html sup, +* html sub { +vertical-align: bottom; +} + +sup { +bottom: 1ex; +} + +sub { +top: .5ex; +} + +/*============================================================================== +Indexes: pretty much the same as the TOC. +==============================================================================*/ + + .index + { + font-size: 80%; + padding-top: 0px; + padding-bottom: 0px; + margin-top: 0px; + margin-bottom: 0px; + margin-left: 0px; + } + + .index ul + { + padding-left: 3em; + } + + .index p + { + padding: 2px; + margin: 2px; + } + + .index-entry-level-0 + { + font-weight: bold; + } + + .index em + { + font-weight: bold; + } + + +/*============================================================================== +Alignment and coloring use 'role' feature, available from Quickbook 1.6 up. +Added from Niall Douglas for role color and alignment. +http://article.gmane.org/gmane.comp.lib.boost.devel/243318 +*/ + +/* Add text alignment (see http://www.w3schools.com/cssref/pr_text_text-align.asp) */ +span.aligncenter +{ + display: inline-block; width: 100%; text-align: center; +} +span.alignright +{ + display: inline-block; width: 100%; text-align: right; +} +/* alignleft is the default. */ +span.alignleft +{ + display: inline-block; width: 100%; text-align: left; +} + +/* alignjustify stretches the word spacing so that each line has equal width +within a chosen fraction of page width (here arbitrarily 20%). +*Not* useful inside table items as the column width remains the total string width. +Nor very useful, except to temporarily restrict the width. +*/ +span.alignjustify +{ + display: inline-block; width: 20%; text-align: justify; +} + +/* Text colors. +Names at http://www.w3.org/TR/2002/WD-css3-color-20020219/ 4.3. X11 color keywords. +Quickbook Usage: [role red Some red text] + +*/ +span.red { inline-block; color: red; } +span.green { color: green; } +span.lime { color: #00FF00; } +span.blue { color: blue; } +span.navy { color: navy; } +span.yellow { color: yellow; } +span.magenta { color: magenta; } +span.indigo { color: #4B0082; } +span.cyan { color: cyan; } +span.purple { color: purple; } +span.gold { color: gold; } +span.silver { color: silver; } /* lighter gray */ +span.gray { color: #808080; } /* light gray */ diff --git a/libs/python/doc/html/building.html b/libs/python/doc/html/building.html new file mode 100644 index 0000000000..5f4a4a6b1d --- /dev/null +++ b/libs/python/doc/html/building.html @@ -0,0 +1,98 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 1. Building and Testing</title> +<link rel="stylesheet" href="boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python"> +<link rel="up" href="index.html" title="Boost.Python"> +<link rel="prev" href="index.html" title="Boost.Python"> +<link rel="next" href="building/background.html" title="Background"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="index.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="building/background.html"><img src="images/next.png" alt="Next"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div> +<div><h1 class="title"> +<a name="building"></a>Chapter 1. Building and Testing</h1></div> +<div><div class="authorgroup"><div class="author"><h3 class="author"> +<span class="firstname">David</span> <span class="surname">Abrahams</span> +</h3></div></div></div> +<div><p class="copyright">Copyright © 2002-2015 David Abrahams, Stefan Seefeld</p></div> +</div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="building.html#building.requirements">Requirements</a></span></dt> +<dt><span class="section"><a href="building/background.html">Background</a></span></dt> +<dt><span class="section"><a href="building/no_install_quickstart.html">No-Install Quickstart</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="building/no_install_quickstart.html#building.no_install_quickstart.basic_procedure">Basic + Procedure</a></span></dt> +<dt><span class="section"><a href="building/no_install_quickstart.html#building.no_install_quickstart.in_case_of_trouble">In + Case of Trouble</a></span></dt> +<dt><span class="section"><a href="building/no_install_quickstart.html#building.no_install_quickstart.in_case_everything_seemed_to_wor">In + Case Everything Seemed to Work</a></span></dt> +<dt><span class="section"><a href="building/no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project">Modifying + the Example Project</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="building/installing_boost_python_on_your_.html">Installing + Boost.Python on your System</a></span></dt> +<dt><span class="section"><a href="building/configuring_boost_build.html">Configuring Boost.Build</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="building/configuring_boost_build.html#building.configuring_boost_build.python_configuration_parameters">Python + Configuration Parameters</a></span></dt> +<dt><span class="section"><a href="building/configuring_boost_build.html#building.configuring_boost_build.examples">Examples</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="building/choosing_a_boost_python_library_.html">Choosing a + Boost.Python Library Binary</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="building/choosing_a_boost_python_library_.html#building.choosing_a_boost_python_library_.the_dynamic_binary">The + Dynamic Binary</a></span></dt> +<dt><span class="section"><a href="building/choosing_a_boost_python_library_.html#building.choosing_a_boost_python_library_.the_static_binary">The + Static Binary</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="building/include_issues.html"><code class="computeroutput"><span class="preprocessor">#include</span></code> + Issues</a></span></dt> +<dt><span class="section"><a href="building/python_debugging_builds.html">Python Debugging Builds</a></span></dt> +<dt><span class="section"><a href="building/testing_boost_python.html">Testing Boost.Python</a></span></dt> +<dt><span class="section"><a href="building/notes_for_mingw_and_cygwin_with_.html">Notes for + MinGW (and Cygwin with -mno-cygwin) GCC Users</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="building.requirements"></a><a class="link" href="building.html#building.requirements" title="Requirements">Requirements</a> +</h3></div></div></div> +<p> + Boost.Python requires <a href="http://www.python.org/2.2" target="_top">Python 2.2</a> + <a href="#ftn.building.requirements.f0" class="footnote" name="building.requirements.f0"><sup class="footnote">[1]</sup></a> <span class="bold"><strong>or</strong></span> <a href="http://www.python.org" target="_top">newer</a>. + </p> +</div> +<div class="footnotes"> +<br><hr style="width:100; text-align:left;margin-left: 0"> +<div id="ftn.building.requirements.f0" class="footnote"><p><a href="#building.requirements.f0" class="para"><sup class="para">[1] </sup></a> + Note that although we tested earlier versions of Boost.Python with Python + 2.2, and we don't <span class="bold"><strong>think</strong></span> we've done anything + to break compatibility, this release of Boost.Python may not have been + tested with versions of Python earlier than 2.4, so we're not 100% sure + that python 2.2 and 2.3 are supported. + </p></div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="index.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="building/background.html"><img src="images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/building/background.html b/libs/python/doc/html/building/background.html new file mode 100644 index 0000000000..a7aca7f031 --- /dev/null +++ b/libs/python/doc/html/building/background.html @@ -0,0 +1,70 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Background</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../building.html" title="Chapter 1. Building and Testing"> +<link rel="prev" href="../building.html" title="Chapter 1. Building and Testing"> +<link rel="next" href="no_install_quickstart.html" title="No-Install Quickstart"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../building.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="no_install_quickstart.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="building.background"></a><a class="link" href="background.html" title="Background">Background</a> +</h3></div></div></div> +<p> + There are two basic models for combining C++ and Python: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <a href="http://www.python.org/doc/current/ext/intro.html" target="_top">extending</a>, + in which the end-user launches the Python interpreter executable and + imports Python “extension modules” written in C++. Think of taking + a library written in C++ and giving it a Python interface so Python programmers + can use it. From Python, these modules look just like regular Python + modules. + </li> +<li class="listitem"> + <a href="http://www.python.org/doc/current/ext/embedding.html" target="_top">embedding</a>, + in which the end-user launches a program written in C++ that in turn + invokes the Python interpreter as a library subroutine. Think of adding + scriptability to an existing application. + </li> +</ul></div> +<p> + The key distinction between extending and embedding is the location of the + C++ <code class="computeroutput"><span class="identifier">main</span><span class="special">()</span></code> + function: in the Python interpreter executable, or in some other program, + respectively. Note that even when embedding Python in another program, <a href="http://www.python.org/doc/current/ext/extending-with-embedding.html" target="_top">extension + modules are often the best way to make C/C++ functionality accessible to + Python code</a>, so the use of extension modules is really at the heart + of both models. + </p> +<p> + Except in rare cases, extension modules are built as dynamically-loaded libraries + with a single entry point, which means you can change them without rebuilding + either the other extension modules or the executable containing <code class="computeroutput"><span class="identifier">main</span><span class="special">()</span></code>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<br>Copyright © 2002-2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../building.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="no_install_quickstart.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/building/choosing_a_boost_python_library_.html b/libs/python/doc/html/building/choosing_a_boost_python_library_.html new file mode 100644 index 0000000000..0e0c4d1120 --- /dev/null +++ b/libs/python/doc/html/building/choosing_a_boost_python_library_.html @@ -0,0 +1,128 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Choosing a Boost.Python Library Binary</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../building.html" title="Chapter 1. Building and Testing"> +<link rel="prev" href="configuring_boost_build.html" title="Configuring Boost.Build"> +<link rel="next" href="include_issues.html" title="#include Issues"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="configuring_boost_build.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="include_issues.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="building.choosing_a_boost_python_library_"></a><a class="link" href="choosing_a_boost_python_library_.html" title="Choosing a Boost.Python Library Binary">Choosing a + Boost.Python Library Binary</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="choosing_a_boost_python_library_.html#building.choosing_a_boost_python_library_.the_dynamic_binary">The + Dynamic Binary</a></span></dt> +<dt><span class="section"><a href="choosing_a_boost_python_library_.html#building.choosing_a_boost_python_library_.the_static_binary">The + Static Binary</a></span></dt> +</dl></div> +<p> + If—instead of letting Boost.Build construct and link with the right libraries + automatically—you choose to use a pre-built Boost.Python library, you'll + need to think about which one to link with. The Boost.Python binary comes + in both static and dynamic flavors. Take care to choose the right flavor + for your application. <a href="#ftn.building.choosing_a_boost_python_library_.f0" class="footnote" name="building.choosing_a_boost_python_library_.f0"><sup class="footnote">[3]</sup></a> + </p> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="building.choosing_a_boost_python_library_.the_dynamic_binary"></a><a class="link" href="choosing_a_boost_python_library_.html#building.choosing_a_boost_python_library_.the_dynamic_binary" title="The Dynamic Binary">The + Dynamic Binary</a> +</h4></div></div></div> +<p> + The dynamic library is the safest and most-versatile choice: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + A single copy of the library code is used by all extension modules + built with a given toolset. <a href="#ftn.building.choosing_a_boost_python_library_.the_dynamic_binary.f0" class="footnote" name="building.choosing_a_boost_python_library_.the_dynamic_binary.f0"><sup class="footnote">[4]</sup></a> + </li> +<li class="listitem"> + The library contains a type conversion registry. Because one registry + is shared among all extension modules, instances of a class exposed + to Python in one dynamically-loaded extension module can be passed + to functions exposed in another such module. + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="building.choosing_a_boost_python_library_.the_static_binary"></a><a class="link" href="choosing_a_boost_python_library_.html#building.choosing_a_boost_python_library_.the_static_binary" title="The Static Binary">The + Static Binary</a> +</h4></div></div></div> +<p> + It might be appropriate to use the static Boost.Python library in any of + the following cases: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + You are <a href="https://docs.python.org/2/extending/extending.html" target="_top">extending</a> + python and the types exposed in your dynamically-loaded extension module + don't need to be used by any other Boost.Python extension modules, + and you don't care if the core library code is duplicated among them. + </li> +<li class="listitem"> + You are <a href="https://docs.python.org/2/extending/embedding.html" target="_top">embedding</a> + python in your application and either: + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> +<li class="listitem"> + You are targeting a Unix variant OS other than MacOS or AIX, + where the dynamically-loaded extension modules can “see” + the Boost.Python library symbols that are part of the executable. + </li> +<li class="listitem"> + Or, you have statically linked some Boost.Python extension modules + into your application and you don't care if any dynamically-loaded + Boost.Python extension modules are able to use the types exposed + by your statically-linked extension modules (and vice-versa). + </li> +</ul></div> + </li> +</ul></div> +</div> +<div class="footnotes"> +<br><hr style="width:100; text-align:left;margin-left: 0"> +<div id="ftn.building.choosing_a_boost_python_library_.f0" class="footnote"><p><a href="#building.choosing_a_boost_python_library_.f0" class="para"><sup class="para">[3] </sup></a> + Information about how to identify the static and dynamic builds of Boost.Python + on <a href="http://boost.org/more/getting_started/windows.html#library-naming" target="_top">Windows</a> + / <a href="http://boost.org/more/getting_started/unix-variants.html#library-naming" target="_top">Unix + variants</a> + </p></div> +<div id="ftn.building.choosing_a_boost_python_library_.the_dynamic_binary.f0" class="footnote"><p><a href="#building.choosing_a_boost_python_library_.the_dynamic_binary.f0" class="para"><sup class="para">[4] </sup></a> + Because of the way most *nix platforms share symbols among dynamically-loaded + objects, I'm not certain that extension modules built with different + compiler toolsets will always use different copies of the Boost.Python + library when loaded into the same Python instance. Not using different + libraries could be a good thing if the compilers have compatible + ABIs, because extension modules built with the two libraries would + be interoperable. Otherwise, it could spell disaster, since an extension + module and the Boost.Python library would have different ideas of + such things as class layout. I would appreciate someone doing the + experiment to find out what happens. + </p></div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<br>Copyright © 2002-2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="configuring_boost_build.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="include_issues.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/building/configuring_boost_build.html b/libs/python/doc/html/building/configuring_boost_build.html new file mode 100644 index 0000000000..5fe5b5e8cc --- /dev/null +++ b/libs/python/doc/html/building/configuring_boost_build.html @@ -0,0 +1,264 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Configuring Boost.Build</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../building.html" title="Chapter 1. Building and Testing"> +<link rel="prev" href="installing_boost_python_on_your_.html" title="Installing Boost.Python on your System"> +<link rel="next" href="choosing_a_boost_python_library_.html" title="Choosing a Boost.Python Library Binary"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="installing_boost_python_on_your_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="choosing_a_boost_python_library_.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="building.configuring_boost_build"></a><a class="link" href="configuring_boost_build.html" title="Configuring Boost.Build">Configuring Boost.Build</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="configuring_boost_build.html#building.configuring_boost_build.python_configuration_parameters">Python + Configuration Parameters</a></span></dt> +<dt><span class="section"><a href="configuring_boost_build.html#building.configuring_boost_build.examples">Examples</a></span></dt> +</dl></div> +<p> + As described in the <a href="http://www.boost.org/build/doc/html/bbv2/overview/configuration.html" target="_top">Boost.Build + Reference Manual</a>, a file called <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code> in + your home directory is used to specify the tools and libraries available + to the build system. You may need to create or edit <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code> to + tell Boost.Build how to invoke Python, <code class="computeroutput"><span class="preprocessor">#include</span></code> + its headers, and link with its libraries. + </p> +<div class="note"><table border="0" summary="Note"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> +<th align="left">Note</th> +</tr> +<tr><td align="left" valign="top"><p> + If you are using a unix-variant OS and you ran Boost's <code class="computeroutput"><span class="identifier">configure</span></code> + script, it may have generated a <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code> + for you. <a href="#ftn.building.configuring_boost_build.f0" class="footnote" name="building.configuring_boost_build.f0"><sup class="footnote">[2]</sup></a> If your <code class="computeroutput"><span class="identifier">configure</span></code>/<code class="computeroutput"><span class="identifier">make</span></code> sequence was successful and Boost.Python + binaries were built, your <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code> + file is probably already correct. + </p></td></tr> +</table></div> +<p> + If you have one fairly “standard” python installation for your platform, + you might not need to do anything special to describe it. If you haven't + configured python in <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code> (and + you don't specify <code class="computeroutput"><span class="special">--</span><span class="identifier">without</span><span class="special">-</span><span class="identifier">python</span></code> + on the Boost.Build command line), Boost.Build will automatically execute + the equivalent of + </p> +<pre class="programlisting"><span class="identifier">import</span> <span class="identifier">toolset</span> <span class="special">:</span> <span class="keyword">using</span> <span class="special">;</span> +<span class="keyword">using</span> <span class="identifier">python</span> <span class="special">;</span> +</pre> +<p> + which automatically looks for Python in the most likely places. However, + that only happens when using the Boost.Python project file (e.g. when referred + to by another project as in the quickstart method). If instead you are linking + against separately-compiled Boost.Python binaries, you should set up a <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code> file + with at least the minimal incantation above. + </p> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="building.configuring_boost_build.python_configuration_parameters"></a><a class="link" href="configuring_boost_build.html#building.configuring_boost_build.python_configuration_parameters" title="Python Configuration Parameters">Python + Configuration Parameters</a> +</h4></div></div></div> +<p> + If you have several versions of Python installed, or Python is installed + in an unusual way, you may want to supply any or all of the following optional + parameters to <code class="computeroutput"><span class="keyword">using</span> <span class="identifier">python</span></code>. + </p> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">version</span></dt> +<dd><p> + the version of Python to use. Should be in Major.Minor format, for + example, <code class="computeroutput"><span class="number">2.3</span></code>. Do not + include the subminor version (i.e. <span class="bold"><strong>not</strong></span> + <code class="computeroutput"><span class="number">2.5</span><span class="special">.</span><span class="number">1</span></code>). If you have multiple Python versions + installed, the version will usually be the only configuration argument + required. + </p></dd> +<dt><span class="term">cmd-or-prefix</span></dt> +<dd><p> + preferably, a command that invokes a Python interpreter. Alternatively, + the installation prefix for Python libraries and header files. Only + use the alternative formulation if there is no appropriate Python + executable available. + </p></dd> +<dt><span class="term"><span class="bold"><strong>includes</strong></span></span></dt> +<dd><p> + the <code class="computeroutput"><span class="preprocessor">#include</span></code> paths + for Python headers. Normally the correct path(s) will be automatically + deduced from <code class="computeroutput"><span class="identifier">version</span></code> + and/or <code class="computeroutput"><span class="identifier">cmd</span><span class="special">-</span><span class="keyword">or</span><span class="special">-</span><span class="identifier">prefix</span></code>. + </p></dd> +<dt><span class="term"><span class="bold"><strong>libraries</strong></span></span></dt> +<dd><p> + the path to Python library binaries. On MacOS/Darwin, you can also + pass the path of the Python framework. Normally the correct path(s) + will be automatically deduced from <code class="computeroutput"><span class="identifier">version</span></code> + and/or <code class="computeroutput"><span class="identifier">cmd</span><span class="special">-</span><span class="keyword">or</span><span class="special">-</span><span class="identifier">prefix</span></code>. + </p></dd> +<dt><span class="term"><span class="bold"><strong>condition</strong></span></span></dt> +<dd><p> + if specified, should be a set of Boost.Build properties that are + matched against the build configuration when Boost.Build selects + a Python configuration to use. See examples below for details. + </p></dd> +<dt><span class="term"><span class="bold"><strong>extension-suffix</strong></span></span></dt> +<dd><p> + A string to append to the name of extension modules before the true + filename extension. You almost certainly don't need to use this. + Usually this suffix is only used when targeting a Windows debug build + of Python, and will be set automatically for you based on the value + of the <a class="link" href="python_debugging_builds.html" title="Python Debugging Builds"><python-debugging></a> + feature. However, at least one Linux distribution (Ubuntu Feisty + Fawn) has a specially configured <a href="https://wiki.ubuntu.com/PyDbgBuilds" target="_top"><python-dbg></a> + package that claims to use such a suffix. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="building.configuring_boost_build.examples"></a><a class="link" href="configuring_boost_build.html#building.configuring_boost_build.examples" title="Examples">Examples</a> +</h4></div></div></div> +<p> + Note that in the examples below, case and <span class="bold"><strong>especially + whitespace</strong></span> are significant. + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> +<p class="simpara"> + If you have both python 2.5 and python 2.4 installed, <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code> might contain + </p> +<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">python</span> <span class="special">:</span> <span class="number">2.5</span> <span class="special">;</span> <span class="special">#</span> <span class="identifier">Make</span> <span class="identifier">both</span> <span class="identifier">versions</span> <span class="identifier">of</span> <span class="identifier">Python</span> <span class="identifier">available</span> +<span class="keyword">using</span> <span class="identifier">python</span> <span class="special">:</span> <span class="number">2.4</span> <span class="special">;</span> <span class="special">#</span> <span class="identifier">To</span> <span class="identifier">build</span> <span class="identifier">with</span> <span class="identifier">python</span> <span class="number">2.4</span><span class="special">,</span> <span class="identifier">add</span> <span class="identifier">python</span><span class="special">=</span><span class="number">2.4</span> + <span class="preprocessor"># to</span> <span class="identifier">your</span> <span class="identifier">command</span> <span class="identifier">line</span><span class="special">.</span> +</pre> +<p class="simpara"> + The first version configured (2.5) becomes the default. To build against + python 2.4, add <code class="computeroutput"><span class="identifier">python</span><span class="special">=</span><span class="number">2.4</span></code> + to the <code class="computeroutput"><span class="identifier">bjam</span></code> command + line. + </p> +</li> +<li class="listitem"> +<p class="simpara"> + If you have python installed in an unusual location, you might supply + the path to the interpreter in the <code class="computeroutput"><span class="identifier">cmd</span><span class="special">-</span><span class="keyword">or</span><span class="special">-</span><span class="identifier">prefix</span></code> + parameter: + </p> +<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">python</span> <span class="special">:</span> <span class="special">:</span> <span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">local</span><span class="special">/</span><span class="identifier">python</span><span class="special">-</span><span class="number">2.6</span><span class="special">-</span><span class="identifier">beta</span><span class="special">/</span><span class="identifier">bin</span><span class="special">/</span><span class="identifier">python</span> <span class="special">;</span> +</pre> +</li> +<li class="listitem"> +<p class="simpara"> + If you have a separate build of Python for use with a particular toolset, + you might supply that toolset in the <code class="computeroutput"><span class="identifier">condition</span></code> + parameter: + </p> +<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">python</span> <span class="special">;</span> <span class="special">#</span> <span class="identifier">use</span> <span class="keyword">for</span> <span class="identifier">most</span> <span class="identifier">toolsets</span> + +<span class="preprocessor"># Use</span> <span class="identifier">with</span> <span class="identifier">Intel</span> <span class="identifier">C</span><span class="special">++</span> <span class="identifier">toolset</span> +<span class="keyword">using</span> <span class="identifier">python</span> + <span class="special">:</span> <span class="special">#</span> <span class="identifier">version</span> + <span class="special">:</span> <span class="identifier">c</span><span class="special">:\\</span><span class="identifier">Devel</span><span class="special">\\</span><span class="identifier">Python</span><span class="special">-</span><span class="number">2.5</span><span class="special">-</span><span class="identifier">IntelBuild</span><span class="special">\\</span><span class="identifier">PCBuild</span><span class="special">\\</span><span class="identifier">python</span> <span class="special">#</span> <span class="identifier">cmd</span><span class="special">-</span><span class="keyword">or</span><span class="special">-</span><span class="identifier">prefix</span> + <span class="special">:</span> <span class="special">#</span> <span class="identifier">includes</span> + <span class="special">:</span> <span class="special">#</span> <span class="identifier">libraries</span> + <span class="special">:</span> <span class="special"><</span><span class="identifier">toolset</span><span class="special">></span><span class="identifier">intel</span> <span class="special">#</span> <span class="identifier">condition</span> + <span class="special">;</span> +</pre> +</li> +<li class="listitem"> +<p class="simpara"> + If you have downloaded the Python sources and built both the normal + and the <a class="link" href="python_debugging_builds.html" title="Python Debugging Builds">"python + debugging"</a> builds from source on Windows, you might see: + </p> +<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">python</span> <span class="special">:</span> <span class="number">2.5</span> <span class="special">:</span> <span class="identifier">C</span><span class="special">:\\</span><span class="identifier">src</span><span class="special">\\</span><span class="identifier">Python</span><span class="special">-</span><span class="number">2.5</span><span class="special">\\</span><span class="identifier">PCBuild</span><span class="special">\\</span><span class="identifier">python</span> <span class="special">;</span> +<span class="keyword">using</span> <span class="identifier">python</span> <span class="special">:</span> <span class="number">2.5</span> <span class="special">:</span> <span class="identifier">C</span><span class="special">:\\</span><span class="identifier">src</span><span class="special">\\</span><span class="identifier">Python</span><span class="special">-</span><span class="number">2.5</span><span class="special">\\</span><span class="identifier">PCBuild</span><span class="special">\\</span><span class="identifier">python_d</span> + <span class="special">:</span> <span class="special">#</span> <span class="identifier">includes</span> + <span class="special">:</span> <span class="special">#</span> <span class="identifier">libs</span> + <span class="special">:</span> <span class="special"><</span><span class="identifier">python</span><span class="special">-</span><span class="identifier">debugging</span><span class="special">></span><span class="identifier">on</span> <span class="special">;</span> +</pre> +</li> +<li class="listitem"> +<p class="simpara"> + You can set up your user-config.jam so a bjam built under Windows can + build/test both Windows and Cygwin_ python extensions. Just pass <code class="computeroutput"><span class="special"><</span><span class="identifier">target</span><span class="special">-</span><span class="identifier">os</span><span class="special">></span><span class="identifier">cygwin</span></code> + in the <code class="computeroutput"><span class="identifier">condition</span></code> parameter + for the cygwin python installation: + </p> +<pre class="programlisting"><span class="preprocessor"># windows</span> <span class="identifier">installation</span> +<span class="keyword">using</span> <span class="identifier">python</span> <span class="special">;</span> + +<span class="preprocessor"># cygwin</span> <span class="identifier">installation</span> +<span class="keyword">using</span> <span class="identifier">python</span> <span class="special">:</span> <span class="special">:</span> <span class="identifier">c</span><span class="special">:\\</span><span class="identifier">cygwin</span><span class="special">\\</span><span class="identifier">bin</span><span class="special">\\</span><span class="identifier">python2</span><span class="special">.</span><span class="number">5</span> <span class="special">:</span> <span class="special">:</span> <span class="special">:</span> <span class="special"><</span><span class="identifier">target</span><span class="special">-</span><span class="identifier">os</span><span class="special">></span><span class="identifier">cygwin</span> <span class="special">;</span> +</pre> +<p class="simpara"> + when you put target-os=cygwin in your build request, it should build + with the cygwin version of python: <a name="flavor"></a>_ + </p> +<pre class="programlisting"><span class="identifier">bjam</span> <span class="identifier">target</span><span class="special">-</span><span class="identifier">os</span><span class="special">=</span><span class="identifier">cygwin</span> <span class="identifier">toolset</span><span class="special">=</span><span class="identifier">gcc</span> +</pre> +<p class="simpara"> + This is supposed to work the other way, too (targeting windows python + with a <a href="http://cygwin.com" target="_top">Cygwin</a> bjam) but it seems + as though the support in Boost.Build's toolsets for building that way + is broken at the time of this writing. + </p> +</li> +<li class="listitem"> +<p class="simpara"> + Note that because of <a href="http://zigzag.cs.msu.su/boost.build/wiki/AlternativeSelection" target="_top">the + way Boost.Build currently selects target alternatives</a>, you + might have be very explicit in your build requests. For example, given: + </p> +<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">python</span> <span class="special">:</span> <span class="number">2.5</span> <span class="special">;</span> <span class="special">#</span> <span class="identifier">a</span> <span class="identifier">regular</span> <span class="identifier">windows</span> <span class="identifier">build</span> +<span class="keyword">using</span> <span class="identifier">python</span> <span class="special">:</span> <span class="number">2.4</span> <span class="special">:</span> <span class="special">:</span> <span class="special">:</span> <span class="special">:</span> <span class="special"><</span><span class="identifier">target</span><span class="special">-</span><span class="identifier">os</span><span class="special">></span><span class="identifier">cygwin</span> <span class="special">;</span> +</pre> +<p class="simpara"> + building with + </p> +<pre class="programlisting"><span class="identifier">bjam</span> <span class="identifier">target</span><span class="special">-</span><span class="identifier">os</span><span class="special">=</span><span class="identifier">cygwin</span> +</pre> +<p class="simpara"> + will yield an error. Instead, you'll need to write + </p> +<pre class="programlisting"><span class="identifier">bjam</span> <span class="identifier">target</span><span class="special">-</span><span class="identifier">os</span><span class="special">=</span><span class="identifier">cygwin</span><span class="special">/</span><span class="identifier">python</span><span class="special">=</span><span class="number">2.4</span> +</pre> +</li> +</ul></div> +</div> +<div class="footnotes"> +<br><hr style="width:100; text-align:left;margin-left: 0"> +<div id="ftn.building.configuring_boost_build.f0" class="footnote"><p><a href="#building.configuring_boost_build.f0" class="para"><sup class="para">[2] </sup></a> + <code class="computeroutput"><span class="identifier">configure</span></code> overwrites + the existing <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code> in your home directory (if any) + after making a backup of the old version. + </p></div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<br>Copyright © 2002-2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="installing_boost_python_on_your_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="choosing_a_boost_python_library_.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/building/include_issues.html b/libs/python/doc/html/building/include_issues.html new file mode 100644 index 0000000000..edaf1ae4ae --- /dev/null +++ b/libs/python/doc/html/building/include_issues.html @@ -0,0 +1,53 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>#include Issues</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../building.html" title="Chapter 1. Building and Testing"> +<link rel="prev" href="choosing_a_boost_python_library_.html" title="Choosing a Boost.Python Library Binary"> +<link rel="next" href="python_debugging_builds.html" title="Python Debugging Builds"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="choosing_a_boost_python_library_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="python_debugging_builds.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="building.include_issues"></a><a class="link" href="include_issues.html" title="#include Issues"><code class="computeroutput"><span class="preprocessor">#include</span></code> + Issues</a> +</h3></div></div></div> +<p> + 1. If you should ever have occasion to <code class="computeroutput"><span class="preprocessor">#include</span> + <span class="string">"python.h"</span></code> directly in a + translation unit of a program using Boost.Python, use <code class="computeroutput"><span class="preprocessor">#include</span> + <span class="string">"boost/python/detail/wrap_python.hpp"</span></code> + instead. It handles several issues necessary for use with Boost.Python, one + of which is mentioned in the next section. + </p> +<p> + 2. Be sure not to <code class="computeroutput"><span class="preprocessor">#include</span></code> + any system headers before <code class="computeroutput"><span class="identifier">wrap_python</span><span class="special">.</span><span class="identifier">hpp</span></code>. This + restriction is actually imposed by Python, or more properly, by Python's + interaction with your operating system. See <a href="http://docs.python.org/ext/simpleExample.html" target="_top">http://docs.python.org/ext/simpleExample.html</a> + for details. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<br>Copyright © 2002-2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="choosing_a_boost_python_library_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="python_debugging_builds.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/building/installing_boost_python_on_your_.html b/libs/python/doc/html/building/installing_boost_python_on_your_.html new file mode 100644 index 0000000000..2d96c30657 --- /dev/null +++ b/libs/python/doc/html/building/installing_boost_python_on_your_.html @@ -0,0 +1,52 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Installing Boost.Python on your System</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../building.html" title="Chapter 1. Building and Testing"> +<link rel="prev" href="no_install_quickstart.html" title="No-Install Quickstart"> +<link rel="next" href="configuring_boost_build.html" title="Configuring Boost.Build"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="no_install_quickstart.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="configuring_boost_build.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="building.installing_boost_python_on_your_"></a><a class="link" href="installing_boost_python_on_your_.html" title="Installing Boost.Python on your System">Installing + Boost.Python on your System</a> +</h3></div></div></div> +<p> + Since Boost.Python is a separately-compiled (as opposed to <code class="computeroutput"><span class="identifier">header</span><span class="special">-</span><span class="identifier">only</span></code>) library, its user relies on the services + of a Boost.Python library binary. + </p> +<p> + If you need a regular installation of the Boost.Python library binaries on + your system, the Boost <a href="http://www.boost.org/more/getting_started/" target="_top">Getting + Started Guide</a> will walk you through the steps of creating one. If + building binaries from source, you might want to supply the <code class="computeroutput"><span class="special">--</span><span class="identifier">with</span><span class="special">-</span><span class="identifier">python</span></code> + argument to <code class="computeroutput"><span class="identifier">bjam</span></code> (or the + <code class="computeroutput"><span class="special">--</span><span class="identifier">with</span><span class="special">-</span><span class="identifier">libraries</span><span class="special">=</span><span class="identifier">python</span></code> + argument to <code class="computeroutput"><span class="identifier">configure</span></code>), so + only the Boost.Python binary will be built, rather than all the Boost binaries. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<br>Copyright © 2002-2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="no_install_quickstart.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="configuring_boost_build.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/building/no_install_quickstart.html b/libs/python/doc/html/building/no_install_quickstart.html new file mode 100644 index 0000000000..714d3850f4 --- /dev/null +++ b/libs/python/doc/html/building/no_install_quickstart.html @@ -0,0 +1,318 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>No-Install Quickstart</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../building.html" title="Chapter 1. Building and Testing"> +<link rel="prev" href="background.html" title="Background"> +<link rel="next" href="installing_boost_python_on_your_.html" title="Installing Boost.Python on your System"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="background.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="installing_boost_python_on_your_.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="building.no_install_quickstart"></a><a class="link" href="no_install_quickstart.html" title="No-Install Quickstart">No-Install Quickstart</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.basic_procedure">Basic + Procedure</a></span></dt> +<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.in_case_of_trouble">In + Case of Trouble</a></span></dt> +<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.in_case_everything_seemed_to_wor">In + Case Everything Seemed to Work</a></span></dt> +<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project">Modifying + the Example Project</a></span></dt> +</dl></div> +<p> + There is no need to “install Boost” in order to get started using Boost.Python. + These instructions use <a href="http://www.boost.org/build" target="_top">Boost.Build</a> + projects, which will build those binaries as soon as they're needed. Your + first tests may take a little longer while you wait for Boost.Python to build, + but doing things this way will save you from worrying about build intricacies + like which library binaries to use for a specific compiler configuration + and figuring out the right compiler options to use yourself. + </p> +<div class="note"><table border="0" summary="Note"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> +<th align="left">Note</th> +</tr> +<tr><td align="left" valign="top"> +<p> + Of course it's possible to use other build systems to build Boost.Python + and its extensions, but they are not officially supported by Boost. Moreover + <span class="bold"><strong>99% of all “I can't build Boost.Python” problems + come from trying to use another build system</strong></span> without first following + these instructions. + </p> +<p> + If you want to use another system anyway, we suggest that you follow these + instructions, and then invoke <code class="computeroutput"><span class="identifier">bjam</span></code> + with the + </p> +<p> + <code class="computeroutput"><span class="special">-</span><span class="identifier">a</span> + <span class="special">-</span><span class="identifier">o</span></code><span class="emphasis"><em>filename</em></span> + </p> +<p> + options to dump the build commands it executes to a file, so you can see + what your alternate build system needs to do. + </p> +</td></tr> +</table></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="building.no_install_quickstart.basic_procedure"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.basic_procedure" title="Basic Procedure">Basic + Procedure</a> +</h4></div></div></div> +<p> + 1. Get Boost; see sections 1 and 2 of the Boost <a href="http://www.boost.org/more/getting_started/" target="_top">Getting + Started Guide</a>. + </p> +<p> + 2. Get the <code class="computeroutput"><span class="identifier">bjam</span></code> build driver. + See section 5 of the Boost <a href="http://www.boost.org/more/getting_started/" target="_top">Getting + Started Guide</a>. + </p> +<p> + 3. cd into the <code class="computeroutput"><span class="identifier">example</span><span class="special">/</span><span class="identifier">quickstart</span><span class="special">/</span></code> directory of your Boost.Python installation, + which contains a small example project. + </p> +<p> + 4. Invoke <code class="computeroutput"><span class="identifier">bjam</span></code>. Replace + the “<code class="computeroutput"><span class="identifier">stage</span></code>“ argument + from the example invocation from section 5 of the Boost <a href="http://www.boost.org/more/getting_started/" target="_top">Getting + Started Guide</a> with “<code class="computeroutput"><span class="identifier">test</span></code>,“ + to build all the test targets. Also add the argument “<code class="computeroutput"><span class="special">--</span><span class="identifier">verbose</span><span class="special">-</span><span class="identifier">test</span></code>” to see the output generated by + the tests when they are run. On Windows, your <code class="computeroutput"><span class="identifier">bjam</span></code> + invocation might look something like: + </p> +<pre class="programlisting"><span class="identifier">C</span><span class="special">:\\...\\</span><span class="identifier">quickstart</span><span class="special">></span> <span class="identifier">bjam</span> <span class="identifier">toolset</span><span class="special">=</span><span class="identifier">msvc</span> <span class="special">--</span><span class="identifier">verbose</span><span class="special">-</span><span class="identifier">test</span> <span class="identifier">test</span> +</pre> +<p> + and on Unix variants, perhaps, + </p> +<pre class="programlisting"><span class="special">.../</span><span class="identifier">quickstart</span><span class="error">$</span> <span class="identifier">bjam</span> <span class="identifier">toolset</span><span class="special">=</span><span class="identifier">gcc</span> <span class="special">--</span><span class="identifier">verbose</span><span class="special">-</span><span class="identifier">test</span> <span class="identifier">test</span> +</pre> +<div class="note"><table border="0" summary="Note"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> +<th align="left">Note</th> +</tr> +<tr><td align="left" valign="top"><p> + For the sake of concision, the rest of this guide will use unix-style + forward slashes in pathnames instead of the backslashes with which Windows + users may be more familiar. The forward slashes should work everywhere + except in <a href="http://www.boost.org/more/getting_started/windows.html#command-prompt" target="_top">Command + Prompt</a> windows, where you should use backslashes. + </p></td></tr> +</table></div> +<p> + If you followed this procedure successfully, you will have built an extension + module called <code class="computeroutput"><span class="identifier">extending</span></code> + and tested it by running a Python script called <code class="computeroutput"><span class="identifier">test_extending</span><span class="special">.</span><span class="identifier">py</span></code>. + You will also have built and run a simple application called <code class="computeroutput"><span class="identifier">embedding</span></code> that embeds python. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="building.no_install_quickstart.in_case_of_trouble"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.in_case_of_trouble" title="In Case of Trouble">In + Case of Trouble</a> +</h4></div></div></div> +<p> + If you're seeing lots of compiler and/or linker error messages, it's probably + because Boost.Build is having trouble finding your Python installation. + You might want to pass the <code class="computeroutput"><span class="special">--</span><span class="identifier">debug</span><span class="special">-</span><span class="identifier">configuration</span></code> option to <code class="computeroutput"><span class="identifier">bjam</span></code> the first few times you invoke it, + to make sure that Boost.Build is correctly locating all the parts of your + Python installation. If it isn't, consider <a class="link" href="configuring_boost_build.html" title="Configuring Boost.Build">Configuring + Boost.Build</a> as detailed below. + </p> +<p> + If you're still having trouble, Someone on one of the following mailing + lists may be able to help: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + The <a href="http://www.boost.org/more/mailing_lists.htm#jamboost" target="_top">Boost.Build + mailing list</a> for issues related to Boost.Build + </li> +<li class="listitem"> + The <a href="http://www.boost.org/more/mailing_lists.htm#cplussig" target="_top">Boost.Python + mailing list</a> for issues specifically related to Boost.Python + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="building.no_install_quickstart.in_case_everything_seemed_to_wor"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.in_case_everything_seemed_to_wor" title="In Case Everything Seemed to Work">In + Case Everything Seemed to Work</a> +</h4></div></div></div> +<p> + Rejoice! If you're new to Boost.Python, at this point it might be a good + idea to ignore build issues for a while and concentrate on learning the + library by going through the <a href="../tutorial/index.html" target="_top">Tutorial</a> + and perhaps some of the <a href="../reference/index.html" target="_top">Reference Manual</a>, + trying out what you've learned about the API by modifying the quickstart + project. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="building.no_install_quickstart.modifying_the_example_project"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project" title="Modifying the Example Project">Modifying + the Example Project</a> +</h4></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project.relocate_the_project">Relocate + the Project</a></span></dt> +<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project.add_new_or_change_names_of_exist">Add + New or Change Names of Existing Source Files</a></span></dt> +<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project.change_the_name_of_your_extensio">Change + the Name of your Extension Module</a></span></dt> +</dl></div> +<p> + If you're content to keep your extension module forever in one source file + called <code class="computeroutput"><span class="identifier">extending</span><span class="special">.</span><span class="identifier">cpp</span></code>, inside your Boost.Python distribution, + and import it forever as <code class="computeroutput"><span class="identifier">extending</span></code>, + then you can stop here. However, it's likely that you will want to make + a few changes. There are a few things you can do without having to learn + <a href="http://www.boost.org/build" target="_top">Boost.Build</a> in depth. + </p> +<p> + The project you just built is specified in two files in the current directory: + <code class="computeroutput"><span class="identifier">boost</span><span class="special">-</span><span class="identifier">build</span><span class="special">.</span><span class="identifier">jam</span></code>, which tells <code class="computeroutput"><span class="identifier">bjam</span></code> + where it can find the interpreted code of the Boost build system, and + <code class="computeroutput"><span class="identifier">Jamroot</span></code>, which describes + the targets you just built. These files are heavily commented, so they + should be easy to modify. Take care, however, to preserve whitespace. Punctuation + such as <code class="computeroutput"><span class="special">;</span></code> will not be recognized + as intended by <code class="computeroutput"><span class="identifier">bjam</span></code> if + it is not surrounded by whitespace. + </p> +<div class="section"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="building.no_install_quickstart.modifying_the_example_project.relocate_the_project"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project.relocate_the_project" title="Relocate the Project">Relocate + the Project</a> +</h5></div></div></div> +<p> + You'll probably want to copy this project elsewhere so you can change + it without modifying your Boost distribution. To do that, simply + </p> +<p> + a. copy the entire <code class="computeroutput"><span class="identifier">example</span><span class="special">/</span><span class="identifier">quickstart</span><span class="special">/</span></code> directory into a new directory. + </p> +<p> + b. In the new copies of <code class="computeroutput"><span class="identifier">boost</span><span class="special">-</span><span class="identifier">build</span><span class="special">.</span><span class="identifier">jam</span></code> + and <code class="computeroutput"><span class="identifier">Jamroot</span></code>, locate the + relative path near the top of the file that is clearly marked by a comment, + and edit that path so that it refers to the same directory your Boost + distribution as it referred to when the file was in its original location + in the <code class="computeroutput"><span class="identifier">example</span><span class="special">/</span><span class="identifier">quickstart</span><span class="special">/</span></code> + directory. + </p> +<p> + For example, if you moved the project from <code class="computeroutput"><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">dave</span><span class="special">/</span><span class="identifier">boost_1_34_0</span><span class="special">/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">example</span><span class="special">/</span><span class="identifier">quickstart</span></code> to <code class="computeroutput"><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">dave</span><span class="special">/</span><span class="identifier">my</span><span class="special">-</span><span class="identifier">project</span></code>, you could change the first + path in <code class="computeroutput"><span class="identifier">boost</span><span class="special">-</span><span class="identifier">build</span><span class="special">.</span><span class="identifier">jam</span></code> from + </p> +<pre class="programlisting"><span class="special">../../../../</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">build</span><span class="special">/</span><span class="identifier">src</span> +</pre> +<p> + to + </p> +<pre class="programlisting"><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">dave</span><span class="special">/</span><span class="identifier">boost_1_34_0</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">build</span><span class="special">/</span><span class="identifier">src</span> +</pre> +<p> + and change the first path in <code class="computeroutput"><span class="identifier">Jamroot</span></code> + from + </p> +<pre class="programlisting"><span class="special">../../../..</span> +</pre> +<p> + to + </p> +<pre class="programlisting"><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">dave</span><span class="special">/</span><span class="identifier">boost_1_34_0</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="building.no_install_quickstart.modifying_the_example_project.add_new_or_change_names_of_exist"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project.add_new_or_change_names_of_exist" title="Add New or Change Names of Existing Source Files">Add + New or Change Names of Existing Source Files</a> +</h5></div></div></div> +<p> + The names of additional source files involved in building your extension + module or embedding application can be listed in <code class="computeroutput"><span class="identifier">Jamroot</span></code> + right alongside <code class="computeroutput"><span class="identifier">extending</span><span class="special">.</span><span class="identifier">cpp</span></code> + or <code class="computeroutput"><span class="identifier">embedding</span><span class="special">.</span><span class="identifier">cpp</span></code> respectively. Just be sure to leave + whitespace around each filename: + </p> +<pre class="programlisting"><span class="error">…</span> <span class="identifier">file1</span><span class="special">.</span><span class="identifier">cpp</span> <span class="identifier">file2</span><span class="special">.</span><span class="identifier">cpp</span> <span class="identifier">file3</span><span class="special">.</span><span class="identifier">cpp</span> <span class="error">…</span> +</pre> +<p> + Naturally, if you want to change the name of a source file you can tell + Boost.Build about it by editing the name in <code class="computeroutput"><span class="identifier">Jamroot</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="building.no_install_quickstart.modifying_the_example_project.change_the_name_of_your_extensio"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project.change_the_name_of_your_extensio" title="Change the Name of your Extension Module">Change + the Name of your Extension Module</a> +</h5></div></div></div> +<p> + The name of the extension module is determined by two things: + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + the name in <code class="computeroutput"><span class="identifier">Jamroot</span></code> + immediately following <code class="computeroutput"><span class="identifier">python</span><span class="special">-</span><span class="identifier">extension</span></code>, + and + </li> +<li class="listitem"> + the name passed to <code class="computeroutput"><span class="identifier">BOOST_PYTHON_MODULE</span></code> + in <code class="computeroutput"><span class="identifier">extending</span><span class="special">.</span><span class="identifier">cpp</span></code>. + </li> +</ol></div> +<p> + To change the name of the extension module from <code class="computeroutput"><span class="identifier">extending</span></code> + to <code class="computeroutput"><span class="identifier">hello</span></code>, you'd edit + <code class="computeroutput"><span class="identifier">Jamroot</span></code>, changing + </p> +<pre class="programlisting"><span class="identifier">python</span><span class="special">-</span><span class="identifier">extension</span> <span class="identifier">extending</span> <span class="special">:</span> <span class="identifier">extending</span><span class="special">.</span><span class="identifier">cpp</span> <span class="special">;</span> +</pre> +<p> + to + </p> +<pre class="programlisting"><span class="identifier">python</span><span class="special">-</span><span class="identifier">extension</span> <span class="identifier">hello</span> <span class="special">:</span> <span class="identifier">extending</span><span class="special">.</span><span class="identifier">cpp</span> <span class="special">;</span> +</pre> +<p> + and you'd edit extending.cpp, changing + </p> +<pre class="programlisting"><span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">extending</span><span class="special">)</span> +</pre> +<p> + to + </p> +<pre class="programlisting"><span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">hello</span><span class="special">)</span> +</pre> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<br>Copyright © 2002-2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="background.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="installing_boost_python_on_your_.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/building/notes_for_mingw_and_cygwin_with_.html b/libs/python/doc/html/building/notes_for_mingw_and_cygwin_with_.html new file mode 100644 index 0000000000..c3303f3367 --- /dev/null +++ b/libs/python/doc/html/building/notes_for_mingw_and_cygwin_with_.html @@ -0,0 +1,47 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../building.html" title="Chapter 1. Building and Testing"> +<link rel="prev" href="testing_boost_python.html" title="Testing Boost.Python"> +<link rel="next" href="../configuration.html" title="Chapter 2. Configuration"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="testing_boost_python.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../configuration.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="building.notes_for_mingw_and_cygwin_with_"></a><a class="link" href="notes_for_mingw_and_cygwin_with_.html" title="Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users">Notes for + MinGW (and Cygwin with -mno-cygwin) GCC Users</a> +</h3></div></div></div> +<p> + If you are using a version of Python prior to 2.4.1 with a MinGW prior to + 3.0.0 (with binutils-2.13.90-20030111-1), you will need to create a MinGW-compatible + version of the Python library; the one shipped with Python will only work + with a Microsoft-compatible linker. Follow the instructions in the “Non-Microsoft” + section of the “Building Extensions: Tips And Tricks” chapter in <a href="https://docs.python.org/2/install/index.html" target="_top">Installing Python Modules</a> + to create <code class="computeroutput"><span class="identifier">libpythonXX</span><span class="special">.</span><span class="identifier">a</span></code>, where <code class="computeroutput"><span class="identifier">XX</span></code> + corresponds to the major and minor version numbers of your Python installation. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<br>Copyright © 2002-2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="testing_boost_python.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../configuration.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/building/python_debugging_builds.html b/libs/python/doc/html/building/python_debugging_builds.html new file mode 100644 index 0000000000..6b4992f6aa --- /dev/null +++ b/libs/python/doc/html/building/python_debugging_builds.html @@ -0,0 +1,78 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Python Debugging Builds</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../building.html" title="Chapter 1. Building and Testing"> +<link rel="prev" href="include_issues.html" title="#include Issues"> +<link rel="next" href="testing_boost_python.html" title="Testing Boost.Python"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="include_issues.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="testing_boost_python.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="building.python_debugging_builds"></a><a class="link" href="python_debugging_builds.html" title="Python Debugging Builds">Python Debugging Builds</a> +</h3></div></div></div> +<p> + Python can be built in a special “python debugging” configuration that + adds extra checks and instrumentation that can be very useful for developers + of extension modules. The data structures used by the debugging configuration + contain additional members, so <span class="bold"><strong>a Python executable + built with python debugging enabled cannot be used with an extension module + or library compiled without it, and vice-versa.</strong></span> + </p> +<p> + Since pre-built “python debugging” versions of the Python executable + and libraries are not supplied with most distributions of Python, <a href="#ftn.building.python_debugging_builds.f0" class="footnote" name="building.python_debugging_builds.f0"><sup class="footnote">[5]</sup></a> and we didn't want to force our users to build them, Boost.Build + does not automatically enable python debugging in its <code class="computeroutput"><span class="identifier">debug</span></code> + build variant (which is the default). Instead there is a special build property + called <code class="computeroutput"><span class="identifier">python</span><span class="special">-</span><span class="identifier">debugging</span></code> that, when used as a build property, + will define the right preprocessor symbols and select the right libraries + to link with. + </p> +<p> + On unix-variant platforms, the debugging versions of Python's data structures + will only be used if the symbol <code class="computeroutput"><span class="identifier">Py_DEBUG</span></code> + is defined. On many windows compilers, when extension modules are built with + the preprocessor symbol <code class="computeroutput"><span class="identifier">_DEBUG</span></code>, + Python defaults to force linking with a special debugging version of the + Python DLL. Since that symbol is very commonly used even when Python is not + present, Boost.Python temporarily undefines <code class="computeroutput"><span class="identifier">_DEBUG</span></code> + when <code class="computeroutput"><span class="identifier">Python</span><span class="special">.</span><span class="identifier">h</span></code> is #included from <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">detail</span><span class="special">/</span><span class="identifier">wrap_python</span><span class="special">.</span><span class="identifier">hpp</span></code> - + unless <code class="computeroutput"><span class="identifier">BOOST_DEBUG_PYTHON</span></code> + is defined. The upshot is that if you want “python debugging”and you + aren't using Boost.Build, you should make sure <code class="computeroutput"><span class="identifier">BOOST_DEBUG_PYTHON</span></code> + is defined, or python debugging will be suppressed. + </p> +<div class="footnotes"> +<br><hr style="width:100; text-align:left;margin-left: 0"> +<div id="ftn.building.python_debugging_builds.f0" class="footnote"><p><a href="#building.python_debugging_builds.f0" class="para"><sup class="para">[5] </sup></a> + On Unix and similar platforms, a debugging python and associated libraries + are built by adding --with-pydebug when configuring the Python build. On + Windows, the debugging version of Python is generated by the "Win32 + Debug" target of the Visual Studio project in the PCBuild subdirectory + of a full Python source code distribution. + </p></div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<br>Copyright © 2002-2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="include_issues.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="testing_boost_python.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/building/testing_boost_python.html b/libs/python/doc/html/building/testing_boost_python.html new file mode 100644 index 0000000000..dc8196238c --- /dev/null +++ b/libs/python/doc/html/building/testing_boost_python.html @@ -0,0 +1,42 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Testing Boost.Python</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../building.html" title="Chapter 1. Building and Testing"> +<link rel="prev" href="python_debugging_builds.html" title="Python Debugging Builds"> +<link rel="next" href="notes_for_mingw_and_cygwin_with_.html" title="Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="python_debugging_builds.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="notes_for_mingw_and_cygwin_with_.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="building.testing_boost_python"></a><a class="link" href="testing_boost_python.html" title="Testing Boost.Python">Testing Boost.Python</a> +</h3></div></div></div> +<p> + To run the full test suite for Boost.Python, invoke <code class="computeroutput"><span class="identifier">bjam</span></code> + in the <code class="computeroutput"><span class="identifier">test</span></code> subdirectory + of your Boost.Python distribution. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<br>Copyright © 2002-2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="python_debugging_builds.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="notes_for_mingw_and_cygwin_with_.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/configuration.html b/libs/python/doc/html/configuration.html new file mode 100644 index 0000000000..61b26e7413 --- /dev/null +++ b/libs/python/doc/html/configuration.html @@ -0,0 +1,350 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 2. Configuration</title> +<link rel="stylesheet" href="boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python"> +<link rel="up" href="index.html" title="Boost.Python"> +<link rel="prev" href="building/notes_for_mingw_and_cygwin_with_.html" title="Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users"> +<link rel="next" href="support.html" title="Chapter 3. Support Resources"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="building/notes_for_mingw_and_cygwin_with_.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="support.html"><img src="images/next.png" alt="Next"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div> +<div><h1 class="title"> +<a name="configuration"></a>Chapter 2. Configuration</h1></div> +<div><div class="authorgroup"><div class="author"><h3 class="author"> +<span class="firstname">David</span> <span class="surname">Abrahams</span> +</h3></div></div></div> +<div><p class="copyright">Copyright © 2002-2015 David Abrahams, Stefan Seefeld</p></div> +</div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="configuration.html#configuration.configuration">Configuration</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="configuration.html#configuration.configuration.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="configuration.html#configuration.configuration.application_defined_macros">Application + Defined Macros</a></span></dt> +<dt><span class="section"><a href="configuration.html#configuration.configuration.library_defined_defined_macros">Library + Defined Defined Macros</a></span></dt> +</dl></dd> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="configuration.configuration"></a><a class="link" href="configuration.html#configuration.configuration" title="Configuration">Configuration</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="configuration.html#configuration.configuration.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="configuration.html#configuration.configuration.application_defined_macros">Application + Defined Macros</a></span></dt> +<dt><span class="section"><a href="configuration.html#configuration.configuration.library_defined_defined_macros">Library + Defined Defined Macros</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="configuration.configuration.introduction"></a><a class="link" href="configuration.html#configuration.configuration.introduction" title="Introduction">Introduction</a> +</h4></div></div></div> +<p> + <span class="bold"><strong>Boost.Python</strong></span> uses several configuration + macros in <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code>, as well as configuration macros meant + to be supplied by the application. These macros are documented here. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="configuration.configuration.application_defined_macros"></a><a class="link" href="configuration.html#configuration.configuration.application_defined_macros" title="Application Defined Macros">Application + Defined Macros</a> +</h4></div></div></div> +<p> + These are the macros that may be defined by an application using Boost.Python. + Note that if you extend a strict interpretation of the C++ standard to + cover dynamic libraries, using different values of these macros when compiling + different libraries (including extension modules and the Boost.Python library + itself) is a violation of the <a class="link" href="glossary.html#odr">ODR</a>. However, + we know of no C++ implementations on which this particular violation is + detectable or causes any problems. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Macro + </p> + </th> +<th> + <p> + Default + </p> + </th> +<th> + <p> + Meaning + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + BOOST_PYTHON_MAX_ARITY + </p> + </td> +<td> + <p> + 15 + </p> + </td> +<td> + <p> + The maximum arity of any function, member function, or constructor + to be wrapped, invocation of a Boost.Python function wich is + specified as taking arguments x1, x2,...Xn. This includes, in + particular, callback mechanisms such as object::operator()(...) + or call_method<R>(... ). + </p> + </td> +</tr> +<tr> +<td> + <p> + BOOST_PYTHON_MAX_BASES + </p> + </td> +<td> + <p> + 10 + </p> + </td> +<td> + <p> + The maximum number of template arguments to the <code class="computeroutput"><span class="identifier">bases</span><span class="special"><...></span></code> + class template, which is used to specify the bases of a wrapped + C++ class.. + </p> + </td> +</tr> +<tr> +<td> + <p> + BOOST_PYTHON_STATIC_MODULE + </p> + </td> +<td> + <p> + <span class="emphasis"><em>not defined</em></span> + </p> + </td> +<td> + <p> + If defined, prevents your module initialization function from + being treated as an exported symbol on platforms which support + that distinction in-code + </p> + </td> +</tr> +<tr> +<td> + <p> + BOOST_PYTHON_ENABLE_CDECL + </p> + </td> +<td> + <p> + <span class="emphasis"><em>not defined</em></span> + </p> + </td> +<td> + <p> + If defined, allows functions using the <code class="computeroutput"><span class="identifier">__cdecl</span></code> + calling convention to be wrapped. + </p> + </td> +</tr> +<tr> +<td> + <p> + BOOST_PYTHON_ENABLE_STDCALL + </p> + </td> +<td> + <p> + <span class="emphasis"><em>not defined</em></span> + </p> + </td> +<td> + <p> + If defined, allows functions using the <code class="computeroutput"><span class="identifier">__stdcall</span></code> + calling convention to be wrapped. + </p> + </td> +</tr> +<tr> +<td> + <p> + BOOST_PYTHON_ENABLE_FASTCALL + </p> + </td> +<td> + <p> + <span class="emphasis"><em>not defined</em></span> + </p> + </td> +<td> + <p> + If defined, allows functions using the <code class="computeroutput"><span class="identifier">__fastcall</span></code> + calling convention to be wrapped. + </p> + </td> +</tr> +</tbody> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="configuration.configuration.library_defined_defined_macros"></a><a class="link" href="configuration.html#configuration.configuration.library_defined_defined_macros" title="Library Defined Defined Macros">Library + Defined Defined Macros</a> +</h4></div></div></div> +<p> + These macros are defined by <span class="bold"><strong>Boost.Python</strong></span> + and are implementation details of interest only to implementors and those + porting to new platforms. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Macro + </p> + </th> +<th> + <p> + Default + </p> + </th> +<th> + <p> + Meaning + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + BOOST_PYTHON_TYPE_ID_NAME + </p> + </td> +<td> + <p> + <span class="emphasis"><em>not defined</em></span> + </p> + </td> +<td> + <p> + If defined, this indicates that the type_info comparison across + shared library boundaries does not work on this platform. In + other words, if shared-lib-1 passes <code class="computeroutput"><span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">)</span></code> to a function in shared-lib-2 + which compares it to <code class="computeroutput"><span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">)</span></code>, that comparison may return + <code class="computeroutput"><span class="keyword">false</span></code>. If this macro + is #defined, Boost.Python uses and compares <code class="computeroutput"><span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">).</span><span class="identifier">name</span><span class="special">()</span></code> instead of using and comparing + the <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">type_info</span></code> objects directly. + </p> + </td> +</tr> +<tr> +<td> + <p> + BOOST_PYTHON_NO_PY_SIGNATURES + </p> + </td> +<td> + <p> + <span class="emphasis"><em>not defined</em></span> + </p> + </td> +<td> + <p> + If defined for a module no pythonic signatures are generated + for the docstrings of the module functions, and no python type + is associated with any of the converters registered by the module. + This also reduces the binary size of the module by about 14% + (gcc compiled). If defined for the boost_python runtime library, + the default for the <code class="computeroutput"><span class="identifier">docstring_options</span><span class="special">.</span><span class="identifier">enable_py_signatures</span><span class="special">()</span></code> is set to <code class="computeroutput"><span class="keyword">false</span></code>. + </p> + </td> +</tr> +<tr> +<td> + <p> + BOOST_PYTHON_SUPPORTS_PY_SIGNATURES + </p> + </td> +<td> + <p> + <span class="emphasis"><em>defined</em></span> if <code class="computeroutput"><span class="identifier">BOOST_PYTHON_NO_PY_SIGNATURES</span></code> + is <span class="emphasis"><em>undefined</em></span> + </p> + </td> +<td> + <p> + This macro is defined to enable a smooth transition from older + Boost.Python versions which do not support pythonic signatures. + For example usage see here. + </p> + </td> +</tr> +<tr> +<td> + <p> + BOOST_PYTHON_PY_SIGNATURES_PROPER_INIT_SELF_TYPE + </p> + </td> +<td> + <p> + <span class="emphasis"><em>not defined</em></span> + </p> + </td> +<td> + <p> + If defined the python type of <code class="computeroutput"><span class="identifier">__init__</span></code> + method "self" parameters is properly generated, otherwise + object is used. It is undefined by default because it increases + the binary size of the module by about 14% (gcc compiled). + </p> + </td> +</tr> +</tbody> +</table></div> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="building/notes_for_mingw_and_cygwin_with_.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="support.html"><img src="images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/docutils.css b/libs/python/doc/html/docutils.css new file mode 100644 index 0000000000..620cf86102 --- /dev/null +++ b/libs/python/doc/html/docutils.css @@ -0,0 +1,275 @@ +/* +:Author: David Goodger +:Contact: goodger@python.org +:Date: $Date$ +:Revision: $Revision$ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin-left: 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left { + clear: left } + +img.align-right { + clear: right } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font-family: serif ; + font-size: 100% } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } diff --git a/libs/python/doc/html/faq.html b/libs/python/doc/html/faq.html new file mode 100644 index 0000000000..4206c87ae7 --- /dev/null +++ b/libs/python/doc/html/faq.html @@ -0,0 +1,116 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 4. Frequently Asked Questions (FAQs)</title> +<link rel="stylesheet" href="boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python"> +<link rel="up" href="index.html" title="Boost.Python"> +<link rel="prev" href="support.html" title="Chapter 3. Support Resources"> +<link rel="next" href="faq/i_m_getting_the_attempt_to_retur.html" title="I'm getting the "attempt to return dangling reference" error. What am I doing wrong?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="support.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="faq/i_m_getting_the_attempt_to_retur.html"><img src="images/next.png" alt="Next"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="faq"></a>Chapter 4. Frequently Asked Questions (FAQs)</h1></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="faq.html#faq.how_can_i_wrap_a_function_which_">How can I wrap + a function which takes a function pointer as an argument?</a></span></dt> +<dt><span class="section"><a href="faq/i_m_getting_the_attempt_to_retur.html">I'm getting the + "attempt to return dangling reference" error. What am I doing wrong?</a></span></dt> +<dt><span class="section"><a href="faq/is_return_internal_reference_eff.html">Is <code class="computeroutput"><span class="identifier">return_internal_reference</span></code> efficient?</a></span></dt> +<dt><span class="section"><a href="faq/how_can_i_wrap_functions_which_t.html">How can I wrap + functions which take C++ containers as arguments?</a></span></dt> +<dt><span class="section"><a href="faq/fatal_error_c1204_compiler_limit.html">fatal error C1204:Compiler + limit:internal structure overflow</a></span></dt> +<dt><span class="section"><a href="faq/how_do_i_debug_my_python_extensi.html">How do I debug + my Python extensions?</a></span></dt> +<dt><span class="section"><a href="faq/why_doesn_t_my_operator_work.html">Why doesn't my <code class="computeroutput"><span class="special">*=</span></code> operator work?</a></span></dt> +<dt><span class="section"><a href="faq/does_boost_python_work_with_mac_.html">Does Boost.Python + work with Mac OS X?</a></span></dt> +<dt><span class="section"><a href="faq/how_can_i_find_the_existing_pyob.html">How can I find + the existing PyObject that holds a C++ object?</a></span></dt> +<dt><span class="section"><a href="faq/how_can_i_wrap_a_function_which0.html">How can I wrap + a function which needs to take ownership of a raw pointer?</a></span></dt> +<dt><span class="section"><a href="faq/compilation_takes_too_much_time_.html">Compilation takes + too much time and eats too much memory! What can I do to make it faster?</a></span></dt> +<dt><span class="section"><a href="faq/how_do_i_create_sub_packages_usi.html">How do I create + sub-packages using Boost.Python?</a></span></dt> +<dt><span class="section"><a href="faq/error_c2064_term_does_not_evalua.html">error C2064: term + does not evaluate to a function taking 2 arguments</a></span></dt> +<dt><span class="section"><a href="faq/how_can_i_automatically_convert_.html">How can I automatically + convert my custom string type to and from a Python string?</a></span></dt> +<dt><span class="section"><a href="faq/why_is_my_automatic_to_python_co.html">Why is my automatic + to-python conversion not being found?</a></span></dt> +<dt><span class="section"><a href="faq/is_boost_python_thread_aware_com.html">Is Boost.Python + thread-aware/compatible with multiple interpreters?</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.how_can_i_wrap_a_function_which_"></a><a class="link" href="faq.html#faq.how_can_i_wrap_a_function_which_" title="How can I wrap a function which takes a function pointer as an argument?">How can I wrap + a function which takes a function pointer as an argument?</a> +</h3></div></div></div> +<p> + If what you're trying to do is something like this: + </p> +<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">function</span><span class="special"><</span><span class="keyword">void</span> <span class="special">(</span><span class="identifier">string</span> <span class="identifier">s</span><span class="special">)</span> <span class="special">></span> <span class="identifier">funcptr</span><span class="special">;</span> + +<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span><span class="identifier">funcptr</span> <span class="identifier">fp</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">fp</span><span class="special">(</span><span class="string">"hello,world!"</span><span class="special">);</span> +<span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">test</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span><span class="identifier">foo</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + And then: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">def</span> <span class="identifier">hello</span><span class="special">(</span><span class="identifier">s</span><span class="special">):</span> +<span class="special">...</span> <span class="identifier">print</span> <span class="identifier">s</span> +<span class="special">...</span> +<span class="special">>>></span> <span class="identifier">foo</span><span class="special">(</span><span class="identifier">hello</span><span class="special">)</span> +<span class="identifier">hello</span><span class="special">,</span> <span class="identifier">world</span><span class="special">!</span> +</pre> +<p> + The short answer is: "you can't". This is not a Boost.Python limitation + so much as a limitation of C++. The problem is that a Python function is + actually data, and the only way of associating data with a C++ function pointer + is to store it in a static variable of the function. The problem with that + is that you can only associate one piece of data with every C++ function, + and we have no way of compiling a new C++ function on-the-fly for every Python + function you decide to pass to <code class="computeroutput"><span class="identifier">foo</span></code>. + In other words, this could work if the C++ function is always going to invoke + the <span class="emphasis"><em>same</em></span> Python function, but you probably don't want + that. + </p> +<p> + If you have the luxury of changing the C++ code you're wrapping, pass it + an <code class="computeroutput"><span class="identifier">object</span></code> instead and call + that; the overloaded function call operator will invoke the Python function + you pass it behind the <code class="computeroutput"><span class="identifier">object</span></code>. + </p> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="support.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="faq/i_m_getting_the_attempt_to_retur.html"><img src="images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/compilation_takes_too_much_time_.html b/libs/python/doc/html/faq/compilation_takes_too_much_time_.html new file mode 100644 index 0000000000..3e99deee42 --- /dev/null +++ b/libs/python/doc/html/faq/compilation_takes_too_much_time_.html @@ -0,0 +1,42 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Compilation takes too much time and eats too much memory! What can I do to make it faster?</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="how_can_i_wrap_a_function_which0.html" title="How can I wrap a function which needs to take ownership of a raw pointer?"> +<link rel="next" href="how_do_i_create_sub_packages_usi.html" title="How do I create sub-packages using Boost.Python?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="how_can_i_wrap_a_function_which0.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="how_do_i_create_sub_packages_usi.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.compilation_takes_too_much_time_"></a><a class="link" href="compilation_takes_too_much_time_.html" title="Compilation takes too much time and eats too much memory! What can I do to make it faster?">Compilation takes + too much time and eats too much memory! What can I do to make it faster?</a> +</h3></div></div></div> +<p> + Please refer to the <code class="computeroutput"><span class="identifier">Reducing</span> <span class="identifier">Compiling</span> <span class="identifier">Time</span></code> + section in the <a href="../tutorial/index.html" target="_top">Tutorial</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="how_can_i_wrap_a_function_which0.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="how_do_i_create_sub_packages_usi.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/does_boost_python_work_with_mac_.html b/libs/python/doc/html/faq/does_boost_python_work_with_mac_.html new file mode 100644 index 0000000000..6f61f8dbf8 --- /dev/null +++ b/libs/python/doc/html/faq/does_boost_python_work_with_mac_.html @@ -0,0 +1,93 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Does Boost.Python work with Mac OS X?</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="why_doesn_t_my_operator_work.html" title="Why doesn't my *= operator work?"> +<link rel="next" href="how_can_i_find_the_existing_pyob.html" title="How can I find the existing PyObject that holds a C++ object?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="why_doesn_t_my_operator_work.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="how_can_i_find_the_existing_pyob.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.does_boost_python_work_with_mac_"></a><a class="link" href="does_boost_python_work_with_mac_.html" title="Does Boost.Python work with Mac OS X?">Does Boost.Python + work with Mac OS X?</a> +</h3></div></div></div> +<p> + It is known to work under 10.2.8 and 10.3 using Apple's gcc 3.3 compiler: + </p> +<pre class="programlisting"><span class="identifier">gcc</span> <span class="special">(</span><span class="identifier">GCC</span><span class="special">)</span> <span class="number">3.3</span> <span class="number">20030304</span> <span class="special">(</span><span class="identifier">Apple</span> <span class="identifier">Computer</span><span class="special">,</span> <span class="identifier">Inc</span><span class="special">.</span> <span class="identifier">build</span> <span class="number">1493</span><span class="special">)</span></pre> +<p> + Under 10.2.8 get the August 2003 gcc update (free at <a href="http://connect.apple.com" target="_top">http://connect.apple.com</a>). + Under 10.3 get the Xcode Tools v1.0 (also free). + </p> +<p> + Python 2.3 is required. The Python that ships with 10.3 is fine. Under 10.2.8 + use these commands to install Python as a framework: + </p> +<pre class="programlisting"><span class="special">./</span><span class="identifier">configure</span> <span class="special">--</span><span class="identifier">enable</span><span class="special">-</span><span class="identifier">framework</span> +<span class="identifier">make</span> +<span class="identifier">make</span> <span class="identifier">frameworkinstall</span></pre> +<p> + The last command requires root privileges because the target directory is + <code class="computeroutput"><span class="special">/</span><span class="identifier">Library</span><span class="special">/</span><span class="identifier">Frameworks</span><span class="special">/</span><span class="identifier">Python</span><span class="special">.</span><span class="identifier">framework</span><span class="special">/</span><span class="identifier">Versions</span><span class="special">/</span><span class="number">2.3</span></code>. However, + the installation does not interfere with the Python version that ships with + 10.2.8. + </p> +<p> + It is also crucial to increase the <code class="computeroutput"><span class="identifier">stacksize</span></code> + before starting compilations, e.g.: + </p> +<pre class="programlisting"><span class="identifier">limit</span> <span class="identifier">stacksize</span> <span class="number">8192</span><span class="identifier">k</span></pre> +<p> + If the <code class="computeroutput"><span class="identifier">stacksize</span></code> is too small + the build might crash with internal compiler errors. + </p> +<p> + Sometimes Apple's compiler exhibits a bug by printing an error like the following + while compiling a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">class_</span><span class="special"><</span><span class="identifier">your_type</span><span class="special">></span></code> + template instantiation: + </p> +<pre class="programlisting"><span class="special">.../</span><span class="identifier">inheritance</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">:</span><span class="number">44</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">cannot</span> + <span class="keyword">dynamic_cast</span> <span class="error">`</span><span class="identifier">p</span><span class="char">' (of type `struct cctbx::boost_python::<unnamed>::add_pair* + '</span><span class="special">)</span> <span class="identifier">to</span> <span class="identifier">type</span> <span class="error">`</span><span class="keyword">void</span><span class="special">*</span><span class="error">'</span> <span class="special">(</span><span class="identifier">source</span> <span class="identifier">type</span> <span class="identifier">is</span> <span class="keyword">not</span> <span class="identifier">polymorphic</span><span class="special">)</span> +</pre> +<p> + We do not know a general workaround, but if the definition of <code class="computeroutput"><span class="identifier">your_type</span></code> can be modified the following + was found to work in all cases encountered so far: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">your_type</span> +<span class="special">{</span> + <span class="comment">// before defining any member data</span> +<span class="preprocessor">#if</span> <span class="identifier">defined</span><span class="special">(</span><span class="identifier">__MACH__</span><span class="special">)</span> <span class="special">&</span><span class="identifier">amp</span><span class="special">;&</span><span class="identifier">amp</span><span class="special">;</span> <span class="identifier">defined</span><span class="special">(</span><span class="identifier">__APPLE_CC__</span><span class="special">)</span> <span class="special">&</span><span class="identifier">amp</span><span class="special">;&</span><span class="identifier">amp</span><span class="special">;</span> <span class="identifier">__APPLE_CC__</span> <span class="special">==</span> <span class="number">1493</span> + <span class="keyword">bool</span> <span class="identifier">dummy_</span><span class="special">;</span> +<span class="preprocessor">#endif</span> + <span class="comment">// now your member data, e.g.</span> + <span class="keyword">double</span> <span class="identifier">x</span><span class="special">;</span> + <span class="keyword">int</span> <span class="identifier">j</span><span class="special">;</span> + <span class="comment">// etc.</span> +<span class="special">};</span> +</pre> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="why_doesn_t_my_operator_work.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="how_can_i_find_the_existing_pyob.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/error_c2064_term_does_not_evalua.html b/libs/python/doc/html/faq/error_c2064_term_does_not_evalua.html new file mode 100644 index 0000000000..179789ac52 --- /dev/null +++ b/libs/python/doc/html/faq/error_c2064_term_does_not_evalua.html @@ -0,0 +1,77 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>error C2064: term does not evaluate to a function taking 2 arguments</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="how_do_i_create_sub_packages_usi.html" title="How do I create sub-packages using Boost.Python?"> +<link rel="next" href="how_can_i_automatically_convert_.html" title="How can I automatically convert my custom string type to and from a Python string?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="how_do_i_create_sub_packages_usi.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="how_can_i_automatically_convert_.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.error_c2064_term_does_not_evalua"></a><a class="link" href="error_c2064_term_does_not_evalua.html" title="error C2064: term does not evaluate to a function taking 2 arguments">error C2064: term + does not evaluate to a function taking 2 arguments</a> +</h3></div></div></div> +<p> + <span class="emphasis"><em>Niall Douglas provides these notes:</em></span> + </p> +<p> + If you see Microsoft Visual C++ 7.1 (MS Visual Studio .NET 2003) issue an + error message like the following it is most likely due to a bug in the compiler: + </p> +<pre class="programlisting"><span class="identifier">boost</span><span class="special">\</span><span class="identifier">boost</span><span class="special">\</span><span class="identifier">python</span><span class="special">\</span><span class="identifier">detail</span><span class="special">\</span><span class="identifier">invoke</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">(</span><span class="number">76</span><span class="special">):</span> +<span class="identifier">error</span> <span class="identifier">C2064</span><span class="special">:</span> <span class="identifier">term</span> <span class="identifier">does</span> <span class="keyword">not</span> <span class="identifier">evaluate</span> <span class="identifier">to</span> <span class="identifier">a</span> <span class="identifier">function</span> <span class="identifier">taking</span> <span class="number">2</span> <span class="identifier">arguments</span><span class="error">"</span> +</pre> +<p> + This message is triggered by code like the following: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="keyword">class</span> <span class="identifier">FXThread</span> +<span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + <span class="keyword">bool</span> <span class="identifier">setAutoDelete</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">doso</span><span class="special">)</span> <span class="keyword">throw</span><span class="special">();</span> +<span class="special">};</span> + +<span class="keyword">void</span> <span class="identifier">Export_FXThread</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span> <span class="identifier">FXThread</span> <span class="special">>(</span><span class="string">"FXThread"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"setAutoDelete"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">amp</span><span class="special">;</span><span class="identifier">FXThread</span><span class="special">::</span><span class="identifier">setAutoDelete</span><span class="special">)</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + The bug is related to the <code class="computeroutput"><span class="keyword">throw</span><span class="special">()</span></code> modifier. As a workaround cast off the + modifier. E.g.: + </p> +<pre class="programlisting"><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"setAutoDelete"</span><span class="special">,</span> <span class="special">(</span><span class="keyword">bool</span> <span class="special">(</span><span class="identifier">FXThread</span><span class="special">::*)(</span><span class="keyword">bool</span><span class="special">))</span> <span class="special">&</span><span class="identifier">FXThread</span><span class="special">::</span><span class="identifier">setAutoDelete</span><span class="special">)</span> +</pre> +<p> + (The bug has been reported to Microsoft.) + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="how_do_i_create_sub_packages_usi.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="how_can_i_automatically_convert_.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/fatal_error_c1204_compiler_limit.html b/libs/python/doc/html/faq/fatal_error_c1204_compiler_limit.html new file mode 100644 index 0000000000..c353d6d67b --- /dev/null +++ b/libs/python/doc/html/faq/fatal_error_c1204_compiler_limit.html @@ -0,0 +1,96 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>fatal error C1204:Compiler limit:internal structure overflow</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="how_can_i_wrap_functions_which_t.html" title="How can I wrap functions which take C++ containers as arguments?"> +<link rel="next" href="how_do_i_debug_my_python_extensi.html" title="How do I debug my Python extensions?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="how_can_i_wrap_functions_which_t.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="how_do_i_debug_my_python_extensi.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.fatal_error_c1204_compiler_limit"></a><a class="link" href="fatal_error_c1204_compiler_limit.html" title="fatal error C1204:Compiler limit:internal structure overflow">fatal error C1204:Compiler + limit:internal structure overflow</a> +</h3></div></div></div> +<p> + <span class="bold"><strong>Q:</strong></span> <span class="emphasis"><em>I get this error message when + compiling a large source file. What can I do?</em></span> + </p> +<p> + <span class="bold"><strong>A:</strong></span> You have two choices: + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + Upgrade your compiler (preferred) + </li> +<li class="listitem"> +<p class="simpara"> + Break your source file up into multiple translation units. + </p> +<p class="simpara"> + <code class="computeroutput"><span class="identifier">my_module</span><span class="special">.</span><span class="identifier">cpp</span></code>: + </p> +<pre class="programlisting"><span class="special">...</span> +<span class="keyword">void</span> <span class="identifier">more_of_my_module</span><span class="special">();</span> +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">my_module</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span> <span class="identifier">foo</span><span class="special">);</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"bar"</span><span class="special">,</span> <span class="identifier">bar</span><span class="special">);</span> + <span class="special">...</span> + <span class="identifier">more_of_my_module</span><span class="special">();</span> +<span class="special">}</span> +</pre> +<p class="simpara"> + <code class="computeroutput"><span class="identifier">more_of_my_module</span><span class="special">.</span><span class="identifier">cpp</span></code>: + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">more_of_my_module</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"baz"</span><span class="special">,</span> <span class="identifier">baz</span><span class="special">);</span> + <span class="special">...</span> +<span class="special">}</span> +</pre> +<p class="simpara"> + If you find that a <code class="computeroutput"><span class="identifier">class_</span><span class="special"><...></span></code> declaration can't fit in a + single source file without triggering the error, you can always pass + a reference to the <code class="computeroutput"><span class="identifier">class_</span></code> + object to a function in another source file, and call some of its member + functions (e.g. <code class="computeroutput"><span class="special">.</span><span class="identifier">def</span><span class="special">(...)</span></code>) in the auxilliary source file: + </p> +<p class="simpara"> + <code class="computeroutput"><span class="identifier">more_of_my_class</span><span class="special">.</span><span class="identifier">cpp</span></code>: + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">more_of_my_class</span><span class="special">(</span><span class="keyword">class</span><span class="special">&</span><span class="identifier">lt</span><span class="special">;</span><span class="identifier">my_class</span><span class="special">&</span><span class="identifier">gt</span><span class="special">;&</span><span class="identifier">amp</span><span class="special">;</span> <span class="identifier">x</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">x</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"baz"</span><span class="special">,</span> <span class="identifier">baz</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">add_property</span><span class="special">(</span><span class="string">"xx"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">my_class</span><span class="special">::</span><span class="identifier">get_xx</span><span class="special">,</span> <span class="special">&</span><span class="identifier">my_class</span><span class="special">::</span><span class="identifier">set_xx</span><span class="special">)</span> + <span class="special">;</span> + <span class="special">...</span> +<span class="special">}</span> +</pre> +</li> +</ol></div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="how_can_i_wrap_functions_which_t.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="how_do_i_debug_my_python_extensi.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/how_can_i_automatically_convert_.html b/libs/python/doc/html/faq/how_can_i_automatically_convert_.html new file mode 100644 index 0000000000..ca02ee26de --- /dev/null +++ b/libs/python/doc/html/faq/how_can_i_automatically_convert_.html @@ -0,0 +1,146 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>How can I automatically convert my custom string type to and from a Python string?</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="error_c2064_term_does_not_evalua.html" title="error C2064: term does not evaluate to a function taking 2 arguments"> +<link rel="next" href="why_is_my_automatic_to_python_co.html" title="Why is my automatic to-python conversion not being found?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="error_c2064_term_does_not_evalua.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="why_is_my_automatic_to_python_co.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.how_can_i_automatically_convert_"></a><a class="link" href="how_can_i_automatically_convert_.html" title="How can I automatically convert my custom string type to and from a Python string?">How can I automatically + convert my custom string type to and from a Python string?</a> +</h3></div></div></div> +<p> + <span class="emphasis"><em>Ralf W. Grosse-Kunstleve provides these notes:</em></span> + </p> +<p> + Below is a small, self-contained demo extension module that shows how to + do this. Here is the corresponding trivial test: + </p> +<pre class="programlisting"><span class="identifier">import</span> <span class="identifier">custom_string</span> +<span class="identifier">assert</span> <span class="identifier">custom_string</span><span class="special">.</span><span class="identifier">hello</span><span class="special">()</span> <span class="special">==</span> <span class="string">"Hello world."</span> +<span class="identifier">assert</span> <span class="identifier">custom_string</span><span class="special">.</span><span class="identifier">size</span><span class="special">(</span><span class="string">"california"</span><span class="special">)</span> <span class="special">==</span> <span class="number">10</span> +</pre> +<p> + If you look at the code you will find: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + A custom <code class="computeroutput"><span class="identifier">to_python</span></code> converter + (easy): <code class="computeroutput"><span class="identifier">custom_string_to_python_str</span></code> + </li> +<li class="listitem"> + A custom lvalue converter (needs more code): <code class="computeroutput"><span class="identifier">custom_string_from_python_str</span></code> + </li> +</ul></div> +<p> + The custom converters are registered in the global Boost.Python registry + near the top of the module initialization function. Once flow control has + passed through the registration code the automatic conversions from and to + Python strings will work in any module imported in the same process. + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">to_python_converter</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">namespace</span> <span class="identifier">sandbox</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="special">{</span> + +<span class="keyword">class</span> <span class="identifier">custom_string</span> +<span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">custom_string</span><span class="special">()</span> <span class="special">{}</span> + <span class="identifier">custom_string</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">value</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">value_</span><span class="special">(</span><span class="identifier">value</span><span class="special">)</span> <span class="special">{}</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">value</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">value_</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">value_</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">struct</span> <span class="identifier">custom_string_to_python_str</span> +<span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">convert</span><span class="special">(</span><span class="identifier">custom_string</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">s</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">incref</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span><span class="special">(</span><span class="identifier">s</span><span class="special">.</span><span class="identifier">value</span><span class="special">()).</span><span class="identifier">ptr</span><span class="special">());</span> + <span class="special">}</span> +<span class="special">};</span> + +<span class="keyword">struct</span> <span class="identifier">custom_string_from_python_str</span> +<span class="special">{</span> + <span class="identifier">custom_string_from_python_str</span><span class="special">()</span> + <span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">converter</span><span class="special">::</span><span class="identifier">registry</span><span class="special">::</span><span class="identifier">push_back</span><span class="special">(</span> + <span class="special">&</span><span class="identifier">convertible</span><span class="special">,</span> + <span class="special">&</span><span class="identifier">construct</span><span class="special">,</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">type_id</span><span class="special"><</span><span class="identifier">custom_string</span><span class="special">>());</span> + <span class="special">}</span> + + <span class="keyword">static</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">convertible</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">obj_ptr</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">PyString_Check</span><span class="special">(</span><span class="identifier">obj_ptr</span><span class="special">))</span> <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> + <span class="keyword">return</span> <span class="identifier">obj_ptr</span><span class="special">;</span> + <span class="special">}</span> + + <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">construct</span><span class="special">(</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">obj_ptr</span><span class="special">,</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">converter</span><span class="special">::</span><span class="identifier">rvalue_from_python_stage1_data</span><span class="special">*</span> <span class="identifier">data</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">value</span> <span class="special">=</span> <span class="identifier">PyString_AsString</span><span class="special">(</span><span class="identifier">obj_ptr</span><span class="special">);</span> + <span class="keyword">if</span> <span class="special">(</span><span class="identifier">value</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">throw_error_already_set</span><span class="special">();</span> + <span class="keyword">void</span><span class="special">*</span> <span class="identifier">storage</span> <span class="special">=</span> <span class="special">(</span> + <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">converter</span><span class="special">::</span><span class="identifier">rvalue_from_python_storage</span><span class="special"><</span><span class="identifier">custom_string</span><span class="special">>*)</span> + <span class="identifier">data</span><span class="special">)-></span><span class="identifier">storage</span><span class="special">.</span><span class="identifier">bytes</span><span class="special">;</span> + <span class="keyword">new</span> <span class="special">(</span><span class="identifier">storage</span><span class="special">)</span> <span class="identifier">custom_string</span><span class="special">(</span><span class="identifier">value</span><span class="special">);</span> + <span class="identifier">data</span><span class="special">-></span><span class="identifier">convertible</span> <span class="special">=</span> <span class="identifier">storage</span><span class="special">;</span> + <span class="special">}</span> +<span class="special">};</span> + +<span class="identifier">custom_string</span> <span class="identifier">hello</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">custom_string</span><span class="special">(</span><span class="string">"Hello world."</span><span class="special">);</span> <span class="special">}</span> + +<span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">(</span><span class="identifier">custom_string</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">s</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">value</span><span class="special">().</span><span class="identifier">size</span><span class="special">();</span> <span class="special">}</span> + +<span class="keyword">void</span> <span class="identifier">init_module</span><span class="special">()</span> +<span class="special">{</span> + <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">to_python_converter</span><span class="special"><</span> + <span class="identifier">custom_string</span><span class="special">,</span> + <span class="identifier">custom_string_to_python_str</span><span class="special">>();</span> + + <span class="identifier">custom_string_from_python_str</span><span class="special">();</span> + + <span class="identifier">def</span><span class="special">(</span><span class="string">"hello"</span><span class="special">,</span> <span class="identifier">hello</span><span class="special">);</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"size"</span><span class="special">,</span> <span class="identifier">size</span><span class="special">);</span> +<span class="special">}</span> + +<span class="special">}}</span> <span class="comment">// namespace sandbox::<anonymous></span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">custom_string</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">sandbox</span><span class="special">::</span><span class="identifier">init_module</span><span class="special">();</span> +<span class="special">}</span> +</pre> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="error_c2064_term_does_not_evalua.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="why_is_my_automatic_to_python_co.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/how_can_i_find_the_existing_pyob.html b/libs/python/doc/html/faq/how_can_i_find_the_existing_pyob.html new file mode 100644 index 0000000000..bf4147c9d2 --- /dev/null +++ b/libs/python/doc/html/faq/how_can_i_find_the_existing_pyob.html @@ -0,0 +1,103 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>How can I find the existing PyObject that holds a C++ object?</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="does_boost_python_work_with_mac_.html" title="Does Boost.Python work with Mac OS X?"> +<link rel="next" href="how_can_i_wrap_a_function_which0.html" title="How can I wrap a function which needs to take ownership of a raw pointer?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="does_boost_python_work_with_mac_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="how_can_i_wrap_a_function_which0.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.how_can_i_find_the_existing_pyob"></a><a class="link" href="how_can_i_find_the_existing_pyob.html" title="How can I find the existing PyObject that holds a C++ object?">How can I find + the existing PyObject that holds a C++ object?</a> +</h3></div></div></div> +<div class="blockquote"><blockquote class="blockquote"><p> + "I am wrapping a function that always returns a pointer to an already-held + C++ object." + </p></blockquote></div> +<p> + One way to do that is to hijack the mechanisms used for wrapping a class + with virtual functions. If you make a wrapper class with an initial PyObject* + constructor argument and store that PyObject* as "self", you can + get back to it by casting down to that wrapper type in a thin wrapper function. + For example: + </p> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">X</span> <span class="special">{</span> <span class="identifier">X</span><span class="special">(</span><span class="keyword">int</span><span class="special">);</span> <span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">X</span><span class="special">();</span> <span class="special">...</span> <span class="special">};</span> +<span class="identifier">X</span><span class="special">*</span> <span class="identifier">f</span><span class="special">();</span> <span class="comment">// known to return Xs that are managed by Python objects</span> + + +<span class="comment">// wrapping code</span> + +<span class="keyword">struct</span> <span class="identifier">X_wrap</span> <span class="special">:</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="identifier">X_wrap</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">self</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">v</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">self</span><span class="special">(</span><span class="identifier">self</span><span class="special">),</span> <span class="identifier">X</span><span class="special">(</span><span class="identifier">v</span><span class="special">)</span> <span class="special">{}</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">self</span><span class="special">;</span> +<span class="special">};</span> + +<span class="identifier">handle</span><span class="special"><></span> <span class="identifier">f_wrap</span><span class="special">()</span> +<span class="special">{</span> + <span class="identifier">X_wrap</span><span class="special">*</span> <span class="identifier">xw</span> <span class="special">=</span> <span class="keyword">dynamic_cast</span><span class="special"><</span><span class="identifier">X_wrap</span><span class="special">*>(</span><span class="identifier">f</span><span class="special">());</span> + <span class="identifier">assert</span><span class="special">(</span><span class="identifier">xw</span> <span class="special">!=</span> <span class="number">0</span><span class="special">);</span> + <span class="keyword">return</span> <span class="identifier">handle</span><span class="special"><>(</span><span class="identifier">borrowed</span><span class="special">(</span><span class="identifier">xw</span><span class="special">-></span><span class="identifier">self</span><span class="special">));</span> +<span class="special">}</span> + +<span class="special">...</span> + +<span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">f_wrap</span><span class="special">());</span> +<span class="identifier">class_</span><span class="special"><</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">X_wrap</span><span class="special">,</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">noncopyable</span><span class="special">>(</span><span class="string">"X"</span><span class="special">,</span> <span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">>())</span> + <span class="special">...</span> + <span class="special">;</span> +</pre> +<p> + Of course, if X has no virtual functions you'll have to use <code class="computeroutput"><span class="keyword">static_cast</span></code> instead of <code class="computeroutput"><span class="keyword">dynamic_cast</span></code> + with no runtime check that it's valid. This approach also only works if the + <code class="computeroutput"><span class="identifier">X</span></code> object was constructed + from Python, because <code class="computeroutput"><span class="identifier">X</span></code>s constructed + from C++ are of course never <code class="computeroutput"><span class="identifier">X_wrap</span></code> + objects. + </p> +<p> + Another approach to this requires you to change your C++ code a bit; if that's + an option for you it might be a better way to go. work we've been meaning + to get to anyway. When a <code class="computeroutput"><span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span></code> + is converted from Python, the shared_ptr actually manages a reference to + the containing Python object. When a shared_ptr<X> is converted back + to Python, the library checks to see if it's one of those "Python object + managers" and if so just returns the original Python object. So you + could just write <code class="computeroutput"><span class="identifier">object</span><span class="special">(</span><span class="identifier">p</span><span class="special">)</span></code> to get + the Python object back. To exploit this you'd have to be able to change the + C++ code you're wrapping so that it deals with shared_ptr instead of raw + pointers. + </p> +<p> + There are other approaches too. The functions that receive the Python object + that you eventually want to return could be wrapped with a thin wrapper that + records the correspondence between the object address and its containing + Python object, and you could have your f_wrap function look in that mapping + to get the Python object out. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="does_boost_python_work_with_mac_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="how_can_i_wrap_a_function_which0.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/how_can_i_wrap_a_function_which0.html b/libs/python/doc/html/faq/how_can_i_wrap_a_function_which0.html new file mode 100644 index 0000000000..a1af8df6a8 --- /dev/null +++ b/libs/python/doc/html/faq/how_can_i_wrap_a_function_which0.html @@ -0,0 +1,86 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>How can I wrap a function which needs to take ownership of a raw pointer?</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="how_can_i_find_the_existing_pyob.html" title="How can I find the existing PyObject that holds a C++ object?"> +<link rel="next" href="compilation_takes_too_much_time_.html" title="Compilation takes too much time and eats too much memory! What can I do to make it faster?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="how_can_i_find_the_existing_pyob.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="compilation_takes_too_much_time_.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.how_can_i_wrap_a_function_which0"></a><a class="link" href="how_can_i_wrap_a_function_which0.html" title="How can I wrap a function which needs to take ownership of a raw pointer?">How can I wrap + a function which needs to take ownership of a raw pointer?</a> +</h3></div></div></div> +<p> + <span class="bold"><strong>Q:</strong></span> Part of an API that I'm wrapping goes + something like this: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">A</span> <span class="special">{};</span> <span class="keyword">struct</span> <span class="identifier">B</span> <span class="special">{</span> <span class="keyword">void</span> <span class="identifier">add</span><span class="special">(</span> <span class="identifier">A</span><span class="special">*</span> <span class="special">);</span> <span class="special">}</span> +<span class="identifier">where</span> <span class="identifier">B</span><span class="special">::</span><span class="identifier">add</span><span class="special">()</span> <span class="identifier">takes</span> <span class="identifier">ownership</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">pointer</span> <span class="identifier">passed</span> <span class="identifier">to</span> <span class="identifier">it</span><span class="special">.</span> +</pre> +<p> + However: + </p> +<pre class="programlisting"><span class="identifier">a</span> <span class="special">=</span> <span class="identifier">mod</span><span class="special">.</span><span class="identifier">A</span><span class="special">()</span> +<span class="identifier">b</span> <span class="special">=</span> <span class="identifier">mod</span><span class="special">.</span><span class="identifier">B</span><span class="special">()</span> +<span class="identifier">b</span><span class="special">.</span><span class="identifier">add</span><span class="special">(</span> <span class="identifier">a</span> <span class="special">)</span> +<span class="identifier">del</span> <span class="identifier">a</span> +<span class="identifier">del</span> <span class="identifier">b</span> +<span class="preprocessor"># python</span> <span class="identifier">interpreter</span> <span class="identifier">crashes</span> +<span class="preprocessor"># later</span> <span class="identifier">due</span> <span class="identifier">to</span> <span class="identifier">memory</span> <span class="identifier">corruption</span><span class="special">.</span> +</pre> +<p> + Even binding the lifetime of a to b via <code class="computeroutput"><span class="identifier">with_custodian_and_ward</span></code> + doesn't prevent the python object a from ultimately trying to delete the + object it's pointing to. Is there a way to accomplish a 'transfer-of-ownership' + of a wrapped C++ object? + </p> +<p> + --Bruce Lowery + </p> +<p> + Yes: Make sure the C++ object is held by auto_ptr: + </p> +<pre class="programlisting"><span class="identifier">class_</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">auto_ptr</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span> <span class="special">>(</span><span class="string">"A"</span><span class="special">)</span> + <span class="special">...</span> + <span class="special">;</span> +</pre> +<p> + Then make a thin wrapper function which takes an auto_ptr parameter: + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">b_insert</span><span class="special">(</span><span class="identifier">B</span> <span class="special">&</span><span class="identifier">b</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">auto_ptr</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span> <span class="identifier">a</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">b</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span><span class="identifier">a</span><span class="special">.</span><span class="identifier">get</span><span class="special">());</span> + <span class="identifier">a</span><span class="special">.</span><span class="identifier">release</span><span class="special">();</span> +<span class="special">}</span> +</pre> +<p> + Wrap that as B.add. Note that pointers returned via <code class="computeroutput"><span class="identifier">manage_new_object</span></code> + will also be held by <code class="computeroutput"><span class="identifier">auto_ptr</span></code>, + so this transfer-of-ownership will also work correctly. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="how_can_i_find_the_existing_pyob.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="compilation_takes_too_much_time_.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/how_can_i_wrap_functions_which_t.html b/libs/python/doc/html/faq/how_can_i_wrap_functions_which_t.html new file mode 100644 index 0000000000..43ab68a6a5 --- /dev/null +++ b/libs/python/doc/html/faq/how_can_i_wrap_functions_which_t.html @@ -0,0 +1,124 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>How can I wrap functions which take C++ containers as arguments?</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="is_return_internal_reference_eff.html" title="Is return_internal_reference efficient?"> +<link rel="next" href="fatal_error_c1204_compiler_limit.html" title="fatal error C1204:Compiler limit:internal structure overflow"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="is_return_internal_reference_eff.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="fatal_error_c1204_compiler_limit.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.how_can_i_wrap_functions_which_t"></a><a class="link" href="how_can_i_wrap_functions_which_t.html" title="How can I wrap functions which take C++ containers as arguments?">How can I wrap + functions which take C++ containers as arguments?</a> +</h3></div></div></div> +<p> + Ralf W. Grosse-Kunstleve provides these notes: + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> +<p class="simpara"> + Using the regular <code class="computeroutput"><span class="identifier">class_</span><span class="special"><></span></code> wrapper: + </p> +<pre class="programlisting"><span class="identifier">class_</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">double</span><span class="special">></span> <span class="special">>(</span><span class="string">"std_vector_double"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(...)</span> + <span class="special">...</span> +<span class="special">;</span> +</pre> +<p class="simpara"> + This can be moved to a template so that several types (<code class="computeroutput"><span class="keyword">double</span></code>, <code class="computeroutput"><span class="keyword">int</span></code>, + <code class="computeroutput"><span class="keyword">long</span></code>, etc.) can be wrapped + with the same code. This technique is used in the file <code class="computeroutput"><span class="identifier">scitbx</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">scitbx</span><span class="special">/</span><span class="identifier">array_family</span><span class="special">/</span><span class="identifier">boost_python</span><span class="special">/</span><span class="identifier">flex_wrapper</span><span class="special">.</span><span class="identifier">h</span></code> in the "scitbx" package. + The file could easily be modified for wrapping <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><></span></code> instantiations. This type of + C++/Python binding is most suitable for containers that may contain a + large number of elements (>10000). + </p> +</li> +<li class="listitem"> +<p class="simpara"> + Using custom rvalue converters. Boost.Python "rvalue converters" + match function signatures such as: + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">double</span><span class="special">></span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">array</span><span class="special">);</span> <span class="comment">// pass by const-reference</span> +<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">double</span><span class="special">></span> <span class="identifier">array</span><span class="special">);</span> <span class="comment">// pass by value</span> +</pre> +<p class="simpara"> + Some custom rvalue converters are implemented in the file <code class="computeroutput"><span class="identifier">scitbx</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">scitbx</span><span class="special">/</span><span class="identifier">boost_python</span><span class="special">/</span><span class="identifier">container_conversions</span><span class="special">.</span><span class="identifier">h</span></code> This code can be used to convert + from C++ container types such as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><></span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special"><></span></code> to Python tuples and vice versa. + A few simple examples can be found in the file <code class="computeroutput"><span class="identifier">scitbx</span><span class="special">/</span><span class="identifier">array_family</span><span class="special">/</span><span class="identifier">boost_python</span><span class="special">/</span><span class="identifier">regression_test_module</span><span class="special">.</span><span class="identifier">cpp</span></code> + Automatic C++ container <-> Python tuple conversions are most suitable + for containers of moderate size. These converters generate significantly + less object code compared to alternative 1 above. + </p> +</li> +</ol></div> +<p> + A disadvantage of using alternative 2 is that operators such as arithmetic + +,-,*,/,% are not available. It would be useful to have custom rvalue converters + that convert to a "math_array" type instead of tuples. This is + currently not implemented but is possible within the framework of Boost.Python + V2 as it will be released in the next couple of weeks. [ed.: this was posted + on 2002/03/10] + </p> +<p> + It would also be useful to also have "custom lvalue converters" + such as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><></span></code> + <-> Python list. These converters would support the modification of + the Python list from C++. For example: + </p> +<p> + C++: + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">double</span><span class="special">></span> <span class="special">&</span><span class="identifier">array</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">for</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">i</span><span class="special">=</span><span class="number">0</span><span class="special">;</span><span class="identifier">i</span><span class="special">&</span><span class="identifier">lt</span><span class="special">;</span><span class="identifier">array</span><span class="special">.</span><span class="identifier">size</span><span class="special">();</span><span class="identifier">i</span><span class="special">++)</span> <span class="special">{</span> + <span class="identifier">array</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">*=</span> <span class="number">2</span><span class="special">;</span> + <span class="special">}</span> +<span class="special">}</span> +</pre> +<p> + Python: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">l</span> <span class="special">=</span> <span class="special">[</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">]</span> +<span class="special">>>></span> <span class="identifier">foo</span><span class="special">(</span><span class="identifier">l</span><span class="special">)</span> +<span class="special">>>></span> <span class="keyword">print</span> <span class="identifier">l</span> +<span class="special">[</span><span class="number">2</span><span class="special">,</span> <span class="number">4</span><span class="special">,</span> <span class="number">6</span><span class="special">]</span> +</pre> +<p> + Custom lvalue converters require changes to the Boost.Python core library + and are currently not available. + </p> +<p> + P.S.: + </p> +<p> + The "scitbx" files referenced above are available via anonymous + CVS: + </p> +<pre class="programlisting"><span class="identifier">cvs</span> <span class="special">-</span><span class="identifier">d</span><span class="special">:</span><span class="identifier">pserver</span><span class="special">:</span><span class="identifier">anonymous</span><span class="error">@</span><span class="identifier">cvs</span><span class="special">.</span><span class="identifier">cctbx</span><span class="special">.</span><span class="identifier">sourceforge</span><span class="special">.</span><span class="identifier">net</span><span class="special">:/</span><span class="identifier">cvsroot</span><span class="special">/</span><span class="identifier">cctbx</span> <span class="identifier">login</span> +<span class="identifier">cvs</span> <span class="special">-</span><span class="identifier">d</span><span class="special">:</span><span class="identifier">pserver</span><span class="special">:</span><span class="identifier">anonymous</span><span class="error">@</span><span class="identifier">cvs</span><span class="special">.</span><span class="identifier">cctbx</span><span class="special">.</span><span class="identifier">sourceforge</span><span class="special">.</span><span class="identifier">net</span><span class="special">:/</span><span class="identifier">cvsroot</span><span class="special">/</span><span class="identifier">cctbx</span> <span class="identifier">co</span> <span class="identifier">scitbx</span> +</pre> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="is_return_internal_reference_eff.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="fatal_error_c1204_compiler_limit.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/how_do_i_create_sub_packages_usi.html b/libs/python/doc/html/faq/how_do_i_create_sub_packages_usi.html new file mode 100644 index 0000000000..5565071b62 --- /dev/null +++ b/libs/python/doc/html/faq/how_do_i_create_sub_packages_usi.html @@ -0,0 +1,41 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>How do I create sub-packages using Boost.Python?</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="compilation_takes_too_much_time_.html" title="Compilation takes too much time and eats too much memory! What can I do to make it faster?"> +<link rel="next" href="error_c2064_term_does_not_evalua.html" title="error C2064: term does not evaluate to a function taking 2 arguments"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="compilation_takes_too_much_time_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="error_c2064_term_does_not_evalua.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.how_do_i_create_sub_packages_usi"></a><a class="link" href="how_do_i_create_sub_packages_usi.html" title="How do I create sub-packages using Boost.Python?">How do I create + sub-packages using Boost.Python?</a> +</h3></div></div></div> +<p> + Please refer to the <code class="computeroutput"><span class="identifier">Creating</span> <span class="identifier">Packages</span></code> section in the <a href="../tutorial/index.html" target="_top">Tutorial</a>. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="compilation_takes_too_much_time_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="error_c2064_term_does_not_evalua.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/how_do_i_debug_my_python_extensi.html b/libs/python/doc/html/faq/how_do_i_debug_my_python_extensi.html new file mode 100644 index 0000000000..aa616e7e34 --- /dev/null +++ b/libs/python/doc/html/faq/how_do_i_debug_my_python_extensi.html @@ -0,0 +1,151 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>How do I debug my Python extensions?</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="fatal_error_c1204_compiler_limit.html" title="fatal error C1204:Compiler limit:internal structure overflow"> +<link rel="next" href="why_doesn_t_my_operator_work.html" title="Why doesn't my *= operator work?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="fatal_error_c1204_compiler_limit.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="why_doesn_t_my_operator_work.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.how_do_i_debug_my_python_extensi"></a><a class="link" href="how_do_i_debug_my_python_extensi.html" title="How do I debug my Python extensions?">How do I debug + my Python extensions?</a> +</h3></div></div></div> +<p> + Greg Burley gives the following answer for Unix GCC users: + </p> +<div class="blockquote"><blockquote class="blockquote"> +<p> + Once you have created a boost python extension for your c++ library or + class, you may need to debug the code. Afterall this is one of the reasons + for wrapping the library in python. An expected side-effect or benefit + of using BPL is that debugging should be isolated to the c++ library that + is under test, given that python code is minimal and boost::python either + works or it doesn't. (ie. While errors can occur when the wrapping method + is invalid, most errors are caught by the compiler ;-). + </p> +<p> + The basic steps required to initiate a gdb session to debug a c++ library + via python are shown here. Note, however that you should start the gdb + session in the directory that contains your BPL my_ext.so module. + </p> +<pre class="programlisting"><span class="special">(</span><span class="identifier">gdb</span><span class="special">)</span> <span class="identifier">target</span> <span class="identifier">exec</span> <span class="identifier">python</span> +<span class="special">(</span><span class="identifier">gdb</span><span class="special">)</span> <span class="identifier">run</span> +<span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">my_ext</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="special">[</span><span class="identifier">C</span><span class="special">-</span><span class="identifier">c</span><span class="special">]</span> +<span class="special">(</span><span class="identifier">gdb</span><span class="special">)</span> <span class="keyword">break</span> <span class="identifier">MyClass</span><span class="special">::</span><span class="identifier">MyBuggyFunction</span> +<span class="special">(</span><span class="identifier">gdb</span><span class="special">)</span> <span class="identifier">cont</span> +<span class="special">>>></span> <span class="identifier">pyobj</span> <span class="special">=</span> <span class="identifier">MyClass</span><span class="special">()</span> +<span class="special">>>></span> <span class="identifier">pyobj</span><span class="special">.</span><span class="identifier">MyBuggyFunction</span><span class="special">()</span> +<span class="identifier">Breakpoint</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">MyClass</span><span class="special">::</span><span class="identifier">MyBuggyFunction</span> <span class="special">...</span> +<span class="identifier">Current</span> <span class="identifier">language</span><span class="special">:</span> <span class="keyword">auto</span><span class="special">;</span> <span class="identifier">currently</span> <span class="identifier">c</span><span class="special">++</span> +<span class="special">(</span><span class="identifier">gdb</span><span class="special">)</span> <span class="keyword">do</span> <span class="identifier">debugging</span> <span class="identifier">stuff</span> +</pre> +</blockquote></div> +<p> + Greg's approach works even better using Emacs' "gdb" command, since + it will show you each line of source as you step through it. + </p> +<p> + On <span class="bold"><strong>Windows</strong></span>, my favorite debugging solution + is the debugger that comes with Microsoft Visual C++ 7. This debugger seems + to work with code generated by all versions of Microsoft and Metrowerks toolsets; + it's rock solid and "just works" without requiring any special + tricks from the user. + </p> +<p> + Raoul Gough has provided the following for gdb on Windows: + </p> +<div class="blockquote"><blockquote class="blockquote"> +<p> + gdb support for Windows DLLs has improved lately, so it is now possible + to debug Python extensions using a few tricks. Firstly, you will need an + up-to-date gdb with support for minimal symbol extraction from a DLL. Any + gdb from version 6 onwards, or Cygwin gdb-20030214-1 and onwards should + do. A suitable release will have a section in the gdb.info file under Configuration + - Native - Cygwin Native - Non-debug DLL symbols. Refer to that info section + for more details of the procedures outlined here. + </p> +<p> + Secondly, it seems necessary to set a breakpoint in the Python interpreter, + rather than using ^C to break execution. A good place to set this breakpoint + is PyOS_Readline, which will stop execution immediately before reading + each interactive Python command. You have to let Python start once under + the debugger, so that it loads its own DLL, before you can set the breakpoint: + </p> +<pre class="programlisting"><span class="error">$</span> <span class="identifier">gdb</span> <span class="identifier">python</span> +<span class="identifier">GNU</span> <span class="identifier">gdb</span> <span class="number">2003</span><span class="special">-</span><span class="number">09</span><span class="special">-</span><span class="number">02</span><span class="special">-</span><span class="identifier">cvs</span> <span class="special">(</span><span class="identifier">cygwin</span><span class="special">-</span><span class="identifier">special</span><span class="special">)</span> +<span class="special">[...]</span> + +<span class="special">(</span><span class="identifier">gdb</span><span class="special">)</span> <span class="identifier">run</span> +<span class="identifier">Starting</span> <span class="identifier">program</span><span class="special">:</span> <span class="special">/</span><span class="identifier">cygdrive</span><span class="special">/</span><span class="identifier">c</span><span class="special">/</span><span class="identifier">Python22</span><span class="special">/</span><span class="identifier">python</span><span class="special">.</span><span class="identifier">exe</span> +<span class="identifier">Python</span> <span class="number">2.2</span><span class="special">.</span><span class="number">2</span> <span class="special">(#</span><span class="number">37</span><span class="special">,</span> <span class="identifier">Oct</span> <span class="number">14</span> <span class="number">2002</span><span class="special">,</span> <span class="number">17</span><span class="special">:</span><span class="number">02</span><span class="special">:</span><span class="number">34</span><span class="special">)</span> <span class="special">[</span><span class="identifier">MSC</span> <span class="number">32</span> <span class="identifier">bit</span> <span class="special">(</span><span class="identifier">Intel</span><span class="special">)]</span> <span class="identifier">on</span> <span class="identifier">win32</span> +<span class="identifier">Type</span> <span class="string">"help"</span><span class="special">,</span> <span class="string">"copyright"</span><span class="special">,</span> <span class="string">"credits"</span> <span class="keyword">or</span> <span class="string">"license"</span> <span class="keyword">for</span> <span class="identifier">more</span> <span class="identifier">information</span><span class="special">.</span> +<span class="special">>>></span> <span class="special">^</span><span class="identifier">Z</span> + + +<span class="identifier">Program</span> <span class="identifier">exited</span> <span class="identifier">normally</span><span class="special">.</span> +<span class="special">(</span><span class="identifier">gdb</span><span class="special">)</span> <span class="keyword">break</span> <span class="special">*&</span><span class="identifier">PyOS_Readline</span> +<span class="identifier">Breakpoint</span> <span class="number">1</span> <span class="identifier">at</span> <span class="number">0x1e04eff0</span> +<span class="special">(</span><span class="identifier">gdb</span><span class="special">)</span> <span class="identifier">run</span> +<span class="identifier">Starting</span> <span class="identifier">program</span><span class="special">:</span> <span class="special">/</span><span class="identifier">cygdrive</span><span class="special">/</span><span class="identifier">c</span><span class="special">/</span><span class="identifier">Python22</span><span class="special">/</span><span class="identifier">python</span><span class="special">.</span><span class="identifier">exe</span> +<span class="identifier">Python</span> <span class="number">2.2</span><span class="special">.</span><span class="number">2</span> <span class="special">(#</span><span class="number">37</span><span class="special">,</span> <span class="identifier">Oct</span> <span class="number">14</span> <span class="number">2002</span><span class="special">,</span> <span class="number">17</span><span class="special">:</span><span class="number">02</span><span class="special">:</span><span class="number">34</span><span class="special">)</span> <span class="special">[</span><span class="identifier">MSC</span> <span class="number">32</span> <span class="identifier">bit</span> <span class="special">(</span><span class="identifier">Intel</span><span class="special">)]</span> <span class="identifier">on</span> <span class="identifier">win32</span> +<span class="identifier">Type</span> <span class="string">"help"</span><span class="special">,</span> <span class="string">"copyright"</span><span class="special">,</span> <span class="string">"credits"</span> <span class="keyword">or</span> <span class="string">"license"</span> <span class="keyword">for</span> <span class="identifier">more</span> <span class="identifier">information</span><span class="special">.</span> + +<span class="identifier">Breakpoint</span> <span class="number">1</span><span class="special">,</span> <span class="number">0x1e04eff0</span> <span class="identifier">in</span> <span class="identifier">python22</span><span class="special">!</span><span class="identifier">PyOS_Readline</span> <span class="special">()</span> + <span class="identifier">from</span> <span class="special">/</span><span class="identifier">cygdrive</span><span class="special">/</span><span class="identifier">c</span><span class="special">/</span><span class="identifier">WINNT</span><span class="special">/</span><span class="identifier">system32</span><span class="special">/</span><span class="identifier">python22</span><span class="special">.</span><span class="identifier">dll</span> +<span class="special">(</span><span class="identifier">gdb</span><span class="special">)</span> <span class="identifier">cont</span> +<span class="identifier">Continuing</span><span class="special">.</span> +<span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">my_ext</span> <span class="identifier">import</span> <span class="special">*</span> + +<span class="identifier">Breakpoint</span> <span class="number">1</span><span class="special">,</span> <span class="number">0x1e04eff0</span> <span class="identifier">in</span> <span class="identifier">python22</span><span class="special">!</span><span class="identifier">PyOS_Readline</span> <span class="special">()</span> + <span class="identifier">from</span> <span class="special">/</span><span class="identifier">cygdrive</span><span class="special">/</span><span class="identifier">c</span><span class="special">/</span><span class="identifier">WINNT</span><span class="special">/</span><span class="identifier">system32</span><span class="special">/</span><span class="identifier">python22</span><span class="special">.</span><span class="identifier">dll</span> +<span class="special">(</span><span class="identifier">gdb</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">my_ext</span> <span class="identifier">now</span> <span class="identifier">loaded</span> <span class="special">(</span><span class="identifier">with</span> <span class="identifier">any</span> <span class="identifier">debugging</span> <span class="identifier">symbols</span> <span class="identifier">it</span> <span class="identifier">contains</span><span class="special">)</span> +</pre> +</blockquote></div> +<h3> +<a name="faq.how_do_i_debug_my_python_extensi.h0"></a> + <span class="phrase"><a name="faq.how_do_i_debug_my_python_extensi.debugging_extensions_through_boo"></a></span><a class="link" href="how_do_i_debug_my_python_extensi.html#faq.how_do_i_debug_my_python_extensi.debugging_extensions_through_boo">Debugging + extensions through Boost.Build</a> + </h3> +<p> + If you are launching your extension module tests with <a href="http://www.boost.org/build" target="_top">Boost.Build</a> + using the <code class="computeroutput"><span class="identifier">boost</span><span class="special">-</span><span class="identifier">python</span><span class="special">-</span><span class="identifier">runtest</span></code> rule, you can ask it to launch + your debugger for you by adding "--debugger=<span class="emphasis"><em>debugger</em></span>" + to your bjam command-line: + </p> +<pre class="programlisting"><span class="identifier">bjam</span> <span class="special">-</span><span class="identifier">sTOOLS</span><span class="special">=</span><span class="identifier">vc7</span><span class="special">.</span><span class="number">1</span> <span class="string">"--debugger=devenv /debugexe"</span> <span class="identifier">test</span> +<span class="identifier">bjam</span> <span class="special">-</span><span class="identifier">sTOOLS</span><span class="special">=</span><span class="identifier">gcc</span> <span class="special">-</span><span class="identifier">sPYTHON_LAUNCH</span><span class="special">=</span><span class="identifier">gdb</span> <span class="identifier">test</span> +</pre> +<p> + It can also be extremely useful to add the <code class="computeroutput"><span class="special">-</span><span class="identifier">d</span><span class="special">+</span><span class="number">2</span></code> + option when you run your test, because Boost.Build will then show you the + exact commands it uses to invoke it. This will invariably involve setting + up PYTHONPATH and other important environment variables such as LD_LIBRARY_PATH + which may be needed by your debugger in order to get things to work right. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="fatal_error_c1204_compiler_limit.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="why_doesn_t_my_operator_work.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/i_m_getting_the_attempt_to_retur.html b/libs/python/doc/html/faq/i_m_getting_the_attempt_to_retur.html new file mode 100644 index 0000000000..103d319780 --- /dev/null +++ b/libs/python/doc/html/faq/i_m_getting_the_attempt_to_retur.html @@ -0,0 +1,67 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>I'm getting the "attempt to return dangling reference" error. What am I doing wrong?</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="next" href="is_return_internal_reference_eff.html" title="Is return_internal_reference efficient?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../faq.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="is_return_internal_reference_eff.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.i_m_getting_the_attempt_to_retur"></a><a class="link" href="i_m_getting_the_attempt_to_retur.html" title="I'm getting the "attempt to return dangling reference" error. What am I doing wrong?">I'm getting the + "attempt to return dangling reference" error. What am I doing wrong?</a> +</h3></div></div></div> +<p> + That exception is protecting you from causing a nasty crash. It usually happens + in response to some code like this: + </p> +<pre class="programlisting"><span class="identifier">period</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">get_floating_frequency</span><span class="special">()</span> <span class="keyword">const</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">call_method</span><span class="special"><</span><span class="identifier">period</span> <span class="keyword">const</span> <span class="special">&>(</span> + <span class="identifier">m_self</span><span class="special">,</span><span class="string">"get_floating_frequency"</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + And you get: + </p> +<pre class="programlisting"><span class="identifier">ReferenceError</span><span class="special">:</span> <span class="identifier">Attempt</span> <span class="identifier">to</span> <span class="keyword">return</span> <span class="identifier">dangling</span> <span class="identifier">reference</span> <span class="identifier">to</span> <span class="identifier">object</span> <span class="identifier">of</span> <span class="identifier">type</span><span class="special">:</span> +<span class="keyword">class</span> <span class="identifier">period</span> +</pre> +<p> + In this case, the Python method invoked by <code class="computeroutput"><span class="identifier">call_method</span></code> + constructs a new Python object. You're trying to return a reference to a + C++ object (an instance of <code class="computeroutput"><span class="keyword">class</span> <span class="identifier">period</span></code>) contained within and owned by that + Python object. Because the called method handed back a brand new object, + the only reference to it is held for the duration of <code class="computeroutput"><span class="identifier">get_floating_frequency</span><span class="special">()</span></code> above. When the function returns, the Python + object will be destroyed, destroying the instance of <code class="computeroutput"><span class="keyword">class</span> + <span class="identifier">period</span></code>, and leaving the returned + reference dangling. That's already undefined behavior, and if you try to + do anything with that reference you're likely to cause a crash. Boost.Python + detects this situation at runtime and helpfully throws an exception instead + of letting you do that. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../faq.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="is_return_internal_reference_eff.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/is_boost_python_thread_aware_com.html b/libs/python/doc/html/faq/is_boost_python_thread_aware_com.html new file mode 100644 index 0000000000..efc1b136a6 --- /dev/null +++ b/libs/python/doc/html/faq/is_boost_python_thread_aware_com.html @@ -0,0 +1,60 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Is Boost.Python thread-aware/compatible with multiple interpreters?</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="why_is_my_automatic_to_python_co.html" title="Why is my automatic to-python conversion not being found?"> +<link rel="next" href="../glossary.html" title="Chapter 5. Glossary"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="why_is_my_automatic_to_python_co.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../glossary.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.is_boost_python_thread_aware_com"></a><a class="link" href="is_boost_python_thread_aware_com.html" title="Is Boost.Python thread-aware/compatible with multiple interpreters?">Is Boost.Python + thread-aware/compatible with multiple interpreters?</a> +</h3></div></div></div> +<p> + <span class="emphasis"><em>Niall Douglas provides these notes:</em></span> + </p> +<p> + The quick answer to this is: no. + </p> +<p> + The longer answer is that it can be patched to be so, but it's complex. You + will need to add custom lock/unlock wrapping of every time your code enters + Boost.Python (particularly every virtual function override) plus heavily + modify <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">detail</span><span class="special">/</span><span class="identifier">invoke</span><span class="special">.</span><span class="identifier">hpp</span></code> with custom unlock/lock wrapping of + every time Boost.Python enters your code. You must furthermore take care + to <span class="emphasis"><em>not</em></span> unlock/lock when Boost.Python is invoking iterator + changes via <code class="computeroutput"><span class="identifier">invoke</span><span class="special">.</span><span class="identifier">hpp</span></code>. + </p> +<p> + There is a patched <code class="computeroutput"><span class="identifier">invoke</span><span class="special">.</span><span class="identifier">hpp</span></code> posted + on the C++-SIG mailing list archives and you can find a real implementation + of all the machinery necessary to fully implement this in the TnFOX project + at <a href="http://sourceforge.net/projects/tnfox/" target="_top">this</a> SourceForge + project location. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="why_is_my_automatic_to_python_co.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../glossary.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/is_return_internal_reference_eff.html b/libs/python/doc/html/faq/is_return_internal_reference_eff.html new file mode 100644 index 0000000000..76382d321c --- /dev/null +++ b/libs/python/doc/html/faq/is_return_internal_reference_eff.html @@ -0,0 +1,62 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Is return_internal_reference efficient?</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="i_m_getting_the_attempt_to_retur.html" title="I'm getting the "attempt to return dangling reference" error. What am I doing wrong?"> +<link rel="next" href="how_can_i_wrap_functions_which_t.html" title="How can I wrap functions which take C++ containers as arguments?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="i_m_getting_the_attempt_to_retur.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="how_can_i_wrap_functions_which_t.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.is_return_internal_reference_eff"></a><a class="link" href="is_return_internal_reference_eff.html" title="Is return_internal_reference efficient?">Is <code class="computeroutput"><span class="identifier">return_internal_reference</span></code> efficient?</a> +</h3></div></div></div> +<p> + <span class="bold"><strong>Q:</strong></span> /I have an object composed of 12 doubles. + A <code class="computeroutput"><span class="keyword">const</span><span class="special">&</span></code> + to this object is returned by a member function of another class. From the + viewpoint of using the returned object in Python I do not care if I get a + copy or a reference to the returned object. In Boost.Python I have the choice + of using <code class="computeroutput"><span class="identifier">copy_const_reference</span></code> + or <code class="computeroutput"><span class="identifier">return_internal_reference</span></code>. + Are there considerations that would lead me to prefer one over the other, + such as size of generated code or memory overhead?/ + </p> +<p> + <span class="bold"><strong>A:</strong></span> <code class="computeroutput"><span class="identifier">copy_const_reference</span></code> + will make an instance with storage for one of your objects, <code class="computeroutput"><span class="identifier">size</span> <span class="special">=</span> <span class="identifier">base_size</span> <span class="special">+</span> <span class="number">12</span> <span class="special">*</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">double</span><span class="special">)</span></code>. + <code class="computeroutput"><span class="identifier">return_internal_reference</span></code> + will make an instance with storage for a pointer to one of your objects, + <code class="computeroutput"><span class="identifier">size</span> <span class="special">=</span> + <span class="identifier">base_size</span> <span class="special">+</span> + <span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">void</span><span class="special">*)</span></code>. However, + it will also create a weak reference object which goes in the source object's + weakreflist and a special callback object to manage the lifetime of the internally-referenced + object. My guess? <code class="computeroutput"><span class="identifier">copy_const_reference</span></code> + is your friend here, resulting in less overall memory use and less fragmentation, + also probably fewer total cycles. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="i_m_getting_the_attempt_to_retur.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="how_can_i_wrap_functions_which_t.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/why_doesn_t_my_operator_work.html b/libs/python/doc/html/faq/why_doesn_t_my_operator_work.html new file mode 100644 index 0000000000..c5083de2ac --- /dev/null +++ b/libs/python/doc/html/faq/why_doesn_t_my_operator_work.html @@ -0,0 +1,63 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Why doesn't my *= operator work?</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="how_do_i_debug_my_python_extensi.html" title="How do I debug my Python extensions?"> +<link rel="next" href="does_boost_python_work_with_mac_.html" title="Does Boost.Python work with Mac OS X?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="how_do_i_debug_my_python_extensi.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="does_boost_python_work_with_mac_.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.why_doesn_t_my_operator_work"></a><a class="link" href="why_doesn_t_my_operator_work.html" title="Why doesn't my *= operator work?">Why doesn't my <code class="computeroutput"><span class="special">*=</span></code> operator work?</a> +</h3></div></div></div> +<p> + <span class="bold"><strong>Q:</strong></span> <span class="emphasis"><em>I have exported my class to + python, with many overloaded operators. it works fine for me except the + <code class="computeroutput"><span class="special">*=</span></code> operator. It always tells + me "can't multiply sequence with non int type". If I use <code class="computeroutput"><span class="identifier">p1</span><span class="special">.</span><span class="identifier">__imul__</span><span class="special">(</span><span class="identifier">p2</span><span class="special">)</span></code> + instead of <code class="computeroutput"><span class="identifier">p1</span> <span class="special">*=</span> + <span class="identifier">p2</span></code>, it successfully executes my + code. What's wrong with me?</em></span> + </p> +<p> + <span class="bold"><strong>A:</strong></span> There's nothing wrong with you. This + is a bug in Python 2.2. You can see the same effect in Pure Python (you can + learn a lot about what's happening in Boost.Python by playing with new-style + classes in Pure Python). + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="keyword">class</span> <span class="identifier">X</span><span class="special">(</span><span class="identifier">object</span><span class="special">):</span> +<span class="special">...</span> <span class="identifier">def</span> <span class="identifier">__imul__</span><span class="special">(</span><span class="identifier">self</span><span class="special">,</span> <span class="identifier">x</span><span class="special">):</span> +<span class="special">...</span> <span class="identifier">print</span> <span class="char">'imul'</span> +<span class="special">...</span> +<span class="special">>>></span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">X</span><span class="special">()</span> +<span class="special">>>></span> <span class="identifier">x</span> <span class="special">*=</span> <span class="number">1</span> +</pre> +<p> + To cure this problem, all you need to do is upgrade your Python to version + 2.2.1 or later. + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="how_do_i_debug_my_python_extensi.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="does_boost_python_work_with_mac_.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/faq/why_is_my_automatic_to_python_co.html b/libs/python/doc/html/faq/why_is_my_automatic_to_python_co.html new file mode 100644 index 0000000000..28d705aec8 --- /dev/null +++ b/libs/python/doc/html/faq/why_is_my_automatic_to_python_co.html @@ -0,0 +1,67 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Why is my automatic to-python conversion not being found?</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python"> +<link rel="up" href="../faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +<link rel="prev" href="how_can_i_automatically_convert_.html" title="How can I automatically convert my custom string type to and from a Python string?"> +<link rel="next" href="is_boost_python_thread_aware_com.html" title="Is Boost.Python thread-aware/compatible with multiple interpreters?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="how_can_i_automatically_convert_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="is_boost_python_thread_aware_com.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="faq.why_is_my_automatic_to_python_co"></a><a class="link" href="why_is_my_automatic_to_python_co.html" title="Why is my automatic to-python conversion not being found?">Why is my automatic + to-python conversion not being found?</a> +</h3></div></div></div> +<p> + <span class="emphasis"><em>Niall Douglas provides these notes:</em></span> + </p> +<p> + If you define custom converters similar to the ones shown above the <code class="computeroutput"><span class="identifier">def_readonly</span><span class="special">()</span></code> + and <code class="computeroutput"><span class="identifier">def_readwrite</span><span class="special">()</span></code> + member functions provided by <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">class_</span></code> + for direct access to your member data will not work as expected. This is + because <code class="computeroutput"><span class="identifier">def_readonly</span><span class="special">(</span><span class="string">"bar"</span><span class="special">,&</span><span class="identifier">foo</span><span class="special">::</span><span class="identifier">bar</span><span class="special">)</span></code> is equivalent to: + </p> +<pre class="programlisting"><span class="special">.</span><span class="identifier">add_property</span><span class="special">(</span><span class="string">"bar"</span><span class="special">,</span> <span class="identifier">make_getter</span><span class="special">(&</span><span class="identifier">foo</span><span class="special">::</span><span class="identifier">bar</span><span class="special">,</span> <span class="identifier">return_internal_reference</span><span class="special">()))</span> +</pre> +<p> + Similarly, <code class="computeroutput"><span class="identifier">def_readwrite</span><span class="special">(</span><span class="string">"bar"</span><span class="special">,&</span><span class="identifier">foo</span><span class="special">::</span><span class="identifier">bar</span><span class="special">)</span></code> + is equivalent to: + </p> +<pre class="programlisting"><span class="special">.</span><span class="identifier">add_property</span><span class="special">(</span><span class="string">"bar"</span><span class="special">,</span> <span class="identifier">make_getter</span><span class="special">(&</span><span class="identifier">foo</span><span class="special">::</span><span class="identifier">bar</span><span class="special">,</span> <span class="identifier">return_internal_reference</span><span class="special">()),</span> + <span class="identifier">make_setter</span><span class="special">(&</span><span class="identifier">foo</span><span class="special">::</span><span class="identifier">bar</span><span class="special">,</span> <span class="identifier">return_internal_reference</span><span class="special">())</span> +</pre> +<p> + In order to define return value policies compatible with the custom conversions + replace <code class="computeroutput"><span class="identifier">def_readonly</span><span class="special">()</span></code> + and <code class="computeroutput"><span class="identifier">def_readwrite</span><span class="special">()</span></code> + by <code class="computeroutput"><span class="identifier">add_property</span><span class="special">()</span></code>. + E.g.: + </p> +<pre class="programlisting"><span class="special">.</span><span class="identifier">add_property</span><span class="special">(</span><span class="string">"bar"</span><span class="special">,</span> <span class="identifier">make_getter</span><span class="special">(&</span><span class="identifier">foo</span><span class="special">::</span><span class="identifier">bar</span><span class="special">,</span> <span class="identifier">return_value_policy</span><span class="special"><</span><span class="identifier">return_by_value</span><span class="special">>()),</span> + <span class="identifier">make_setter</span><span class="special">(&</span><span class="identifier">foo</span><span class="special">::</span><span class="identifier">bar</span><span class="special">,</span> <span class="identifier">return_value_policy</span><span class="special"><</span><span class="identifier">return_by_value</span><span class="special">>()))</span> +</pre> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="how_can_i_automatically_convert_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../faq.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="is_boost_python_thread_aware_com.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/glossary.html b/libs/python/doc/html/glossary.html new file mode 100644 index 0000000000..693f954d1c --- /dev/null +++ b/libs/python/doc/html/glossary.html @@ -0,0 +1,81 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 5. Glossary</title> +<link rel="stylesheet" href="boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python"> +<link rel="up" href="index.html" title="Boost.Python"> +<link rel="prev" href="faq/is_boost_python_thread_aware_com.html" title="Is Boost.Python thread-aware/compatible with multiple interpreters?"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="faq/is_boost_python_thread_aware_com.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="glossary"></a>Chapter 5. Glossary</h1></div></div></div> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">arity <a name="arity"></a></span></dt> +<dd><p> + The number of argumnts accepted by a function or member function. Unless + otherwise specified, the hidden <code class="computeroutput"><span class="keyword">this</span></code> + argument to member functions is not counted when specifying arity. + </p></dd> +<dt><span class="term">ntbs <a name="ntbs"></a></span></dt> +<dd><p> + Null-Terminated Byte String, or 'C'-string. C++ string literals are + <span class="bold"><strong>ntbs</strong></span>es. An <span class="bold"><strong>ntbs</strong></span> + must never be null. + </p></dd> +<dt><span class="term">raise <a name="raise"></a></span></dt> +<dd><p> + Exceptions in Python are "raised", not "thrown", + as they are in C++. When this documentation says that some Python exception + is "raised" in the context of C++ code, it means that the corresponding + Python exception is set via the <a href="http://www.python.org/doc/current/api/exceptionHandling.html" target="_top">Python/'C' + API</a>, and <code class="computeroutput"><span class="identifier">throw_error_already_set</span><span class="special">()</span></code> is called. + </p></dd> +<dt><span class="term">POD <a name="pod"></a></span></dt> +<dd><p> + A technical term from the C++ standard. Short for "Plain Ol'Data": + A POD-struct is an aggregate class that has no non-static data members + of type pointer to member, non-POD-struct, non-POD-union (or array of + such types) or reference, and has no user-defined copy assign- ment operator + and no user-defined destructor. Similarly, a POD-union is an aggregate + union that has no non-static data members of type pointer to member, + non-POD-struct, non-POD-union (or array of such types) or reference, + and has no user-defined copy assignment operator and no user-defined + destructor. A POD class is a class that is either a POD-struct or a POD-union. + An aggregate is an array or a class (clause 9) with no user-declared + constructors (12.1), no private or protected non-static data members + (clause 11), no base classes (clause 10), and no virtual functions (10.3). + </p></dd> +<dt><span class="term">ODR <a name="odr"></a></span></dt> +<dd><p> + The "One Definition Rule", which says that any entity in a + C++ program must have the same definition in all translation units (object + files) which make up a program. + </p></dd> +</dl> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="faq/is_boost_python_thread_aware_com.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/tutorial/doc/html/images/alert.png b/libs/python/doc/html/images/alert.png Binary files differindex b4645bc7e7..b4645bc7e7 100755..100644 --- a/libs/python/doc/tutorial/doc/html/images/alert.png +++ b/libs/python/doc/html/images/alert.png diff --git a/libs/python/doc/html/images/blank.png b/libs/python/doc/html/images/blank.png Binary files differnew file mode 100644 index 0000000000..764bf4f0c3 --- /dev/null +++ b/libs/python/doc/html/images/blank.png diff --git a/libs/python/doc/html/images/boost.png b/libs/python/doc/html/images/boost.png Binary files differnew file mode 100644 index 0000000000..b4d51fcd5c --- /dev/null +++ b/libs/python/doc/html/images/boost.png diff --git a/libs/python/doc/html/images/callouts/1.png b/libs/python/doc/html/images/callouts/1.png Binary files differnew file mode 100644 index 0000000000..6003ad3af4 --- /dev/null +++ b/libs/python/doc/html/images/callouts/1.png diff --git a/libs/python/doc/html/images/callouts/1.svg b/libs/python/doc/html/images/callouts/1.svg new file mode 100644 index 0000000000..e2e87dc526 --- /dev/null +++ b/libs/python/doc/html/images/callouts/1.svg @@ -0,0 +1,15 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M10.428,10.411h0.56c3.78,0,4.788-1.96,4.872-3.444h3.22v19.88h-3.92V13.154h-4.732V10.411z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/10.png b/libs/python/doc/html/images/callouts/10.png Binary files differnew file mode 100644 index 0000000000..0426f516a4 --- /dev/null +++ b/libs/python/doc/html/images/callouts/10.png diff --git a/libs/python/doc/html/images/callouts/10.svg b/libs/python/doc/html/images/callouts/10.svg new file mode 100644 index 0000000000..4740f587bd --- /dev/null +++ b/libs/python/doc/html/images/callouts/10.svg @@ -0,0 +1,18 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M3.815,10.758h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76v17.04h-3.36V13.11H3.815V10.758z"/> + <path style="fill:#FFFFFF;" d="M22.175,7.806c4.009,0,5.904,2.76,5.904,8.736c0,5.975-1.896,8.76-5.904,8.76 + c-4.008,0-5.904-2.785-5.904-8.76C16.271,10.566,18.167,7.806,22.175,7.806z M22.175,22.613c1.921,0,2.448-1.68,2.448-6.071 + c0-4.393-0.527-6.049-2.448-6.049c-1.92,0-2.448,1.656-2.448,6.049C19.727,20.934,20.255,22.613,22.175,22.613z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/11.png b/libs/python/doc/html/images/callouts/11.png Binary files differnew file mode 100644 index 0000000000..821afc4fa8 --- /dev/null +++ b/libs/python/doc/html/images/callouts/11.png diff --git a/libs/python/doc/html/images/callouts/11.svg b/libs/python/doc/html/images/callouts/11.svg new file mode 100644 index 0000000000..09a0b2cf71 --- /dev/null +++ b/libs/python/doc/html/images/callouts/11.svg @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M5.209,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.36V12.764H5.209V10.412z"/> + <path style="fill:#FFFFFF;" d="M18.553,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.359V12.764h-4.056V10.412z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/12.png b/libs/python/doc/html/images/callouts/12.png Binary files differnew file mode 100644 index 0000000000..7cec72720f --- /dev/null +++ b/libs/python/doc/html/images/callouts/12.png diff --git a/libs/python/doc/html/images/callouts/12.svg b/libs/python/doc/html/images/callouts/12.svg new file mode 100644 index 0000000000..9794044c71 --- /dev/null +++ b/libs/python/doc/html/images/callouts/12.svg @@ -0,0 +1,18 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M4.813,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.36V12.764H4.813V10.412z"/> + <path style="fill:#FFFFFF;" d="M17.316,13.484c0-5.545,4.056-6.024,5.568-6.024c3.265,0,5.856,1.92,5.856,5.376 + c0,2.928-1.896,4.416-3.553,5.544c-2.256,1.584-3.432,2.353-3.815,3.145h7.392V24.5h-11.64c0.12-1.992,0.264-4.08,3.96-6.768 + c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.353-2.424c-2.352,0-2.423,1.944-2.447,3.192H17.316z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/13.png b/libs/python/doc/html/images/callouts/13.png Binary files differnew file mode 100644 index 0000000000..5b41e02a67 --- /dev/null +++ b/libs/python/doc/html/images/callouts/13.png diff --git a/libs/python/doc/html/images/callouts/13.svg b/libs/python/doc/html/images/callouts/13.svg new file mode 100644 index 0000000000..64268bb4fa --- /dev/null +++ b/libs/python/doc/html/images/callouts/13.svg @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M3.813,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.36V12.764H3.813V10.412z"/> + <path style="fill:#FFFFFF;" d="M20.611,14.636h0.529c1.008,0,2.855-0.096,2.855-2.304c0-0.624-0.288-2.185-2.137-2.185 + c-2.303,0-2.303,2.185-2.303,2.784h-3.12c0-3.191,1.8-5.472,5.64-5.472c2.279,0,5.279,1.152,5.279,4.752 + c0,1.728-1.08,2.808-2.039,3.24V15.5c0.6,0.168,2.568,1.056,2.568,3.96c0,3.216-2.377,5.496-5.809,5.496 + c-1.607,0-5.928-0.36-5.928-5.688h3.288l-0.024,0.024c0,0.912,0.24,2.976,2.496,2.976c1.344,0,2.52-0.911,2.52-2.808 + c0-2.328-2.256-2.424-3.816-2.424V14.636z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/14.png b/libs/python/doc/html/images/callouts/14.png Binary files differnew file mode 100644 index 0000000000..de5bdbd3eb --- /dev/null +++ b/libs/python/doc/html/images/callouts/14.png diff --git a/libs/python/doc/html/images/callouts/14.svg b/libs/python/doc/html/images/callouts/14.svg new file mode 100644 index 0000000000..469aa97487 --- /dev/null +++ b/libs/python/doc/html/images/callouts/14.svg @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M4.146,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.36V12.764H4.146V10.412z"/> + <path style="fill:#FFFFFF;" d="M28.457,20.732h-1.896V24.5h-3.36v-3.768h-6.72v-2.904L22.746,7.46h3.815v10.656h1.896V20.732z + M23.201,18.116c0-4.128,0.072-6.792,0.072-7.32h-0.048l-4.272,7.32H23.201z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/15.png b/libs/python/doc/html/images/callouts/15.png Binary files differnew file mode 100644 index 0000000000..3fd6ac3860 --- /dev/null +++ b/libs/python/doc/html/images/callouts/15.png diff --git a/libs/python/doc/html/images/callouts/15.svg b/libs/python/doc/html/images/callouts/15.svg new file mode 100644 index 0000000000..8202233ef0 --- /dev/null +++ b/libs/python/doc/html/images/callouts/15.svg @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M3.479,11.079h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76v17.04h-3.36V13.43H3.479V11.079z"/> + <path style="fill:#FFFFFF;" d="M19.342,14.943c0.625-0.433,1.392-0.937,3.048-0.937c2.279,0,5.16,1.584,5.16,5.496 + c0,2.328-1.176,6.121-6.192,6.121c-2.664,0-5.376-1.584-5.544-5.016h3.36c0.144,1.391,0.888,2.326,2.376,2.326 + c1.607,0,2.544-1.367,2.544-3.191c0-1.512-0.72-3.047-2.496-3.047c-0.456,0-1.608,0.023-2.256,1.223l-3-0.143l1.176-9.361h9.36 + v2.832h-6.937L19.342,14.943z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/16.svg b/libs/python/doc/html/images/callouts/16.svg new file mode 100644 index 0000000000..01d6bf8164 --- /dev/null +++ b/libs/python/doc/html/images/callouts/16.svg @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M3.813,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.36V12.764H3.813V10.412z"/> + <path style="fill:#FFFFFF;" d="M24.309,11.78c-0.097-0.96-0.721-1.633-1.969-1.633c-2.184,0-2.688,2.496-2.808,4.704L19.58,14.9 + c0.456-0.624,1.296-1.416,3.191-1.416c3.529,0,5.209,2.712,5.209,5.256c0,3.72-2.28,6.216-5.568,6.216 + c-5.16,0-6.168-4.32-6.168-8.568c0-3.24,0.432-8.928,6.336-8.928c0.695,0,2.641,0.264,3.48,1.104 + c0.936,0.912,1.271,1.416,1.584,3.217H24.309z M22.172,16.172c-1.271,0-2.568,0.792-2.568,2.928c0,1.849,1.056,3.168,2.664,3.168 + c1.225,0,2.353-0.936,2.353-3.239C24.62,16.868,23.229,16.172,22.172,16.172z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/17.svg b/libs/python/doc/html/images/callouts/17.svg new file mode 100644 index 0000000000..0a04c5560e --- /dev/null +++ b/libs/python/doc/html/images/callouts/17.svg @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M3.479,11.079h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76v17.04h-3.36V13.43H3.479V11.079z"/> + <path style="fill:#FFFFFF;" d="M27.838,11.006c-1.631,1.776-5.807,6.816-6.215,14.16h-3.457c0.36-6.816,4.632-12.24,6.072-13.776 + h-8.472l0.072-2.976h12V11.006z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/18.svg b/libs/python/doc/html/images/callouts/18.svg new file mode 100644 index 0000000000..1cb891b34d --- /dev/null +++ b/libs/python/doc/html/images/callouts/18.svg @@ -0,0 +1,21 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M4.813,10.412h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76V24.5h-3.36V12.764H4.813V10.412z"/> + <path style="fill:#FFFFFF;" d="M23.172,24.956c-4.392,0-5.904-2.856-5.904-5.185c0-0.863,0-3.119,2.592-4.319 + c-1.344-0.672-2.064-1.752-2.064-3.336c0-2.904,2.328-4.656,5.304-4.656c3.528,0,5.4,2.088,5.4,4.44 + c0,1.464-0.6,2.712-1.968,3.432c1.632,0.815,2.544,1.896,2.544,4.104C29.076,21.596,27.684,24.956,23.172,24.956z M23.124,16.916 + c-1.224,0-2.4,0.792-2.4,2.64c0,1.632,0.936,2.712,2.472,2.712c1.752,0,2.424-1.512,2.424-2.688 + C25.62,18.38,24.996,16.916,23.124,16.916z M25.284,12.26c0-1.296-0.888-2.112-1.968-2.112c-1.512,0-2.305,0.864-2.305,2.112 + c0,1.008,0.744,2.112,2.185,2.112C24.516,14.372,25.284,13.484,25.284,12.26z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/19.svg b/libs/python/doc/html/images/callouts/19.svg new file mode 100644 index 0000000000..e6fbb179fc --- /dev/null +++ b/libs/python/doc/html/images/callouts/19.svg @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M4.146,10.746h0.48c3.24,0,4.104-1.681,4.176-2.952h2.76v17.041h-3.36V13.097H4.146V10.746z"/> + <path style="fill:#FFFFFF;" d="M20.225,20.898v0.023c0.192,1.176,0.936,1.68,1.968,1.68c1.392,0,2.783-1.176,2.808-4.752 + l-0.048-0.049c-0.768,1.152-2.088,1.441-3.24,1.441c-3.264,0-5.16-2.473-5.16-5.329c0-4.176,2.472-6.12,5.808-6.12 + c5.904,0,6,6.36,6,8.76c0,6.601-3.12,8.736-6.192,8.736c-2.904,0-4.992-1.68-5.28-4.391H20.225z M22.434,16.553 + c1.176,0,2.472-0.84,2.472-2.855c0-1.944-0.841-3.145-2.568-3.145c-0.864,0-2.424,0.433-2.424,2.88 + C19.913,16.001,21.161,16.553,22.434,16.553z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/2.png b/libs/python/doc/html/images/callouts/2.png Binary files differnew file mode 100644 index 0000000000..f7c1578846 --- /dev/null +++ b/libs/python/doc/html/images/callouts/2.png diff --git a/libs/python/doc/html/images/callouts/2.svg b/libs/python/doc/html/images/callouts/2.svg new file mode 100644 index 0000000000..07d03395d0 --- /dev/null +++ b/libs/python/doc/html/images/callouts/2.svg @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M9.668,12.328c0-6.469,4.732-7.028,6.496-7.028c3.808,0,6.833,2.24,6.833,6.271 + c0,3.416-2.213,5.152-4.145,6.469c-2.632,1.848-4.004,2.744-4.452,3.668h8.624v3.472H9.444c0.14-2.324,0.308-4.76,4.62-7.896 + c3.584-2.604,5.012-3.612,5.012-5.853c0-1.315-0.84-2.828-2.744-2.828c-2.744,0-2.828,2.269-2.856,3.725H9.668z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/20.svg b/libs/python/doc/html/images/callouts/20.svg new file mode 100644 index 0000000000..ccbfd40319 --- /dev/null +++ b/libs/python/doc/html/images/callouts/20.svg @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376 + c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768 + c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/> + <path style="fill:#FFFFFF;" d="M23.172,7.46c4.008,0,5.904,2.76,5.904,8.736c0,5.976-1.896,8.76-5.904,8.76 + s-5.904-2.784-5.904-8.76C17.268,10.22,19.164,7.46,23.172,7.46z M23.172,22.268c1.92,0,2.448-1.68,2.448-6.071 + c0-4.393-0.528-6.049-2.448-6.049s-2.448,1.656-2.448,6.049C20.724,20.588,21.252,22.268,23.172,22.268z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/21.svg b/libs/python/doc/html/images/callouts/21.svg new file mode 100644 index 0000000000..93ec53fdd9 --- /dev/null +++ b/libs/python/doc/html/images/callouts/21.svg @@ -0,0 +1,18 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M5.306,13.151c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376 + c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392v2.976H5.114c0.12-1.992,0.264-4.08,3.96-6.768 + c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H5.306z"/> + <path style="fill:#FFFFFF;" d="M19.49,10.079h0.48c3.239,0,4.104-1.681,4.176-2.952h2.761v17.04h-3.361V12.431H19.49V10.079z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/22.svg b/libs/python/doc/html/images/callouts/22.svg new file mode 100644 index 0000000000..f48c5f3fd1 --- /dev/null +++ b/libs/python/doc/html/images/callouts/22.svg @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376 + c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768 + c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/> + <path style="fill:#FFFFFF;" d="M17.316,13.484c0-5.545,4.056-6.024,5.568-6.024c3.265,0,5.856,1.92,5.856,5.376 + c0,2.928-1.896,4.416-3.553,5.544c-2.256,1.584-3.432,2.353-3.815,3.145h7.392V24.5h-11.64c0.12-1.992,0.264-4.08,3.96-6.768 + c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.353-2.424c-2.352,0-2.423,1.944-2.447,3.192H17.316z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/23.svg b/libs/python/doc/html/images/callouts/23.svg new file mode 100644 index 0000000000..6624212957 --- /dev/null +++ b/libs/python/doc/html/images/callouts/23.svg @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376 + c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768 + c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/> + <path style="fill:#FFFFFF;" d="M21.612,14.636h0.528c1.008,0,2.855-0.096,2.855-2.304c0-0.624-0.287-2.185-2.136-2.185 + c-2.304,0-2.304,2.185-2.304,2.784h-3.12c0-3.191,1.8-5.472,5.64-5.472c2.28,0,5.28,1.152,5.28,4.752 + c0,1.728-1.08,2.808-2.04,3.24V15.5c0.6,0.168,2.568,1.056,2.568,3.96c0,3.216-2.377,5.496-5.809,5.496 + c-1.607,0-5.928-0.36-5.928-5.688h3.288l-0.024,0.024c0,0.912,0.24,2.976,2.496,2.976c1.344,0,2.521-0.911,2.521-2.808 + c0-2.328-2.257-2.424-3.816-2.424V14.636z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/24.svg b/libs/python/doc/html/images/callouts/24.svg new file mode 100644 index 0000000000..a3d552535f --- /dev/null +++ b/libs/python/doc/html/images/callouts/24.svg @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M4.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376 + c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H4.78c0.12-1.992,0.264-4.08,3.96-6.768 + c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H4.972z"/> + <path style="fill:#FFFFFF;" d="M30.124,20.732h-1.896V24.5h-3.36v-3.768h-6.72v-2.904L24.412,7.46h3.816v10.656h1.896V20.732z + M24.868,18.116c0-4.128,0.071-6.792,0.071-7.32h-0.047l-4.272,7.32H24.868z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/25.svg b/libs/python/doc/html/images/callouts/25.svg new file mode 100644 index 0000000000..56614a979a --- /dev/null +++ b/libs/python/doc/html/images/callouts/25.svg @@ -0,0 +1,21 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376 + c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768 + c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/> + <path style="fill:#FFFFFF;" d="M20.676,14.276c0.624-0.433,1.393-0.937,3.049-0.937c2.279,0,5.16,1.584,5.16,5.496 + c0,2.328-1.177,6.12-6.193,6.12c-2.664,0-5.375-1.584-5.543-5.016h3.36c0.144,1.392,0.889,2.327,2.376,2.327 + c1.608,0,2.544-1.367,2.544-3.191c0-1.513-0.72-3.048-2.496-3.048c-0.455,0-1.607,0.023-2.256,1.224l-3-0.144l1.176-9.36h9.36 + v2.832h-6.937L20.676,14.276z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/26.svg b/libs/python/doc/html/images/callouts/26.svg new file mode 100644 index 0000000000..56faeaca30 --- /dev/null +++ b/libs/python/doc/html/images/callouts/26.svg @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376 + c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768 + c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/> + <path style="fill:#FFFFFF;" d="M25.309,11.78c-0.097-0.96-0.721-1.633-1.969-1.633c-2.184,0-2.688,2.496-2.808,4.704L20.58,14.9 + c0.456-0.624,1.296-1.416,3.191-1.416c3.529,0,5.209,2.712,5.209,5.256c0,3.72-2.28,6.216-5.568,6.216 + c-5.16,0-6.168-4.32-6.168-8.568c0-3.24,0.432-8.928,6.336-8.928c0.695,0,2.641,0.264,3.48,1.104 + c0.936,0.912,1.271,1.416,1.584,3.217H25.309z M23.172,16.172c-1.271,0-2.568,0.792-2.568,2.928c0,1.849,1.056,3.168,2.664,3.168 + c1.225,0,2.353-0.936,2.353-3.239C25.62,16.868,24.229,16.172,23.172,16.172z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/27.svg b/libs/python/doc/html/images/callouts/27.svg new file mode 100644 index 0000000000..a75c812159 --- /dev/null +++ b/libs/python/doc/html/images/callouts/27.svg @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376 + c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768 + c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/> + <path style="fill:#FFFFFF;" d="M29.172,10.34c-1.632,1.776-5.808,6.816-6.216,14.16H19.5c0.36-6.816,4.632-12.24,6.072-13.776 + H17.1l0.072-2.976h12V10.34z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/28.svg b/libs/python/doc/html/images/callouts/28.svg new file mode 100644 index 0000000000..7f8cf1a350 --- /dev/null +++ b/libs/python/doc/html/images/callouts/28.svg @@ -0,0 +1,23 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376 + c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768 + c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/> + <path style="fill:#FFFFFF;" d="M23.172,24.956c-4.392,0-5.904-2.856-5.904-5.185c0-0.863,0-3.119,2.592-4.319 + c-1.344-0.672-2.064-1.752-2.064-3.336c0-2.904,2.328-4.656,5.304-4.656c3.528,0,5.4,2.088,5.4,4.44 + c0,1.464-0.6,2.712-1.968,3.432c1.632,0.815,2.544,1.896,2.544,4.104C29.076,21.596,27.684,24.956,23.172,24.956z M23.124,16.916 + c-1.224,0-2.4,0.792-2.4,2.64c0,1.632,0.936,2.712,2.472,2.712c1.752,0,2.424-1.512,2.424-2.688 + C25.62,18.38,24.996,16.916,23.124,16.916z M25.284,12.26c0-1.296-0.888-2.112-1.968-2.112c-1.512,0-2.305,0.864-2.305,2.112 + c0,1.008,0.744,2.112,2.185,2.112C24.516,14.372,25.284,13.484,25.284,12.26z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/29.svg b/libs/python/doc/html/images/callouts/29.svg new file mode 100644 index 0000000000..cb63adf1fe --- /dev/null +++ b/libs/python/doc/html/images/callouts/29.svg @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M3.972,13.484c0-5.545,4.056-6.024,5.568-6.024c3.264,0,5.856,1.92,5.856,5.376 + c0,2.928-1.896,4.416-3.552,5.544c-2.256,1.584-3.432,2.353-3.816,3.145h7.392V24.5H3.78c0.12-1.992,0.264-4.08,3.96-6.768 + c3.072-2.232,4.296-3.097,4.296-5.017c0-1.128-0.72-2.424-2.352-2.424c-2.352,0-2.424,1.944-2.448,3.192H3.972z"/> + <path style="fill:#FFFFFF;" d="M20.893,20.564v0.023c0.191,1.176,0.936,1.68,1.967,1.68c1.393,0,2.785-1.176,2.809-4.752 + l-0.048-0.048c-0.769,1.152-2.088,1.44-3.24,1.44c-3.264,0-5.16-2.473-5.16-5.328c0-4.176,2.472-6.12,5.807-6.12 + c5.904,0,6.001,6.36,6.001,8.76c0,6.601-3.12,8.736-6.192,8.736c-2.904,0-4.992-1.68-5.28-4.392H20.893z M23.1,16.22 + c1.176,0,2.473-0.84,2.473-2.855c0-1.944-0.84-3.145-2.568-3.145c-0.863,0-2.424,0.433-2.424,2.88 + C20.58,15.668,21.828,16.22,23.1,16.22z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/3.png b/libs/python/doc/html/images/callouts/3.png Binary files differnew file mode 100644 index 0000000000..3ff0a93931 --- /dev/null +++ b/libs/python/doc/html/images/callouts/3.png diff --git a/libs/python/doc/html/images/callouts/3.svg b/libs/python/doc/html/images/callouts/3.svg new file mode 100644 index 0000000000..918be806f4 --- /dev/null +++ b/libs/python/doc/html/images/callouts/3.svg @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M15.127,14.005h0.616c1.176,0,3.332-0.112,3.332-2.688c0-0.728-0.336-2.548-2.492-2.548 + c-2.688,0-2.688,2.548-2.688,3.248h-3.64c0-3.724,2.1-6.384,6.58-6.384c2.66,0,6.16,1.344,6.16,5.544 + c0,2.016-1.261,3.276-2.38,3.78v0.056c0.699,0.196,2.996,1.232,2.996,4.62c0,3.752-2.772,6.412-6.776,6.412 + c-1.876,0-6.916-0.42-6.916-6.636h3.836l-0.028,0.027c0,1.064,0.28,3.473,2.912,3.473c1.568,0,2.94-1.064,2.94-3.276 + c0-2.716-2.632-2.828-4.452-2.828V14.005z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/30.svg b/libs/python/doc/html/images/callouts/30.svg new file mode 100644 index 0000000000..dc43ba1e3c --- /dev/null +++ b/libs/python/doc/html/images/callouts/30.svg @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M8.268,14.636h0.528c1.008,0,2.856-0.096,2.856-2.304c0-0.624-0.288-2.185-2.136-2.185 + c-2.304,0-2.304,2.185-2.304,2.784h-3.12c0-3.191,1.8-5.472,5.64-5.472c2.28,0,5.28,1.152,5.28,4.752 + c0,1.728-1.08,2.808-2.04,3.24V15.5c0.6,0.168,2.568,1.056,2.568,3.96c0,3.216-2.376,5.496-5.808,5.496 + c-1.608,0-5.928-0.36-5.928-5.688h3.288l-0.024,0.024c0,0.912,0.24,2.976,2.496,2.976c1.344,0,2.52-0.911,2.52-2.808 + c0-2.328-2.256-2.424-3.816-2.424V14.636z"/> + <path style="fill:#FFFFFF;" d="M23.172,7.46c4.008,0,5.904,2.76,5.904,8.736c0,5.976-1.896,8.76-5.904,8.76 + s-5.904-2.784-5.904-8.76C17.268,10.22,19.164,7.46,23.172,7.46z M23.172,22.268c1.92,0,2.448-1.68,2.448-6.071 + c0-4.393-0.528-6.049-2.448-6.049s-2.448,1.656-2.448,6.049C20.724,20.588,21.252,22.268,23.172,22.268z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/4.png b/libs/python/doc/html/images/callouts/4.png Binary files differnew file mode 100644 index 0000000000..6aa29fc0b4 --- /dev/null +++ b/libs/python/doc/html/images/callouts/4.png diff --git a/libs/python/doc/html/images/callouts/4.svg b/libs/python/doc/html/images/callouts/4.svg new file mode 100644 index 0000000000..8eb6a53b3b --- /dev/null +++ b/libs/python/doc/html/images/callouts/4.svg @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M21.891,20.784h-2.212v4.396h-3.92v-4.396h-7.84v-3.389L15.227,5.3h4.452v12.432h2.212V20.784z + M15.759,17.731c0-4.815,0.084-7.924,0.084-8.54h-0.056l-4.984,8.54H15.759z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/5.png b/libs/python/doc/html/images/callouts/5.png Binary files differnew file mode 100644 index 0000000000..36e785867a --- /dev/null +++ b/libs/python/doc/html/images/callouts/5.png diff --git a/libs/python/doc/html/images/callouts/5.svg b/libs/python/doc/html/images/callouts/5.svg new file mode 100644 index 0000000000..ca7a9f22f6 --- /dev/null +++ b/libs/python/doc/html/images/callouts/5.svg @@ -0,0 +1,18 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M14.035,14.252c0.728-0.504,1.624-1.092,3.556-1.092c2.66,0,6.02,1.848,6.02,6.411 + c0,2.717-1.372,7.141-7.224,7.141c-3.108,0-6.272-1.849-6.468-5.853h3.92c0.168,1.624,1.036,2.717,2.772,2.717 + c1.876,0,2.968-1.597,2.968-3.725c0-1.764-0.839-3.556-2.912-3.556c-0.532,0-1.876,0.028-2.632,1.428l-3.5-0.168l1.372-10.92 + h10.919v3.304h-8.092L14.035,14.252z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/6.png b/libs/python/doc/html/images/callouts/6.png Binary files differnew file mode 100644 index 0000000000..c943676bea --- /dev/null +++ b/libs/python/doc/html/images/callouts/6.png diff --git a/libs/python/doc/html/images/callouts/6.svg b/libs/python/doc/html/images/callouts/6.svg new file mode 100644 index 0000000000..783a0b9d77 --- /dev/null +++ b/libs/python/doc/html/images/callouts/6.svg @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M19.106,10.673c-0.112-1.12-0.84-1.904-2.296-1.904c-2.548,0-3.136,2.912-3.276,5.488l0.056,0.056 + c0.532-0.728,1.512-1.651,3.724-1.651c4.116,0,6.077,3.164,6.077,6.131c0,4.34-2.66,7.252-6.497,7.252 + c-6.02,0-7.196-5.039-7.196-9.996c0-3.78,0.504-10.416,7.392-10.416c0.812,0,3.08,0.308,4.061,1.288 + c1.092,1.063,1.483,1.652,1.848,3.752H19.106z M16.614,15.797c-1.484,0-2.996,0.924-2.996,3.416c0,2.156,1.232,3.697,3.108,3.697 + c1.428,0,2.745-1.094,2.745-3.781C19.471,16.609,17.846,15.797,16.614,15.797z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/7.png b/libs/python/doc/html/images/callouts/7.png Binary files differnew file mode 100644 index 0000000000..20940de30d --- /dev/null +++ b/libs/python/doc/html/images/callouts/7.png diff --git a/libs/python/doc/html/images/callouts/7.svg b/libs/python/doc/html/images/callouts/7.svg new file mode 100644 index 0000000000..59b3714b56 --- /dev/null +++ b/libs/python/doc/html/images/callouts/7.svg @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M24.28,9.66c-1.904,2.071-6.776,7.951-7.252,16.52h-4.032c0.42-7.952,5.404-14.28,7.084-16.072 + h-9.884l0.084-3.472h14V9.66z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/8.png b/libs/python/doc/html/images/callouts/8.png Binary files differnew file mode 100644 index 0000000000..d8e34d4a09 --- /dev/null +++ b/libs/python/doc/html/images/callouts/8.png diff --git a/libs/python/doc/html/images/callouts/8.svg b/libs/python/doc/html/images/callouts/8.svg new file mode 100644 index 0000000000..c1803a3c0d --- /dev/null +++ b/libs/python/doc/html/images/callouts/8.svg @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M16.28,26.712c-5.124,0-6.888-3.332-6.888-6.048c0-1.009,0-3.641,3.024-5.04 + c-1.568-0.784-2.408-2.044-2.408-3.893c0-3.388,2.716-5.432,6.188-5.432c4.116,0,6.3,2.436,6.3,5.18 + c0,1.708-0.7,3.164-2.296,4.004c1.903,0.952,2.968,2.212,2.968,4.788C23.168,22.792,21.544,26.712,16.28,26.712z M16.224,17.332 + c-1.428,0-2.8,0.924-2.8,3.08c0,1.903,1.092,3.164,2.884,3.164c2.043,0,2.829-1.765,2.829-3.137 + C19.137,19.04,18.408,17.332,16.224,17.332z M18.744,11.899c0-1.512-1.036-2.464-2.296-2.464c-1.764,0-2.688,1.008-2.688,2.464 + c0,1.177,0.868,2.464,2.548,2.464C17.848,14.363,18.744,13.328,18.744,11.899z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/callouts/9.png b/libs/python/doc/html/images/callouts/9.png Binary files differnew file mode 100644 index 0000000000..abe636072b --- /dev/null +++ b/libs/python/doc/html/images/callouts/9.png diff --git a/libs/python/doc/html/images/callouts/9.svg b/libs/python/doc/html/images/callouts/9.svg new file mode 100644 index 0000000000..bc149d3cb2 --- /dev/null +++ b/libs/python/doc/html/images/callouts/9.svg @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 12.0.1, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --> +<!DOCTYPE svg [ + <!ENTITY ns_svg "http://www.w3.org/2000/svg"> + <!ENTITY ns_xlink "http://www.w3.org/1999/xlink"> +]> +<svg version="1.0" id="Layer_1" xmlns="&ns_svg;" xmlns:xlink="&ns_xlink;" width="33" height="33" viewBox="0 0 33 33" + style="overflow:visible;enable-background:new 0 0 33 33;" xml:space="preserve"> +<circle style="stroke:#000000;" cx="16.5" cy="16.5" r="16"/> +<g> + <g style="enable-background:new ;"> + <path style="fill:#FFFFFF;" d="M13.953,21.921v0.027c0.224,1.372,1.092,1.961,2.296,1.961c1.624,0,3.248-1.372,3.276-5.545 + l-0.057-0.056c-0.896,1.344-2.436,1.68-3.78,1.68c-3.808,0-6.02-2.884-6.02-6.216c0-4.872,2.884-7.14,6.776-7.14 + c6.888,0,7,7.42,7,10.22c0,7.7-3.641,10.192-7.224,10.192c-3.388,0-5.824-1.96-6.16-5.124H13.953z M16.529,16.853 + c1.372,0,2.884-0.979,2.884-3.332c0-2.268-0.98-3.668-2.996-3.668c-1.008,0-2.828,0.504-2.828,3.36 + C13.589,16.209,15.045,16.853,16.529,16.853z"/> + </g> +</g> +</svg> diff --git a/libs/python/doc/html/images/caution.png b/libs/python/doc/html/images/caution.png Binary files differnew file mode 100644 index 0000000000..5b7809ca4a --- /dev/null +++ b/libs/python/doc/html/images/caution.png diff --git a/libs/python/doc/html/images/caution.svg b/libs/python/doc/html/images/caution.svg new file mode 100644 index 0000000000..4bd586a08e --- /dev/null +++ b/libs/python/doc/html/images/caution.svg @@ -0,0 +1,68 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Generator: Adobe Illustrator 12.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 51448) --><svg height="120.648" id="Layer_1" inkscape:version="0.42" sodipodi:docbase="F:\openclip\svg da inviare" sodipodi:docname="Attenzione.svg" sodipodi:version="0.32" space="preserve" style="overflow:visible;enable-background:new 0 0 133.878 120.648;" version="1.1" viewBox="0 0 133.878 120.648" width="133.878" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://web.resource.org/cc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:svg="http://www.w3.org/2000/svg"> + <metadata> + <rdf:RDF xmlns:cc="http://web.resource.org/cc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <cc:Work rdf:about=""> + <dc:title>Attenzione</dc:title> + <dc:description></dc:description> + <dc:subject> + <rdf:Bag> + <rdf:li>pulsante</rdf:li> + </rdf:Bag> + </dc:subject> + <dc:publisher> + <cc:Agent rdf:about="http://www.openclipart.org/"> + <dc:title>Open Clip Art Library</dc:title> + </cc:Agent> + </dc:publisher> + <dc:creator> + <cc:Agent> + <dc:title>Architetto Francesco Rollandin</dc:title> + </cc:Agent> + </dc:creator> + <dc:rights> + <cc:Agent> + <dc:title>Architetto Francesco Rollandin</dc:title> + </cc:Agent> + </dc:rights> + <dc:date></dc:date> + <dc:format>image/svg+xml</dc:format> + <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/> + <cc:license rdf:resource="http://web.resource.org/cc/PublicDomain"/> + <dc:language>en</dc:language> + </cc:Work> + <cc:License rdf:about="http://web.resource.org/cc/PublicDomain"> + <cc:permits rdf:resource="http://web.resource.org/cc/Reproduction"/> + <cc:permits rdf:resource="http://web.resource.org/cc/Distribution"/> + <cc:permits rdf:resource="http://web.resource.org/cc/DerivativeWorks"/> + </cc:License> + </rdf:RDF> + </metadata> + <defs id="defs43"/> + <sodipodi:namedview bordercolor="#666666" borderopacity="1.0" id="base" inkscape:current-layer="Layer_1" inkscape:cx="66.939003" inkscape:cy="60.324001" inkscape:pageopacity="0.0" inkscape:pageshadow="2" inkscape:window-height="510" inkscape:window-width="787" inkscape:window-x="44" inkscape:window-y="58" inkscape:zoom="2.9838869" pagecolor="#ffffff"/> + <g id="g3"> + <linearGradient gradientTransform="matrix(56.9977 90.4964 90.4964 -56.9977 -27343.9609 47971.0547)" gradientUnits="userSpaceOnUse" id="XMLID_4_" x1="-244.5732" x2="-242.8169" y1="455.4199" y2="455.4199"> + <stop id="stop6" offset="0" style="stop-color:#FFFA5F"/> + <stop id="stop8" offset="1" style="stop-color:#9F3300"/> + </linearGradient> + <path d="M51.333,8.834C34.985,37.343,18.638,65.854,2.289,94.363 c-7.081,12.352,3.352,26.285,16.453,26.285c6.708,0,13.418,0,20.128,0c22.109,0,44.217,0,66.327,0c3.644,0,7.286,0,10.931,0 c13.293,0,20.963-14.273,16.452-26.031c-4.114-10.729-11.861-20.99-17.542-30.922c-8.81-15.403-17.618-30.809-26.429-46.212 c-1.813-3.167-3.622-6.333-5.434-9.5C76.601-3.516,57.616-2.03,51.333,8.834 M53.973,9.064" id="path10" style="fill:url(#XMLID_4_);"/> + <path d="M55.474,12.388c-8.247,14.279-16.492,28.559-24.739,42.839 c-5.526,9.567-11.05,19.137-16.577,28.707c-2.732,4.73-7.323,10.456-8.284,16c-3.799,21.9,34.927,15.743,46.734,15.743 c20.073,0,40.144,0,60.215,0c13.716,0,18.636-11.963,12.229-23.063c-6.462-11.195-12.927-22.388-19.389-33.582 c-7.249-12.557-14.499-25.113-21.75-37.671c-1.682-2.916-3.364-5.829-5.049-8.745C73.767,3.785,60.676,3.364,55.474,12.388" id="path12" style="fill-rule:evenodd;clip-rule:evenodd;fill:#FFF200;"/> + <path d="M55.474,12.388c-8.247,14.279-16.492,28.559-24.739,42.839c-5.526,9.567-11.05,19.137-16.577,28.707 c-2.732,4.73-7.323,10.456-8.284,16c-3.799,21.9,34.927,15.743,46.734,15.743c20.073,0,40.144,0,60.215,0 c13.716,0,18.636-11.963,12.229-23.063c-6.462-11.195-12.927-22.388-19.389-33.582c-7.249-12.557-14.499-25.113-21.75-37.671 c-1.682-2.916-3.364-5.829-5.049-8.745C73.767,3.785,60.676,3.364,55.474,12.388" id="path14" style="fill:#FFCE00;"/> + <path d="M126.731,95.522c-8.733-15.127-17.468-30.253-26.201-45.379 c-5.537-9.595-11.078-19.188-16.616-28.781c-3.938-6.821-7.459-15.689-16.813-15.689c1.013,0,5.901,10.225,6.469,11.196 c5.451,9.314,10.902,18.63,16.352,27.947c9.217,15.749,18.433,31.498,27.646,47.249c2.302,3.933,5.356,10.555,1.308,14.397 c-3.148,2.987-7.99,3.196-12.099,3.196c-7.225,0-14.448,0-21.674,0c-22.125,0-44.251,0-66.377,0c-3.598,0-7.197,0-10.794,0 c5.285,7.909,16.341,6.02,24.546,6.02c13.009,0,26.017,0,39.023,0c11.979,0,23.958,0,35.937,0c2.516,0,5.032,0,7.547,0 C125.136,115.678,131.878,104.435,126.731,95.522" id="path16" style="fill:#FFB600;"/> + <path d="M14.615,112.457c-4.483-7.751,1.908-16.103,5.793-22.834 c4.698-8.138,9.398-16.276,14.097-24.414C44.54,47.83,54.574,30.448,64.61,13.069c0.789-1.367,3.725-4.568,2.594-5.539 c-3.913-3.353-10.287,1.936-12.107,5.087c-3.129,5.417-6.258,10.835-9.386,16.252c-11.105,19.226-22.209,38.453-33.313,57.68 c-1.649,2.854-3.299,5.713-4.95,8.569c-4.771,8.265-0.075,19.162,9.658,20.446C16.124,114.65,15.294,113.615,14.615,112.457" id="path18" style="fill-rule:evenodd;clip-rule:evenodd;fill:#FFE600;"/> + <path d="M77.076,34.654c0,10.183-1.788,20.758-3.439,30.772 c-0.369,2.239-4.03,23.609-7.796,14.179c-4.247-10.632-4.832-23.419-5.958-34.696c-0.363-3.638-1.538-8.425-0.563-12.06 C61.667,24.099,77.076,25.199,77.076,34.654" id="path20" style="fill-rule:evenodd;clip-rule:evenodd;fill:#FFFFE1;"/> + <path d="M77.076,34.654c-2.018,0.995-1.521,8.717-1.797,11.395c-0.685,6.643-1.505,13.282-2.614,19.869 c-0.79,4.701-1.301,10.862-3.954,14.981c-1.642,2.567-3.405-5.958-3.634-6.932c-2.948-12.443-4.464-25.664-5.09-38.43 c-0.272-5.52,5.164-8.854,10.277-7.622c3.87,0.933,5.217,7.36,7.688,6.738c0.009-11.451-19.755-11.453-19.746,0 c0.017,11.956,2.087,24.599,4.423,36.294c0.501,2.507,1.642,12.376,5.449,12.376c4.059-0.021,5.285-11.432,5.79-14.137 c1.261-6.765,2.139-13.605,2.887-20.444C77.084,45.722,79.281,35.942,77.076,34.654" id="path22" style="fill:#FFFFFF;"/> + <linearGradient gradientTransform="matrix(68.2284 33.0019 33.0019 -68.2284 1613.9791 39385.6641)" gradientUnits="userSpaceOnUse" id="XMLID_5_" x1="-246.981" x2="-245.2275" y1="458.29" y2="458.29"> + <stop id="stop25" offset="0" style="stop-color:#FFFA5F"/> + <stop id="stop27" offset="1" style="stop-color:#9F3300"/> + </linearGradient> + <path d="M57.957,34.654c0,10.053,1.632,20.54,3.242,30.431 c0.479,2.936,4.912,26.502,9.99,15.164c4.987-11.134,5.351-25.201,6.386-37.184c0.273-3.169,1.153-7.045,0.421-10.221 C75.628,22.587,57.957,23.788,57.957,34.654 M60.207,34.654c0-8.061,13.138-9.015,15.459-1.792c1.156,3.597-0.13,8.748-0.508,12.38 c-1.135,10.904-2.052,22.602-5.501,33.069c-2.816,8.545-5.546-10.187-5.934-12.522C62.039,55.63,60.207,44.985,60.207,34.654" id="path29" style="fill-rule:evenodd;clip-rule:evenodd;fill:url(#XMLID_5_);"/> + <path d="M77.076,96.788c0,11.964-18.555,11.964-18.555,0 C58.521,84.822,77.076,84.822,77.076,96.788" id="path31" style="fill-rule:evenodd;clip-rule:evenodd;fill:#FFFFE1;"/> + <path d="M77.076,96.788c-2.605,1.661-2.157,6.757-7.044,8.101c-6.178,1.7-12.033-4.159-10.336-10.335 c1.439-5.23,7.657-7.767,12.341-5.021c2.91,1.704,3.164,7.913,5.915,7.256c0-14.267-22.698-12.238-20.143,1.826 c0.987,5.444,6.375,9.15,11.814,8.162C72.417,106.271,81.44,98.19,77.076,96.788" id="path33" style="fill:#FFFFFF;"/> + <linearGradient gradientTransform="matrix(68.2241 32.9998 32.9998 -68.2241 1604.682 39402.625)" gradientUnits="userSpaceOnUse" id="XMLID_6_" x1="-246.998" x2="-245.2348" y1="458.0625" y2="458.0625"> + <stop id="stop36" offset="0" style="stop-color:#FFFA5F"/> + <stop id="stop38" offset="1" style="stop-color:#9F3300"/> + </linearGradient> + <path d="M57.395,96.788c0,13.41,20.805,13.41,20.805,0 C78.2,83.376,57.395,83.375,57.395,96.788 M59.647,96.788c0-10.514,16.301-10.514,16.301,0 C75.948,107.3,59.647,107.3,59.647,96.788" id="path40" style="fill-rule:evenodd;clip-rule:evenodd;fill:url(#XMLID_6_);"/> + </g> +</svg> diff --git a/libs/python/doc/html/images/draft.png b/libs/python/doc/html/images/draft.png Binary files differnew file mode 100644 index 0000000000..0084708c9b --- /dev/null +++ b/libs/python/doc/html/images/draft.png diff --git a/libs/python/doc/tutorial/doc/html/images/home.png b/libs/python/doc/html/images/home.png Binary files differindex 5584aacb09..5584aacb09 100755..100644 --- a/libs/python/doc/tutorial/doc/html/images/home.png +++ b/libs/python/doc/html/images/home.png diff --git a/libs/python/doc/html/images/home.svg b/libs/python/doc/html/images/home.svg new file mode 100644 index 0000000000..e803a3178f --- /dev/null +++ b/libs/python/doc/html/images/home.svg @@ -0,0 +1,26 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- Generator: Adobe Illustrator 9.0, SVG Export Plug-In --> +<!DOCTYPE svg [ + <!ENTITY st0 "fill-rule:nonzero;clip-rule:nonzero;fill:#FFFFFF;stroke:#000000;stroke-miterlimit:4;"> + <!ENTITY st1 "fill:none;stroke:none;"> + <!ENTITY st2 "fill:#000000;"> + <!ENTITY st3 "fill:none;stroke:#FFFFFF;stroke-width:6.3469;stroke-linejoin:round;"> + <!ENTITY st4 "fill-rule:evenodd;clip-rule:evenodd;stroke:none;"> + <!ENTITY st5 "fill-rule:nonzero;clip-rule:nonzero;stroke:#000000;stroke-miterlimit:4;"> +]> +<svg width="48pt" height="48pt" viewBox="0 0 48 48" xml:space="preserve" xmlns="http://www.w3.org/2000/svg"> + <g id="Layer_x0020_3" style="&st0;"> + <g style="&st4;"> + <path style="&st3;" d="M22.9,7.1L5.1,21.8l0,0c-0.3,0.3-0.5,0.8-0.5,1.2c0,0.2,0,0.4,0.1,0.6c0.3,0.6,0.9,1,1.6,1c0,0,1.1,0,2.2,0c0,2.4,0,14.2,0,14.2c0,1.1,0.8,1.9,1.8,1.9h27.4c1.1,0,1.9-0.9,1.9-2c0,0,0-11.8,0-14.2c1,0,2,0,2,0c0.8,0,1.4-0.5,1.7-1.2 + c0.1-0.2,0.1-0.4,0.1-0.6c0-0.5-0.2-1-0.7-1.4c0,0-3.6-3-4.5-3.7c0-1.2,0-6.9,0-6.9c0-1.2-0.8-2-2-2h-4.8c-1,0-1.7,0.6-1.9,1.5c-1.9-1.6-4.1-3.5-4.1-3.5l0.1,0.1c-0.7-0.7-1.8-0.8-2.7-0.1z"/> + <path style="&st2;" d="M22.9,7.1L5.1,21.8l0,0c-0.3,0.3-0.5,0.8-0.5,1.2c0,0.2,0,0.4,0.1,0.6c0.3,0.6,0.9,1,1.6,1c0,0,1.1,0,2.2,0c0,2.4,0,14.2,0,14.2c0,1.1,0.8,1.9,1.8,1.9h27.4c1.1,0,1.9-0.9,1.9-2c0,0,0-11.8,0-14.2c1,0,2,0,2,0c0.8,0,1.4-0.5,1.7-1.2 + c0.1-0.2,0.1-0.4,0.1-0.6c0-0.5-0.2-1-0.7-1.4c0,0-3.6-3-4.5-3.7c0-1.2,0-6.9,0-6.9c0-1.2-0.8-2-2-2h-4.8c-1,0-1.7,0.6-1.9,1.5c-1.9-1.6-4.1-3.5-4.1-3.5l0.1,0.1c-0.7-0.7-1.8-0.8-2.7-0.1z"/> + <path style="&st2;" d="M41.8,22.8l-5.1-4.2v-0.1L31,13.7v0l-6.5-5.5C24.2,8,24,8,23.8,8.2L6.2,22.9c-0.1,0.1-0.1,0.3,0.1,0.3h1.6H10h28.1h1.2h2.3c0.2,0,0.4-0.2,0.2-0.4z"/> + <path d="M35.8,16.8l0-5.1c0-0.2-0.1-0.4-0.3-0.4h-3.2c-0.2,0-0.3,0.1-0.3,0.3v2.2l3.9,2.9z"/> + <path d="M11.9,24.7V37c0,0.3,0.1,0.4,0.3,0.4h23.6c0.3,0,0.4-0.2,0.4-0.4V24.7H11.9z"/> + </g> + </g> + <g id="crop_x0020_marks" style="&st5;"> + <path style="&st1;" d="M48,48H0V0h48v48z"/> + </g> +</svg> diff --git a/libs/python/doc/html/images/important.png b/libs/python/doc/html/images/important.png Binary files differnew file mode 100644 index 0000000000..12c90f607a --- /dev/null +++ b/libs/python/doc/html/images/important.png diff --git a/libs/python/doc/html/images/important.svg b/libs/python/doc/html/images/important.svg new file mode 100644 index 0000000000..dd84f3fe36 --- /dev/null +++ b/libs/python/doc/html/images/important.svg @@ -0,0 +1,25 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- Generator: Adobe Illustrator 9.0, SVG Export Plug-In --> +<!DOCTYPE svg [ + <!ENTITY st0 "fill:#FFFFFF;stroke:none;"> + <!ENTITY st1 "fill:#FFFFFF;stroke-width:6.6112;stroke-linecap:round;stroke-linejoin:round;"> + <!ENTITY st2 "stroke:#FFFFFF;stroke-width:6.6112;"> + <!ENTITY st3 "fill:none;stroke:none;"> + <!ENTITY st4 "fill-rule:nonzero;clip-rule:nonzero;stroke:#000000;stroke-miterlimit:4;"> + <!ENTITY st5 "stroke:none;"> +]> +<svg width="48pt" height="48pt" viewBox="0 0 48 48" xml:space="preserve" xmlns="http://www.w3.org/2000/svg"> + <g id="Layer_x0020_3" style="&st4;"> + <g> + <path style="&st2;" d="M41.7,35.3L26.6,9.4c-0.6-1-1.7-1.7-2.9-1.6c-1.2,0-2.3,0.7-2.9,1.7L6.3,35.4c-0.6,1-0.6,2.3,0,3.3c0.6,1,1.7,1.6,2.9,1.6h29.6c1.2,0,2.3-0.6,2.9-1.7c0.6-1,0.6-2.3,0-3.3z"/> + <path style="&st1;" d="M23.7,11L9.2,37h29.6L23.7,11z"/> + <path style="&st0;" d="M23.7,11.9L10.3,36.1h27.5l-14-24.1z"/> + <g> + <path style="&st5;" d="M24.1,34c-1.1,0-1.8-0.8-1.8-1.8c0-1.1,0.7-1.8,1.8-1.8c1.1,0,1.8,0.7,1.8,1.8c0,1-0.7,1.8-1.8,1.8h0z M22.9,29.3l-0.4-9.1h3.2l-0.4,9.1h-2.3z"/> + </g> + </g> + </g> + <g id="crop_x0020_marks" style="&st4;"> + <path style="&st3;" d="M48,48H0V0h48v48z"/> + </g> +</svg> diff --git a/libs/python/doc/tutorial/doc/html/images/jam.png b/libs/python/doc/html/images/jam.png Binary files differindex 224ed7914b..224ed7914b 100644 --- a/libs/python/doc/tutorial/doc/html/images/jam.png +++ b/libs/python/doc/html/images/jam.png diff --git a/libs/python/doc/tutorial/doc/html/images/next.png b/libs/python/doc/html/images/next.png Binary files differindex 59800b4e87..59800b4e87 100755..100644 --- a/libs/python/doc/tutorial/doc/html/images/next.png +++ b/libs/python/doc/html/images/next.png diff --git a/libs/python/doc/html/images/next.svg b/libs/python/doc/html/images/next.svg new file mode 100644 index 0000000000..75fa83ed8c --- /dev/null +++ b/libs/python/doc/html/images/next.svg @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- Generator: Adobe Illustrator 9.0, SVG Export Plug-In --> +<!DOCTYPE svg [ + <!ENTITY st0 "fill:none;stroke:none;"> + <!ENTITY st1 "fill:#FFFFFF;stroke:#FFFFFF;stroke-width:7.5901;stroke-linejoin:round;"> + <!ENTITY st2 "fill-rule:nonzero;clip-rule:nonzero;stroke:#000000;stroke-miterlimit:4;"> + <!ENTITY st3 "stroke:none;"> +]> +<svg width="48pt" height="48pt" viewBox="0 0 48 48" xml:space="preserve" xmlns="http://www.w3.org/2000/svg"> + <g id="Layer_x0020_3" style="&st2;"> + <g> + <path style="&st1;" d="M22.4,41.1c0,0.3,0.3,0.3,0.5,0.2l16.6-16.9c0.5-0.5,0.4-0.7,0-1L22.9,6.7c-0.1-0.1-0.4-0.1-0.4,0.1v10H8.9c-0.3,0-0.5,0.2-0.5,0.4l0,13.3C8.4,30.9,8.6,31,9,31h13.5l-0.1,10.1z"/> + <path style="&st3;" d="M22.4,41.1c0,0.3,0.3,0.3,0.5,0.2l16.6-16.9c0.5-0.5,0.4-0.7,0-1L22.9,6.7c-0.1-0.1-0.4-0.1-0.4,0.1v10H8.9c-0.3,0-0.5,0.2-0.5,0.4l0,13.3C8.4,30.9,8.6,31,9,31h13.5l-0.1,10.1z"/> + </g> + </g> + <g id="crop_x0020_marks" style="&st2;"> + <path style="&st0;" d="M48,48H0V0h48v48z"/> + </g> +</svg> diff --git a/libs/python/doc/html/images/next_disabled.png b/libs/python/doc/html/images/next_disabled.png Binary files differnew file mode 100644 index 0000000000..10a8c59d7b --- /dev/null +++ b/libs/python/doc/html/images/next_disabled.png diff --git a/libs/python/doc/html/images/note.png b/libs/python/doc/html/images/note.png Binary files differnew file mode 100644 index 0000000000..d0c3c645ab --- /dev/null +++ b/libs/python/doc/html/images/note.png diff --git a/libs/python/doc/html/images/note.svg b/libs/python/doc/html/images/note.svg new file mode 100644 index 0000000000..648299d26f --- /dev/null +++ b/libs/python/doc/html/images/note.svg @@ -0,0 +1,33 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- Generator: Adobe Illustrator 9.0, SVG Export Plug-In --> +<!DOCTYPE svg [ + <!ENTITY st0 "fill:none;stroke:#FFFFFF;stroke-width:12.1438;stroke-linejoin:round;"> + <!ENTITY st1 "fill:none;stroke-width:1.2429;"> + <!ENTITY st2 "fill:#FFFFFF;stroke:none;"> + <!ENTITY st3 "fill:none;stroke:#FFFFFF;stroke-width:12.7649;stroke-linejoin:round;"> + <!ENTITY st4 "fill:#FFFFFF;stroke-width:6.3824;stroke-linejoin:round;"> + <!ENTITY st5 "fill:none;stroke:none;"> + <!ENTITY st6 "fill-rule:nonzero;clip-rule:nonzero;stroke:#000000;stroke-miterlimit:4;"> + <!ENTITY st7 "fill:#FFFFFF;stroke:#FFFFFF;stroke-width:12.7649;stroke-linejoin:round;"> + <!ENTITY st8 "stroke:none;"> + <!ENTITY st9 "fill:none;stroke-width:4.9715;stroke-linejoin:round;"> +]> +<svg xmlns="http://www.w3.org/2000/svg" width="48pt" height="48pt" viewBox="0 0 48 48" xml:space="preserve"> + <g id="Layer_x0020_1" style="&st6;"> + <path style="&st0;" d="M35.7,19.8v18.9H11V8.8h13.9l10.8,11z"/> + <path style="&st3;" d="M38.7,30.4L25,16.7l-7.7-3l2.7,8.7l13.3,13.4l5.4-5.4z"/> + <path style="&st7;" d="M35.7,8.8H11v29.9h24.7V8.8z"/> + <path style="&st4;" d="M35.7,8.8H11v29.9h24.7V8.8z"/> + <path style="&st2;" d="M35.7,8.8H11v29.9h24.7V8.8z"/> + </g> + <g id="Layer_x0020_4" style="&st6;"> + <path style="&st9;" d="M38.7,30.4L25,16.7l-7.7-3l2.7,8.7l13.3,13.4l5.4-5.4z"/> + <path style="&st8;" d="M38.7,30.4L25,16.7l-7.7-3l2.7,8.7l13.3,13.4l5.4-5.4z"/> + <path style="&st8;" d="M20.6,14.7l-2.5,2.5L17,13.4l3.6,1.3z"/> + <path style="&st1;" d="M19.6,22.2l3-0.3l2.4-2.4l0.4-2.8"/> + <path style="&st2;" d="M20.4,14.9L18.3,17l1.6,5.2l2.7-0.3l2.4-2.4l0.3-2.4l-5-2.2z"/> + </g> + <g id="crop" style="&st6;"> + <path style="&st5;" d="M48,48H0V0h48v48z"/> + </g> +</svg> diff --git a/libs/python/doc/tutorial/doc/html/images/prev.png b/libs/python/doc/html/images/prev.png Binary files differindex d88a40f923..d88a40f923 100755..100644 --- a/libs/python/doc/tutorial/doc/html/images/prev.png +++ b/libs/python/doc/html/images/prev.png diff --git a/libs/python/doc/html/images/prev.svg b/libs/python/doc/html/images/prev.svg new file mode 100644 index 0000000000..6d88ffdd0d --- /dev/null +++ b/libs/python/doc/html/images/prev.svg @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- Generator: Adobe Illustrator 9.0, SVG Export Plug-In --> +<!DOCTYPE svg [ + <!ENTITY st0 "fill:none;stroke:none;"> + <!ENTITY st1 "fill:#FFFFFF;stroke:#FFFFFF;stroke-width:7.5901;stroke-linejoin:round;"> + <!ENTITY st2 "fill-rule:nonzero;clip-rule:nonzero;stroke:#000000;stroke-miterlimit:4;"> + <!ENTITY st3 "stroke:none;"> +]> +<svg width="48pt" height="48pt" viewBox="0 0 48 48" xml:space="preserve" xmlns="http://www.w3.org/2000/svg"> + <g id="Layer_x0020_3" style="&st2;"> + <g> + <path style="&st1;" d="M25.6,6.9c0-0.3-0.3-0.3-0.5-0.2L8.4,23.6c-0.5,0.5-0.4,0.7,0,1l16.6,16.6c0.1,0.1,0.4,0.1,0.4-0.1v-10h13.6c0.3,0,0.5-0.2,0.5-0.4l0-13.3c0-0.3-0.2-0.5-0.5-0.5H25.5l0.1-10.1z"/> + <path style="&st3;" d="M25.6,6.9c0-0.3-0.3-0.3-0.5-0.2L8.4,23.6c-0.5,0.5-0.4,0.7,0,1l16.6,16.6c0.1,0.1,0.4,0.1,0.4-0.1v-10h13.6c0.3,0,0.5-0.2,0.5-0.4l0-13.3c0-0.3-0.2-0.5-0.5-0.5H25.5l0.1-10.1z"/> + </g> + </g> + <g id="crop_x0020_marks" style="&st2;"> + <path style="&st0;" d="M48,48H0V0h48v48z"/> + </g> +</svg> diff --git a/libs/python/doc/html/images/prev_disabled.png b/libs/python/doc/html/images/prev_disabled.png Binary files differnew file mode 100644 index 0000000000..ab3c17e02d --- /dev/null +++ b/libs/python/doc/html/images/prev_disabled.png diff --git a/libs/python/doc/tutorial/doc/html/images/python.png b/libs/python/doc/html/images/python.png Binary files differindex cc2ff1d54a..cc2ff1d54a 100644 --- a/libs/python/doc/tutorial/doc/html/images/python.png +++ b/libs/python/doc/html/images/python.png diff --git a/libs/python/doc/PyConDC_2003/python_cpp_mix.png b/libs/python/doc/html/images/python_cpp_mix.png Binary files differindex fd74cbb224..fd74cbb224 100755 --- a/libs/python/doc/PyConDC_2003/python_cpp_mix.png +++ b/libs/python/doc/html/images/python_cpp_mix.png diff --git a/libs/python/doc/tutorial/doc/html/images/smiley.png b/libs/python/doc/html/images/smiley.png Binary files differindex 30a77f71ce..30a77f71ce 100644 --- a/libs/python/doc/tutorial/doc/html/images/smiley.png +++ b/libs/python/doc/html/images/smiley.png diff --git a/libs/python/doc/html/images/tip.png b/libs/python/doc/html/images/tip.png Binary files differnew file mode 100644 index 0000000000..5c4aab3bb3 --- /dev/null +++ b/libs/python/doc/html/images/tip.png diff --git a/libs/python/doc/html/images/tip.svg b/libs/python/doc/html/images/tip.svg new file mode 100644 index 0000000000..cd437a5e85 --- /dev/null +++ b/libs/python/doc/html/images/tip.svg @@ -0,0 +1,84 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --><svg height="1052.3622047" id="svg2" inkscape:version="0.42.2" sodipodi:docbase="/home/sergio/tmp/downloads" sodipodi:docname="lamp.svg" sodipodi:version="0.32" width="744.09448819" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://web.resource.org/cc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:svg="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> + <metadata> + <rdf:RDF xmlns:cc="http://web.resource.org/cc/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <cc:Work rdf:about=""> + <dc:title>lamp</dc:title> + <dc:description></dc:description> + <dc:subject> + <rdf:Bag> + <rdf:li>office</rdf:li> + <rdf:li></rdf:li> + <rdf:li>lamp</rdf:li> + </rdf:Bag> + </dc:subject> + <dc:publisher> + <cc:Agent rdf:about="http://www.openclipart.org/"> + <dc:title>Open Clip Art Library</dc:title> + </cc:Agent> + </dc:publisher> + <dc:creator> + <cc:Agent> + <dc:title>Sergio Luiz Araujo Silva</dc:title> + </cc:Agent> + </dc:creator> + <dc:rights> + <cc:Agent> + <dc:title>Public Domain</dc:title> + </cc:Agent> + </dc:rights> + <dc:date>set 2005</dc:date> + <dc:format>image/svg+xml</dc:format> + <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/> + <cc:license rdf:resource="http://web.resource.org/cc/PublicDomain"/> + <dc:language>en</dc:language> + </cc:Work> + <cc:License rdf:about="http://web.resource.org/cc/PublicDomain"> + <cc:permits rdf:resource="http://web.resource.org/cc/Reproduction"/> + <cc:permits rdf:resource="http://web.resource.org/cc/Distribution"/> + <cc:permits rdf:resource="http://web.resource.org/cc/DerivativeWorks"/> + </cc:License> + </rdf:RDF> + </metadata> + <defs id="defs4"> + <linearGradient id="linearGradient13125"> + <stop id="stop13127" offset="0.0000000" style="stop-color:#ffffff;stop-opacity:1.0000000;"/> + <stop id="stop13129" offset="1" style="stop-color:#fffeff;stop-opacity:0;"/> + </linearGradient> + <linearGradient id="linearGradient12389"> + <stop id="stop12391" offset="0.0000000" style="stop-color:#fefefe;stop-opacity:1.0000000;"/> + <stop id="stop12393" offset="1.0000000" style="stop-color:#fffefe;stop-opacity:1.0000000;"/> + </linearGradient> + <radialGradient cx="358.25909" cy="186.06468" fx="358.25909" fy="186.06468" gradientTransform="matrix(1.000001,-8.244061e-7,3.143917e-7,0.381356,-4.028738e-4,115.1081)" gradientUnits="userSpaceOnUse" id="radialGradient13131" inkscape:collect="always" r="27.486719" xlink:href="#linearGradient13125"/> + <radialGradient cx="358.25909" cy="186.06468" fx="358.25909" fy="186.06468" gradientTransform="matrix(1.000001,-8.244061e-7,3.143917e-7,0.381356,-4.028738e-4,115.1081)" gradientUnits="userSpaceOnUse" id="radialGradient14587" inkscape:collect="always" r="27.486719" xlink:href="#linearGradient13125"/> + <radialGradient cx="358.25909" cy="186.06468" fx="358.25909" fy="186.06468" gradientTransform="matrix(1.000001,-8.244061e-7,3.143917e-7,0.381356,-4.028738e-4,115.1081)" gradientUnits="userSpaceOnUse" id="radialGradient15390" inkscape:collect="always" r="27.486719" xlink:href="#linearGradient13125"/> + <radialGradient cx="358.25909" cy="186.06468" fx="358.25909" fy="186.06468" gradientTransform="matrix(1.000001,-8.244061e-7,3.143917e-7,0.381356,-4.028738e-4,115.1081)" gradientUnits="userSpaceOnUse" id="radialGradient16141" inkscape:collect="always" r="27.486719" xlink:href="#linearGradient13125"/> + </defs> + <sodipodi:namedview bordercolor="#666666" borderopacity="1.0" id="base" inkscape:current-layer="layer1" inkscape:cx="344.34505" inkscape:cy="795.78292" inkscape:document-units="px" inkscape:guide-bbox="true" inkscape:pageopacity="0.0" inkscape:pageshadow="2" inkscape:window-height="693" inkscape:window-width="1024" inkscape:window-x="0" inkscape:window-y="25" inkscape:zoom="0.72123084" pagecolor="#ffffff" showguides="true"/> + <g id="layer1" inkscape:groupmode="layer" inkscape:label="Layer 1"> + <path d="M 369.44028,121.86683 C 302.64703,119.68096 242.59223,184.30679 250.47188,250.87980 C 252.47522,280.21980 267.84094,306.49880 285.94332,328.82253 C 303.71281,358.65039 312.13900,393.24133 313.51068,427.73030 C 317.00419,446.97288 338.01608,454.57063 355.35334,455.26572 C 375.18456,456.91501 395.94281,455.09265 414.43470,447.69729 C 430.92724,435.70557 427.37713,413.20597 430.74488,395.55648 C 434.70351,361.57615 449.78002,329.76555 471.07843,303.26619 C 504.41026,252.31528 488.56419,176.76397 437.75400,143.26422 C 417.82956,129.49394 393.70573,121.69096 369.44028,121.86683 z " id="path1384" style="opacity:1.0000000;fill:#f3f2f3;fill-opacity:0.83333331;stroke:#000000;stroke-width:0.58960420;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"/> + <path d="M 425.72698,154.07768 C 437.68158,164.87540 453.68534,182.03604 451.17873,203.82428 C 455.99913,200.54641 460.81954,197.26853 465.63995,193.99066 C 459.85546,170.27425 448.28648,162.75442 425.72698,154.07768 z " id="path2153" sodipodi:nodetypes="cccc" style="fill:#fefefe;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 506.99897 296.94009 A 37.120701 18.718985 0 1 1 432.75756,296.94009 A 37.120701 18.718985 0 1 1 506.99897 296.94009 z" id="path2881" sodipodi:cx="469.87827" sodipodi:cy="296.94009" sodipodi:rx="37.120701" sodipodi:ry="18.718985" sodipodi:type="arc" style="opacity:1.0000000;color:#000000;fill:#fefefe;fill-opacity:1.0000000;fill-rule:nonzero;stroke:none;stroke-width:0.64700001;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;visibility:visible;display:inline;overflow:visible" transform="matrix(0.818103,0.000000,0.000000,0.896150,-13.89510,-26.68653)"/> + <path d="M 359.20536,314.30802 L 336.64585,244.31570 C 362.29042,230.62575 382.72895,234.28926 403.16748,243.15881 L 379.45107,315.46491 L 379.45107,315.46491" id="path3617" sodipodi:nodetypes="ccccc" style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#8f9595;stroke-width:0.91160071px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 513.73605 514.32300 A 52.508934 11.885468 0 1 1 408.71818,514.32300 A 52.508934 11.885468 0 1 1 513.73605 514.32300 z" id="path4361" sodipodi:cx="461.22711" sodipodi:cy="514.32300" sodipodi:rx="52.508934" sodipodi:ry="11.885468" sodipodi:type="arc" style="opacity:1.0000000;color:#000000;fill:#a0a0a0;fill-opacity:1.0000000;fill-rule:nonzero;stroke:none;stroke-width:0.64700001;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;visibility:visible;display:inline;overflow:visible" transform="matrix(0.982435,0.000000,0.000000,1.387810,-83.52495,-281.2705)"/> + <path d="M 315.87677,433.07959 C 319.14672,442.90428 329.03398,448.82383 338.76816,450.68840 C 362.00206,456.37952 386.74882,455.38004 409.63484,448.57985 C 414.28840,447.19363 419.18392,445.42184 422.06530,441.25295 C 423.42527,439.84003 425.68582,434.46169 424.07088,434.30126 C 411.81432,444.17256 395.75685,447.78808 380.34111,448.56322 C 362.85475,449.05661 344.64886,448.26521 328.51659,440.79114 C 324.02706,438.71576 319.76022,436.14612 315.87677,433.07959 z " id="path4363" style="fill:#d6dee6;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 400.47436,522.16227 C 396.48542,528.09177 392.49650,534.02126 388.50756,539.95076 C 383.93367,541.47295 366.98819,546.44954 353.57745,538.01018 C 350.34318,532.29631 347.10892,526.58244 343.87465,520.86856 C 364.35835,531.64946 396.48542,523.99502 400.47436,522.16227 z " id="path5094" sodipodi:nodetypes="ccccc" style="fill:#090a0c;fill-opacity:1.0000000;fill-rule:evenodd;stroke:#000000;stroke-width:0.91160071px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 419.65600,444.27781 C 419.97026,446.39906 420.28452,448.52031 420.59878,450.64156 C 421.46299,450.95582 422.32720,451.27008 423.19142,451.58434 C 423.19142,452.91994 423.19142,454.25554 423.19142,455.59114 C 422.32720,455.98397 421.46299,456.37678 420.59878,456.76961 C 420.36308,459.20512 420.12739,461.64063 419.89170,464.07614 C 420.52021,464.23327 421.14873,464.39039 421.77725,464.54753 C 421.69869,466.59021 421.62012,468.63289 421.54156,470.67558 C 420.83447,471.46123 420.12739,472.24688 419.42030,473.03253 C 419.57744,474.05387 419.73456,475.07522 419.89170,476.09656 C 420.91303,477.11790 421.93438,478.13925 422.95572,479.16058 C 422.87716,480.18193 422.79859,481.20328 422.72003,482.22461 C 422.01294,483.01026 421.30586,483.79591 420.59878,484.58156 C 420.36308,485.05294 420.12739,485.52433 419.89170,485.99572 C 419.57744,486.70280 419.26317,487.40989 418.94892,488.11697 C 419.10605,489.05975 419.26317,490.00253 419.42030,490.94531 C 419.89170,491.65239 420.36308,492.35947 420.83447,493.06655 C 420.67734,494.71641 420.52021,496.36627 420.36308,498.01614 C 415.02067,505.24410 409.67827,512.47206 404.33587,519.70003 C 403.15740,520.24998 401.97892,520.79994 400.80045,521.34989 C 397.81498,522.29266 394.82952,523.23544 391.84406,524.17822 C 386.34452,524.80674 380.84498,525.43525 375.34545,526.06378 C 371.96717,525.90664 368.58887,525.74952 365.21059,525.59238 C 362.46082,525.51382 359.71105,525.43525 356.96128,525.35669 C 353.42587,524.49247 349.89045,523.62827 346.35503,522.76405 C 345.17656,521.82128 343.99809,520.87850 342.81962,519.93572 C 339.75559,517.81447 336.69157,515.69322 333.62754,513.57197 C 328.75652,508.30813 323.88551,503.04429 319.01448,497.78044 C 319.01448,496.52341 319.01448,495.26636 319.01448,494.00933 C 319.87870,494.00933 320.74291,494.00933 321.60712,494.00933 C 321.13574,492.83086 320.66435,491.65239 320.19296,490.47392 C 319.09305,488.19554 317.99314,485.91716 316.89323,483.63878 C 316.89323,482.93170 316.89323,482.22461 316.89323,481.51753 C 318.38597,480.26049 319.87869,479.00345 321.37143,477.74642 C 320.03583,475.54660 318.70022,473.34679 317.36462,471.14697 C 317.28606,470.83271 317.20748,470.51845 317.12892,470.20419 C 318.46453,468.39720 319.80013,466.59021 321.13574,464.78322 C 320.74291,463.68331 320.35009,462.58341 319.95726,461.48350 C 319.09305,460.38359 318.22883,459.28369 317.36462,458.18378 C 317.12892,457.31956 316.89323,456.45536 316.65753,455.59114 C 317.75744,454.17697 318.85735,452.76281 319.95726,451.34864 C 319.87870,450.01304 319.80013,448.67744 319.72157,447.34184 C 319.32874,446.71332 318.93592,446.08480 318.54310,445.45628 C 318.62166,444.74920 318.70023,444.04212 318.77879,443.33503 C 319.48588,443.25647 320.19296,443.17790 320.90004,443.09934 C 324.04263,445.22059 327.18523,447.34184 330.32782,449.46309 C 348.08347,456.92674 391.76550,461.09068 419.65600,444.27781 z " id="path7284" sodipodi:nodetypes="ccccccccccccccccccccccccccccccccccccccccccccccc" style="fill:#fba246;fill-opacity:1.0000000;fill-rule:evenodd;stroke:#000000;stroke-width:0.91160071px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 389.86281,523.00744 C 389.46998,521.82897 391.23336,522.26765 390.84054,521.08918 C 383.37688,521.01061 375.91323,520.93205 368.44957,520.85348 C 368.44957,520.53923 368.44957,520.22496 368.44957,519.91070 C 374.10624,519.75357 379.76290,519.59645 385.41957,519.43932 C 388.24790,518.88937 391.07623,518.33941 393.90457,517.78946 C 395.39730,517.55377 396.89003,517.31807 398.38277,517.08237 C 401.44679,515.03969 404.51082,512.99701 407.57485,510.95432 C 407.49629,510.64006 407.41771,510.32580 407.33915,510.01153 C 401.36822,510.48292 395.39730,510.95432 389.42637,511.42571 C 387.30512,511.81853 385.18387,512.21135 383.06263,512.60418 C 379.13438,512.36849 375.20615,512.13279 371.27790,511.89710 C 369.78518,511.73997 368.29244,511.58284 366.79971,511.42571 C 364.44277,510.32580 362.08582,509.22589 359.72888,508.12598 C 376.54175,507.18320 396.89003,507.18320 415.11707,493.98432 C 391.31192,502.15506 371.27790,500.19093 355.01499,497.99112 C 375.91322,494.06288 396.57577,493.19867 417.00262,478.42849 C 387.38368,489.42756 366.24975,485.57788 349.35832,483.84946 C 371.51360,479.29269 403.56804,478.27136 414.40998,466.64376 C 383.06263,474.89306 355.95776,473.47890 338.75207,469.47210 C 352.81517,467.58654 366.87827,465.70098 380.94137,463.81543 C 374.10624,463.18691 367.27110,462.55840 360.43596,461.92988 C 373.32059,459.73006 386.20522,457.53024 399.08985,455.33043 C 381.88416,456.19465 346.53000,460.82997 319.89653,444.48849 C 323.66763,447.63108 328.61721,449.83090 331.20985,453.91627 C 327.28161,453.44487 323.35338,452.97349 319.42513,452.50210 C 319.66083,453.83770 319.89653,455.17330 320.13222,456.50890 C 324.13902,459.02298 328.14582,461.53704 332.15263,464.05112 C 327.43875,466.25093 322.72485,468.45075 318.01096,470.65057 C 323.90332,472.53612 329.79568,474.42169 335.68805,476.30724 C 330.03138,478.66418 322.48915,476.30724 318.71804,483.37807 C 325.55318,486.59923 335.21666,487.22774 339.22346,493.04154 C 333.33110,493.51293 326.73166,489.27043 321.54639,494.45571 C 327.67444,498.06968 333.80249,501.68367 339.93055,505.29765 C 336.55226,504.82626 333.17397,504.35487 329.79568,503.88348 C 334.58814,509.30445 341.26727,513.37780 346.05972,518.79877 C 362.00838,520.29150 373.91416,521.51471 389.86281,523.00744 z " id="path6556" sodipodi:nodetypes="ccccccccccccccccccccccccccccccccccccc" style="fill:#ffc080;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 410.63580,448.38806 C 375.91016,459.46570 347.07688,453.33765 330.49970,448.38806 C 332.54238,449.09515 334.58507,449.80223 336.62775,450.50931 C 365.30391,460.56561 396.80839,453.41621 407.80747,450.27362 C 408.75025,449.64510 409.69303,449.01658 410.63580,448.38806 z " id="path7286" sodipodi:nodetypes="ccccc" style="fill:#ffffff;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 431.22109,368.33927 C 427.74256,388.71364 424.26401,409.08801 420.78546,429.46237 C 416.60557,437.06563 407.94091,440.30372 400.07083,442.61238 C 391.48668,445.18530 382.40444,445.05799 373.54205,444.61656 C 371.08048,446.38986 364.99205,442.92177 370.06503,441.81235 C 377.17154,440.98795 384.60188,442.10538 391.38552,439.26558 C 401.04319,435.47671 410.26670,429.97354 417.05844,422.00834 C 421.19961,403.95301 425.34070,385.89766 429.48184,367.84233 C 430.06159,368.00798 430.64135,368.17360 431.22109,368.33927 z " id="path3629" style="fill:#ffffff;fill-opacity:0.64285713;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 353.42087,428.84088 L 351.10708,419.00725 L 351.68553,378.22661 L 353.13164,373.45440 L 353.05576,339.28565 L 349.95018,336.28751 L 349.37173,316.04336 C 363.86558,304.49563 376.56238,306.21837 388.70625,316.23514 L 388.12780,336.28907 L 385.23556,339.18131 L 384.65711,373.58108 L 386.39245,378.21491 L 385.81401,427.68398 L 382.34331,429.99778 L 374.24503,428.84088 L 371.35278,425.37019 L 366.14675,425.37019 L 360.94071,429.41933 L 353.42087,428.84088 z " id="path3619" sodipodi:nodetypes="ccccccccccccccccccc" style="fill:#c1c1c1;fill-opacity:1.0000000;fill-rule:evenodd;stroke:#9b989f;stroke-width:0.91160071px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 358.25832,325.31572 L 358.25832,416.41507" id="path5096" style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#ffffff;stroke-width:0.91160071px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 380.15345,325.31572 L 380.15345,416.41507" id="path5824" style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#ffffff;stroke-width:0.91160071px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 361.91098,325.31572 L 361.91098,416.41507" id="path5826" style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#8f8f92;stroke-width:0.91160071px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 376.52161,325.31572 L 376.52161,416.41507" id="path6554" style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#8f8f92;stroke-width:0.91160071px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <g id="g9475" transform="matrix(0.911601,0.000000,0.000000,0.911601,328.5961,-156.2531)"> + <path d="M 86.864034,673.56687 L 79.199560,676.97330 L 77.155700,678.67652 L 75.793127,679.69845 L 65.573829,679.35780 L 65.403508,678.33587 L 70.683478,676.97330 C 70.683478,676.97330 74.430554,676.63266 75.111841,676.46234 C 75.793127,676.29201 78.688595,674.92944 78.688595,674.92944 L 84.649852,671.52301 L 87.034355,671.52301 L 86.864034,673.56687 z " id="path8741" style="fill:#ffffff;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 91.973683,686.34099 L 88.056285,686.17067 L 85.331139,687.53324 L 81.073098,689.23646 L 77.836987,691.45064 L 75.111841,692.30225 L 70.853800,692.64289 L 69.320905,693.15386 L 71.024122,693.83514 L 75.963449,693.83514 L 80.221490,694.51643 L 83.627923,693.83514 L 87.545320,690.42871 C 87.545320,690.42871 90.270466,689.23646 90.951753,688.89581 C 91.633039,688.55517 93.165934,687.87388 93.165934,687.87388 L 91.973683,686.34099 z " id="path8743" style="fill:#ffffff;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 94.017542,700.30736 L 89.078215,703.03251 L 85.842104,705.07637 L 83.457601,706.94991 L 77.836987,708.14216 L 75.622806,708.14216 L 81.584063,710.01570 L 86.353069,707.97184 L 91.292396,705.58733 L 92.825291,704.05444 L 94.017542,700.30736 z " id="path8745" style="fill:#ffffff;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 91.462718,717.85049 C 91.462718,717.85049 81.924706,721.59757 81.584063,722.27885 C 81.243420,722.96014 78.688595,723.98207 78.688595,723.98207 L 72.897660,724.66336 L 71.024122,725.68529 L 76.644736,726.36657 L 82.435671,724.49304 L 86.693712,724.32271 L 89.929823,722.10853 L 91.462718,720.40532 L 91.462718,717.85049 z " id="path8747" style="fill:#ffffff;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + </g> + <path d="M 378.14273,525.28637 C 377.57434,530.51553 378.00099,537.83204 377.43261,543.06120 C 372.27918,543.00443 367.82875,543.82657 360.97078,541.72320 C 359.43614,536.89190 356.80919,529.30796 355.27454,524.47667 C 356.26507,524.72572 356.68741,524.86790 357.82038,524.93742 C 358.95335,525.00694 360.79692,524.96593 361.90337,525.03791 C 363.00981,525.10990 364.25012,525.06768 365.31257,525.13480 C 366.37503,525.20191 367.41113,525.22689 368.41214,525.28180 C 369.41314,525.33669 370.37905,525.38365 371.30113,525.41898 C 372.22321,525.45432 374.35115,525.55378 375.17683,525.56221 C 376.00251,525.57065 375.56381,525.48806 376.27564,525.46225 C 376.98745,525.43643 377.56225,525.35378 378.14273,525.28637 z " id="path10207" sodipodi:nodetypes="ccccsssssssc" style="fill:#ffffff;fill-opacity:0.31547615;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000"/> + <path d="M 467.06377,199.37552 L 453.69293,208.53364 L 451.86130,221.53816 L 468.71223,214.21167 L 467.06377,199.37552 z " id="path16869" style="fill:#fefefe;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000;opacity:1.0000000;color:#000000;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0;visibility:visible;display:inline;overflow:visible"/> + </g> +</svg> diff --git a/libs/python/doc/html/images/toc-blank.png b/libs/python/doc/html/images/toc-blank.png Binary files differnew file mode 100644 index 0000000000..6ffad17a0c --- /dev/null +++ b/libs/python/doc/html/images/toc-blank.png diff --git a/libs/python/doc/html/images/toc-minus.png b/libs/python/doc/html/images/toc-minus.png Binary files differnew file mode 100644 index 0000000000..abbb020c8e --- /dev/null +++ b/libs/python/doc/html/images/toc-minus.png diff --git a/libs/python/doc/html/images/toc-plus.png b/libs/python/doc/html/images/toc-plus.png Binary files differnew file mode 100644 index 0000000000..941312ce0d --- /dev/null +++ b/libs/python/doc/html/images/toc-plus.png diff --git a/libs/python/doc/tutorial/doc/html/images/up.png b/libs/python/doc/html/images/up.png Binary files differindex 17d9c3ec49..17d9c3ec49 100755..100644 --- a/libs/python/doc/tutorial/doc/html/images/up.png +++ b/libs/python/doc/html/images/up.png diff --git a/libs/python/doc/html/images/up.svg b/libs/python/doc/html/images/up.svg new file mode 100644 index 0000000000..d31aa9c809 --- /dev/null +++ b/libs/python/doc/html/images/up.svg @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- Generator: Adobe Illustrator 9.0, SVG Export Plug-In --> +<!DOCTYPE svg [ + <!ENTITY st0 "fill:none;stroke:none;"> + <!ENTITY st1 "fill:#FFFFFF;stroke:#FFFFFF;stroke-width:7.5901;stroke-linejoin:round;"> + <!ENTITY st2 "fill-rule:nonzero;clip-rule:nonzero;stroke:#000000;stroke-miterlimit:4;"> + <!ENTITY st3 "stroke:none;"> +]> +<svg width="48pt" height="48pt" viewBox="0 0 48 48" xml:space="preserve" xmlns="http://www.w3.org/2000/svg"> + <g id="Layer_x0020_3" style="&st2;"> + <g> + <path style="&st1;" d="M41.1,25.6c0.3,0,0.3-0.3,0.2-0.5L24.4,8.4c-0.5-0.5-0.7-0.4-1,0L6.7,25.1c-0.1,0.1-0.1,0.4,0.1,0.4h10v13.6c0,0.3,0.2,0.5,0.4,0.5l13.3,0c0.3,0,0.5-0.2,0.5-0.5V25.5l10.1,0.1z"/> + <path style="&st3;" d="M41.1,25.6c0.3,0,0.3-0.3,0.2-0.5L24.4,8.4c-0.5-0.5-0.7-0.4-1,0L6.7,25.1c-0.1,0.1-0.1,0.4,0.1,0.4h10v13.6c0,0.3,0.2,0.5,0.4,0.5l13.3,0c0.3,0,0.5-0.2,0.5-0.5V25.5l10.1,0.1z"/> + </g> + </g> + <g id="crop_x0020_marks" style="&st2;"> + <path style="&st0;" d="M48,48H0V0h48v48z"/> + </g> +</svg> diff --git a/libs/python/doc/html/images/up_disabled.png b/libs/python/doc/html/images/up_disabled.png Binary files differnew file mode 100644 index 0000000000..e22bc87121 --- /dev/null +++ b/libs/python/doc/html/images/up_disabled.png diff --git a/libs/python/doc/html/images/warning.png b/libs/python/doc/html/images/warning.png Binary files differnew file mode 100644 index 0000000000..1c33db8f34 --- /dev/null +++ b/libs/python/doc/html/images/warning.png diff --git a/libs/python/doc/html/images/warning.svg b/libs/python/doc/html/images/warning.svg new file mode 100644 index 0000000000..fc8d7484cb --- /dev/null +++ b/libs/python/doc/html/images/warning.svg @@ -0,0 +1,23 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- Generator: Adobe Illustrator 9.0, SVG Export Plug-In --> +<!DOCTYPE svg [ + <!ENTITY st0 "fill:#000000;stroke:#FFFFFF;stroke-width:7.9139;stroke-linejoin:round;"> + <!ENTITY st1 "fill-rule:nonzero;clip-rule:nonzero;fill:#FFFFFF;stroke:#000000;stroke-miterlimit:4;"> + <!ENTITY st2 "fill:none;stroke:none;"> + <!ENTITY st3 "fill:#000000;"> + <!ENTITY st4 "fill-rule:evenodd;clip-rule:evenodd;stroke:none;"> + <!ENTITY st5 "fill-rule:nonzero;clip-rule:nonzero;stroke:#000000;stroke-miterlimit:4;"> +]> +<svg width="48pt" height="48pt" viewBox="0 0 48 48" xml:space="preserve" xmlns="http://www.w3.org/2000/svg"> + <g id="Layer_x0020_4" style="&st1;"> + <g style="&st4;"> + <path style="&st0;" d="M16.4,42.3L5.7,31.6V16.4L16.4,5.7h15.2l10.7,10.7v15.2L31.6,42.3H16.4z"/> + <path style="&st3;" d="M16.4,42.3L5.7,31.6V16.4L16.4,5.7h15.2l10.7,10.7v15.2L31.6,42.3H16.4z"/> + <path d="M11.7,17.7l18.7,18.7l5.9-5.9L17.6,11.7l-5.9,5.9z"/> + <path d="M11.7,30.5l5.9,5.9l18.7-18.7l-5.9-5.9L11.7,30.5z"/> + </g> + </g> + <g id="crop_x0020_marks" style="&st5;"> + <path style="&st2;" d="M48,48H0V0h48v48z"/> + </g> +</svg> diff --git a/libs/python/doc/html/index.html b/libs/python/doc/html/index.html new file mode 100644 index 0000000000..a333b48065 --- /dev/null +++ b/libs/python/doc/html/index.html @@ -0,0 +1,129 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Boost.Python</title> +<link rel="stylesheet" href="boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python"> +<link rel="next" href="building.html" title="Chapter 1. Building and Testing"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"><a accesskey="n" href="building.html"><img src="images/next.png" alt="Next"></a></div> +<div class="book"> +<div class="titlepage"> +<div> +<div><h1 class="title"> +<a name="python"></a>Boost.Python</h1></div> +<div><div class="authorgroup"> +<div class="author"><h3 class="author"> +<span class="firstname">David</span> <span class="surname">Abrahams</span> +</h3></div> +<div class="author"><h3 class="author"> +<span class="firstname">Stefan</span> <span class="surname">Seefeld</span> +</h3></div> +</div></div> +<div><p class="copyright">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld</p></div> +<div><div class="legalnotice"> +<a name="python.legal"></a><p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></div> +</div> +<hr> +</div> +<h3> +<a name="python.h0"></a> + <span class="phrase"><a name="python.synopsis"></a></span><a class="link" href="index.html#python.synopsis">Synopsis</a> + </h3> +<p> + Welcome to Boost.Python, a C++ library which enables seamless interoperability + between C++ and the Python programming language. The library includes support + for: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + References and Pointers + </li> +<li class="listitem"> + Globally Registered Type Coercions + </li> +<li class="listitem"> + Automatic Cross-Module Type Conversions + </li> +<li class="listitem"> + Efficient Function Overloading + </li> +<li class="listitem"> + C++ to Python Exception Translation + </li> +<li class="listitem"> + Default Arguments + </li> +<li class="listitem"> + Keyword Arguments + </li> +<li class="listitem"> + Manipulating Python objects in C++ + </li> +<li class="listitem"> + Exporting C++ Iterators as Python Iterators + </li> +<li class="listitem"> + Documentation Strings + </li> +</ul></div> +<p> + The development of these features was funded in part by grants to <code class="computeroutput"><span class="identifier">Boost</span> <span class="identifier">Consulting</span></code> + from the <a href="http://www.llnl.gov" target="_top">Lawrence Livermore National Laboratories</a> + and by the <a href="http://cci.lbl.gov" target="_top">Computational Crystallography Initiative</a> + at Lawrence Berkeley National Laboratories. + </p> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="python.contents"></a><a class="link" href="index.html#python.contents" title="Contents">Contents</a> +</h2></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + <a href="tutorial/index.html" target="_top">Tutorial</a> + </li> +<li class="listitem"> + <a class="link" href="building.html" title="Chapter 1. Building and Testing">Building and Testing</a> + </li> +<li class="listitem"> + <a href="reference/index.html" target="_top">Reference Manual</a> + </li> +<li class="listitem"> + <a class="link" href="configuration.html" title="Chapter 2. Configuration">Configuration Information</a> + </li> +<li class="listitem"> + <a class="link" href="glossary.html" title="Chapter 5. Glossary">Glossary</a> + </li> +<li class="listitem"> + <a class="link" href="support.html" title="Chapter 3. Support Resources">Support Resources</a> + </li> +<li class="listitem"> + <a class="link" href="faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)">Frequently Asked Questions (FAQs)</a> + </li> +</ul></div> +</div> +<h3> +<a name="python.h1"></a> + <span class="phrase"><a name="python.articles"></a></span><a class="link" href="index.html#python.articles">Articles</a> + </h3> +<p> + <a href="article.html" target="_top">Building Hybrid Systems With Boost Python</a>, + by Dave Abrahams and Ralf W. Grosse-Kunstleve + </p> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"><p><small>Last revised: December 14, 2015 at 09:15:10 GMT</small></p></td> +<td align="right"><div class="copyright-footer"></div></td> +</tr></table> +<hr> +<div class="spirit-nav"><a accesskey="n" href="building.html"><img src="images/next.png" alt="Next"></a></div> +</body> +</html> diff --git a/libs/python/doc/html/python_HTML.manifest b/libs/python/doc/html/python_HTML.manifest new file mode 100644 index 0000000000..375d383244 --- /dev/null +++ b/libs/python/doc/html/python_HTML.manifest @@ -0,0 +1,30 @@ +index.html +building.html +building/background.html +building/no_install_quickstart.html +building/installing_boost_python_on_your_.html +building/configuring_boost_build.html +building/choosing_a_boost_python_library_.html +building/include_issues.html +building/python_debugging_builds.html +building/testing_boost_python.html +building/notes_for_mingw_and_cygwin_with_.html +configuration.html +support.html +faq.html +faq/i_m_getting_the_attempt_to_retur.html +faq/is_return_internal_reference_eff.html +faq/how_can_i_wrap_functions_which_t.html +faq/fatal_error_c1204_compiler_limit.html +faq/how_do_i_debug_my_python_extensi.html +faq/why_doesn_t_my_operator_work.html +faq/does_boost_python_work_with_mac_.html +faq/how_can_i_find_the_existing_pyob.html +faq/how_can_i_wrap_a_function_which0.html +faq/compilation_takes_too_much_time_.html +faq/how_do_i_create_sub_packages_usi.html +faq/error_c2064_term_does_not_evalua.html +faq/how_can_i_automatically_convert_.html +faq/why_is_my_automatic_to_python_co.html +faq/is_boost_python_thread_aware_com.html +glossary.html diff --git a/libs/python/doc/html/reference/concepts.html b/libs/python/doc/html/reference/concepts.html new file mode 100644 index 0000000000..49ca292b52 --- /dev/null +++ b/libs/python/doc/html/reference/concepts.html @@ -0,0 +1,261 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 1. Concepts</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="index.html" title="Boost.Python Reference Manual"> +<link rel="prev" href="index.html" title="Boost.Python Reference Manual"> +<link rel="next" href="concepts/dereferenceable.html" title="Dereferenceable"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="index.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="concepts/dereferenceable.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="concepts"></a>Chapter 1. Concepts</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="concepts.html#concepts.callpolicies">CallPolicies</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="concepts.html#concepts.callpolicies.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="concepts.html#concepts.callpolicies.callpolicies_composition">CallPolicies + Composition</a></span></dt> +<dt><span class="section"><a href="concepts.html#concepts.callpolicies.concept_requirements">Concept + Requirements</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="concepts/dereferenceable.html">Dereferenceable</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="concepts/dereferenceable.html#concepts.dereferenceable.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="concepts/dereferenceable.html#concepts.dereferenceable.concept_requirements">Concept + Requirements</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="concepts/extractor.html">Extractor</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="concepts/extractor.html#concepts.extractor.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="concepts/extractor.html#concepts.extractor.concept_requirements">Concept Requirements</a></span></dt> +<dt><span class="section"><a href="concepts/extractor.html#concepts.extractor.notes">Notes</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="concepts/holdergenerator.html">HolderGenerator</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="concepts/holdergenerator.html#concepts.holdergenerator.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="concepts/holdergenerator.html#concepts.holdergenerator.concept_requirements">Concept + Requirements</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="concepts/resultconverter.html">ResultConverter</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="concepts/resultconverter.html#concepts.resultconverter.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="concepts/resultconverter.html#concepts.resultconverter.resultconverter_concept_requirem">ResultConverter + Concept Requirements</a></span></dt> +<dt><span class="section"><a href="concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept">ResultConverterGenerator + Concept Requirements</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="concepts/objectwrapper.html">ObjectWrapper</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="concepts/objectwrapper.html#concepts.objectwrapper.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="concepts/objectwrapper.html#concepts.objectwrapper.objectwrapper_concept_requiremen">ObjectWrapper + Concept Requirements</a></span></dt> +<dt><span class="section"><a href="concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements">TypeWrapper + Concept Requirements</a></span></dt> +<dt><span class="section"><a href="concepts/objectwrapper.html#concepts.objectwrapper.caveat">Caveat</a></span></dt> +</dl></dd> +</dl> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="concepts.callpolicies"></a><a class="link" href="concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="concepts.html#concepts.callpolicies.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="concepts.html#concepts.callpolicies.callpolicies_composition">CallPolicies + Composition</a></span></dt> +<dt><span class="section"><a href="concepts.html#concepts.callpolicies.concept_requirements">Concept + Requirements</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.callpolicies.introduction"></a><a class="link" href="concepts.html#concepts.callpolicies.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Models of the CallPolicies concept are used to specialize the behavior + of Python callable objects generated by Boost.Python to wrapped C++ objects + like function and member function pointers, providing three behaviors: + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">precall</span></code> - Python argument + tuple management before the wrapped object is invoked + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">result_converter</span></code> - + C++ return value handling + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">postcall</span></code> - Python argument + tuple and result management after the wrapped object is invoked + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">extract_return_type</span></code> + - metafunction for extracting the return type from a given signature + type sequence + </li> +</ol></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.callpolicies.callpolicies_composition"></a><a class="link" href="concepts.html#concepts.callpolicies.callpolicies_composition" title="CallPolicies Composition">CallPolicies + Composition</a> +</h3></div></div></div> +<p> + In order to allow the use of multiple models of CallPolicies in the same + callable object, Boost.Python's CallPolicies class templates provide a + chaining interface which allows them to be recursively composed. This interface + takes the form of an optional template parameter, <code class="computeroutput"><span class="identifier">Base</span></code>, + which defaults to <code class="computeroutput"><span class="identifier">default_call_policies</span></code>. + By convention, the <code class="computeroutput"><span class="identifier">precall</span></code> + function of the <code class="computeroutput"><span class="identifier">Base</span></code> is + invoked after the <code class="computeroutput"><span class="identifier">precall</span></code> + function supplied by the <code class="computeroutput"><span class="identifier">outer</span></code> + template, and the <code class="computeroutput"><span class="identifier">postcall</span></code> + function of the <code class="computeroutput"><span class="identifier">Base</span></code> is + invoked before the <code class="computeroutput"><span class="identifier">postcall</span></code> + function of the <code class="computeroutput"><span class="identifier">outer</span></code> template. + If a <code class="computeroutput"><span class="identifier">result_converter</span></code> is + supplied by the <code class="computeroutput"><span class="identifier">outer</span></code> template, + it replaces any <code class="computeroutput"><span class="identifier">result_converter</span></code> + supplied by the <code class="computeroutput"><span class="identifier">Base</span></code>. For + an example, see <code class="computeroutput"><span class="identifier">return_internal_reference</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.callpolicies.concept_requirements"></a><a class="link" href="concepts.html#concepts.callpolicies.concept_requirements" title="Concept Requirements">Concept + Requirements</a> +</h3></div></div></div> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Expression + </p> + </th> +<th> + <p> + Type + </p> + </th> +<th> + <p> + Result/Semantics + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span><span class="special">.</span><span class="identifier">precall</span><span class="special">(</span><span class="identifier">a</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + convertible to <code class="computeroutput"><span class="keyword">bool</span></code> + </p> + </td> +<td> + <p> + returns <code class="computeroutput"><span class="keyword">false</span></code> and + <code class="computeroutput"><span class="identifier">PyErr_Occurred</span><span class="special">()</span> <span class="special">!=</span> + <span class="number">0</span></code> upon failure, <code class="computeroutput"><span class="keyword">true</span></code> otherwise. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">P</span><span class="special">::</span><span class="identifier">result_converter</span></code> + </p> + </td> +<td> + <p> + A model of <code class="computeroutput"><span class="identifier">ResultConverterGenerator</span></code>. + </p> + </td> +<td> + <p> + An MPL unary Metafunction Class used produce the "preliminary" + result object. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span><span class="special">.</span><span class="identifier">postcall</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> + <span class="identifier">r</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + convertible to <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="number">0</span></code> and <code class="computeroutput"><span class="identifier">PyErr_Occurred</span><span class="special">()</span> + <span class="special">!=</span> <span class="number">0</span></code> + upon failure. Must "conserve references" even in the + event of an exception. In other words, if <code class="computeroutput"><span class="identifier">r</span></code> + is not returned, its reference count must be decremented; if + another existing object is returned, its reference count must + be incremented. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">P</span><span class="special">::</span><span class="identifier">extract_return_type</span></code> + </p> + </td> +<td> + <p> + A model of Metafunction. + </p> + </td> +<td> + <p> + An MPL unary Metafunction used extract the return type from a + given signature. By default it is derived from <code class="computeroutput"><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">front</span></code>. + </p> + </td> +</tr> +</tbody> +</table></div> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="index.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="concepts/dereferenceable.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/concepts/dereferenceable.html b/libs/python/doc/html/reference/concepts/dereferenceable.html new file mode 100644 index 0000000000..78df9ff0f4 --- /dev/null +++ b/libs/python/doc/html/reference/concepts/dereferenceable.html @@ -0,0 +1,104 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Dereferenceable</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../concepts.html" title="Chapter 1. Concepts"> +<link rel="prev" href="../concepts.html" title="Chapter 1. Concepts"> +<link rel="next" href="extractor.html" title="Extractor"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../concepts.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="extractor.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="concepts.dereferenceable"></a><a class="link" href="dereferenceable.html" title="Dereferenceable">Dereferenceable</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="dereferenceable.html#concepts.dereferenceable.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="dereferenceable.html#concepts.dereferenceable.concept_requirements">Concept + Requirements</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.dereferenceable.introduction"></a><a class="link" href="dereferenceable.html#concepts.dereferenceable.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Instances of a <code class="computeroutput"><span class="identifier">Dereferenceable</span></code> + type can be used like a pointer to access an lvalue. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.dereferenceable.concept_requirements"></a><a class="link" href="dereferenceable.html#concepts.dereferenceable.concept_requirements" title="Concept Requirements">Concept + Requirements</a> +</h3></div></div></div> +<p> + In the table below, <code class="computeroutput"><span class="identifier">T</span></code> is + a model of Dereferenceable, and <code class="computeroutput"><span class="identifier">x</span></code> + denotes an object of type <code class="computeroutput"><span class="identifier">T</span></code>. + In addition, all pointers are <code class="computeroutput"><span class="identifier">Dereferenceable</span></code>. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Expression + </p> + </th> +<th> + <p> + Result + </p> + </th> +<th> + <p> + Operational Semantics + </p> + </th> +</tr></thead> +<tbody><tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + convertible to <code class="computeroutput"><span class="identifier">pointee</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">type</span><span class="special">*</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="special">&*</span><span class="identifier">x</span></code>, + or a null pointer + </p> + </td> +</tr></tbody> +</table></div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../concepts.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="extractor.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/concepts/extractor.html b/libs/python/doc/html/reference/concepts/extractor.html new file mode 100644 index 0000000000..38ebbea20d --- /dev/null +++ b/libs/python/doc/html/reference/concepts/extractor.html @@ -0,0 +1,135 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Extractor</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../concepts.html" title="Chapter 1. Concepts"> +<link rel="prev" href="dereferenceable.html" title="Dereferenceable"> +<link rel="next" href="holdergenerator.html" title="HolderGenerator"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="dereferenceable.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="holdergenerator.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="concepts.extractor"></a><a class="link" href="extractor.html" title="Extractor">Extractor</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="extractor.html#concepts.extractor.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="extractor.html#concepts.extractor.concept_requirements">Concept Requirements</a></span></dt> +<dt><span class="section"><a href="extractor.html#concepts.extractor.notes">Notes</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.extractor.introduction"></a><a class="link" href="extractor.html#concepts.extractor.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + An Extractor is a class which Boost.Python can use to extract C++ objects + from Python objects, and is typically used by facilities that define <code class="computeroutput"><span class="identifier">from_python</span></code> conversions for "traditional" + Python extension types. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.extractor.concept_requirements"></a><a class="link" href="extractor.html#concepts.extractor.concept_requirements" title="Concept Requirements">Concept Requirements</a> +</h3></div></div></div> +<p> + In the table below, <code class="computeroutput"><span class="identifier">X</span></code> denotes + a model of <code class="computeroutput"><span class="identifier">Extractor</span></code> and + <code class="computeroutput"><span class="identifier">a</span></code> denotes an instance of + a Python object type. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Expression + </p> + </th> +<th> + <p> + Type + </p> + </th> +<th> + <p> + Semantics + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">X</span><span class="special">::</span><span class="identifier">execute</span><span class="special">(</span><span class="identifier">a</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + non-void + </p> + </td> +<td> + <p> + Returns the C++ object being extracted. The execute function + must not be overloaded. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="special">&</span><span class="identifier">a</span><span class="special">.</span><span class="identifier">ob_type</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">PyTypeObject</span><span class="special">**</span></code> + </p> + </td> +<td> + <p> + Points to the <code class="computeroutput"><span class="identifier">ob_type</span></code> + field of an object which is layout-compatible with <code class="computeroutput"><span class="identifier">PyObject</span></code> + </p> + </td> +</tr> +</tbody> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.extractor.notes"></a><a class="link" href="extractor.html#concepts.extractor.notes" title="Notes">Notes</a> +</h3></div></div></div> +<p> + Informally, an Extractor's execute member must be a non-overloaded static + function whose single argument is a Python object type. Acceptable Python + object types include those publicly (and unambiguously) derived from PyObject, + and POD types which are layout-compatible with PyObject. + </p> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="dereferenceable.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="holdergenerator.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/concepts/holdergenerator.html b/libs/python/doc/html/reference/concepts/holdergenerator.html new file mode 100644 index 0000000000..2e82370001 --- /dev/null +++ b/libs/python/doc/html/reference/concepts/holdergenerator.html @@ -0,0 +1,92 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>HolderGenerator</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../concepts.html" title="Chapter 1. Concepts"> +<link rel="prev" href="extractor.html" title="Extractor"> +<link rel="next" href="resultconverter.html" title="ResultConverter"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="extractor.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="resultconverter.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="concepts.holdergenerator"></a><a class="link" href="holdergenerator.html" title="HolderGenerator">HolderGenerator</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="holdergenerator.html#concepts.holdergenerator.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="holdergenerator.html#concepts.holdergenerator.concept_requirements">Concept + Requirements</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.holdergenerator.introduction"></a><a class="link" href="holdergenerator.html#concepts.holdergenerator.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + A HolderGenerator is a unary metafunction class which returns types suitable + for holding instances of its argument in a wrapped C++ class instance. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.holdergenerator.concept_requirements"></a><a class="link" href="holdergenerator.html#concepts.holdergenerator.concept_requirements" title="Concept Requirements">Concept + Requirements</a> +</h3></div></div></div> +<p> + In the table below, <code class="computeroutput"><span class="identifier">G</span></code> denotes + an type which models <code class="computeroutput"><span class="identifier">HolderGenerator</span></code>, + and <code class="computeroutput"><span class="identifier">X</span></code> denotes a class type. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Expression + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +</tr></thead> +<tbody><tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">G</span><span class="special">::</span><span class="identifier">apply</span><span class="special"><</span><span class="identifier">X</span><span class="special">>::</span><span class="identifier">type</span></code> + </p> + </td> +<td> + <p> + A concrete subclass of <code class="computeroutput"><span class="identifier">instance_holder</span></code> + which can hold objects of type <code class="computeroutput"><span class="identifier">X</span></code>. + </p> + </td> +</tr></tbody> +</table></div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="extractor.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="resultconverter.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/concepts/objectwrapper.html b/libs/python/doc/html/reference/concepts/objectwrapper.html new file mode 100644 index 0000000000..7f3c68f9c5 --- /dev/null +++ b/libs/python/doc/html/reference/concepts/objectwrapper.html @@ -0,0 +1,132 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>ObjectWrapper</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../concepts.html" title="Chapter 1. Concepts"> +<link rel="prev" href="resultconverter.html" title="ResultConverter"> +<link rel="next" href="../high_level_components.html" title="Chapter 2. High Level Components"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="resultconverter.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../high_level_components.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="concepts.objectwrapper"></a><a class="link" href="objectwrapper.html" title="ObjectWrapper">ObjectWrapper</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="objectwrapper.html#concepts.objectwrapper.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="objectwrapper.html#concepts.objectwrapper.objectwrapper_concept_requiremen">ObjectWrapper + Concept Requirements</a></span></dt> +<dt><span class="section"><a href="objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements">TypeWrapper + Concept Requirements</a></span></dt> +<dt><span class="section"><a href="objectwrapper.html#concepts.objectwrapper.caveat">Caveat</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.objectwrapper.introduction"></a><a class="link" href="objectwrapper.html#concepts.objectwrapper.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + 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. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.objectwrapper.objectwrapper_concept_requiremen"></a><a class="link" href="objectwrapper.html#concepts.objectwrapper.objectwrapper_concept_requiremen" title="ObjectWrapper Concept Requirements">ObjectWrapper + Concept Requirements</a> +</h3></div></div></div> +<p> + Models of the ObjectWrapper concept have <a class="link" href="../object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object">object</a> + 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 <a class="link" href="objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a>, + a member function invocation of the form + </p> +<pre class="programlisting"><span class="identifier">x</span><span class="special">.</span><span class="identifier">some_function</span><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,...</span><span class="identifier">an</span><span class="special">)</span></pre> +<p> + always has semantics equivalent to: + </p> +<pre class="programlisting"><span class="identifier">extract</span><span class="special"><</span><span class="identifier">R</span><span class="special">>(</span><span class="identifier">x</span><span class="special">.</span><span class="identifier">attr</span><span class="special">(</span><span class="string">"some_function"</span><span class="special">)(</span><span class="identifier">object</span><span class="special">(</span><span class="identifier">a1</span><span class="special">),</span> <span class="identifier">object</span><span class="special">(</span><span class="identifier">a2</span><span class="special">),...</span><span class="identifier">object</span><span class="special">(</span><span class="identifier">an</span><span class="special">)))()</span></pre> +<p> + (see <a class="link" href="objectwrapper.html#concepts.objectwrapper.caveat" title="Caveat">caveat</a> below). + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.objectwrapper.typewrapper_concept_requirements"></a><a class="link" href="objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper + Concept Requirements</a> +</h3></div></div></div> +<p> + TypeWrapper is a refinement of <a class="link" href="objectwrapper.html#concepts.objectwrapper.objectwrapper_concept_requiremen" title="ObjectWrapper Concept Requirements">ObjectWrapper</a> + which is associated with a particular Python type <code class="computeroutput"><span class="identifier">X</span></code>. + For a given TypeWrapper <code class="computeroutput"><span class="identifier">T</span></code>, + a valid constructor expression + </p> +<pre class="programlisting"><span class="identifier">T</span><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,...</span><span class="identifier">an</span><span class="special">)</span></pre> +<p> + builds a new T object managing the result of invoking X with arguments + corresponding to + </p> +<pre class="programlisting"><span class="identifier">object</span><span class="special">(</span><span class="identifier">a1</span><span class="special">),</span> <span class="identifier">object</span><span class="special">(</span><span class="identifier">a2</span><span class="special">),...</span><span class="identifier">object</span><span class="special">(</span><span class="identifier">an</span><span class="special">)</span></pre> +<p> + . When used as arguments to wrapped C++ functions, or as the template parameter + to <a class="link" href="../to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract" title="Class template extract">extract<></a>, + only instances of the associated Python type will be considered a match. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.objectwrapper.caveat"></a><a class="link" href="objectwrapper.html#concepts.objectwrapper.caveat" title="Caveat">Caveat</a> +</h3></div></div></div> +<p> + 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 <a class="link" href="../object_wrappers.html#object_wrappers.boost_python_dict_hpp.class_dict" title="Class dict">dict</a> + member function <code class="computeroutput"><span class="identifier">items</span></code> returns + an object of type <a class="link" href="../object_wrappers/boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.class_list" title="Class list">list</a>. + Now suppose the user defines this <code class="computeroutput"><span class="identifier">dict</span></code> + subclass in Python: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="keyword">class</span> <span class="identifier">mydict</span><span class="special">(</span><span class="identifier">dict</span><span class="special">):</span> +<span class="special">...</span> <span class="identifier">def</span> <span class="identifier">items</span><span class="special">(</span><span class="identifier">self</span><span class="special">):</span> +<span class="special">...</span> <span class="keyword">return</span> <span class="identifier">tuple</span><span class="special">(</span><span class="identifier">dict</span><span class="special">.</span><span class="identifier">items</span><span class="special">(</span><span class="identifier">self</span><span class="special">))</span> <span class="special">#</span> <span class="keyword">return</span> <span class="identifier">a</span> <span class="identifier">tuple</span> +</pre> +<p> + Since an instance of <code class="computeroutput"><span class="identifier">mydict</span></code> + is also an instance of <code class="computeroutput"><span class="identifier">dict</span></code>, + when used as an argument to a wrapped C++ function, <a class="link" href="../object_wrappers.html#object_wrappers.boost_python_dict_hpp.class_dict" title="Class dict">boost::python::dict</a> + can accept objects of Python type <code class="computeroutput"><span class="identifier">mydict</span></code>. + Invoking <code class="computeroutput"><span class="identifier">items</span><span class="special">()</span></code> + on this object can result in an instance of <a class="link" href="../object_wrappers/boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.class_list" title="Class list">boost::python::list</a> + which actually holds a Python <code class="computeroutput"><span class="identifier">tuple</span></code>. + Subsequent attempts to use <code class="computeroutput"><span class="identifier">list</span></code> + methods (e.g. <code class="computeroutput"><span class="identifier">append</span></code>, or + any other mutating operation) on this object will raise the same exception + that would occur if you tried to do it from Python. + </p> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="resultconverter.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../high_level_components.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/concepts/resultconverter.html b/libs/python/doc/html/reference/concepts/resultconverter.html new file mode 100644 index 0000000000..b3f1b88940 --- /dev/null +++ b/libs/python/doc/html/reference/concepts/resultconverter.html @@ -0,0 +1,210 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>ResultConverter</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../concepts.html" title="Chapter 1. Concepts"> +<link rel="prev" href="holdergenerator.html" title="HolderGenerator"> +<link rel="next" href="objectwrapper.html" title="ObjectWrapper"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="holdergenerator.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="objectwrapper.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="concepts.resultconverter"></a><a class="link" href="resultconverter.html" title="ResultConverter">ResultConverter</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="resultconverter.html#concepts.resultconverter.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="resultconverter.html#concepts.resultconverter.resultconverter_concept_requirem">ResultConverter + Concept Requirements</a></span></dt> +<dt><span class="section"><a href="resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept">ResultConverterGenerator + Concept Requirements</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.resultconverter.introduction"></a><a class="link" href="resultconverter.html#concepts.resultconverter.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + A ResultConverter for a type <code class="computeroutput"><span class="identifier">T</span></code> + is a type whose instances can be used to convert C++ return values of type + <code class="computeroutput"><span class="identifier">T</span></code> <code class="computeroutput"><span class="identifier">to_python</span></code>. + A ResultConverterGenerator is an MPL unary metafunction class which, given + the return type of a C++ function, returns a ResultConverter for that type. + ResultConverters in Boost.Python generally inspect library's registry of + converters to find a suitable converter, but converters which don't use + the registry are also possible. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.resultconverter.resultconverter_concept_requirem"></a><a class="link" href="resultconverter.html#concepts.resultconverter.resultconverter_concept_requirem" title="ResultConverter Concept Requirements">ResultConverter + Concept Requirements</a> +</h3></div></div></div> +<p> + In the table below, <code class="computeroutput"><span class="identifier">C</span></code> denotes + a ResultConverter type for a type <code class="computeroutput"><span class="identifier">R</span></code>, + <code class="computeroutput"><span class="identifier">c</span></code> denotes an object of + type <code class="computeroutput"><span class="identifier">C</span></code>, and <code class="computeroutput"><span class="identifier">r</span></code> denotes an object of type <code class="computeroutput"><span class="identifier">R</span></code>. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Expression + </p> + </th> +<th> + <p> + Type + </p> + </th> +<th> + <p> + Semantics + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">C</span> <span class="identifier">c</span></code> + </p> + </td> +<td> + </td> +<td> + <p> + Constructs a <code class="computeroutput"><span class="identifier">c</span></code> + object. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">c</span><span class="special">.</span><span class="identifier">convertible</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + convertible to <code class="computeroutput"><span class="keyword">bool</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="keyword">false</span></code> iff no conversion + from any <code class="computeroutput"><span class="identifier">R</span></code> value + to a Python object is possible. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">c</span><span class="special">(</span><span class="identifier">r</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + convertible to <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code> + </p> + </td> +<td> + <p> + A pointer to a Python object corresponding to <code class="computeroutput"><span class="identifier">r</span></code>, + or <code class="computeroutput"><span class="number">0</span></code> iff <code class="computeroutput"><span class="identifier">r</span></code> could not be converted <code class="computeroutput"><span class="identifier">to_python</span></code>, in which case <code class="computeroutput"><span class="identifier">PyErr_Occurred</span></code> should return + non-zero. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">c</span><span class="special">.</span><span class="identifier">get_pytype</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span></code> + </p> + </td> +<td> + <p> + A pointer to a Python Type object corresponding to result of + the conversion, or <code class="computeroutput"><span class="number">0</span></code>. + Used for documentation generation. If <code class="computeroutput"><span class="number">0</span></code> + is returned the generated type in the documentation will be object. + </p> + </td> +</tr> +</tbody> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="concepts.resultconverter.resultconvertergenerator_concept"></a><a class="link" href="resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements">ResultConverterGenerator + Concept Requirements</a> +</h3></div></div></div> +<p> + In the table below, <code class="computeroutput"><span class="identifier">G</span></code> denotes + a ResultConverterGenerator type and <code class="computeroutput"><span class="identifier">R</span></code> + denotes a possible C++ function return type. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Expression + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +</tr></thead> +<tbody><tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">G</span><span class="special">::</span><span class="identifier">apply</span><span class="special"><</span><span class="identifier">R</span><span class="special">>::</span><span class="identifier">type</span></code> + </p> + </td> +<td> + <p> + A ResultConverter type for <code class="computeroutput"><span class="identifier">R</span></code>. + </p> + </td> +</tr></tbody> +</table></div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="holdergenerator.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="objectwrapper.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/embedding.html b/libs/python/doc/html/reference/embedding.html new file mode 100644 index 0000000000..1fa7e30a8e --- /dev/null +++ b/libs/python/doc/html/reference/embedding.html @@ -0,0 +1,205 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 6. Embedding</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="index.html" title="Boost.Python Reference Manual"> +<link rel="prev" href="to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html" title="boost/python/register_ptr_to_python.hpp"> +<link rel="next" href="embedding/boost_python_import_hpp.html" title="boost/python/import.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="embedding/boost_python_import_hpp.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="embedding"></a>Chapter 6. Embedding</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp">boost/python/exec.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.function_eval">Function + <code class="computeroutput"><span class="identifier">eval</span></code></a></span></dt> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.function_exec">Function + <code class="computeroutput"><span class="identifier">exec</span></code></a></span></dt> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.function_exec_file">Function + <code class="computeroutput"><span class="identifier">exec_file</span></code></a></span></dt> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.examples">Examples</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="embedding/boost_python_import_hpp.html">boost/python/import.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="embedding/boost_python_import_hpp.html#embedding.boost_python_import_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="embedding/boost_python_import_hpp.html#embedding.boost_python_import_hpp.function_import">Function + <code class="computeroutput"><span class="identifier">import</span></code></a></span></dt> +<dt><span class="section"><a href="embedding/boost_python_import_hpp.html#embedding.boost_python_import_hpp.examples">Examples</a></span></dt> +</dl></dd> +</dl> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="embedding.boost_python_exec_hpp"></a><a class="link" href="embedding.html#embedding.boost_python_exec_hpp" title="boost/python/exec.hpp">boost/python/exec.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.function_eval">Function + <code class="computeroutput"><span class="identifier">eval</span></code></a></span></dt> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.function_exec">Function + <code class="computeroutput"><span class="identifier">exec</span></code></a></span></dt> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.function_exec_file">Function + <code class="computeroutput"><span class="identifier">exec_file</span></code></a></span></dt> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.examples">Examples</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="embedding.boost_python_exec_hpp.introduction"></a><a class="link" href="embedding.html#embedding.boost_python_exec_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Exposes a mechanism for embedding the python interpreter into C++ code. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="embedding.boost_python_exec_hpp.function_eval"></a><a class="link" href="embedding.html#embedding.boost_python_exec_hpp.function_eval" title="Function eval">Function + <code class="computeroutput"><span class="identifier">eval</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">object</span> <span class="identifier">eval</span><span class="special">(</span><span class="identifier">str</span> <span class="identifier">expression</span><span class="special">,</span> + <span class="identifier">object</span> <span class="identifier">globals</span> <span class="special">=</span> <span class="identifier">object</span><span class="special">(),</span> + <span class="identifier">object</span> <span class="identifier">locals</span> <span class="special">=</span> <span class="identifier">object</span><span class="special">());</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Evaluate Python expression from expression in the context specified + by the dictionaries globals and locals. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An instance of object which holds the value of the expression. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="embedding.boost_python_exec_hpp.function_exec"></a><a class="link" href="embedding.html#embedding.boost_python_exec_hpp.function_exec" title="Function exec">Function + <code class="computeroutput"><span class="identifier">exec</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">object</span> <span class="identifier">exec</span><span class="special">(</span><span class="identifier">str</span> <span class="identifier">code</span><span class="special">,</span> + <span class="identifier">object</span> <span class="identifier">globals</span> <span class="special">=</span> <span class="identifier">object</span><span class="special">(),</span> + <span class="identifier">object</span> <span class="identifier">locals</span> <span class="special">=</span> <span class="identifier">object</span><span class="special">());</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Execute Python source code from code in the context specified by + the dictionaries globals and locals. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An instance of object which holds the result of executing the code. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="embedding.boost_python_exec_hpp.function_exec_file"></a><a class="link" href="embedding.html#embedding.boost_python_exec_hpp.function_exec_file" title="Function exec_file">Function + <code class="computeroutput"><span class="identifier">exec_file</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">object</span> <span class="identifier">exec_file</span><span class="special">(</span><span class="identifier">str</span> <span class="identifier">filename</span><span class="special">,</span> + <span class="identifier">object</span> <span class="identifier">globals</span> <span class="special">=</span> <span class="identifier">object</span><span class="special">(),</span> + <span class="identifier">object</span> <span class="identifier">locals</span> <span class="special">=</span> <span class="identifier">object</span><span class="special">());</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Execute Python source code from the file named by filename in the + context specified by the dictionaries globals and locals. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An instance of object which holds the result of executing the code. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="embedding.boost_python_exec_hpp.examples"></a><a class="link" href="embedding.html#embedding.boost_python_exec_hpp.examples" title="Examples">Examples</a> +</h3></div></div></div> +<p> + The following example demonstrates the use of import and exec to define + a function in python, and later call it from within C++. + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">string</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="keyword">void</span> <span class="identifier">greet</span><span class="special">()</span> +<span class="special">{</span> + <span class="comment">// Retrieve the main module.</span> + <span class="identifier">object</span> <span class="identifier">main</span> <span class="special">=</span> <span class="identifier">import</span><span class="special">(</span><span class="string">"__main__"</span><span class="special">);</span> + + <span class="comment">// Retrieve the main module's namespace</span> + <span class="identifier">object</span> <span class="identifier">global</span><span class="special">(</span><span class="identifier">main</span><span class="special">.</span><span class="identifier">attr</span><span class="special">(</span><span class="string">"__dict__"</span><span class="special">));</span> + + <span class="comment">// Define greet function in Python.</span> + <span class="identifier">object</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">exec</span><span class="special">(</span> + <span class="string">"def greet(): \n"</span> + <span class="string">" return 'Hello from Python!' \n"</span><span class="special">,</span> + <span class="identifier">global</span><span class="special">,</span> <span class="identifier">global</span><span class="special">);</span> + + <span class="comment">// Create a reference to it.</span> + <span class="identifier">object</span> <span class="identifier">greet</span> <span class="special">=</span> <span class="identifier">global</span><span class="special">[</span><span class="string">"greet"</span><span class="special">];</span> + + <span class="comment">// Call it.</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">message</span> <span class="special">=</span> <span class="identifier">extract</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">>(</span><span class="identifier">greet</span><span class="special">());</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">message</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + Instead of embedding the python script into a string, we could also store + it in an a file... + </p> +<pre class="programlisting"><span class="identifier">def</span> <span class="identifier">greet</span><span class="special">():</span> + <span class="keyword">return</span> <span class="char">'Hello from Python!'</span> +</pre> +<p> + ... and execute that instead. + </p> +<pre class="programlisting"> <span class="comment">// ...</span> + <span class="comment">// Load the greet function from a file.</span> + <span class="identifier">object</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">exec_file</span><span class="special">(</span><span class="identifier">script</span><span class="special">,</span> <span class="identifier">global</span><span class="special">,</span> <span class="identifier">global</span><span class="special">);</span> + <span class="comment">// ...</span> +<span class="special">}</span> +</pre> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="embedding/boost_python_import_hpp.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/embedding/boost_python_import_hpp.html b/libs/python/doc/html/reference/embedding/boost_python_import_hpp.html new file mode 100644 index 0000000000..2d3f97ede1 --- /dev/null +++ b/libs/python/doc/html/reference/embedding/boost_python_import_hpp.html @@ -0,0 +1,94 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/import.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../embedding.html" title="Chapter 6. Embedding"> +<link rel="prev" href="../embedding.html" title="Chapter 6. Embedding"> +<link rel="next" href="../utility_and_infrastructure.html" title="Chapter 7. Utility and Infrastructure"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../embedding.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../embedding.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../utility_and_infrastructure.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="embedding.boost_python_import_hpp"></a><a class="link" href="boost_python_import_hpp.html" title="boost/python/import.hpp">boost/python/import.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_import_hpp.html#embedding.boost_python_import_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_import_hpp.html#embedding.boost_python_import_hpp.function_import">Function + <code class="computeroutput"><span class="identifier">import</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_import_hpp.html#embedding.boost_python_import_hpp.examples">Examples</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="embedding.boost_python_import_hpp.introduction"></a><a class="link" href="boost_python_import_hpp.html#embedding.boost_python_import_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Exposes a mechanism for importing python modules. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="embedding.boost_python_import_hpp.function_import"></a><a class="link" href="boost_python_import_hpp.html#embedding.boost_python_import_hpp.function_import" title="Function import">Function + <code class="computeroutput"><span class="identifier">import</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">object</span> <span class="identifier">import</span><span class="special">(</span><span class="identifier">str</span> <span class="identifier">name</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Imports the module named by name. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An instance of object which holds a reference to the imported module. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="embedding.boost_python_import_hpp.examples"></a><a class="link" href="boost_python_import_hpp.html#embedding.boost_python_import_hpp.examples" title="Examples">Examples</a> +</h3></div></div></div> +<p> + The following example demonstrates the use of import to access a function + in python, and later call it from within C++. + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">string</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="keyword">void</span> <span class="identifier">print_python_version</span><span class="special">()</span> +<span class="special">{</span> + <span class="comment">// Load the sys module.</span> + <span class="identifier">object</span> <span class="identifier">sys</span> <span class="special">=</span> <span class="identifier">import</span><span class="special">(</span><span class="string">"sys"</span><span class="special">);</span> + + <span class="comment">// Extract the python version.</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">version</span> <span class="special">=</span> <span class="identifier">extract</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">>(</span><span class="identifier">sys</span><span class="special">.</span><span class="identifier">attr</span><span class="special">(</span><span class="string">"version"</span><span class="special">));</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">version</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../embedding.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../embedding.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../utility_and_infrastructure.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/function_invocation_and_creation.html b/libs/python/doc/html/reference/function_invocation_and_creation.html new file mode 100644 index 0000000000..04800de1c5 --- /dev/null +++ b/libs/python/doc/html/reference/function_invocation_and_creation.html @@ -0,0 +1,287 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 4. Function Invocation and Creation</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="index.html" title="Boost.Python Reference Manual"> +<link rel="prev" href="object_wrappers/boost_python_tuple_hpp.html" title="boost/python/tuple.hpp"> +<link rel="next" href="function_invocation_and_creation/boost_python_call_hpp.html" title="boost/python/call.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="object_wrappers/boost_python_tuple_hpp.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="function_invocation_and_creation/boost_python_call_hpp.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="function_invocation_and_creation"></a>Chapter 4. Function Invocation and Creation</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp">boost/python/args.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.class_arg">Class + <code class="computeroutput"><span class="identifier">arg</span></code></a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.class_arg_constructor">Class + <code class="computeroutput"><span class="identifier">arg</span></code> constructor</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.class_arg_operator">Class + <code class="computeroutput"><span class="identifier">arg</span></code> operator=</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.keyword_expression_operator">Keyword-expression + operator,</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_hpp.html">boost/python/call.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.function_call">Function + <code class="computeroutput"><span class="identifier">call</span></code></a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_method_hpp.html">boost/python/call_method.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.function_call_method">Function + <code class="computeroutput"><span class="identifier">call_method</span></code></a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_data_members_hpp.html">boost/python/data_members.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_make_function_hpp.html">boost/python/make_function.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_overloads_hpp.html">boost/python/overloads.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.overloaddispatcher_concept">OverloadDispatcher + Concept</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.macros">Macros</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html">boost/python/ptr.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code></a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_t">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> + types</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_c">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> + constructors and destructor</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_o">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> + observer functions</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions">Metafunctions</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_raw_function_hpp.html">boost/python/raw_function.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.function_raw_function">Function + <code class="computeroutput"><span class="identifier">raw_function</span></code></a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/function_documentation.html">Function + documentation</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat">boost/python/function_doc_signature.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp">boost/python/pytype_function.hpp</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_callpolicies.html">Models + of CallPolicies</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici">boost/python/default_call_policies.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp">boost/python/return_arg.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref">boost/python/return_internal_reference.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy">boost/python/return_value_policy.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_">boost/python/with_custodian_and_ward.hpp</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconverter.html">Models + of ResultConverter</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_">boost/python/to_python_indirect.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp">boost/python/to_python_value.hpp</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html">Models + of ResultConverterGenerator</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc">boost/python/copy_const_reference.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe">boost/python/copy_non_const_reference.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h">boost/python/manage_new_object.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_">boost/python/reference_existing_object.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp">boost/python/return_by_value.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point">boost/python/return_opaque_pointer.hpp</a></span></dt> +</dl></dd> +</dl> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="function_invocation_and_creation.boost_python_args_hpp"></a><a class="link" href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp" title="boost/python/args.hpp">boost/python/args.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.class_arg">Class + <code class="computeroutput"><span class="identifier">arg</span></code></a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.class_arg_constructor">Class + <code class="computeroutput"><span class="identifier">arg</span></code> constructor</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.class_arg_operator">Class + <code class="computeroutput"><span class="identifier">arg</span></code> operator=</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.keyword_expression_operator">Keyword-expression + operator,</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_args_hpp.introduction"></a><a class="link" href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"><dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions">keyword-expressions</a></span></dt></dl></div> +<p> + Supplies a family of overloaded functions for specifying argument keywords + for wrapped C++ functions. + </p> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions"></a><a class="link" href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions" title="keyword-expressions">keyword-expressions</a> +</h4></div></div></div> +<p> + A keyword-expression results in an object which holds a sequence of + <a class="link" href="glossary.html#ntbs">ntbs</a>es, and whose type encodes the number + of keywords specified. The keyword-expression may contain default values + for some or all of the keywords it holds + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_args_hpp.class_arg"></a><a class="link" href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.class_arg" title="Class arg">Class + <code class="computeroutput"><span class="identifier">arg</span></code></a> +</h3></div></div></div> +<p> + The objects of class arg are keyword-expressions holding one keyword ( + size one ) + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">arg</span> + <span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">arg</span> <span class="special">&</span><span class="keyword">operator</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">value</span><span class="special">);</span> + <span class="keyword">explicit</span> <span class="identifier">arg</span> <span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">name</span><span class="special">){</span><span class="identifier">elements</span><span class="special">[</span><span class="number">0</span><span class="special">].</span><span class="identifier">name</span> <span class="special">=</span> <span class="identifier">name</span><span class="special">;}</span> + <span class="special">};</span> + +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_args_hpp.class_arg_constructor"></a><a class="link" href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.class_arg_constructor" title="Class arg constructor">Class + <code class="computeroutput"><span class="identifier">arg</span></code> constructor</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">arg</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + The argument must be a <a class="link" href="glossary.html#ntbs">ntbs</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Constructs an arg object holding a keyword with name name. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_args_hpp.class_arg_operator"></a><a class="link" href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.class_arg_operator" title="Class arg operator=">Class + <code class="computeroutput"><span class="identifier">arg</span></code> operator=</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">arg</span> <span class="special">&</span><span class="keyword">operator</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">value</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + The argument must convertible to python. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Assigns default value for the keyword. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + Reference to <code class="computeroutput"><span class="keyword">this</span></code>. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_args_hpp.keyword_expression_operator"></a><a class="link" href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.keyword_expression_operator" title="Keyword-expression operator,">Keyword-expression + operator,</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">keyword</span><span class="special">-</span><span class="identifier">expression</span> <span class="keyword">operator</span> <span class="special">,</span> <span class="special">(</span><span class="identifier">keyword</span><span class="special">-</span><span class="identifier">expression</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">arg</span> <span class="special">&</span><span class="identifier">kw</span><span class="special">)</span> <span class="keyword">const</span> +<span class="identifier">keyword</span><span class="special">-</span><span class="identifier">expression</span> <span class="keyword">operator</span> <span class="special">,</span> <span class="special">(</span><span class="identifier">keyword</span><span class="special">-</span><span class="identifier">expression</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span> <span class="special">*</span><span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + The argument name must be a <a class="link" href="glossary.html#ntbs">ntbs</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Extends the keyword-expression argument with one more keyword. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + The extended keyword-expression. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_args_hpp.example"></a><a class="link" href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">z</span><span class="special">=</span><span class="number">0.0</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">w</span><span class="special">=</span><span class="number">1.0</span><span class="special">);</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">xxx</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="special">(</span><span class="identifier">arg</span><span class="special">(</span><span class="string">"x"</span><span class="special">),</span> <span class="string">"y"</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"z"</span><span class="special">)=</span><span class="number">0.0</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"w"</span><span class="special">)=</span><span class="number">1.0</span><span class="special">));</span> +<span class="special">}</span> +</pre> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="object_wrappers/boost_python_tuple_hpp.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="function_invocation_and_creation/boost_python_call_hpp.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_call_hpp.html b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_call_hpp.html new file mode 100644 index 0000000000..ddf8b71756 --- /dev/null +++ b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_call_hpp.html @@ -0,0 +1,96 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/call.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> +<link rel="prev" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> +<link rel="next" href="boost_python_call_method_hpp.html" title="boost/python/call_method.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../function_invocation_and_creation.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_call_method_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="function_invocation_and_creation.boost_python_call_hpp"></a><a class="link" href="boost_python_call_hpp.html" title="boost/python/call.hpp">boost/python/call.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.function_call">Function + <code class="computeroutput"><span class="identifier">call</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_call_hpp.introduction"></a><a class="link" href="boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<pre class="programlisting"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">call</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> <span class="identifier">defines</span> <span class="identifier">the</span> <span class="identifier">call</span> <span class="identifier">family</span> <span class="identifier">of</span> <span class="identifier">overloaded</span> <span class="identifier">function</span> <span class="identifier">templates</span><span class="special">,</span> <span class="identifier">used</span> <span class="identifier">to</span> <span class="identifier">invoke</span> <span class="identifier">Python</span> <span class="identifier">callable</span> <span class="identifier">objects</span> <span class="identifier">from</span> <span class="identifier">C</span><span class="special">++.</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_call_hpp.function_call"></a><a class="link" href="boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.function_call" title="Function call">Function + <code class="computeroutput"><span class="identifier">call</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">,</span> <span class="special">...</span> <span class="keyword">class</span> <span class="identifier">An</span><span class="special">></span> +<span class="identifier">R</span> <span class="identifier">call</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">callable</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">A2</span> <span class="keyword">const</span><span class="special">&,</span> <span class="special">...</span> <span class="identifier">An</span> <span class="keyword">const</span><span class="special">&)</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + R is a pointer type, reference type, or a complete type with an accessible + copy constructor + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Invokes callable(a1, a2, ...an) in Python, where a1...an are the + arguments to call(), converted to Python objects. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + The result of the Python call, converted to the C++ type R. + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + For a complete semantic description and rationale, see this page. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_call_hpp.example"></a><a class="link" href="boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<p> + The following C++ function applies a Python callable object to its two + arguments and returns the result. If a Python exception is raised or the + result can't be converted to a double, an exception is thrown. + </p> +<pre class="programlisting"><span class="keyword">double</span> <span class="identifier">apply2</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">func</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">call</span><span class="special"><</span><span class="keyword">double</span><span class="special">>(</span><span class="identifier">func</span><span class="special">,</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">);</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../function_invocation_and_creation.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_call_method_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_call_method_hpp.html b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_call_method_hpp.html new file mode 100644 index 0000000000..0fecfcc720 --- /dev/null +++ b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_call_method_hpp.html @@ -0,0 +1,156 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/call_method.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> +<link rel="prev" href="boost_python_call_hpp.html" title="boost/python/call.hpp"> +<link rel="next" href="boost_python_data_members_hpp.html" title="boost/python/data_members.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_call_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_data_members_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="function_invocation_and_creation.boost_python_call_method_hpp"></a><a class="link" href="boost_python_call_method_hpp.html" title="boost/python/call_method.hpp">boost/python/call_method.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.function_call_method">Function + <code class="computeroutput"><span class="identifier">call_method</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_call_method_hpp.introduction"></a><a class="link" href="boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/call_method.hpp> defines the call_method family of + overloaded function templates, used to invoke callable attributes of Python + objects from C++. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_call_method_hpp.function_call_method"></a><a class="link" href="boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.function_call_method" title="Function call_method">Function + <code class="computeroutput"><span class="identifier">call_method</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">,</span> <span class="special">...</span> <span class="keyword">class</span> <span class="identifier">An</span><span class="special">></span> +<span class="identifier">R</span> <span class="identifier">call_method</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">self</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">method</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">A2</span> <span class="keyword">const</span><span class="special">&,</span> <span class="special">...</span> <span class="identifier">An</span> <span class="keyword">const</span><span class="special">&)</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">R</span></code> is a pointer type, + reference type, or a complete type with an accessible copy constructor + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Invokes <code class="computeroutput"><span class="identifier">self</span><span class="special">.</span><span class="identifier">method</span><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,</span> <span class="special">...</span><span class="identifier">an</span><span class="special">)</span></code> in Python, where <code class="computeroutput"><span class="identifier">a1</span><span class="special">...</span><span class="identifier">an</span></code> + are the arguments to <code class="computeroutput"><span class="identifier">call_method</span><span class="special">()</span></code>, converted to Python objects. For + a complete semantic description, see this page. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + The result of the Python call, converted to the C++ type <code class="computeroutput"><span class="identifier">R</span></code>. + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">call_method</span></code> is critical + to implementing C++ virtual functions which are overridable in Python, + as shown by the example below. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_call_method_hpp.example"></a><a class="link" href="boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<p> + The following C++ illustrates the use of <code class="computeroutput"><span class="identifier">call_method</span></code> + in wrapping a class with a virtual function that can be overridden in Python: + C++ Module Definition + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">utility</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cstring</span><span class="special">></span> + +<span class="comment">// class to be wrapped</span> +<span class="keyword">class</span> <span class="identifier">Base</span> +<span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="keyword">virtual</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">class_name</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"Base"</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">Base</span><span class="special">();</span> +<span class="special">};</span> + +<span class="keyword">bool</span> <span class="identifier">is_base</span><span class="special">(</span><span class="identifier">Base</span><span class="special">*</span> <span class="identifier">b</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="special">!</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">strcmp</span><span class="special">(</span><span class="identifier">b</span><span class="special">-></span><span class="identifier">class_name</span><span class="special">(),</span> <span class="string">"Base"</span><span class="special">);</span> +<span class="special">}</span> + +<span class="comment">// Wrapper code begins here</span> +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="comment">// Callback class</span> +<span class="keyword">class</span> <span class="identifier">Base_callback</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">Base</span> +<span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">Base_callback</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">self</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">m_self</span><span class="special">(</span><span class="identifier">self</span><span class="special">)</span> <span class="special">{}</span> + + <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">class_name</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">call_method</span><span class="special"><</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*>(</span><span class="identifier">m_self</span><span class="special">,</span> <span class="string">"class_name"</span><span class="special">);</span> <span class="special">}</span> + <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">Base_name</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">Base</span><span class="special">::</span><span class="identifier">class_name</span><span class="special">();</span> <span class="special">}</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="keyword">const</span> <span class="identifier">m_self</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">my_module</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"is_base"</span><span class="special">,</span> <span class="identifier">is_base</span><span class="special">);</span> + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Base</span><span class="special">,</span><span class="identifier">Base_callback</span><span class="special">,</span> <span class="identifier">noncopyable</span><span class="special">>(</span><span class="string">"Base"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"class_name"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Base_callback</span><span class="special">::</span><span class="identifier">Base_name</span><span class="special">)</span> + <span class="special">;</span> + +<span class="special">}</span> +</pre> +<p> + Python code: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">my_module</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="keyword">class</span> <span class="identifier">Derived</span><span class="special">(</span><span class="identifier">Base</span><span class="special">):</span> +<span class="special">...</span> <span class="identifier">def</span> <span class="identifier">__init__</span><span class="special">(</span><span class="identifier">self</span><span class="special">):</span> +<span class="special">...</span> <span class="identifier">Base</span><span class="special">.</span><span class="identifier">__init__</span><span class="special">(</span><span class="identifier">self</span><span class="special">)</span> +<span class="special">...</span> <span class="identifier">def</span> <span class="identifier">class_name</span><span class="special">(</span><span class="identifier">self</span><span class="special">):</span> +<span class="special">...</span> <span class="keyword">return</span> <span class="identifier">self</span><span class="special">.</span><span class="identifier">__class__</span><span class="special">.</span><span class="identifier">__name__</span> +<span class="special">...</span> +<span class="special">>>></span> <span class="identifier">is_base</span><span class="special">(</span><span class="identifier">Base</span><span class="special">())</span> <span class="special">#</span> <span class="identifier">calls</span> <span class="identifier">the</span> <span class="identifier">class_name</span><span class="special">()</span> <span class="identifier">method</span> <span class="identifier">from</span> <span class="identifier">C</span><span class="special">++</span> +<span class="number">1</span> +<span class="special">>>></span> <span class="identifier">is_base</span><span class="special">(</span><span class="identifier">Derived</span><span class="special">())</span> +<span class="number">0</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_call_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_data_members_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_data_members_hpp.html b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_data_members_hpp.html new file mode 100644 index 0000000000..8bb289f8ee --- /dev/null +++ b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_data_members_hpp.html @@ -0,0 +1,215 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/data_members.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> +<link rel="prev" href="boost_python_call_method_hpp.html" title="boost/python/call_method.hpp"> +<link rel="next" href="boost_python_make_function_hpp.html" title="boost/python/make_function.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_call_method_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_make_function_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="function_invocation_and_creation.boost_python_data_members_hpp"></a><a class="link" href="boost_python_data_members_hpp.html" title="boost/python/data_members.hpp">boost/python/data_members.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_data_members_hpp.introduction"></a><a class="link" href="boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">make_getter</span><span class="special">()</span></code> + and <code class="computeroutput"><span class="identifier">make_setter</span><span class="special">()</span></code> + are the functions used internally by <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu" title="Class template class_ modifier functions"><code class="computeroutput"><span class="identifier">class_</span><span class="special"><>::</span><span class="identifier">def_readonly</span></code></a> and <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu" title="Class template class_ modifier functions"><code class="computeroutput"><span class="identifier">class_</span><span class="special"><>::</span><span class="identifier">def_readwrite</span></code></a> to produce Python + callable objects which wrap C++ data members. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_data_members_hpp.functions"></a><a class="link" href="boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.functions" title="Functions">Functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">D</span> <span class="identifier">C</span><span class="special">::*</span><span class="identifier">pm</span><span class="special">);</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">D</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">D</span> <span class="identifier">C</span><span class="special">::*</span><span class="identifier">pm</span><span class="special">,</span> <span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + Policies is a model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Creates a Python callable object which accepts a single argument + that can be converted from_python to C*, and returns the corresponding + member D member of the C object, converted to_python. If policies + is supplied, it will be applied to the function as described here. + Otherwise, the library attempts to determine whether D is a user-defined + class type, and if so uses return_internal_reference<> for + Policies. Note that this test may inappropriately choose return_internal_reference<> + in some cases when D is a smart pointer type. This is a known defect. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An instance of object which holds the new Python callable object. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">D</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">d</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">D</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">d</span><span class="special">,</span> <span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">);</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">D</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">p</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">D</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + Policies is a model of CallPolicies. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Creates a Python callable object which accepts no arguments and returns + d or *p, converted to_python on demand. If policies is supplied, + it will be applied to the function as described here. Otherwise, + the library attempts to determine whether D is a user-defined class + type, and if so uses reference_existing_object for Policies. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An instance of object which holds the new Python callable object. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">D</span> <span class="identifier">C</span><span class="special">::*</span><span class="identifier">pm</span><span class="special">);</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">C</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">D</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">D</span> <span class="identifier">C</span><span class="special">::*</span><span class="identifier">pm</span><span class="special">,</span> <span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + Policies is a model of CallPolicies. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Creates a Python callable object which, when called from Python, + expects two arguments which can be converted from_python to C* and + D const&, respectively, and sets the corresponding D member of + the C object. If policies is supplied, it will be applied to the + function as described here. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An instance of object which holds the new Python callable object. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">D</span><span class="special">&</span> <span class="identifier">d</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">D</span><span class="special">&</span> <span class="identifier">d</span><span class="special">,</span> <span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">);</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">D</span><span class="special">*</span> <span class="identifier">p</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">D</span><span class="special">*</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + Policies is a model of CallPolicies. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Creates a Python callable object which accepts one argument, which + is converted from Python to D const& and written into d or *p, + respectively. If policies is supplied, it will be applied to the + function as described here. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An instance of object which holds the new Python callable object. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_data_members_hpp.example"></a><a class="link" href="boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<p> + The code below uses make_getter and make_setter to expose a data member + as functions: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">data_members</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="identifier">X</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">y</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span> + <span class="keyword">int</span> <span class="identifier">y</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="identifier">BOOST_PYTHON_MODULE_INIT</span><span class="special">(</span><span class="identifier">data_members_example</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">X</span><span class="special">>(</span><span class="string">"X"</span><span class="special">,</span> <span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">>())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get"</span><span class="special">,</span> <span class="identifier">make_getter</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">y</span><span class="special">))</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"set"</span><span class="special">,</span> <span class="identifier">make_setter</span><span class="special">(&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">y</span><span class="special">))</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + It can be used this way in Python: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">data_members_example</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">X</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> +<span class="special">>>></span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">get</span><span class="special">()</span> +<span class="number">1</span> +<span class="special">>>></span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">set</span><span class="special">(</span><span class="number">2</span><span class="special">)</span> +<span class="special">>>></span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">get</span><span class="special">()</span> +<span class="number">2</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_call_method_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_make_function_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_make_function_hpp.html b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_make_function_hpp.html new file mode 100644 index 0000000000..ef9e1b0ac7 --- /dev/null +++ b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_make_function_hpp.html @@ -0,0 +1,194 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/make_function.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> +<link rel="prev" href="boost_python_data_members_hpp.html" title="boost/python/data_members.hpp"> +<link rel="next" href="boost_python_overloads_hpp.html" title="boost/python/overloads.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_data_members_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_overloads_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="function_invocation_and_creation.boost_python_make_function_hpp"></a><a class="link" href="boost_python_make_function_hpp.html" title="boost/python/make_function.hpp">boost/python/make_function.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_make_function_hpp.introduction"></a><a class="link" href="boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + make_function() and make_constructor() are the functions used internally + by def() and class_<>::def() to produce Python callable objects which + wrap C++ functions and member functions. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_make_function_hpp.functions"></a><a class="link" href="boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.functions" title="Functions">Functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_function</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">)</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_function</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">)</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">KeywordsOrSignature</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_function</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">,</span> <span class="identifier">KeywordsOrSignature</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">ks</span><span class="special">)</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Keywords</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Signature</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_function</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">,</span> <span class="identifier">Keywords</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">kw</span><span class="special">,</span> <span class="identifier">Signature</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sig</span><span class="special">)</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + F is a function pointer or member function pointer type. If policies + are supplied, it must be a model of CallPolicies. If kewords are + supplied, it must be the result of a keyword-expression specifying + no more arguments than the arity of f. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd> +<p> + Creates a Python callable object which, when called from Python, + converts its arguments to C++ and calls f. If F is a pointer-to-member-function + type, the target object of the function call (*this) will be taken + from the first Python argument, and subsequent Python arguments will + be used as the arguments to f. + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + If policies are supplied, it will be applied to the function + as described here. + </li> +<li class="listitem"> + If keywords are supplied, the keywords will be applied in order + to the final arguments of the resulting function. + </li> +<li class="listitem"> + If Signature is supplied, it should be an instance of an MPL + front-extensible sequence representing the function's return + type followed by its argument types. Pass a Signature when wrapping + function object types whose signatures can't be deduced, or when + you wish to override the types which will be passed to the wrapped + function. + </li> +</ul></div> +</dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An instance of object which holds the new Python callable object. + </p></dd> +<dt><span class="term">Caveats</span></dt> +<dd><p> + An argument of pointer type may be 0 if None is passed from Python. + An argument type which is a constant reference may refer to a temporary + which was created from the Python object for just the duration of + the call to the wrapped function, for example a std::vector conjured + up by the conversion process from a Python list. Use a non-const + reference argument when a persistent lvalue is required. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_constructor</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">)</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_constructor</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">)</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">KeywordsOrSignature</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_constructor</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">,</span> <span class="identifier">KeywordsOrSignature</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">ks</span><span class="special">)</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Keywords</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Signature</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">make_constructor</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">,</span> <span class="identifier">Keywords</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">kw</span><span class="special">,</span> <span class="identifier">Signature</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sig</span><span class="special">)</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + F is a function pointer type. If policies are supplied, it must be + a model of CallPolicies. If kewords are supplied, it must be the + result of a keyword-expression specifying no more arguments than + the arity of f. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Creates a Python callable object which, when called from Python, + converts its arguments to C++ and calls f. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An instance of object which holds the new Python callable object. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_make_function_hpp.example"></a><a class="link" href="boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<p> + C++ function exposed below returns a callable object wrapping one of two + functions. + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">make_function</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">foo</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"foo"</span><span class="special">;</span> <span class="special">}</span> +<span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">bar</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"bar"</span><span class="special">;</span> <span class="special">}</span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">object</span> <span class="identifier">choose_function</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">selector</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">if</span> <span class="special">(</span><span class="identifier">selector</span><span class="special">)</span> + <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">make_function</span><span class="special">(</span><span class="identifier">foo</span><span class="special">);</span> + <span class="keyword">else</span> + <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">make_function</span><span class="special">(</span><span class="identifier">bar</span><span class="special">);</span> +<span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">make_function_test</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"choose_function"</span><span class="special">,</span> <span class="identifier">choose_function</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + It can be used this way in Python: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">make_function_test</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">choose_function</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> +<span class="special">>>></span> <span class="identifier">g</span> <span class="special">=</span> <span class="identifier">choose_function</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> +<span class="special">>>></span> <span class="identifier">f</span><span class="special">()</span> +<span class="char">'foo'</span> +<span class="special">>>></span> <span class="identifier">g</span><span class="special">()</span> +<span class="char">'bar'</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_data_members_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_overloads_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_overloads_hpp.html b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_overloads_hpp.html new file mode 100644 index 0000000000..d2bdaf9a9d --- /dev/null +++ b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_overloads_hpp.html @@ -0,0 +1,208 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/overloads.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> +<link rel="prev" href="boost_python_make_function_hpp.html" title="boost/python/make_function.hpp"> +<link rel="next" href="boost_python_ptr_hpp.html" title="boost/python/ptr.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_make_function_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_ptr_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="function_invocation_and_creation.boost_python_overloads_hpp"></a><a class="link" href="boost_python_overloads_hpp.html" title="boost/python/overloads.hpp">boost/python/overloads.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.overloaddispatcher_concept">OverloadDispatcher + Concept</a></span></dt> +<dt><span class="section"><a href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.macros">Macros</a></span></dt> +<dt><span class="section"><a href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_overloads_hpp.introduction"></a><a class="link" href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"><dt><span class="section"><a href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions">overload-dispatch-expressions</a></span></dt></dl></div> +<p> + 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 + </p> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions"></a><a class="link" href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions" title="overload-dispatch-expressions">overload-dispatch-expressions</a> +</h4></div></div></div> +<p> + 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: + </p> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">docstring</span></dt> +<dd><p> + An <a class="link" href="../glossary.html#ntbs">ntbs</a> whose value will bound to the + methods' <code class="computeroutput"><span class="identifier">__doc__</span></code> + attribute + </p></dd> +<dt><span class="term">keywords</span></dt> +<dd><p> + A <a class="link" href="../function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions" title="keyword-expressions">keyword-expression</a> + which will be used to name (a trailing subsequence of) the arguments + to the generated methods. + </p></dd> +<dt><span class="term">call policies</span></dt> +<dd><p> + An instance of some type which models CallPolicies. + </p></dd> +<dt><span class="term">minimum arity</span></dt> +<dd><p> + The minimum number of arguments to be accepted by a generated method + overload. + </p></dd> +<dt><span class="term">maximum arity</span></dt> +<dd><p> + The maximum number of arguments to be accepted by a generated method + overload. + </p></dd> +</dl> +</div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_overloads_hpp.overloaddispatcher_concept"></a><a class="link" href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.overloaddispatcher_concept" title="OverloadDispatcher Concept">OverloadDispatcher + Concept</a> +</h3></div></div></div> +<p> + 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. + </p> +<pre class="programlisting"><span class="identifier">X</span><span class="special">()</span> +<span class="identifier">X</span><span class="special">(</span><span class="identifier">docstring</span><span class="special">)</span> +<span class="identifier">X</span><span class="special">(</span><span class="identifier">docstring</span><span class="special">,</span> <span class="identifier">keywords</span><span class="special">)</span> +<span class="identifier">X</span><span class="special">(</span><span class="identifier">keywords</span><span class="special">,</span> <span class="identifier">docstring</span><span class="special">)</span> +<span class="identifier">X</span><span class="special">()[</span><span class="identifier">policies</span><span class="special">]</span> +<span class="identifier">X</span><span class="special">(</span><span class="identifier">docstring</span><span class="special">)[</span><span class="identifier">policies</span><span class="special">]</span> +<span class="identifier">X</span><span class="special">(</span><span class="identifier">docstring</span><span class="special">,</span> <span class="identifier">keywords</span><span class="special">)[</span><span class="identifier">policies</span><span class="special">]</span> +<span class="identifier">X</span><span class="special">(</span><span class="identifier">keywords</span><span class="special">,</span> <span class="identifier">docstring</span><span class="special">)[</span><span class="identifier">policies</span><span class="special">]</span> +</pre> +<p> + * If policies are supplied, it must be an instance of a type which models + <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>, and will be + used as the result's call policies. Otherwise the result's call policies + will be an instance of <a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici" title="boost/python/default_call_policies.hpp"><code class="computeroutput"><span class="identifier">default_call_policies</span></code></a>. * If docstring + is supplied it must be an <a class="link" href="../glossary.html#ntbs">ntbs</a>, and will be + used as the result's docstring. Otherwise the result has an empty docstring. + * If keywords is supplied it must be the result of a <a class="link" href="../function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions" title="keyword-expressions">keyword-expression</a> + whose length is no greater than X's maximum arity, and will be used as + the result's keywords. Otherwise the result's keywords will be empty. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_overloads_hpp.macros"></a><a class="link" href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.macros" title="Macros">Macros</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">BOOST_PYTHON_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">func_id</span><span class="special">,</span> <span class="identifier">min_args</span><span class="special">,</span> <span class="identifier">max_args</span><span class="special">)</span> +</pre> +<p> + Expands to the definition of an OverloadDispatcher called name in the current + scope which can be used to generate the following function invocation: + </p> +<pre class="programlisting"><span class="identifier">func_id</span><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,...</span><span class="identifier">ai</span><span class="special">);</span></pre> +<p> + for all <code class="computeroutput"><span class="identifier">min_args</span> <span class="special"><=</span> + <span class="identifier">i</span> <span class="special"><=</span> + <span class="identifier">max_args</span></code>. + </p> +<pre class="programlisting"><span class="identifier">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">member_name</span><span class="special">,</span> <span class="identifier">min_args</span><span class="special">,</span> <span class="identifier">max_args</span><span class="special">)</span> +</pre> +<p> + Expands to the definition of an OverloadDispatcher called name in the current + scope which can be used to generate the following function invocation: + </p> +<pre class="programlisting"><span class="identifier">x</span><span class="special">.</span><span class="identifier">member_name</span><span class="special">(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,...</span><span class="identifier">ai</span><span class="special">);</span></pre> +<p> + for all min_args <= i <= max_args, where x is a reference to an object + of class type. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_overloads_hpp.example"></a><a class="link" href="boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">args</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">tuple</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">overloads</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_internal_reference</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="identifier">tuple</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="number">4.25</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">z</span> <span class="special">=</span> <span class="string">"wow"</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">);</span> +<span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">f_overloads</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span> + +<span class="keyword">struct</span> <span class="identifier">Y</span> <span class="special">{};</span> +<span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="identifier">Y</span><span class="special">&</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="number">4.25</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">z</span> <span class="special">=</span> <span class="string">"wow"</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">inner</span><span class="special">;</span> + <span class="special">}</span> + <span class="identifier">Y</span> <span class="identifier">inner</span><span class="special">;</span> +<span class="special">};</span> + +<span class="identifier">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">f_member_overloads</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">args_ext</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> + <span class="identifier">f_overloads</span><span class="special">(</span> + <span class="identifier">args</span><span class="special">(</span><span class="string">"x"</span><span class="special">,</span> <span class="string">"y"</span><span class="special">,</span> <span class="string">"z"</span><span class="special">),</span> <span class="string">"This is f's docstring"</span> + <span class="special">));</span> + + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Y</span><span class="special">>(</span><span class="string">"Y"</span><span class="special">)</span> + <span class="special">;</span> + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">X</span><span class="special">>(</span><span class="string">"X"</span><span class="special">,</span> <span class="string">"This is X's docstring"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f1"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> + <span class="identifier">f_member_overloads</span><span class="special">(</span> + <span class="identifier">args</span><span class="special">(</span><span class="string">"x"</span><span class="special">,</span> <span class="string">"y"</span><span class="special">,</span> <span class="string">"z"</span><span class="special">),</span> <span class="string">"f's docstring"</span> + <span class="special">)[</span><span class="identifier">return_internal_reference</span><span class="special"><>()]</span> + <span class="special">)</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_make_function_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_ptr_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_ptr_hpp.html b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_ptr_hpp.html new file mode 100644 index 0000000000..706774c11d --- /dev/null +++ b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_ptr_hpp.html @@ -0,0 +1,287 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/ptr.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> +<link rel="prev" href="boost_python_overloads_hpp.html" title="boost/python/overloads.hpp"> +<link rel="next" href="boost_python_raw_function_hpp.html" title="boost/python/raw_function.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_overloads_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_raw_function_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="function_invocation_and_creation.boost_python_ptr_hpp"></a><a class="link" href="boost_python_ptr_hpp.html" title="boost/python/ptr.hpp">boost/python/ptr.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_t">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> + types</a></span></dt> +<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_c">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> + constructors and destructor</a></span></dt> +<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_o">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> + observer functions</a></span></dt> +<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions">Metafunctions</a></span></dt> +<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_ptr_hpp.introduction"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/ptr.hpp> defines the ptr() function template, which + allows users to specify how to convert C++ pointer values to python in + the context of implementing overridable virtual functions, invoking Python + callable objects, or explicitly converting C++ objects to Python. Normally, + when passing pointers to Python callbacks, the pointee is copied to ensure + that the Python object never holds a dangling reference. To specify that + the new Python object should merely contain a copy of a pointer p, the + user can pass ptr(p) instead of passing p directly. This interface is meant + to mirror the use of boost::ref(), which can be similarly used to prevent + copying of referents. + </p> +<p> + ptr(p) returns an instance of <a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper" title="Class template pointer_wrapper"><code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special"><></span></code></a>, + which can be detected using the <a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe" title="Class template is_pointer_wrapper"><code class="computeroutput"><span class="identifier">is_pointer_wrapper</span><span class="special"><></span></code></a> + metafunction; <a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer" title="Class template unwrap_pointer"><code class="computeroutput"><span class="identifier">unwrap_pointer</span><span class="special"><></span></code></a> + is a metafunction which extracts the original pointer type from a <code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special"><></span></code>. + These classes can be thought of as implementation details. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_ptr_hpp.functions"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.functions" title="Functions">Functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> +<span class="identifier">pointer_wrapper</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">ptr</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + T is a pointer type. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + pointer_wrapper<T>(x) + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + nothing. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper" title="Class template pointer_wrapper">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code></a> +</h3></div></div></div> +<p> + A "type envelope" which is returned by <code class="computeroutput"><span class="identifier">ptr</span><span class="special">()</span></code>, used to indicate reference semantics + for pointers passed to Python callbacks. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">Ptr</span><span class="special">></span> <span class="keyword">class</span> <span class="identifier">pointer_wrapper</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="keyword">typedef</span> <span class="identifier">Ptr</span> <span class="identifier">type</span><span class="special">;</span> + + <span class="keyword">explicit</span> <span class="identifier">pointer_wrapper</span><span class="special">(</span><span class="identifier">Ptr</span> <span class="identifier">x</span><span class="special">);</span> + <span class="keyword">operator</span> <span class="identifier">Ptr</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">Ptr</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_t"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_t" title="Class template pointer_wrapper types">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> + types</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">Ptr</span> <span class="identifier">type</span><span class="special">;</span> +</pre> +<p> + The type of the pointer being wrapped. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_c"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_c" title="Class template pointer_wrapper constructors and destructor">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> + constructors and destructor</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">pointer_wrapper</span><span class="special">(</span><span class="identifier">Ptr</span> <span class="identifier">x</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">Ptr</span></code> is a pointer + type + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Stores <code class="computeroutput"><span class="identifier">x</span></code> in a the + <code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special"><></span></code>. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + nothing. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_o"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_o" title="Class template pointer_wrapper observer functions">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> + observer functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">operator</span> <span class="identifier">Ptr</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">Ptr</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + a copy of the stored pointer. + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + pointer_wrapper is intended to be a stand-in for the actual pointer + type, but sometimes it's better to have an explicit way to retrieve + the pointer. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_ptr_hpp.metafunctions"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions" title="Metafunctions">Metafunctions</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe">Class + template <code class="computeroutput"><span class="identifier">is_pointer_wrapper</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer">Class + template <code class="computeroutput"><span class="identifier">unwrap_pointer</span></code></a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe" title="Class template is_pointer_wrapper">Class + template <code class="computeroutput"><span class="identifier">is_pointer_wrapper</span></code></a> +</h4></div></div></div> +<p> + A unary metafunction whose value is true iff its argument is a pointer_wrapper<>. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">class</span> <span class="identifier">is_pointer_wrapper</span> + <span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">unspecified</span> <span class="identifier">value</span> <span class="special">=</span> <span class="special">...;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="keyword">true</span></code> iff <code class="computeroutput"><span class="identifier">T</span></code> is a specialization of <code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special"><></span></code>. + value is an integral constant convertible to bool of unspecified + type + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer" title="Class template unwrap_pointer">Class + template <code class="computeroutput"><span class="identifier">unwrap_pointer</span></code></a> +</h4></div></div></div> +<p> + A unary metafunction which extracts the wrapped pointer type from a specialization + of pointer_wrapper<>. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">class</span> <span class="identifier">unwrap_pointer</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">unspecified</span> <span class="identifier">type</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">type</span></code> if <code class="computeroutput"><span class="identifier">T</span></code> + is a specialization of <code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special"><></span></code>, <code class="computeroutput"><span class="identifier">T</span></code> + otherwise + </p></dd> +</dl> +</div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_ptr_hpp.example"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<p> + This example illustrates the use of ptr() to prevent an object from being + copied: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">call</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">ptr</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">class</span> <span class="identifier">expensive_to_copy</span> +<span class="special">{</span> + <span class="special">...</span> +<span class="special">};</span> + +<span class="keyword">void</span> <span class="identifier">pass_as_arg</span><span class="special">(</span><span class="identifier">expensive_to_copy</span><span class="special">*</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">f</span><span class="special">)</span> +<span class="special">{</span> + <span class="comment">// call the Python function f, passing a Python object built around</span> + <span class="comment">// which refers to *x by-pointer.</span> + <span class="comment">//</span> + <span class="comment">// *** Note: ensuring that *x outlives the argument to f() is ***</span> + <span class="comment">// *** up to the user! Failure to do so could result in a crash! ***</span> + + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">call</span><span class="special"><</span><span class="keyword">void</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">ptr</span><span class="special">(</span><span class="identifier">x</span><span class="special">));</span> +<span class="special">}</span> +<span class="special">...</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_overloads_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_raw_function_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_raw_function_hpp.html b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_raw_function_hpp.html new file mode 100644 index 0000000000..fe3cde7440 --- /dev/null +++ b/libs/python/doc/html/reference/function_invocation_and_creation/boost_python_raw_function_hpp.html @@ -0,0 +1,111 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/raw_function.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> +<link rel="prev" href="boost_python_ptr_hpp.html" title="boost/python/ptr.hpp"> +<link rel="next" href="function_documentation.html" title="Function documentation"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_ptr_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="function_documentation.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="function_invocation_and_creation.boost_python_raw_function_hpp"></a><a class="link" href="boost_python_raw_function_hpp.html" title="boost/python/raw_function.hpp">boost/python/raw_function.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.function_raw_function">Function + <code class="computeroutput"><span class="identifier">raw_function</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_raw_function_hpp.introduction"></a><a class="link" href="boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">raw_function</span><span class="special">(...)</span></code> + is used to convert a function taking a <a class="link" href="../object_wrappers/boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.class_tuple" title="Class tuple"><code class="computeroutput"><span class="identifier">tuple</span></code></a> and a <a class="link" href="../object_wrappers.html#object_wrappers.boost_python_dict_hpp.class_dict" title="Class dict"><code class="computeroutput"><span class="identifier">dict</span></code></a> into a Python callable object + which accepts a variable number of arguments and arbitrary keyword arguments. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_raw_function_hpp.function_raw_function"></a><a class="link" href="boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.function_raw_function" title="Function raw_function">Function + <code class="computeroutput"><span class="identifier">raw_function</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">raw_function</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">min_args</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + f(tuple(), dict()) is well-formed. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + a callable object which requires at least min_args arguments. When + called, the actual non-keyword arguments will be passed in a tuple + as the first argument to f, and the keyword arguments will be passed + in a dict as the second argument to f. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.boost_python_raw_function_hpp.example"></a><a class="link" href="boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<p> + C++: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">tuple</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">dict</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">raw_function</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="identifier">tuple</span> <span class="identifier">raw</span><span class="special">(</span><span class="identifier">tuple</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">dict</span> <span class="identifier">kw</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">args</span><span class="special">,</span> <span class="identifier">kw</span><span class="special">);</span> +<span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">raw_test</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"raw"</span><span class="special">,</span> <span class="identifier">raw_function</span><span class="special">(</span><span class="identifier">raw</span><span class="special">));</span> +<span class="special">}</span> +</pre> +<p> + Python: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">raw_test</span> <span class="identifier">import</span> <span class="special">*</span> + +<span class="special">>>></span> <span class="identifier">raw</span><span class="special">(</span><span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">,</span> <span class="identifier">foo</span> <span class="special">=</span> <span class="char">'bar'</span><span class="special">,</span> <span class="identifier">baz</span> <span class="special">=</span> <span class="number">42</span><span class="special">)</span> +<span class="special">((</span><span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">),</span> <span class="special">{</span><span class="char">'foo'</span><span class="special">:</span> <span class="char">'bar'</span><span class="special">,</span> <span class="char">'baz'</span><span class="special">:</span> <span class="number">42</span><span class="special">})</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_ptr_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="function_documentation.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/function_invocation_and_creation/function_documentation.html b/libs/python/doc/html/reference/function_invocation_and_creation/function_documentation.html new file mode 100644 index 0000000000..772ac1b2ab --- /dev/null +++ b/libs/python/doc/html/reference/function_invocation_and_creation/function_documentation.html @@ -0,0 +1,458 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Function documentation</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> +<link rel="prev" href="boost_python_raw_function_hpp.html" title="boost/python/raw_function.hpp"> +<link rel="next" href="models_of_callpolicies.html" title="Models of CallPolicies"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_raw_function_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="models_of_callpolicies.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="function_invocation_and_creation.function_documentation"></a><a class="link" href="function_documentation.html" title="Function documentation">Function + documentation</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat">boost/python/function_doc_signature.hpp</a></span></dt> +<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp">boost/python/pytype_function.hpp</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.function_documentation.boost_python_function_doc_signat"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat" title="boost/python/function_doc_signature.hpp">boost/python/function_doc_signature.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.class_function_doc_signature_gen">Class + <code class="computeroutput"><span class="identifier">function_doc_signature_generator</span></code></a></span></dt> +<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.introduction"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.introduction" title="Introduction">Introduction</a> +</h4></div></div></div> +<p> + Boost.Python supports docstrings with automatic appending of Pythonic + and C++ signatures. This feature is implemented by class <code class="computeroutput"><span class="identifier">function_doc_signature_generator</span></code>. The + class uses all of the overloads, supplied arg names and default values, + as well as the user-defined docstrings, to generate documentation for + a given function. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.class_function_doc_signature_gen"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.class_function_doc_signature_gen" title="Class function_doc_signature_generator">Class + <code class="computeroutput"><span class="identifier">function_doc_signature_generator</span></code></a> +</h4></div></div></div> +<p> + The class has only one public function which returns a list of strings + documenting the overloads of a function. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">objects</span> <span class="special">{</span> + + <span class="keyword">class</span> <span class="identifier">function_doc_signature_generator</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="keyword">static</span> <span class="identifier">list</span> <span class="identifier">function_doc_signatures</span><span class="special">(</span><span class="identifier">function</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">f</span><span class="special">);</span> + <span class="special">};</span> + +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.example"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.example" title="Example">Example</a> +</h4></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">args</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">tuple</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">overloads</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">raw_function</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="identifier">tuple</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="number">4.25</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">z</span> <span class="special">=</span> <span class="string">"wow"</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">);</span> +<span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">f_overloads</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span> + + +<span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="identifier">tuple</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="number">4.25</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">z</span> <span class="special">=</span> <span class="string">"wow"</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">);</span> + <span class="special">}</span> +<span class="special">};</span> + +<span class="identifier">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">X_f_overloads</span><span class="special">,</span> <span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span> + +<span class="identifier">tuple</span> <span class="identifier">raw_func</span><span class="special">(</span><span class="identifier">tuple</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">dict</span> <span class="identifier">kw</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">args</span><span class="special">,</span> <span class="identifier">kw</span><span class="special">);</span> +<span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">args_ext</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="special">(</span><span class="identifier">arg</span><span class="special">(</span><span class="string">"x"</span><span class="special">)=</span><span class="number">1</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"y"</span><span class="special">)=</span><span class="number">4.25</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"z"</span><span class="special">)=</span><span class="string">"wow"</span><span class="special">)</span> + <span class="special">,</span> <span class="string">"This is f's docstring"</span> + <span class="special">);</span> + + <span class="identifier">def</span><span class="special">(</span><span class="string">"raw"</span><span class="special">,</span> <span class="identifier">raw_function</span><span class="special">(</span><span class="identifier">raw_func</span><span class="special">));</span> + + <span class="identifier">def</span><span class="special">(</span><span class="string">"f1"</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">f_overloads</span><span class="special">(</span><span class="string">"f1's docstring"</span><span class="special">,</span> <span class="identifier">args</span><span class="special">(</span><span class="string">"x"</span><span class="special">,</span> <span class="string">"y"</span><span class="special">,</span> <span class="string">"z"</span><span class="special">)));</span> + + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">X</span><span class="special">>(</span><span class="string">"X"</span><span class="special">,</span> <span class="string">"This is X's docstring"</span><span class="special">,</span> <span class="identifier">init</span><span class="special"><>(</span><span class="identifier">args</span><span class="special">(</span><span class="string">"self"</span><span class="special">)))</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span> + <span class="special">,</span> <span class="string">"This is X.f's docstring"</span> + <span class="special">,</span> <span class="identifier">args</span><span class="special">(</span><span class="string">"self"</span><span class="special">,</span><span class="string">"x"</span><span class="special">,</span> <span class="string">"y"</span><span class="special">,</span> <span class="string">"z"</span><span class="special">))</span> + + <span class="special">;</span> + +<span class="special">}</span> +</pre> +<p> + Python code: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="keyword">import</span> <span class="identifier">args_ext</span> +<span class="special">>>></span> <span class="identifier">help</span><span class="special">(</span><span class="identifier">args_ext</span><span class="special">)</span> +<span class="identifier">Help</span> <span class="identifier">on</span> <span class="identifier">module</span> <span class="identifier">args_ext</span><span class="special">:</span> + +<span class="identifier">NAME</span> + <span class="identifier">args_ext</span> + +<span class="identifier">FILE</span> + <span class="identifier">args_ext</span><span class="special">.</span><span class="identifier">pyd</span> + +<span class="identifier">CLASSES</span> + <span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span><span class="special">.</span><span class="identifier">instance</span><span class="special">(</span><span class="identifier">__builtin__</span><span class="special">.</span><span class="identifier">object</span><span class="special">)</span> + <span class="identifier">X</span> + + <span class="keyword">class</span> <span class="identifier">X</span><span class="special">(</span><span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span><span class="special">.</span><span class="identifier">instance</span><span class="special">)</span> + <span class="special">|</span> <span class="identifier">This</span> <span class="keyword">is</span> <span class="identifier">X</span><span class="string">'s docstring + | + | Method resolution order: + | X + | Boost.Python.instance + | __builtin__.object + | + | Methods defined here: + | + | __init__(...) + | __init__( (object)self) -> None : + | C++ signature: + | void __init__(struct _object *) + | + | f(...) + | f( (X)self, (int)x, (float)y, (str)z) -> tuple : This is X.f'</span><span class="identifier">s</span> <span class="identifier">docstring</span> + <span class="special">|</span> <span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span> + <span class="special">|</span> <span class="keyword">class</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">tuple</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">struct</span> <span class="identifier">X</span> <span class="special">{</span><span class="identifier">lvalue</span><span class="special">},</span><span class="identifier">int</span><span class="special">,</span><span class="identifier">double</span><span class="special">,</span><span class="identifier">char</span> <span class="identifier">const</span> <span class="special">*)</span> + <span class="special">|</span> + <span class="special">|</span> <span class="special">.................</span> + <span class="special">|</span> +<span class="identifier">FUNCTIONS</span> + <span class="identifier">f</span><span class="special">(...)</span> + <span class="identifier">f</span><span class="special">([</span> <span class="special">(</span><span class="identifier">int</span><span class="special">)</span><span class="identifier">x</span><span class="special">=</span><span class="number">1</span> <span class="special">[,</span> <span class="special">(</span><span class="identifier">float</span><span class="special">)</span><span class="identifier">y</span><span class="special">=</span><span class="number">4.25</span> <span class="special">[,</span> <span class="special">(</span><span class="identifier">str</span><span class="special">)</span><span class="identifier">z</span><span class="special">=</span><span class="string">'wow'</span><span class="special">]]])</span> <span class="special">-></span> <span class="identifier">tuple</span> <span class="special">:</span> <span class="identifier">This</span> <span class="keyword">is</span> <span class="identifier">f</span><span class="string">'s docstring + C++ signature: + class boost::python::tuple f([ int=1 [,double=4.25 [,char const *='</span><span class="identifier">wow</span><span class="string">']]]) + + f1(...) + f1([ (int)x [, (float)y [, (str)z]]]) -> tuple : f1'</span><span class="identifier">s</span> <span class="identifier">docstring</span> + <span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span> + <span class="keyword">class</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">tuple</span> <span class="identifier">f1</span><span class="special">([</span> <span class="identifier">int</span> <span class="special">[,</span><span class="identifier">double</span> <span class="special">[,</span><span class="identifier">char</span> <span class="identifier">const</span> <span class="special">*]]])</span> + + <span class="identifier">raw</span><span class="special">(...)</span> + <span class="identifier">object</span> <span class="identifier">raw</span><span class="special">(</span><span class="identifier">tuple</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">dict</span> <span class="identifier">kwds</span><span class="special">)</span> <span class="special">:</span> + <span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span> + <span class="identifier">object</span> <span class="identifier">raw</span><span class="special">(</span><span class="identifier">tuple</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">dict</span> <span class="identifier">kwds</span><span class="special">)</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp" title="boost/python/pytype_function.hpp">boost/python/pytype_function.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_wrap_pytype">Class + <code class="computeroutput"><span class="identifier">wrap_pytype</span></code></a></span></dt> +<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_registered_pytype">Class + <code class="computeroutput"><span class="identifier">registered_pytype</span></code></a></span></dt> +<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_expected_from_python_type">Class + <code class="computeroutput"><span class="identifier">expected_from_python_type</span></code></a></span></dt> +<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_to_python_target_type">Class + <code class="computeroutput"><span class="identifier">to_python_target_type</span></code></a></span></dt> +<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.introduction"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.introduction" title="Introduction">Introduction</a> +</h4></div></div></div> +<p> + To support Pythonic signatures the converters should supply a <code class="computeroutput"><span class="identifier">get_pytype</span></code> function returning a pointer + to the associated <code class="computeroutput"><span class="identifier">PyTypeObject</span></code>. + See for example <a class="link" href="../concepts/resultconverter.html" title="ResultConverter"><code class="computeroutput"><span class="identifier">ResultConverter</span></code></a> or <a class="link" href="../to_from_python_type_conversion/boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert.class_template_to_python_convert" title="Class template to_python_converter constructor"><code class="computeroutput"><span class="identifier">to_python_converter</span></code></a>. The classes + in this header file are meant to be used when implmenting <code class="computeroutput"><span class="identifier">get_pytype</span></code>. There are also <code class="computeroutput"><span class="identifier">_direct</span></code> versions of the templates of + <code class="computeroutput"><span class="keyword">class</span> <span class="identifier">T</span></code> + which should be used with undecorated type parameter, expected to be + in the conversion registry when the module loads. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_wrap_pytype"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_wrap_pytype" title="Class wrap_pytype">Class + <code class="computeroutput"><span class="identifier">wrap_pytype</span></code></a> +</h4></div></div></div> +<p> + This template generates a static <code class="computeroutput"><span class="identifier">get_pytype</span></code> + member returning the template parameter. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">converter</span><span class="special">{</span> + + <span class="keyword">template</span> <span class="special"><</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">pytype</span> <span class="special">></span> + <span class="keyword">class</span> <span class="identifier">wrap_pytype</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="keyword">static</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">get_pytype</span><span class="special">(){</span><span class="keyword">return</span> <span class="identifier">pytype</span><span class="special">;</span> <span class="special">}</span> + <span class="special">};</span> + +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_registered_pytype"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_registered_pytype" title="Class registered_pytype">Class + <code class="computeroutput"><span class="identifier">registered_pytype</span></code></a> +</h4></div></div></div> +<p> + This template should be used with template parameters which are (possibly + decorated) types exported to python using <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_<T, Bases, HeldType, NonCopyable>"><code class="computeroutput"><span class="identifier">class_</span></code></a>. The generated a static + <code class="computeroutput"><span class="identifier">get_pytype</span></code> member returns + the corresponding python type. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">converter</span><span class="special">{</span> + + <span class="keyword">template</span> <span class="special"><</span> <span class="keyword">class</span> <span class="identifier">T</span> <span class="special">></span> + <span class="keyword">class</span> <span class="identifier">registered_pytype</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="keyword">static</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">get_pytype</span><span class="special">();</span> + <span class="special">};</span> + +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_expected_from_python_type"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_expected_from_python_type" title="Class expected_from_python_type">Class + <code class="computeroutput"><span class="identifier">expected_from_python_type</span></code></a> +</h4></div></div></div> +<p> + This template generates a static <code class="computeroutput"><span class="identifier">get_pytype</span></code> + member which inspects the registered <code class="computeroutput"><span class="identifier">from_python</span></code> + converters for the type <code class="computeroutput"><span class="identifier">T</span></code> + and returns a matching python type. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">converter</span><span class="special">{</span> + + <span class="keyword">template</span> <span class="special"><</span> <span class="keyword">class</span> <span class="identifier">T</span> <span class="special">></span> + <span class="keyword">class</span> <span class="identifier">expected_from_python_type</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="keyword">static</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">get_pytype</span><span class="special">();</span> + <span class="special">};</span> + +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_to_python_target_type"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_to_python_target_type" title="Class to_python_target_type">Class + <code class="computeroutput"><span class="identifier">to_python_target_type</span></code></a> +</h4></div></div></div> +<p> + This template generates a static <code class="computeroutput"><span class="identifier">get_pytype</span></code> + member returning the python type to which <code class="computeroutput"><span class="identifier">T</span></code> + can be converted. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">converter</span><span class="special">{</span> + + <span class="keyword">template</span> <span class="special"><</span> <span class="keyword">class</span> <span class="identifier">T</span> <span class="special">></span> + <span class="keyword">class</span> <span class="identifier">to_python_target_type</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="keyword">static</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">get_pytype</span><span class="special">();</span> + <span class="special">};</span> + +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.example"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.example" title="Example">Example</a> +</h4></div></div></div> +<p> + This example presumes that someone has implemented the standard noddy + example module from the Python documentation, and placed the corresponding + declarations in "noddy.h". Because <code class="computeroutput"><span class="identifier">noddy_NoddyObject</span></code> + is the ultimate trivial extension type, the example is a bit contrived: + it wraps a function for which all information is contained in the type + of its return value. + </p> +<p> + C++ module definition: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">reference</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="string">"noddy.h"</span> + +<span class="keyword">struct</span> <span class="identifier">tag</span> <span class="special">{};</span> +<span class="identifier">tag</span> <span class="identifier">make_tag</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">tag</span><span class="special">();</span> <span class="special">}</span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="keyword">struct</span> <span class="identifier">tag_to_noddy</span> +<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//unnecessary overhead if py signatures are not supported</span> +<span class="special">:</span> <span class="identifier">wrap_pytype</span><span class="special"><&</span><span class="identifier">noddy_NoddyType</span><span class="special">></span> <span class="comment">//inherits get_pytype from wrap_pytype</span> +<span class="preprocessor">#endif</span> +<span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">convert</span><span class="special">(</span><span class="identifier">tag</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">PyObject_New</span><span class="special">(</span><span class="identifier">noddy_NoddyObject</span><span class="special">,</span> <span class="special">&</span><span class="identifier">noddy_NoddyType</span><span class="special">);</span> + <span class="special">}</span> +<span class="special">};</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">to_python_converter</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"make_tag"</span><span class="special">,</span> <span class="identifier">make_tag</span><span class="special">);</span> + <span class="identifier">to_python_converter</span><span class="special"><</span><span class="identifier">tag</span><span class="special">,</span> <span class="identifier">tag_to_noddy</span> +<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//invalid if py signatures are not supported</span> + <span class="special">,</span> <span class="keyword">true</span> +<span class="preprocessor">#endif</span> + <span class="special">>();</span> <span class="comment">//"true" because tag_to_noddy has member get_pytype</span> +<span class="special">}</span> +</pre> +<p> + The following example registers to and from python converters using the + templates expected_from_python_type and to_pyhton_target_type. + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">extract</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">to_python_converter</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="keyword">struct</span> <span class="identifier">A</span> +<span class="special">{</span> +<span class="special">};</span> + +<span class="keyword">struct</span> <span class="identifier">B</span> +<span class="special">{</span> + <span class="identifier">A</span> <span class="identifier">a</span><span class="special">;</span> + <span class="identifier">B</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&</span> <span class="identifier">a_</span><span class="special">):</span><span class="identifier">a</span><span class="special">(</span><span class="identifier">a_</span><span class="special">){}</span> +<span class="special">};</span> + +<span class="comment">// Converter from A to python int</span> +<span class="keyword">struct</span> <span class="identifier">BToPython</span> +<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//unnecessary overhead if py signatures are not supported</span> + <span class="special">:</span> <span class="identifier">converter</span><span class="special">::</span><span class="identifier">to_python_target_type</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span> <span class="comment">//inherits get_pytype</span> +<span class="preprocessor">#endif</span> +<span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">convert</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">B</span><span class="special">&</span> <span class="identifier">b</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">incref</span><span class="special">(</span><span class="identifier">object</span><span class="special">(</span><span class="identifier">b</span><span class="special">.</span><span class="identifier">a</span><span class="special">).</span><span class="identifier">ptr</span><span class="special">());</span> + <span class="special">}</span> +<span class="special">};</span> + +<span class="comment">// Conversion from python int to A</span> +<span class="keyword">struct</span> <span class="identifier">BFromPython</span> +<span class="special">{</span> + <span class="identifier">BFromPython</span><span class="special">()</span> + <span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">converter</span><span class="special">::</span><span class="identifier">registry</span><span class="special">::</span><span class="identifier">push_back</span> + <span class="special">(</span> <span class="special">&</span><span class="identifier">convertible</span> + <span class="special">,</span> <span class="special">&</span><span class="identifier">construct</span> + <span class="special">,</span> <span class="identifier">type_id</span><span class="special"><</span> <span class="identifier">B</span> <span class="special">>()</span> +<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//invalid if py signatures are not supported</span> + <span class="special">,</span> <span class="special">&</span><span class="identifier">converter</span><span class="special">::</span><span class="identifier">expected_from_python_type</span><span class="special"><</span><span class="identifier">A</span><span class="special">>::</span><span class="identifier">get_pytype</span><span class="comment">//convertible to A can be converted to B</span> +<span class="preprocessor">#endif</span> + <span class="special">);</span> + <span class="special">}</span> + + <span class="keyword">static</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">convertible</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">obj_ptr</span><span class="special">)</span> + <span class="special">{</span> + <span class="identifier">extract</span><span class="special"><</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&></span> <span class="identifier">ex</span><span class="special">(</span><span class="identifier">obj_ptr</span><span class="special">);</span> + <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">ex</span><span class="special">.</span><span class="identifier">check</span><span class="special">())</span> <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> + <span class="keyword">return</span> <span class="identifier">obj_ptr</span><span class="special">;</span> + <span class="special">}</span> + + <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">construct</span><span class="special">(</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">obj_ptr</span><span class="special">,</span> + <span class="identifier">converter</span><span class="special">::</span><span class="identifier">rvalue_from_python_stage1_data</span><span class="special">*</span> <span class="identifier">data</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">void</span><span class="special">*</span> <span class="identifier">storage</span> <span class="special">=</span> <span class="special">(</span> + <span class="special">(</span><span class="identifier">converter</span><span class="special">::</span><span class="identifier">rvalue_from_python_storage</span><span class="special"><</span> <span class="identifier">B</span> <span class="special">>*)</span><span class="identifier">data</span><span class="special">)-></span> <span class="identifier">storage</span><span class="special">.</span><span class="identifier">bytes</span><span class="special">;</span> + + <span class="identifier">extract</span><span class="special"><</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&></span> <span class="identifier">ex</span><span class="special">(</span><span class="identifier">obj_ptr</span><span class="special">);</span> + <span class="keyword">new</span> <span class="special">(</span><span class="identifier">storage</span><span class="special">)</span> <span class="identifier">B</span><span class="special">(</span><span class="identifier">ex</span><span class="special">());</span> + <span class="identifier">data</span><span class="special">-></span><span class="identifier">convertible</span> <span class="special">=</span> <span class="identifier">storage</span><span class="special">;</span> + <span class="special">}</span> +<span class="special">};</span> + + +<span class="identifier">B</span> <span class="identifier">func</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">B</span><span class="special">&</span> <span class="identifier">b</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">b</span> <span class="special">;</span> <span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">pytype_function_ext</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">to_python_converter</span><span class="special"><</span> <span class="identifier">B</span> <span class="special">,</span> <span class="identifier">BToPython</span> +<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//invalid if py signatures are not supported</span> + <span class="special">,</span><span class="keyword">true</span> +<span class="preprocessor">#endif</span> + <span class="special">>();</span> <span class="comment">//has get_pytype</span> + <span class="identifier">BFromPython</span><span class="special">();</span> + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">A</span><span class="special">>(</span><span class="string">"A"</span><span class="special">)</span> <span class="special">;</span> + + <span class="identifier">def</span><span class="special">(</span><span class="string">"func"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">func</span><span class="special">);</span> + +<span class="special">}</span> + + + +<span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">pytype_function_ext</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">func</span><span class="special">.</span><span class="identifier">__doc__</span> +<span class="identifier">func</span><span class="special">(</span> <span class="special">(</span><span class="identifier">A</span><span class="special">)</span><span class="identifier">arg1</span><span class="special">)</span> <span class="special">-></span> <span class="identifier">A</span> <span class="special">:</span> + <span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span> + <span class="keyword">struct</span> <span class="identifier">B</span> <span class="identifier">func</span><span class="special">(</span><span class="keyword">struct</span> <span class="identifier">B</span><span class="special">)</span> +</pre> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_raw_function_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="models_of_callpolicies.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/function_invocation_and_creation/models_of_callpolicies.html b/libs/python/doc/html/reference/function_invocation_and_creation/models_of_callpolicies.html new file mode 100644 index 0000000000..385e2c15e0 --- /dev/null +++ b/libs/python/doc/html/reference/function_invocation_and_creation/models_of_callpolicies.html @@ -0,0 +1,1098 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Models of CallPolicies</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> +<link rel="prev" href="function_documentation.html" title="Function documentation"> +<link rel="next" href="models_of_resultconverter.html" title="Models of ResultConverter"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="function_documentation.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="models_of_resultconverter.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="function_invocation_and_creation.models_of_callpolicies"></a><a class="link" href="models_of_callpolicies.html" title="Models of CallPolicies">Models + of CallPolicies</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici">boost/python/default_call_policies.hpp</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp">boost/python/return_arg.hpp</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref">boost/python/return_internal_reference.hpp</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy">boost/python/return_value_policy.hpp</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_">boost/python/with_custodian_and_ward.hpp</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici" title="boost/python/default_call_policies.hpp">boost/python/default_call_policies.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_call_policies">Class + <code class="computeroutput"><span class="identifier">default_call_policies</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_call_policies_stat">Class + <code class="computeroutput"><span class="identifier">default_call_policies</span></code> static + functions</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_result_converter">Class + <code class="computeroutput"><span class="identifier">default_result_converter</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_result_converter_m">Class + <code class="computeroutput"><span class="identifier">default_result_converter</span></code> + metafunctions</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_call_policies"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_call_policies" title="Class default_call_policies">Class + <code class="computeroutput"><span class="identifier">default_call_policies</span></code></a> +</h4></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">default_call_policies</span></code> + is a model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a> + with no <code class="computeroutput"><span class="identifier">precall</span></code> or <code class="computeroutput"><span class="identifier">postcall</span></code> behavior and a <code class="computeroutput"><span class="identifier">result_converter</span></code> which handles by-value + returns. Wrapped C++ functions and member functions <code class="computeroutput"><span class="identifier">use</span> + <span class="identifier">default_call_policies</span></code> unless + otherwise specified. You may find it convenient to derive new models + of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a> + from <code class="computeroutput"><span class="identifier">default_call_policies</span></code>. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">default_call_policies</span> + <span class="special">{</span> + <span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">precall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*);</span> + <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span> + <span class="keyword">typedef</span> <span class="identifier">default_result_converter</span> <span class="identifier">result_converter</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Sig</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">extract_return_type</span> <span class="special">:</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">front</span><span class="special"><</span><span class="identifier">Sig</span><span class="special">>{};</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_call_policies_stat"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_call_policies_stat" title="Class default_call_policies static functions">Class + <code class="computeroutput"><span class="identifier">default_call_policies</span></code> static + functions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">precall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + true + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + nothing + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + result + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + nothing + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_result_converter"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_result_converter" title="Class default_result_converter">Class + <code class="computeroutput"><span class="identifier">default_result_converter</span></code></a> +</h4></div></div></div> +<p> + default_result_converter is a model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements"><code class="computeroutput"><span class="identifier">ResultConverterGenerator</span></code></a> which + can be used to wrap C++ functions returning non-pointer types, <code class="computeroutput"><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span></code>, and <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code>, by-value. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">default_result_converter</span> + <span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_result_converter_m"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_result_converter_m" title="Class default_result_converter metafunctions">Class + <code class="computeroutput"><span class="identifier">default_result_converter</span></code> + metafunctions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + T is not a reference type. If T is a pointer type, T is const char* + or PyObject*. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + typedef to_python_value<T const&> type; + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.example"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.example" title="Example">Example</a> +</h4></div></div></div> +<p> + 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: + </p> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Handler</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">></span> +<span class="keyword">struct</span> <span class="identifier">return_value_policy</span> <span class="special">:</span> <span class="identifier">Base</span> +<span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">Handler</span> <span class="identifier">result_converter</span><span class="special">;</span> +<span class="special">};</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp" title="boost/python/return_arg.hpp">boost/python/return_arg.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_return_arg">Class + <code class="computeroutput"><span class="identifier">return_arg</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_return_arg_static_function">Class + <code class="computeroutput"><span class="identifier">return_arg</span></code> static functions</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_template_return_self">Class + template <code class="computeroutput"><span class="identifier">return_self</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.introduction"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.introduction" title="Introduction">Introduction</a> +</h4></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">return_arg</span></code> and <code class="computeroutput"><span class="identifier">return_self</span></code> instantiations are models + of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a> + which return the specified argument parameter (usually <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>) + of a wrapped (member) function. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_return_arg"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_return_arg" title="Class return_arg">Class + <code class="computeroutput"><span class="identifier">return_arg</span></code></a> +</h4></div></div></div> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Description + </p> + </th> +<th> + <p> + Default + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + arg_pos + </p> + </td> +<td> + <p> + A positive compile-time constant of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>. + </p> + </td> +<td> + <p> + the position of the argument to be returned. + </p> + </td> +<td> + <p> + 1 + </p> + </td> +</tr> +<tr> +<td> + <p> + Base + </p> + </td> +<td> + <p> + A model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a> + </p> + </td> +<td> + <p> + Used for policy composition. Any <code class="computeroutput"><span class="identifier">result_converter</span></code> + it supplies will be overridden by <code class="computeroutput"><span class="identifier">return_arg</span></code>, + but its <code class="computeroutput"><span class="identifier">precall</span></code> + and <code class="computeroutput"><span class="identifier">postcall</span></code> + policies are composed as described here <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>. + </p> + </td> +<td> + <p> + default_call_policies + </p> + </td> +</tr> +</tbody> +</table></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="identifier">size_t</span> <span class="identifier">arg_pos</span><span class="special">=</span><span class="number">1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">return_arg</span> <span class="special">:</span> <span class="identifier">Base</span> + <span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span> + <span class="keyword">struct</span> <span class="identifier">result_converter</span><span class="special">{</span> <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span><span class="special">;</span> <span class="special">};</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Sig</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">extract_return_type</span> <span class="special">:</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">at_c</span><span class="special"><</span><span class="identifier">Sig</span><span class="special">,</span> <span class="identifier">arg_pos</span><span class="special">>{};</span> + + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_return_arg_static_function"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_return_arg_static_function" title="Class return_arg static functions">Class + <code class="computeroutput"><span class="identifier">return_arg</span></code> static functions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">PyTuple_Check</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span> + <span class="special">!=</span> <span class="number">0</span></code> + and <code class="computeroutput"><span class="identifier">PyTuple_Size</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span> <span class="special">!=</span> <span class="number">0</span></code> + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + PyTuple_GetItem(args,arg_pos-1) + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_template_return_self"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_template_return_self" title="Class template return_self">Class + template <code class="computeroutput"><span class="identifier">return_self</span></code></a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">return_self</span> + <span class="special">:</span> <span class="identifier">return_arg</span><span class="special"><</span><span class="number">1</span><span class="special">,</span><span class="identifier">Base</span><span class="special">></span> + <span class="special">{};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.example"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.example" title="Example">Example</a> +</h4></div></div></div> +<p> + C++ module definition: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_arg</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">struct</span> <span class="identifier">Widget</span> +<span class="special">{</span> + <span class="identifier">Widget</span><span class="special">()</span> <span class="special">:</span><span class="identifier">sensitive_</span><span class="special">(</span><span class="keyword">true</span><span class="special">){}</span> + <span class="keyword">bool</span> <span class="identifier">get_sensitive</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">sensitive_</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">void</span> <span class="identifier">set_sensitive</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">s</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">this</span><span class="special">-></span><span class="identifier">sensitive_</span> <span class="special">=</span> <span class="identifier">s</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="keyword">bool</span> <span class="identifier">sensitive_</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">struct</span> <span class="identifier">Label</span> <span class="special">:</span> <span class="identifier">Widget</span> +<span class="special">{</span> + <span class="identifier">Label</span><span class="special">()</span> <span class="special">{}</span> + + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">get_label</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">label_</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">void</span> <span class="identifier">set_label</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&</span><span class="identifier">l</span><span class="special">){</span> <span class="identifier">label_</span> <span class="special">=</span> <span class="identifier">l</span><span class="special">;</span> <span class="special">}</span> + + <span class="keyword">private</span><span class="special">:</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">label_</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">return_self_ext</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">widget</span><span class="special">>(</span><span class="string">"Widget"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"sensitive"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Widget</span><span class="special">::</span><span class="identifier">get_sensitive</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"sensitive"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Widget</span><span class="special">::</span><span class="identifier">set_sensitive</span><span class="special">,</span> <span class="identifier">return_self</span><span class="special"><>())</span> + <span class="special">;</span> + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Label</span><span class="special">,</span> <span class="identifier">bases</span><span class="special"><</span><span class="identifier">Widget</span><span class="special">></span> <span class="special">>(</span><span class="string">"Label"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"label"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Label</span><span class="special">::</span><span class="identifier">get_label</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"label"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Label</span><span class="special">::</span><span class="identifier">set_label</span><span class="special">,</span> <span class="identifier">return_self</span><span class="special"><>())</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + Python code: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">return_self_ext</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="identifier">l1</span> <span class="special">=</span> <span class="identifier">Label</span><span class="special">().</span><span class="identifier">label</span><span class="special">(</span><span class="string">"foo"</span><span class="special">).</span><span class="identifier">sensitive</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span> +<span class="special">>>></span> <span class="identifier">l2</span> <span class="special">=</span> <span class="identifier">Label</span><span class="special">().</span><span class="identifier">sensitive</span><span class="special">(</span><span class="keyword">false</span><span class="special">).</span><span class="identifier">label</span><span class="special">(</span><span class="string">"foo"</span><span class="special">)</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref" title="boost/python/return_internal_reference.hpp">boost/python/return_internal_reference.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r">Class + template <code class="computeroutput"><span class="identifier">return_internal_reference</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_return_internal_reference_">Class + <code class="computeroutput"><span class="identifier">return_internal_reference</span></code> + static functions</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.introduction"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.introduction" title="Introduction">Introduction</a> +</h4></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">return_internal_reference</span></code> + instantiations are models of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a> which allow pointers + and references to objects held internally by a free or member function + argument or from the target of a member function to be returned safely + without making a copy of the referent. The default for its first template + argument handles the common case where the containing object is the target + (<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>) + of a wrapped member function. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r" title="Class template return_internal_reference">Class + template <code class="computeroutput"><span class="identifier">return_internal_reference</span></code></a> +</h4></div></div></div> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Description + </p> + </th> +<th> + <p> + Default + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + owner_arg + </p> + </td> +<td> + <p> + A positive compile-time constant of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>. + </p> + </td> +<td> + <p> + The index of the parameter which contains the object to which + the reference or pointer is being returned. If used to wrap + a member function, parameter 1 is the target object (<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>). + Note that if the target Python object type doesn't support + weak references, a Python TypeError exception will be raised + when the function being wrapped is called. + </p> + </td> +<td> + </td> +</tr> +<tr> +<td> + <p> + Base + </p> + </td> +<td> + <p> + A model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a> + </p> + </td> +<td> + <p> + Used for policy composition. Any <code class="computeroutput"><span class="identifier">result_converter</span></code> + it supplies will be overridden by <code class="computeroutput"><span class="identifier">return_internal_reference</span></code>, + but its <code class="computeroutput"><span class="identifier">precall</span></code> + and <code class="computeroutput"><span class="identifier">postcall</span></code> + policies are composed as described here <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>. + </p> + </td> +<td> + <p> + default_call_policies + </p> + </td> +</tr> +</tbody> +</table></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">owner_arg</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">return_internal_reference</span> <span class="special">:</span> <span class="identifier">Base</span> + <span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span> + <span class="keyword">typedef</span> <span class="identifier">reference_existing_object</span> <span class="identifier">result_converter</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_return_internal_reference_"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_return_internal_reference_" title="Class return_internal_reference static functions">Class + <code class="computeroutput"><span class="identifier">return_internal_reference</span></code> + static functions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">PyTuple_Check</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span> + <span class="special">!=</span> <span class="number">0</span></code> + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_st" title="Class with_custodian_and_ward static functions"><code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span><span class="special">::</span><span class="identifier">postcall</span><span class="special">(</span><span class="identifier">args</span><span class="special">,</span> <span class="identifier">result</span><span class="special">)</span></code></a> + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.example"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.example" title="Example">Example</a> +</h4></div></div></div> +<p> + C++ module definition: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_internal_reference</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">class</span> <span class="identifier">Bar</span> +<span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">Bar</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">x</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span> + <span class="keyword">int</span> <span class="identifier">get_x</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">void</span> <span class="identifier">set_x</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">this</span><span class="special">-></span><span class="identifier">x</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">class</span> <span class="identifier">Foo</span> +<span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">Foo</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">b</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span> + + <span class="comment">// Returns an internal reference</span> + <span class="identifier">Bar</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">get_bar</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">}</span> + + <span class="keyword">private</span><span class="special">:</span> + <span class="identifier">Bar</span> <span class="identifier">b</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">internal_refs</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Bar</span><span class="special">>(</span><span class="string">"Bar"</span><span class="special">,</span> <span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">>())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get_x"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Bar</span><span class="special">::</span><span class="identifier">get_x</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"set_x"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Bar</span><span class="special">::</span><span class="identifier">set_x</span><span class="special">)</span> + <span class="special">;</span> + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Foo</span><span class="special">>(</span><span class="string">"Foo"</span><span class="special">,</span> <span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">>())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get_bar"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">get_bar</span> + <span class="special">,</span> <span class="identifier">return_internal_reference</span><span class="special"><>())</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + Python code: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">internal_refs</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">Foo</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> +<span class="special">>>></span> <span class="identifier">b1</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">get_bar</span><span class="special">()</span> +<span class="special">>>></span> <span class="identifier">b2</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">get_bar</span><span class="special">()</span> +<span class="special">>>></span> <span class="identifier">b1</span><span class="special">.</span><span class="identifier">get_x</span><span class="special">()</span> +<span class="number">3</span> +<span class="special">>>></span> <span class="identifier">b2</span><span class="special">.</span><span class="identifier">get_x</span><span class="special">()</span> +<span class="number">3</span> +<span class="special">>>></span> <span class="identifier">b1</span><span class="special">.</span><span class="identifier">set_x</span><span class="special">(</span><span class="number">42</span><span class="special">)</span> +<span class="special">>>></span> <span class="identifier">b2</span><span class="special">.</span><span class="identifier">get_x</span><span class="special">()</span> +<span class="number">42</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy" title="boost/python/return_value_policy.hpp">boost/python/return_value_policy.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.class_template_return_value_poli">Class + template <code class="computeroutput"><span class="identifier">return_value_policy</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.introduction"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.introduction" title="Introduction">Introduction</a> +</h4></div></div></div> +<p> + return_value_policy instantiations are simply models of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a> which are composed + of a <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements"><code class="computeroutput"><span class="identifier">ResultConverterGenerator</span></code></a> and + optional <code class="computeroutput"><span class="identifier">Base</span></code> <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.class_template_return_value_poli"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.class_template_return_value_poli" title="Class template return_value_policy">Class + template <code class="computeroutput"><span class="identifier">return_value_policy</span></code></a> +</h4></div></div></div> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Default + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + ResultConverterGenerator + </p> + </td> +<td> + <p> + A model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements"><code class="computeroutput"><span class="identifier">ResultConverterGenerator</span></code></a> + </p> + </td> +<td> + </td> +</tr> +<tr> +<td> + <p> + Base + </p> + </td> +<td> + <p> + A model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a> + </p> + </td> +<td> + <p> + default_call_policies + </p> + </td> +</tr> +</tbody> +</table></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">ResultConverterGenerator</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">return_value_policy</span> <span class="special">:</span> <span class="identifier">Base</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">ResultConverterGenerator</span> <span class="identifier">result_converter</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.example"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.example" title="Example">Example</a> +</h4></div></div></div> +<p> + C++ module definition: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">copy_const_reference</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_value_policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="comment">// classes to wrap</span> +<span class="keyword">struct</span> <span class="identifier">Bar</span> <span class="special">{</span> <span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> + +<span class="keyword">struct</span> <span class="identifier">Foo</span> <span class="special">{</span> + <span class="identifier">Foo</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="special">{</span> <span class="identifier">b</span><span class="special">.</span><span class="identifier">x</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> + <span class="identifier">Bar</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">get_bar</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="identifier">Bar</span> <span class="identifier">b</span><span class="special">;</span> +<span class="special">};</span> + +<span class="comment">// Wrapper code</span> +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">my_module</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Bar</span><span class="special">>(</span><span class="string">"Bar"</span><span class="special">);</span> + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Foo</span><span class="special">>(</span><span class="string">"Foo"</span><span class="special">,</span> <span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">>())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get_bar"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">get_bar</span> + <span class="special">,</span> <span class="identifier">return_value_policy</span><span class="special"><</span><span class="identifier">copy_const_reference</span><span class="special">>())</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + Python code: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">my_module</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">Foo</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">create</span> <span class="identifier">a</span> <span class="identifier">Foo</span> <span class="identifier">object</span> +<span class="special">>>></span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">get_bar</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">make</span> <span class="identifier">a</span> <span class="identifier">copy</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">internal</span> <span class="identifier">Bar</span> <span class="identifier">object</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_" title="boost/python/with_custodian_and_ward.hpp">boost/python/with_custodian_and_ward.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward">Class + <code class="computeroutput"><span class="identifier">with_custodian_and_ward</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_st">Class + <code class="computeroutput"><span class="identifier">with_custodian_and_ward</span></code> + static functions</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_po">Class + <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_p0">Class + <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code> + static functions</a></span></dt> +<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.introduction"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.introduction" title="Introduction">Introduction</a> +</h4></div></div></div> +<p> + This header provides facilities for establishing a lifetime dependency + between two of a function's Python argument or result objects. The ward + object will not be destroyed until after the custodian as long as the + custodian object supports <a href="http://www.python.org/doc/current/lib/module-weakref.html" target="_top">weak + references</a> (Boost.Python extension classes all support weak references). + If the custodian object does not support weak references and is not + <code class="computeroutput"><span class="identifier">None</span></code>, an appropriate + exception will be thrown. The two class templates <code class="computeroutput"><span class="identifier">with_custodian_and_ward</span></code> + and <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code> + differ in the point at which they take effect. + </p> +<p> + In order to reduce the chance of inadvertently creating dangling pointers, + the default is to do lifetime binding before the underlying C++ object + is invoked. However, before invocation the result object is not available, + so <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code> + is provided to bind lifetimes after invocation. Also, if a C++ exception + is thrown after <code class="computeroutput"><span class="identifier">with_custodian_and_ward</span><span class="special"><>::</span><span class="identifier">precall</span></code> + but before the underlying C++ object actually stores a pointer, the lifetime + of the custodian and ward objects will be artificially bound together, + so one might choose <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code> + instead, depending on the semantics of the function being wrapped. + </p> +<p> + Please note that this is not the appropriate tool to use when wrapping + functions which transfer ownership of a raw pointer across the function-call + boundary. Please see the FAQ if you want to do that. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward" title="Class with_custodian_and_ward">Class + <code class="computeroutput"><span class="identifier">with_custodian_and_ward</span></code></a> +</h4></div></div></div> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Description + </p> + </th> +<th> + <p> + Default + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + custodian + </p> + </td> +<td> + <p> + A positive compile-time constant of <code class="computeroutput"><span class="identifier">type</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>. + </p> + </td> +<td> + <p> + The 1-based index of the parameter which is the dependency + in the lifetime relationship to be established. If used to + wrap a member function, parameter 1 is the target object (<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>). + Note that if the target Python object type doesn't support + weak references, a Python TypeError exception will be raised + when the C++ object being wrapped is called. + </p> + </td> +<td> + </td> +</tr> +<tr> +<td> + <p> + ward + </p> + </td> +<td> + <p> + A positive compile-time constant of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>. + </p> + </td> +<td> + <p> + The 1-based index of the parameter which is the dependent in + the lifetime relationship to be established. If used to wrap + a member function, parameter 1 is the target object (<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>). + </p> + </td> +<td> + </td> +</tr> +<tr> +<td> + <p> + Base + </p> + </td> +<td> + <p> + A model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a> + </p> + </td> +<td> + <p> + Used for policy <a class="link" href="../concepts.html#concepts.callpolicies.callpolicies_composition" title="CallPolicies Composition">composition</a>. + </p> + </td> +<td> + <p> + default_call_policies + </p> + </td> +</tr> +</tbody> +</table></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">custodian</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">ward</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">with_custodian_and_ward</span> <span class="special">:</span> <span class="identifier">Base</span> + <span class="special">{</span> + <span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">precall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}</span></pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_st"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_st" title="Class with_custodian_and_ward static functions">Class + <code class="computeroutput"><span class="identifier">with_custodian_and_ward</span></code> + static functions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">precall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">PyTuple_Check</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span> + <span class="special">!=</span> <span class="number">0</span></code> + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Makes the lifetime of the argument indicated by ward dependent + on the lifetime of the argument indicated by custodian. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + false and PyErr_Occurred() != 0 upon failure, true otherwise. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_po"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_po" title="Class with_custodian_and_ward_postcall">Class + <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code></a> +</h4></div></div></div> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Description + </p> + </th> +<th> + <p> + Default + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + custodian + </p> + </td> +<td> + <p> + A positive compile-time constant of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>. + </p> + </td> +<td> + <p> + The index of the parameter which is the dependency in the lifetime + relationship to be established. Zero indicates the result object; + 1 indicates the first argument. If used to wrap a member function, + parameter 1 is the target object (<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>). Note that if the target + Python object type doesn't support weak references, a Python + TypeError exception will be raised when the C++ object being + wrapped is called. + </p> + </td> +<td> + </td> +</tr> +<tr> +<td> + <p> + ward + </p> + </td> +<td> + <p> + A positive compile-time constant of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>. + </p> + </td> +<td> + <p> + The index of the parameter which is the dependent in the lifetime + relationship to be established. Zero indicates the result object; + 1 indicates the first argument. If used to wrap a member function, + parameter 1 is the target object (<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>). + </p> + </td> +<td> + </td> +</tr> +<tr> +<td> + <p> + Base + </p> + </td> +<td> + <p> + A model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a> + </p> + </td> +<td> + <p> + Used for policy <a class="link" href="../concepts.html#concepts.callpolicies.callpolicies_composition" title="CallPolicies Composition">composition</a>. + </p> + </td> +<td> + <p> + default_call_policies + </p> + </td> +</tr> +</tbody> +</table></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">custodian</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">ward</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">with_custodian_and_ward_postcall</span> <span class="special">:</span> <span class="identifier">Base</span> + <span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_p0"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_p0" title="Class with_custodian_and_ward_postcall static functions">Class + <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code> + static functions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="identifier">PyObject</span> <span class="special">*</span><span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">PyTuple_Check</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span> + <span class="special">!=</span> <span class="number">0</span></code>, + <code class="computeroutput"><span class="identifier">result</span> <span class="special">!=</span> + <span class="number">0</span></code> + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Makes the lifetime of the object indicated by ward dependent on + the lifetime of the object indicated by custodian. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="number">0</span></code> and <code class="computeroutput"><span class="identifier">PyErr_Occurred</span><span class="special">()</span> + <span class="special">!=</span> <span class="number">0</span></code> + upon failure, <code class="computeroutput"><span class="keyword">true</span></code> + otherwise. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.example"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.example" title="Example">Example</a> +</h4></div></div></div> +<p> + The following example shows how <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code> + is used by the library to implement <code class="computeroutput"><span class="identifier">return_internal_reference</span></code> + </p> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">owner_arg</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">></span> +<span class="keyword">struct</span> <span class="identifier">return_internal_reference</span> + <span class="special">:</span> <span class="identifier">with_custodian_and_ward_postcall</span><span class="special"><</span><span class="number">0</span><span class="special">,</span> <span class="identifier">owner_arg</span><span class="special">,</span> <span class="identifier">Base</span><span class="special">></span> +<span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">reference_existing_object</span> <span class="identifier">result_converter</span><span class="special">;</span> +<span class="special">};</span> +</pre> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="function_documentation.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="models_of_resultconverter.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/function_invocation_and_creation/models_of_resultconverter.html b/libs/python/doc/html/reference/function_invocation_and_creation/models_of_resultconverter.html new file mode 100644 index 0000000000..d5a96bce97 --- /dev/null +++ b/libs/python/doc/html/reference/function_invocation_and_creation/models_of_resultconverter.html @@ -0,0 +1,308 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Models of ResultConverter</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> +<link rel="prev" href="models_of_callpolicies.html" title="Models of CallPolicies"> +<link rel="next" href="models_of_resultconvertergenerat.html" title="Models of ResultConverterGenerator"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="models_of_callpolicies.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="models_of_resultconvertergenerat.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="function_invocation_and_creation.models_of_resultconverter"></a><a class="link" href="models_of_resultconverter.html" title="Models of ResultConverter">Models + of ResultConverter</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_">boost/python/to_python_indirect.hpp</a></span></dt> +<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp">boost/python/to_python_value.hpp</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_" title="boost/python/to_python_indirect.hpp">boost/python/to_python_indirect.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction" title="Introduction">Introduction</a> +</h4></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect">Class + <code class="computeroutput"><span class="identifier">to_python_indirect</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect_observe">Class + <code class="computeroutput"><span class="identifier">to_python_indirect</span></code> observers</a></span></dt> +<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect_statics">Class + <code class="computeroutput"><span class="identifier">to_python_indirect</span></code> statics</a></span></dt> +</dl></div> +<pre class="programlisting"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">to_python_indirect</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> <span class="identifier">supplies</span> <span class="identifier">a</span> <span class="identifier">way</span> <span class="identifier">to</span> <span class="identifier">construct</span> <span class="keyword">new</span> <span class="identifier">Python</span> <span class="identifier">objects</span> <span class="identifier">that</span> <span class="identifier">hold</span> <span class="identifier">wrapped</span> <span class="identifier">C</span><span class="special">++</span> <span class="keyword">class</span> <span class="identifier">instances</span> <span class="identifier">via</span> <span class="identifier">a</span> <span class="identifier">pointer</span> <span class="keyword">or</span> <span class="identifier">smart</span> <span class="identifier">pointer</span><span class="special">.</span> +<span class="special">[</span><span class="identifier">endsect</span><span class="special">]</span> +</pre> +<div class="section"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect" title="Class to_python_indirect">Class + <code class="computeroutput"><span class="identifier">to_python_indirect</span></code></a> +</h5></div></div></div> +<p> + Class template <code class="computeroutput"><span class="identifier">to_python_indirect</span></code> + converts objects of its first argument type to python as extension + class instances, using the ownership policy provided by its 2nd argument. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Description + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + T + </p> + </td> +<td> + <p> + Either <code class="computeroutput"><span class="identifier">U</span> <span class="identifier">cv</span><span class="special">&</span></code> + (where cv is any optional cv-qualification) or a <a class="link" href="../concepts/dereferenceable.html" title="Dereferenceable">Dereferenceable</a> + type such that <code class="computeroutput"><span class="special">*</span><span class="identifier">x</span></code> is convertible to <code class="computeroutput"><span class="identifier">U</span> <span class="keyword">const</span><span class="special">&</span></code>, where <code class="computeroutput"><span class="identifier">U</span></code> is a class type. + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">A</span></code> type deferencing + a C++ class exposed to Python using class template <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_<T, Bases, HeldType, NonCopyable>"><code class="computeroutput"><span class="identifier">class_</span></code></a>. + </p> + </td> +</tr> +<tr> +<td> + <p> + MakeHolder + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">h</span> <span class="special">=</span> + <span class="identifier">MakeHolder</span><span class="special">::</span><span class="identifier">execute</span><span class="special">(</span><span class="identifier">p</span><span class="special">);</span></code> + </p> + </td> +<td> + <p> + A class whose static <code class="computeroutput"><span class="identifier">execute</span><span class="special">()</span></code> creates an <code class="computeroutput"><span class="identifier">instance_holder</span></code>. + </p> + </td> +</tr> +</tbody> +</table></div> +<p> + Instantiations of to_python_indirect are models of <a class="link" href="../concepts/resultconverter.html" title="ResultConverter"><code class="computeroutput"><span class="identifier">ResultConverter</span></code></a>. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">MakeHolder</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">to_python_indirect</span> + <span class="special">{</span> + <span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">convertible</span><span class="special">();</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">T</span> <span class="identifier">ptr_or_reference</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="keyword">static</span> <span class="identifier">PyTypeObject</span><span class="special">*</span> <span class="identifier">type</span><span class="special">();</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect_observe"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect_observe" title="Class to_python_indirect observers">Class + <code class="computeroutput"><span class="identifier">to_python_indirect</span></code> observers</a> +</h5></div></div></div> +<pre class="programlisting"><span class="identifier">PyObject</span><span class="special">*</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">x</span></code> refers to an + object (if it is a pointer type, it is non-null). <code class="computeroutput"><span class="identifier">convertible</span><span class="special">()</span> + <span class="special">==</span> <span class="keyword">true</span></code>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Creates an appropriately-typed Boost.Python extension class instance, + uses MakeHolder to create an instance_holder from x, installs + the instance_holder in the new extension class instance, and + returns a pointer to it. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect_statics"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.introduction.class_to_python_indirect_statics" title="Class to_python_indirect statics">Class + <code class="computeroutput"><span class="identifier">to_python_indirect</span></code> statics</a> +</h5></div></div></div> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">convertible</span><span class="special">()</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Returns true iff any module has registered a Python type corresponding + to U. + </p></dd> +</dl> +</div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.example"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_.example" title="Example">Example</a> +</h4></div></div></div> +<p> + This example replicates the functionality of <a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object" title="Class reference_existing_object"><code class="computeroutput"><span class="identifier">reference_existing_object</span></code></a>, but + without some of the compile-time error checking. + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">make_reference_holder</span> +<span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">objects</span><span class="special">::</span><span class="identifier">instance_holder</span><span class="special">*</span> <span class="identifier">result_type</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">static</span> <span class="identifier">result_type</span> <span class="identifier">execute</span><span class="special">(</span><span class="identifier">T</span><span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">return</span> <span class="keyword">new</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">objects</span><span class="special">::</span><span class="identifier">pointer_holder</span><span class="special"><</span><span class="identifier">T</span><span class="special">*,</span> <span class="identifier">T</span><span class="special">>(</span><span class="identifier">p</span><span class="special">);</span> + <span class="special">}</span> +<span class="special">};</span> + +<span class="keyword">struct</span> <span class="identifier">reference_existing_object</span> +<span class="special">{</span> + <span class="comment">// metafunction returning the ResultConverter</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">apply</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">to_python_indirect</span><span class="special"><</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">make_reference_holder</span><span class="special">></span> <span class="identifier">type</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">};</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp" title="boost/python/to_python_value.hpp">boost/python/to_python_value.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.class_template_to_python_value">Class + template <code class="computeroutput"><span class="identifier">to_python_value</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.class_to_python_value_observers">Class + <code class="computeroutput"><span class="identifier">to_python_value</span></code> observers</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.introduction"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.introduction" title="Introduction">Introduction</a> +</h4></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">to_python_value</span></code> is a + model of <a class="link" href="../concepts/resultconverter.html" title="ResultConverter">ResultConverter</a> + which copies its argument into a new Python object. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.class_template_to_python_value"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.class_template_to_python_value" title="Class template to_python_value">Class + template <code class="computeroutput"><span class="identifier">to_python_value</span></code></a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">to_python_value</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">add_reference</span><span class="special"><</span> + <span class="keyword">typename</span> <span class="identifier">add_const</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">type</span> + <span class="special">>::</span><span class="identifier">type</span> <span class="identifier">argument_type</span><span class="special">;</span> + + <span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">convertible</span><span class="special">();</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">argument_type</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.class_to_python_value_observers"></a><a class="link" href="models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp.class_to_python_value_observers" title="Class to_python_value observers">Class + <code class="computeroutput"><span class="identifier">to_python_value</span></code> observers</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">convertible</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="keyword">true</span></code> iff a converter + has been registered which can convert <code class="computeroutput"><span class="identifier">T</span></code> + to python by-value. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">PyObject</span><span class="special">*</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">argument_type</span> <span class="identifier">x</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">convertible</span><span class="special">()</span> + <span class="special">==</span> <span class="keyword">true</span></code> + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + converts <code class="computeroutput"><span class="identifier">x</span></code> to python + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + the resulting Python object iff a converter for <code class="computeroutput"><span class="identifier">T</span></code> + has been registered, <code class="computeroutput"><span class="number">0</span></code> + otherwise. + </p></dd> +</dl> +</div> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="models_of_callpolicies.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="models_of_resultconvertergenerat.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/function_invocation_and_creation/models_of_resultconvertergenerat.html b/libs/python/doc/html/reference/function_invocation_and_creation/models_of_resultconvertergenerat.html new file mode 100644 index 0000000000..622c61ac37 --- /dev/null +++ b/libs/python/doc/html/reference/function_invocation_and_creation/models_of_resultconvertergenerat.html @@ -0,0 +1,683 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Models of ResultConverterGenerator</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> +<link rel="prev" href="models_of_resultconverter.html" title="Models of ResultConverter"> +<link rel="next" href="../to_from_python_type_conversion.html" title="Chapter 5. To/From Python Type Conversion"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="models_of_resultconverter.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../to_from_python_type_conversion.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat"></a><a class="link" href="models_of_resultconvertergenerat.html" title="Models of ResultConverterGenerator">Models + of ResultConverterGenerator</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc">boost/python/copy_const_reference.hpp</a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe">boost/python/copy_non_const_reference.hpp</a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h">boost/python/manage_new_object.hpp</a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_">boost/python/reference_existing_object.hpp</a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp">boost/python/return_by_value.hpp</a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point">boost/python/return_opaque_pointer.hpp</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc" title="boost/python/copy_const_reference.hpp">boost/python/copy_const_reference.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.class_copy_const_reference">Class + <code class="computeroutput"><span class="identifier">copy_const_reference</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.class_copy_const_reference_metaf">Class + <code class="computeroutput"><span class="identifier">copy_const_reference</span></code> metafunctions</a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.class_copy_const_reference"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.class_copy_const_reference" title="Class copy_const_reference">Class + <code class="computeroutput"><span class="identifier">copy_const_reference</span></code></a> +</h4></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">copy_const_reference</span></code> + is a model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements">ResultConverterGenerator</a> + 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. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">copy_const_reference</span> + <span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.class_copy_const_reference_metaf"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.class_copy_const_reference_metaf" title="Class copy_const_reference metafunctions">Class + <code class="computeroutput"><span class="identifier">copy_const_reference</span></code> metafunctions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">T</span></code> is <code class="computeroutput"><span class="identifier">U</span> <span class="keyword">const</span><span class="special">&</span></code> for some <code class="computeroutput"><span class="identifier">U</span></code>. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="keyword">typedef</span> <span class="identifier">to_python_value</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">type</span><span class="special">;</span></code> + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.example"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc.example" title="Example">Example</a> +</h4></div></div></div> +<p> + C++ module definition: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">copy_const_reference</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_value_policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="comment">// classes to wrap</span> +<span class="keyword">struct</span> <span class="identifier">Bar</span> <span class="special">{</span> <span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> + +<span class="keyword">struct</span> <span class="identifier">Foo</span> <span class="special">{</span> + <span class="identifier">Foo</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="special">{</span> <span class="identifier">b</span><span class="special">.</span><span class="identifier">x</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> + <span class="identifier">Bar</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">get_bar</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="identifier">Bar</span> <span class="identifier">b</span><span class="special">;</span> +<span class="special">};</span> + +<span class="comment">// Wrapper code</span> +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">my_module</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Bar</span><span class="special">>(</span><span class="string">"Bar"</span><span class="special">);</span> + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Foo</span><span class="special">>(</span><span class="string">"Foo"</span><span class="special">,</span> <span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">>())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get_bar"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">get_bar</span> + <span class="special">,</span> <span class="identifier">return_value_policy</span><span class="special"><</span><span class="identifier">copy_const_reference</span><span class="special">>())</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + Python code: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">my_module</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">Foo</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">create</span> <span class="identifier">a</span> <span class="identifier">Foo</span> <span class="identifier">object</span> +<span class="special">>>></span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">get_bar</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">make</span> <span class="identifier">a</span> <span class="identifier">copy</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">internal</span> <span class="identifier">Bar</span> <span class="identifier">object</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe" title="boost/python/copy_non_const_reference.hpp">boost/python/copy_non_const_reference.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.class_copy_non_const_reference">Class + <code class="computeroutput"><span class="identifier">copy_non_const_reference</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.class_copy_non_const_reference_m">Class + <code class="computeroutput"><span class="identifier">copy_non_const_reference</span></code> + metafunctions</a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.class_copy_non_const_reference"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.class_copy_non_const_reference" title="Class copy_non_const_reference">Class + <code class="computeroutput"><span class="identifier">copy_non_const_reference</span></code></a> +</h4></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">copy_non_const_reference</span></code> + is a model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements">ResultConverterGenerator</a> + 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. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">copy_non_const_reference</span> + <span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.class_copy_non_const_reference_m"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.class_copy_non_const_reference_m" title="Class copy_non_const_reference metafunctions">Class + <code class="computeroutput"><span class="identifier">copy_non_const_reference</span></code> + metafunctions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">T</span></code> is <code class="computeroutput"><span class="identifier">U</span> <span class="special">&</span></code> + for some non-const <code class="computeroutput"><span class="identifier">U</span></code>. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="keyword">typedef</span> <span class="identifier">to_python_value</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">type</span></code>; + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.example"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe.example" title="Example">Example</a> +</h4></div></div></div> +<p> + C++ module definition: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">copy_non_const_reference</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_value_policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="comment">// classes to wrap</span> +<span class="keyword">struct</span> <span class="identifier">Bar</span> <span class="special">{</span> <span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> + +<span class="keyword">struct</span> <span class="identifier">Foo</span> <span class="special">{</span> + <span class="identifier">Foo</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="special">{</span> <span class="identifier">b</span><span class="special">.</span><span class="identifier">x</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> + <span class="identifier">Bar</span><span class="special">&</span> <span class="identifier">get_bar</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="identifier">Bar</span> <span class="identifier">b</span><span class="special">;</span> +<span class="special">};</span> + +<span class="comment">// Wrapper code</span> +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">my_module</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Bar</span><span class="special">>(</span><span class="string">"Bar"</span><span class="special">);</span> + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Foo</span><span class="special">>(</span><span class="string">"Foo"</span><span class="special">,</span> <span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">>())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get_bar"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">get_bar</span> + <span class="special">,</span> <span class="identifier">return_value_policy</span><span class="special"><</span><span class="identifier">copy_non_const_reference</span><span class="special">>())</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + Python code: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">my_module</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">Foo</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">create</span> <span class="identifier">a</span> <span class="identifier">Foo</span> <span class="identifier">object</span> +<span class="special">>>></span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">get_bar</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">make</span> <span class="identifier">a</span> <span class="identifier">copy</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">internal</span> <span class="identifier">Bar</span> <span class="identifier">object</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h" title="boost/python/manage_new_object.hpp">boost/python/manage_new_object.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.class_manage_new_object">Class + <code class="computeroutput"><span class="identifier">manage_new_object</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.class_manage_new_object_metafunc">Class + <code class="computeroutput"><span class="identifier">manage_new_object</span></code> metafunctions</a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.class_manage_new_object"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.class_manage_new_object" title="Class manage_new_object">Class + <code class="computeroutput"><span class="identifier">manage_new_object</span></code></a> +</h4></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">manage_new_object</span></code> is + a model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements">ResultConverterGenerator</a> + which can be used to wrap C++ functions which return a pointer to an + object allocated with a new-expression, and expect the caller to take + responsibility for deleting that object. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">manage_new_object</span> + <span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.class_manage_new_object_metafunc"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.class_manage_new_object_metafunc" title="Class manage_new_object metafunctions">Class + <code class="computeroutput"><span class="identifier">manage_new_object</span></code> metafunctions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">T</span></code> is <code class="computeroutput"><span class="identifier">U</span><span class="special">*</span></code> + for some <code class="computeroutput"><span class="identifier">U</span></code>. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="keyword">typedef</span> <span class="identifier">to_python_indirect</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">type</span><span class="special">;</span></code> + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.example"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h.example" title="Example">Example</a> +</h4></div></div></div> +<p> + In C++: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">manage_new_object</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_value_policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + + +<span class="keyword">struct</span> <span class="identifier">Foo</span> <span class="special">{</span> + <span class="identifier">Foo</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">x</span><span class="special">(</span><span class="identifier">x</span><span class="special">){}</span> + <span class="keyword">int</span> <span class="identifier">get_x</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span> +<span class="special">};</span> + +<span class="identifier">Foo</span><span class="special">*</span> <span class="identifier">make_foo</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">new</span> <span class="identifier">Foo</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span> <span class="special">}</span> + +<span class="comment">// Wrapper code</span> +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">my_module</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"make_foo"</span><span class="special">,</span> <span class="identifier">make_foo</span><span class="special">,</span> <span class="identifier">return_value_policy</span><span class="special"><</span><span class="identifier">manage_new_object</span><span class="special">>())</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Foo</span><span class="special">>(</span><span class="string">"Foo"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get_x"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">get_x</span><span class="special">)</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + Python code: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">my_module</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">make_foo</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">create</span> <span class="identifier">a</span> <span class="identifier">Foo</span> <span class="identifier">object</span> +<span class="special">>>></span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">get_x</span><span class="special">()</span> +<span class="number">3</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_" title="boost/python/reference_existing_object.hpp">boost/python/reference_existing_object.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object">Class + <code class="computeroutput"><span class="identifier">reference_existing_object</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object_">Class + <code class="computeroutput"><span class="identifier">reference_existing_object</span></code> + metafunctions</a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object" title="Class reference_existing_object">Class + <code class="computeroutput"><span class="identifier">reference_existing_object</span></code></a> +</h4></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">reference_existing_object</span></code> + is a model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements">ResultConverterGenerator</a> + which can be used to wrap C++ functions which return a reference or pointer + to a C++ object. When the wrapped function is called, the value referenced + by its return value is not copied. A new Python object is created which + contains a pointer to the referent, and no attempt is made to ensure + that the lifetime of the referent is at least as long as that of the + corresponding Python object. Thus, it can be <span class="bold"><strong>highly + dangerous</strong></span> to use <code class="computeroutput"><span class="identifier">reference_existing_object</span></code> + without additional lifetime management from such models of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a> + as <a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward" title="Class with_custodian_and_ward"><code class="computeroutput"><span class="identifier">with_custodian_and_ward</span></code></a>. This + class is used in the implementation of <a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r" title="Class template return_internal_reference"><code class="computeroutput"><span class="identifier">return_internal_reference</span></code></a>. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">reference_existing_object</span> + <span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object_"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object_" title="Class reference_existing_object metafunctions">Class + <code class="computeroutput"><span class="identifier">reference_existing_object</span></code> + metafunctions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">T</span></code> is <code class="computeroutput"><span class="identifier">U</span><span class="special">&</span></code> + or <code class="computeroutput"><span class="identifier">U</span><span class="special">*</span></code> + for some <code class="computeroutput"><span class="identifier">U</span></code>. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="keyword">typedef</span> <span class="identifier">to_python_indirect</span><span class="special"><</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">V</span><span class="special">></span> <span class="identifier">type</span><span class="special">;</span></code>, where V is a class whose static + execute function constructs an instance holder containing an unowned + <code class="computeroutput"><span class="identifier">U</span><span class="special">*</span></code> + pointing to the referent of the wrapped function's return value. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.example"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.example" title="Example">Example</a> +</h4></div></div></div> +<p> + In C++: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">reference_existing_object</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_value_policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">utility</span><span class="special">></span> + +<span class="comment">// classes to wrap</span> +<span class="keyword">struct</span> <span class="identifier">Singleton</span> +<span class="special">{</span> + <span class="identifier">Singleton</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">x</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">{}</span> + + <span class="keyword">int</span> <span class="identifier">exchange</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">n</span><span class="special">)</span> <span class="comment">// set x and return the old value</span> + <span class="special">{</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">swap</span><span class="special">(</span><span class="identifier">n</span><span class="special">,</span> <span class="identifier">x</span><span class="special">);</span> + <span class="keyword">return</span> <span class="identifier">n</span><span class="special">;</span> + <span class="special">}</span> + + <span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span> +<span class="special">};</span> + +<span class="identifier">Singleton</span><span class="special">&</span> <span class="identifier">get_it</span><span class="special">()</span> +<span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">Singleton</span> <span class="identifier">just_one</span><span class="special">;</span> + <span class="keyword">return</span> <span class="identifier">just_one</span><span class="special">;</span> +<span class="special">}</span> + +<span class="comment">// Wrapper code</span> +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">singleton</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"get_it"</span><span class="special">,</span> <span class="identifier">get_it</span><span class="special">,</span> + <span class="identifier">return_value_policy</span><span class="special"><</span><span class="identifier">reference_existing_object</span><span class="special">>());</span> + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Singleton</span><span class="special">>(</span><span class="string">"Singleton"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"exchange"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Singleton</span><span class="special">::</span><span class="identifier">exchange</span><span class="special">)</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + Python code: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">import</span> <span class="identifier">singleton</span> +<span class="special">>>></span> <span class="identifier">s1</span> <span class="special">=</span> <span class="identifier">singleton</span><span class="special">.</span><span class="identifier">get_it</span><span class="special">()</span> +<span class="special">>>></span> <span class="identifier">s2</span> <span class="special">=</span> <span class="identifier">singleton</span><span class="special">.</span><span class="identifier">get_it</span><span class="special">()</span> +<span class="special">>>></span> <span class="identifier">id</span><span class="special">(</span><span class="identifier">s1</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">id</span><span class="special">(</span><span class="identifier">s2</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">s1</span> <span class="keyword">and</span> <span class="identifier">s2</span> <span class="identifier">are</span> <span class="keyword">not</span> <span class="identifier">the</span> <span class="identifier">same</span> <span class="identifier">object</span> +<span class="number">0</span> +<span class="special">>>></span> <span class="identifier">s1</span><span class="special">.</span><span class="identifier">exchange</span><span class="special">(</span><span class="number">42</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">but</span> <span class="identifier">they</span> <span class="identifier">reference</span> <span class="identifier">the</span> <span class="identifier">same</span> <span class="identifier">C</span><span class="special">++</span> <span class="identifier">Singleton</span> +<span class="number">0</span> +<span class="special">>>></span> <span class="identifier">s2</span><span class="special">.</span><span class="identifier">exchange</span><span class="special">(</span><span class="number">99</span><span class="special">)</span> +<span class="number">42</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp" title="boost/python/return_by_value.hpp">boost/python/return_by_value.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.class_return_by_value">Class + <code class="computeroutput"><span class="identifier">return_by_value</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.class_return_by_value_metafuncti">Class + <code class="computeroutput"><span class="identifier">return_by_value</span></code> metafunctions</a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.class_return_by_value"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.class_return_by_value" title="Class return_by_value">Class + <code class="computeroutput"><span class="identifier">return_by_value</span></code></a> +</h4></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">return_by_value</span></code> is a + model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements">ResultConverterGenerator</a> + which can be used to wrap C++ functions returning any reference or value + type such that the return value is copied into a new Python object. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">return_by_value</span> + <span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.class_return_by_value_metafuncti"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.class_return_by_value_metafuncti" title="Class return_by_value metafunctions">Class + <code class="computeroutput"><span class="identifier">return_by_value</span></code> metafunctions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="keyword">typedef</span> <span class="identifier">to_python_value</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">type</span><span class="special">;</span></code> + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.example"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp.example" title="Example">Example</a> +</h4></div></div></div> +<p> + In C++: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_by_value</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_value_policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="comment">// classes to wrap</span> +<span class="keyword">struct</span> <span class="identifier">Bar</span> <span class="special">{</span> <span class="special">};</span> + +<span class="identifier">Bar</span> <span class="identifier">global_bar</span><span class="special">;</span> + +<span class="comment">// functions to wrap:</span> +<span class="identifier">Bar</span> <span class="identifier">b1</span><span class="special">();</span> +<span class="identifier">Bar</span><span class="special">&</span> <span class="identifier">b2</span><span class="special">();</span> +<span class="identifier">Bar</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">b3</span><span class="special">();</span> + +<span class="comment">// Wrapper code</span> +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">def_void_function</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">R</span> <span class="special">(*</span><span class="identifier">f</span><span class="special">)())</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">return_value_policy</span><span class="special"><</span><span class="identifier">return_by_value</span><span class="special">>());</span> +<span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">my_module</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Bar</span><span class="special">>(</span><span class="string">"Bar"</span><span class="special">);</span> + <span class="identifier">def_void_function</span><span class="special">(</span><span class="string">"b1"</span><span class="special">,</span> <span class="identifier">b1</span><span class="special">);</span> + <span class="identifier">def_void_function</span><span class="special">(</span><span class="string">"b2"</span><span class="special">,</span> <span class="identifier">b2</span><span class="special">);</span> + <span class="identifier">def_void_function</span><span class="special">(</span><span class="string">"b3"</span><span class="special">,</span> <span class="identifier">b3</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + Python code: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">my_module</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">b1</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">each</span> <span class="identifier">of</span> <span class="identifier">these</span> <span class="identifier">calls</span> +<span class="special">>>></span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">b2</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">creates</span> <span class="identifier">a</span> <span class="identifier">brand</span> +<span class="special">>>></span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">b3</span><span class="special">()</span> <span class="special">#</span> <span class="keyword">new</span> <span class="identifier">Bar</span> <span class="identifier">object</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point" title="boost/python/return_opaque_pointer.hpp">boost/python/return_opaque_pointer.hpp</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.class_return_opaqe_pointer">Class + <code class="computeroutput"><span class="identifier">return_opaqe_pointer</span></code></a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.class_return_opaque_pointer_meta">Class + <code class="computeroutput"><span class="identifier">return_opaque_pointer</span></code> metafunctions</a></span></dt> +<dt><span class="section"><a href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.class_return_opaqe_pointer"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.class_return_opaqe_pointer" title="Class return_opaqe_pointer">Class + <code class="computeroutput"><span class="identifier">return_opaqe_pointer</span></code></a> +</h4></div></div></div> +<p> + return_opaque_pointer is a model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements">ResultConverterGenerator</a> + which can be used to wrap C++ functions returning pointers to undefined + types such that the return value is copied into a new Python object. + </p> +<p> + In addition to specifying the <code class="computeroutput"><span class="identifier">return_opaque_pointer</span></code> + policy the <a class="link" href="../to_from_python_type_conversion/boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.macro_boost_python_opaque_specia" title="Macro BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID(Pointee)"><code class="computeroutput"><span class="identifier">BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</span></code></a> + macro must be used to define specializations for the <a class="link" href="../utility_and_infrastructure/boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.functions" title="Functions"><code class="computeroutput"><span class="identifier">type_id</span></code></a> function on the type + pointed to by returned pointer. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">return_opaque_pointer</span> + <span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.class_return_opaque_pointer_meta"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.class_return_opaque_pointer_meta" title="Class return_opaque_pointer metafunctions">Class + <code class="computeroutput"><span class="identifier">return_opaque_pointer</span></code> metafunctions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">apply</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">detail</span><span class="special">::</span><span class="identifier">opaque_conversion_holder</span><span class="special"><</span><span class="identifier">R</span><span class="special">></span> + <span class="identifier">type</span><span class="special">;</span></code> + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.example"></a><a class="link" href="models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point.example" title="Example">Example</a> +</h4></div></div></div> +<p> + In C++: + </p> +<pre class="programlisting"><span class="preprocessor"># include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_opaque_pointer</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor"># include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor"># include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor"># include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_value_policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">typedef</span> <span class="keyword">struct</span> <span class="identifier">opaque_</span> <span class="special">*</span><span class="identifier">opaque</span><span class="special">;</span> + +<span class="identifier">opaque</span> <span class="identifier">the_op</span> <span class="special">=</span> <span class="special">((</span><span class="identifier">opaque</span><span class="special">)</span> <span class="number">0x47110815</span><span class="special">);</span> + +<span class="identifier">opaque</span> <span class="identifier">get</span> <span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">the_op</span><span class="special">;</span> <span class="special">}</span> +<span class="keyword">void</span> <span class="identifier">use</span> <span class="special">(</span><span class="identifier">opaque</span> <span class="identifier">op</span><span class="special">)</span> <span class="special">{</span> + <span class="keyword">if</span> <span class="special">(</span><span class="identifier">op</span> <span class="special">!=</span> <span class="identifier">the_op</span><span class="special">)</span> + <span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">(</span><span class="string">"failed"</span><span class="special">));</span> +<span class="special">}</span> + +<span class="keyword">void</span> <span class="identifier">failuse</span> <span class="special">(</span><span class="identifier">opaque</span> <span class="identifier">op</span><span class="special">)</span> <span class="special">{</span> + <span class="keyword">if</span> <span class="special">(</span><span class="identifier">op</span> <span class="special">==</span> <span class="identifier">the_op</span><span class="special">)</span> + <span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">(</span><span class="string">"success"</span><span class="special">));</span> +<span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</span><span class="special">(</span><span class="identifier">opaque_</span><span class="special">)</span> + +<span class="keyword">namespace</span> <span class="identifier">bpl</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">opaque_ext</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">bpl</span><span class="special">::</span><span class="identifier">def</span> <span class="special">(</span> + <span class="string">"get"</span><span class="special">,</span> <span class="special">&::</span><span class="identifier">get</span><span class="special">,</span> <span class="identifier">bpl</span><span class="special">::</span><span class="identifier">return_value_policy</span><span class="special"><</span><span class="identifier">bpl</span><span class="special">::</span><span class="identifier">return_opaque_pointer</span><span class="special">>());</span> + <span class="identifier">bpl</span><span class="special">::</span><span class="identifier">def</span> <span class="special">(</span><span class="string">"use"</span><span class="special">,</span> <span class="special">&::</span><span class="identifier">use</span><span class="special">);</span> + <span class="identifier">bpl</span><span class="special">::</span><span class="identifier">def</span> <span class="special">(</span><span class="string">"failuse"</span><span class="special">,</span> <span class="special">&::</span><span class="identifier">failuse</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + Python code: + </p> +<pre class="programlisting"><span class="string">""</span><span class="string">" +>>> from opaque_ext import * +>>> # +>>> # Check for correct conversion +>>> use(get()) +>>> failuse(get()) +Traceback (most recent call last): + ... +RuntimeError: success +>>> # +>>> # Check that there is no conversion from integers ... +>>> use(0) +Traceback (most recent call last): + ... +TypeError: bad argument type for built-in operation +>>> # +>>> # ... and from strings to opaque objects +>>> use("</span><span class="string">") +Traceback (most recent call last): + ... +TypeError: bad argument type for built-in operation +"</span><span class="string">""</span> +<span class="identifier">def</span> <span class="identifier">run</span><span class="special">(</span><span class="identifier">args</span> <span class="special">=</span> <span class="identifier">None</span><span class="special">):</span> + <span class="identifier">import</span> <span class="identifier">sys</span> + <span class="identifier">import</span> <span class="identifier">doctest</span> + + <span class="keyword">if</span> <span class="identifier">args</span> <span class="identifier">is</span> <span class="keyword">not</span> <span class="identifier">None</span><span class="special">:</span> + <span class="identifier">sys</span><span class="special">.</span><span class="identifier">argv</span> <span class="special">=</span> <span class="identifier">args</span> + <span class="keyword">return</span> <span class="identifier">doctest</span><span class="special">.</span><span class="identifier">testmod</span><span class="special">(</span><span class="identifier">sys</span><span class="special">.</span><span class="identifier">modules</span><span class="special">.</span><span class="identifier">get</span><span class="special">(</span><span class="identifier">__name__</span><span class="special">))</span> + +<span class="keyword">if</span> <span class="identifier">__name__</span> <span class="special">==</span> <span class="char">'__main__'</span><span class="special">:</span> + <span class="identifier">print</span> <span class="string">"running..."</span> + <span class="identifier">import</span> <span class="identifier">sys</span> + <span class="identifier">sys</span><span class="special">.</span><span class="identifier">exit</span><span class="special">(</span><span class="identifier">run</span><span class="special">()[</span><span class="number">0</span><span class="special">])</span> +</pre> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="models_of_resultconverter.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../to_from_python_type_conversion.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/glossary.html b/libs/python/doc/html/reference/glossary.html new file mode 100644 index 0000000000..d58a7967e2 --- /dev/null +++ b/libs/python/doc/html/reference/glossary.html @@ -0,0 +1,80 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 9. Glossary</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="index.html" title="Boost.Python Reference Manual"> +<link rel="prev" href="topics/indexing_support.html" title="Indexing support"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="topics/indexing_support.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="glossary"></a>Chapter 9. Glossary</h1></div></div></div> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">arity <a name="arity"></a></span></dt> +<dd><p> + The number of argumnts accepted by a function or member function. Unless + otherwise specified, the hidden <code class="computeroutput"><span class="keyword">this</span></code> + argument to member functions is not counted when specifying arity. + </p></dd> +<dt><span class="term">ntbs <a name="ntbs"></a></span></dt> +<dd><p> + Null-Terminated Byte String, or 'C'-string. C++ string literals are + <span class="bold"><strong>ntbs</strong></span>es. An <span class="bold"><strong>ntbs</strong></span> + must never be null. + </p></dd> +<dt><span class="term">raise <a name="raise"></a></span></dt> +<dd><p> + Exceptions in Python are "raised", not "thrown", + as they are in C++. When this documentation says that some Python exception + is "raised" in the context of C++ code, it means that the corresponding + Python exception is set via the <a href="http://www.python.org/doc/current/api/exceptionHandling.html" target="_top">Python/'C' + API</a>, and <code class="computeroutput"><span class="identifier">throw_error_already_set</span><span class="special">()</span></code> is called. + </p></dd> +<dt><span class="term">POD <a name="pod"></a></span></dt> +<dd><p> + A technical term from the C++ standard. Short for "Plain Ol'Data": + A POD-struct is an aggregate class that has no non-static data members + of type pointer to member, non-POD-struct, non-POD-union (or array of + such types) or reference, and has no user-defined copy assign- ment operator + and no user-defined destructor. Similarly, a POD-union is an aggregate + union that has no non-static data members of type pointer to member, + non-POD-struct, non-POD-union (or array of such types) or reference, + and has no user-defined copy assignment operator and no user-defined + destructor. A POD class is a class that is either a POD-struct or a POD-union. + An aggregate is an array or a class (clause 9) with no user-declared + constructors (12.1), no private or protected non-static data members + (clause 11), no base classes (clause 10), and no virtual functions (10.3). + </p></dd> +<dt><span class="term">ODR <a name="odr"></a></span></dt> +<dd><p> + The "One Definition Rule", which says that any entity in a + C++ program must have the same definition in all translation units (object + files) which make up a program. + </p></dd> +</dl> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="topics/indexing_support.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components.html b/libs/python/doc/html/reference/high_level_components.html new file mode 100644 index 0000000000..f73397b38e --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components.html @@ -0,0 +1,1090 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 2. High Level Components</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="index.html" title="Boost.Python Reference Manual"> +<link rel="prev" href="concepts/objectwrapper.html" title="ObjectWrapper"> +<link rel="next" href="high_level_components/boost_python_def_hpp.html" title="boost/python/def.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="concepts/objectwrapper.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="high_level_components/boost_python_def_hpp.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="high_level_components"></a>Chapter 2. High Level Components</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp">boost/python/class.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel">Class + template <code class="computeroutput"><span class="identifier">class_</span><span class="special"><</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">Bases</span><span class="special">,</span> <span class="identifier">HeldType</span><span class="special">,</span> <span class="identifier">NonCopyable</span><span class="special">></span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_bases_t1_t2_tn">Class + template bases<T1, T2, ...TN></a></span></dt> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.examples">Examples</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_def_hpp.html">boost/python/def.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_def_visitor_hpp.html">boost/python/def_visitor.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.class_def_visitor">Class + <code class="computeroutput"><span class="identifier">def_visitor</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html">boost/python/docstring_options.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options">Class + <code class="computeroutput"><span class="identifier">docstring_options</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_dostring_options_construct">Class + dostring_options constructors</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options_destruct">Class + docstring_options destructor</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options_modifier">Class + <code class="computeroutput"><span class="identifier">docstring_options</span></code> modifier + functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_enum_hpp.html">boost/python/enum.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum">Class + template <code class="computeroutput"><span class="identifier">enum_</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum_constructors">Class + template <code class="computeroutput"><span class="identifier">enum_</span></code> constructors</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum_modifier_fun">Class + template <code class="computeroutput"><span class="identifier">enum_</span></code> modifier functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_errors_hpp.html">boost/python/errors.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set">Class + <code class="computeroutput"><span class="identifier">error_already_set</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_exception_translato.html">boost/python/exception_translator.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.function_register_exception_tran">Function + <code class="computeroutput"><span class="identifier">register_exception_translator</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_init_hpp.html">boost/python/init.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init">Class + template <code class="computeroutput"><span class="identifier">init</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_optional">Class + template <code class="computeroutput"><span class="identifier">optional</span></code> </a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html">boost/python/iterator.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterator">Class + template <code class="computeroutput"><span class="identifier">iterator</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterator_construc">Class + template iterator constructors</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators">Class + template <code class="computeroutput"><span class="identifier">iterators</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators_nested_">Class + template iterators nested types</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators_static_">Class + template iterators static functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_module_hpp.html">boost/python/module.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.macros">Macros</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.examples">Examples</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html">boost/python/operators.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t">Class + <code class="computeroutput"><span class="identifier">self_ns</span><span class="special">::</span><span class="identifier">self_t</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_template_other">Class + template <code class="computeroutput"><span class="identifier">other</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_template_detail_operator">Class + template <code class="computeroutput"><span class="identifier">detail</span><span class="special">::</span><span class="identifier">operator_</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.object_self">Object + <code class="computeroutput"><span class="identifier">self</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_scope_hpp.html">boost/python/scope.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.class_scope">Class + <code class="computeroutput"><span class="identifier">scope</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.class_scope_constructors_and_des">Class + scope constructors and destructor</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html">boost/python/stl_iterator.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterato">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat0">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code> + constructors</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat1">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code> + modifiers</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat2">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code> + observers</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html">boost/python/wrapper.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_override">Class + <code class="computeroutput"><span class="identifier">override</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_override_observer_function">Class + <code class="computeroutput"><span class="identifier">override</span></code> observer functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper">Class + template <code class="computeroutput"><span class="identifier">wrapper</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper_observer_">Class + template <code class="computeroutput"><span class="identifier">wrapper</span></code> observer + functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.example">Example</a></span></dt> +</dl></dd> +</dl> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_class_hpp"></a><a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp" title="boost/python/class.hpp">boost/python/class.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel">Class + template <code class="computeroutput"><span class="identifier">class_</span><span class="special"><</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">Bases</span><span class="special">,</span> <span class="identifier">HeldType</span><span class="special">,</span> <span class="identifier">NonCopyable</span><span class="special">></span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_bases_t1_t2_tn">Class + template bases<T1, T2, ...TN></a></span></dt> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.examples">Examples</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_class_hpp.introduction"></a><a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code> + defines the interface through which users expose their C++ classes to Python. + It declares the <code class="computeroutput"><span class="identifier">class_</span></code> + class template, which is parameterized on the class type being exposed. + It also exposes the <code class="computeroutput"><span class="identifier">init</span></code>, + <code class="computeroutput"><span class="identifier">optional</span></code> and <code class="computeroutput"><span class="identifier">bases</span></code> utility class templates, which + are used in conjunction with <code class="computeroutput"><span class="identifier">class_</span></code>. + </p> +<p> + <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">class_fwd</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code> contains a forward declaration of the + <code class="computeroutput"><span class="identifier">class_</span></code> class template. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel"></a><a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_<T, Bases, HeldType, NonCopyable>">Class + template <code class="computeroutput"><span class="identifier">class_</span><span class="special"><</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">Bases</span><span class="special">,</span> <span class="identifier">HeldType</span><span class="special">,</span> <span class="identifier">NonCopyable</span><span class="special">></span></code></a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.heldtype_semantics">HeldType + Semantics</a></span></dt> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_synopsis">Class + template <code class="computeroutput"><span class="identifier">class_</span></code> synopsis</a></span></dt> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_constructor">Class + template <code class="computeroutput"><span class="identifier">class_</span></code> constructors</a></span></dt> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu">Class + template <code class="computeroutput"><span class="identifier">class_</span></code> modifier + functions</a></span></dt> +</dl></div> +<p> + Creates a Python class associated with the C++ type passed as its first + parameter. Although it has four template parameters, only the first one + is required. The three optional arguments can actually be supplied <span class="bold"><strong>in any order</strong></span>; Boost.Python determines the role of + the argument from its type. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Template Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Semantics + </p> + </th> +<th> + <p> + Default + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">T</span></code> + </p> + </td> +<td> + <p> + A class type. + </p> + </td> +<td> + <p> + The class being wrapped + </p> + </td> +<td> + </td> +</tr> +<tr> +<td> + <p> + Bases + </p> + </td> +<td> + <p> + A specialization of <a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_bases_t1_t2_tn" title="Class template bases<T1, T2, ...TN>">bases<...></a> + which specifies previously-exposed C++ base classes of <code class="computeroutput"><span class="identifier">T</span></code>. + </p> + </td> +<td> + <p> + Registers <code class="computeroutput"><span class="identifier">from_python</span></code> + conversions from wrapped <code class="computeroutput"><span class="identifier">T</span></code> + instances to each of its exposed direct and indirect bases. For + each polymorphic base <code class="computeroutput"><span class="identifier">B</span></code>, + registers conversions from indirectly-held wrapped <code class="computeroutput"><span class="identifier">B</span></code> instances to <code class="computeroutput"><span class="identifier">T</span></code>. + </p> + </td> +<td> + <p> + <a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_bases_t1_t2_tn" title="Class template bases<T1, T2, ...TN>">bases<></a> + </p> + </td> +</tr> +<tr> +<td> + <p> + HeldType + </p> + </td> +<td> + <p> + Must be <code class="computeroutput"><span class="identifier">T</span></code>, a + class derived from <code class="computeroutput"><span class="identifier">T</span></code>, + or a <a class="link" href="concepts/dereferenceable.html#concepts.dereferenceable.concept_requirements" title="Concept Requirements">Dereferenceable</a> + type for which <code class="computeroutput"><span class="identifier">pointee</span><span class="special"><</span><span class="identifier">HeldType</span><span class="special">>::</span><span class="identifier">type</span></code> + is <code class="computeroutput"><span class="identifier">T</span></code> or a class + derived from <code class="computeroutput"><span class="identifier">T</span></code>. + </p> + </td> +<td> + <p> + Specifies the type that is actually embedded in a Python object + wrapping a <code class="computeroutput"><span class="identifier">T</span></code> + instance when <code class="computeroutput"><span class="identifier">T</span></code>'s + constructor is called or when a <code class="computeroutput"><span class="identifier">T</span></code> + or <code class="computeroutput"><span class="identifier">T</span><span class="special">*</span></code> + is converted to Python without the use of <a class="link" href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.functions" title="Functions">ptr</a>, + <code class="computeroutput"><span class="identifier">ref</span></code>, or <a class="link" href="concepts.html#concepts.callpolicies" title="CallPolicies">Call Policies</a> such as + <a class="link" href="function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r" title="Class template return_internal_reference">return_internal_reference</a>. + More details below. + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">T</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + NonCopyable + </p> + </td> +<td> + <p> + If supplied, must be <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">noncopyable</span></code>. + </p> + </td> +<td> + <p> + Suppresses automatic registration of <code class="computeroutput"><span class="identifier">to_python</span></code> + conversions which copy <code class="computeroutput"><span class="identifier">T</span></code> + instances. Required when <code class="computeroutput"><span class="identifier">T</span></code> + has no publicly-accessible copy constructor. + </p> + </td> +<td> + <p> + An unspecified type other than boost::noncopyable. + </p> + </td> +</tr> +</tbody> +</table></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.heldtype_semantics"></a><a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.heldtype_semantics" title="HeldType Semantics">HeldType + Semantics</a> +</h4></div></div></div> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + If HeldType is derived from <code class="computeroutput"><span class="identifier">T</span></code>, + its exposed constructor(s) must accept an initial <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code> argument which refers back to the + Python object that contains the HeldType instance, as shown in this + example. This argument is not included in the <a class="link" href="high_level_components/boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction.init_expressions" title="init-expressions">init-expression</a> + passed to <a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu" title="Class template class_ modifier functions">def(init_expr)</a>, + below, nor is it passed explicitly by users when Python instances + of <code class="computeroutput"><span class="identifier">T</span></code> are created. + This idiom allows C++ virtual functions which will be overridden + in Python to access the Python object so the Python method can be + invoked. Boost.Python automatically registers additional converters + which allow wrapped instances of <code class="computeroutput"><span class="identifier">T</span></code> + to be passed to wrapped C++ functions expecting HeldType arguments. + </li> +<li class="listitem"> + Because Boost.Python will always allow wrapped instances of <code class="computeroutput"><span class="identifier">T</span></code> to be passed in place of HeldType + arguments, specifying a smart pointer for HeldType allows users to + pass Python <code class="computeroutput"><span class="identifier">T</span></code> instances + where a smart pointer-to-T is expected. Smart pointers such as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">auto_ptr</span><span class="special"><></span></code> + or <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special"><></span></code> + which contain a nested type <code class="computeroutput"><span class="identifier">element_type</span></code> + designating the referent type are automatically supported; additional + smart pointer types can be supported by specializing <code class="computeroutput"><span class="identifier">pointee</span><span class="special"><</span><span class="identifier">HeldType</span><span class="special">></span></code>. + </li> +<li class="listitem"> + As in case 1 above, when HeldType is a smart pointer to a class derived + from <code class="computeroutput"><span class="identifier">T</span></code>, the initial + <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code> + argument must be supplied by all of HeldType's exposed constructors. + </li> +<li class="listitem"> + Except in cases 1 and 3, users may optionally specify that T itself + gets initialized with a similar initial <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code> argument by specializing <a class="link" href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_.class_template_has_back_referenc" title="Class template has_back_reference">has_back_reference<T></a>. + </li> +</ol></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_synopsis"></a><a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_synopsis" title="Class template class_ synopsis">Class + template <code class="computeroutput"><span class="identifier">class_</span></code> synopsis</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span> + <span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Bases</span> <span class="special">=</span> <span class="identifier">bases</span><span class="special"><></span> + <span class="special">,</span> <span class="keyword">class</span> <span class="identifier">HeldType</span> <span class="special">=</span> <span class="identifier">T</span> + <span class="special">,</span> <span class="keyword">class</span> <span class="identifier">NonCopyable</span> <span class="special">=</span> <span class="identifier">unspecified</span> + <span class="special">></span> +<span class="keyword">class</span> <span class="identifier">class_</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object</span> +<span class="special">{</span> + <span class="comment">// Constructors with default __init__</span> + <span class="identifier">class_</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">);</span> + <span class="identifier">class_</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">docstring</span><span class="special">);</span> + + <span class="comment">// Constructors, specifying non-default __init__</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Init</span><span class="special">></span> + <span class="identifier">class_</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Init</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Init</span><span class="special">></span> + <span class="identifier">class_</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">docstring</span><span class="special">,</span> <span class="identifier">Init</span><span class="special">);</span> + + <span class="comment">// Exposing additional __init__ functions</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Init</span><span class="special">></span> + <span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def</span><span class="special">(</span><span class="identifier">Init</span><span class="special">);</span> + + <span class="comment">// defining methods</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> + <span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> + <span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> + <span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">A2</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A3</span><span class="special">></span> + <span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">A2</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">A3</span> <span class="keyword">const</span><span class="special">&);</span> + + <span class="comment">// declaring method as static</span> + <span class="identifier">class_</span><span class="special">&</span> <span class="identifier">staticmethod</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">);</span> + + <span class="comment">// exposing operators</span> + <span class="keyword">template</span> <span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> + <span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def</span><span class="special">(</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">>);</span> + + <span class="comment">// Raw attribute modification</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> + <span class="identifier">class_</span><span class="special">&</span> <span class="identifier">setattr</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">U</span> <span class="keyword">const</span><span class="special">&);</span> + + <span class="comment">// exposing data members</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> + <span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def_readonly</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">D</span> <span class="identifier">T</span><span class="special">::*</span><span class="identifier">pm</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> + <span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def_readwrite</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">D</span> <span class="identifier">T</span><span class="special">::*</span><span class="identifier">pm</span><span class="special">);</span> + + <span class="comment">// exposing static data members</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> + <span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def_readonly</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">D</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">d</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> + <span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def_readwrite</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">D</span><span class="special">&</span> <span class="identifier">d</span><span class="special">);</span> + + <span class="comment">// property creation</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Get</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">add_property</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Get</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fget</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span><span class="special">=</span><span class="number">0</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Get</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Set</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">add_property</span><span class="special">(</span> + <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Get</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fget</span><span class="special">,</span> <span class="identifier">Set</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fset</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span><span class="special">=</span><span class="number">0</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Get</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">add_static_property</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Get</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fget</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Get</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Set</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">add_static_property</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Get</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fget</span><span class="special">,</span> <span class="identifier">Set</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fset</span><span class="special">);</span> + + <span class="comment">// pickle support</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">PickleSuite</span><span class="special">></span> + <span class="identifier">self</span><span class="special">&</span> <span class="identifier">def_pickle</span><span class="special">(</span><span class="identifier">PickleSuite</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="identifier">self</span><span class="special">&</span> <span class="identifier">enable_pickling</span><span class="special">();</span> +<span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_constructor"></a><a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_constructor" title="Class template class_ constructors">Class + template <code class="computeroutput"><span class="identifier">class_</span></code> constructors</a> +</h4></div></div></div> +<pre class="programlisting"><span class="identifier">class_</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">);</span> +<span class="identifier">class_</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">docstring</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Init</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Init</span> <span class="identifier">init_spec</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Init</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">docstring</span><span class="special">,</span> <span class="identifier">Init</span> <span class="identifier">init_spec</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + name is an <a class="link" href="glossary.html#ntbs">ntbs</a> which conforms to Python's + <a href="http://www.python.org/doc/current/ref/identifiers.html" target="_top">identifier + naming rules</a>. If docstring is supplied, it must be an + <a class="link" href="glossary.html#ntbs">ntbs</a>. If <code class="computeroutput"><span class="identifier">init_spec</span></code> + is supplied, it must be either the special enumeration constant + <code class="computeroutput"><span class="identifier">no_init</span></code> or an + <a class="link" href="high_level_components/boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction.init_expressions" title="init-expressions">init-expression</a> + compatible with <code class="computeroutput"><span class="identifier">T</span></code>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd> +<p> + Constructs a <code class="computeroutput"><span class="identifier">class_</span></code> + object holding a Boost.Python extension class named name. The named + attribute of the <a class="link" href="high_level_components/boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.introduction" title="Introduction">current + scope</a> is bound to the new extension class. + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + If supplied, the value of docstring is bound to the <code class="computeroutput"><span class="identifier">__doc__</span></code> attribute of the + extension class. + </li> +<li class="listitem"> + If <code class="computeroutput"><span class="identifier">init_spec</span></code> + is <code class="computeroutput"><span class="identifier">no_init</span></code>, + a special <code class="computeroutput"><span class="identifier">__init__</span></code> + function is generated which always raises a Python exception. + Otherwise, <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">def</span><span class="special">(</span><span class="identifier">init_spec</span><span class="special">)</span></code> is called. + </li> +<li class="listitem"> + If <code class="computeroutput"><span class="identifier">init_spec</span></code> + is not supplied, <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">def</span><span class="special">(</span><span class="identifier">init</span><span class="special"><>())</span></code> is called. + </li> +</ul></div> +</dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Allowing the user to specify constructor arguments in the <code class="computeroutput"><span class="identifier">class_</span><span class="special"><></span></code> + constructor helps her to avoid the common run-time errors which + result from invoking wrapped member functions without having exposed + an <code class="computeroutput"><span class="identifier">__init__</span></code> function + which creates the requisite <code class="computeroutput"><span class="identifier">T</span></code> + instance. Types which are not default-constructible will cause + a compile-time error unless <code class="computeroutput"><span class="identifier">Init</span></code> + is supplied. The user must always supply name as there is currently + no portable method to derive the text of the class name from its + type. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu"></a><a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu" title="Class template class_ modifier functions">Class + template <code class="computeroutput"><span class="identifier">class_</span></code> modifier + functions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Init</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def</span><span class="special">(</span><span class="identifier">Init</span> <span class="identifier">init_expr</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">init_expr</span></code> is the + result of an <a class="link" href="high_level_components/boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction.init_expressions" title="init-expressions">init-expression</a> + compatible with <code class="computeroutput"><span class="identifier">T</span></code>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + For each <a class="link" href="high_level_components/boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction.init_expressions" title="init-expressions">valid + prefix</a> <code class="computeroutput"><span class="identifier">P</span></code> + of <code class="computeroutput"><span class="identifier">Init</span></code>, adds an + <code class="computeroutput"><span class="identifier">__init__</span><span class="special">(...)</span></code> + function overload to the extension class accepting P as arguments. + Each overload generated constructs an object of HeldType according + to the semantics described above, using a copy of init_expr's call + policies. If the longest <a class="link" href="high_level_components/boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction.init_expressions" title="init-expressions">valid + prefix</a> of Init contains N types and init_expr holds M keywords, + an initial sequence of the keywords are used for all but the first + N - M arguments of each overload. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Allows users to easily expose a class' constructor to Python. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="identifier">fn</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a1</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a2</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A3</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a2</span><span class="special">,</span> <span class="identifier">A3</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a3</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd> +<p> + name is an <a class="link" href="glossary.html#ntbs">ntbs</a> which conforms to Python's + <a href="http://www.python.org/doc/current/ref/identifiers.html" target="_top">identifier + naming rules</a>. * If a1 is the result of an <a class="link" href="function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions" title="overload-dispatch-expressions">overload-dispatch-expression</a>, + only the second form is allowed and fn must be a pointer to function + or pointer to member function whose <a class="link" href="glossary.html#arity">arity</a> + is the same as A1's <a class="link" href="function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions" title="overload-dispatch-expressions">maximum + arity</a>. + </p> +<p> + <span class="bold"><strong>Effects:</strong></span> For each prefix <code class="computeroutput"><span class="identifier">P</span></code> of <code class="computeroutput"><span class="identifier">Fn</span></code>'s + sequence of argument types, beginning with the one whose length + is <code class="computeroutput"><span class="identifier">A1</span></code>'s <a class="link" href="function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions" title="overload-dispatch-expressions">minimum + arity</a>, adds a <code class="computeroutput"><span class="identifier">name</span><span class="special">(...)</span></code> method overload to the extension + class. Each overload generated invokes a1's call-expression with + <code class="computeroutput"><span class="identifier">P</span></code>, using a copy + of a1's call policies. If the longest valid prefix of <code class="computeroutput"><span class="identifier">A1</span></code> contains <code class="computeroutput"><span class="identifier">N</span></code> + types and a1 holds <code class="computeroutput"><span class="identifier">M</span></code> + keywords, an initial sequence of the keywords are used for all + but the first <code class="computeroutput"><span class="identifier">N</span> <span class="special">-</span> <span class="identifier">M</span></code> + arguments of each overload. + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + Otherwise, a single method overload is built around fn, which + must not be null: + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> +<li class="listitem"> + If fn is a function pointer, its first argument must + be of the form U, U cv&, U cv*, or U cv* const&, + where T* is convertible to U*, and a1-a3, if supplied, + may be selected in any order from the table below. + </li> +<li class="listitem"> + Otherwise, if fn is a member function pointer, its target + must be T or one of its public base classes, and a1-a3, + if supplied, may be selected in any order from the table + below. + </li> +<li class="listitem"> +<p class="simpara"> + Otherwise, Fn must be [derived from] <a class="link" href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object">object</a>, + and a1-a2, if supplied, may be selcted in any order from + the first two rows of the table below. To be useful, + fn should be <a href="http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-6" target="_top">callable</a>. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Mnemonic Name + </p> + </th> +<th> + <p> + Requirements/Type properties + </p> + </th> +<th> + <p> + Effects + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + docstring + </p> + </td> +<td> + <p> + Any <a class="link" href="glossary.html#ntbs">ntbs</a> + </p> + </td> +<td> + <p> + Value will be bound to the __doc__ attribute + of the resulting method overload. If an earlier + overload supplied a docstring, two newline + characters and the new docstring are appended + to it. + </p> + </td> +</tr> +<tr> +<td> + <p> + policies + </p> + </td> +<td> + <p> + A model of <a class="link" href="concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a> + </p> + </td> +<td> + <p> + A copy will be used as the call policies of + the resulting method overload. + </p> + </td> +</tr> +<tr> +<td> + <p> + keywords + </p> + </td> +<td> + <p> + The result of a <a class="link" href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions" title="keyword-expressions">keyword-expression</a> + specifying no more arguments than the <a class="link" href="glossary.html#arity">arity</a> of fn. + </p> + </td> +<td> + <p> + A copy will be used as the call policies of + the resulting method overload. + </p> + </td> +</tr> +</tbody> +</table></div> +</li> +</ul></div> + </li></ul></div> +</dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">class_</span><span class="special">&</span> <span class="identifier">staticmethod</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + name is an <a class="link" href="glossary.html#ntbs">ntbs</a> which conforms to Python's + <a href="http://www.python.org/doc/current/ref/identifiers.html" target="_top">identifier + naming rules</a>, and corresponds to a method whose overloads + have all been defined. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Replaces the existing named attribute <code class="computeroutput"><span class="identifier">x</span></code> + with the result of invoking <code class="computeroutput"><span class="identifier">staticmethod</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> in Python. Specifies that the + corresponding method is static and therefore no object instance + will be passed to it. This is equivalent to the Python statement: + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">setattr</span><span class="special">(</span><span class="identifier">self</span><span class="special">,</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">staticmethod</span><span class="special">(</span><span class="identifier">getattr</span><span class="special">(</span><span class="identifier">self</span><span class="special">,</span> <span class="identifier">name</span><span class="special">)))</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Note</span></dt> +<dd><p> + Attempting to invoke def(name,...) after invoking staticmethod(name) + will <a class="link" href="glossary.html#raise">raise</a> a RuntimeError. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def</span><span class="special">(</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">>);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Adds a Python <a href="http://www.python.org/doc/ref/specialnames.html" target="_top">special + method</a> as described <a class="link" href="high_level_components/boost_python_operators_hpp.html" title="boost/python/operators.hpp">here</a>. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">&</span> <span class="identifier">setattr</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">U</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">u</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + name is an <a class="link" href="glossary.html#ntbs">ntbs</a> which conforms to Python's + <a href="http://www.python.org/doc/current/ref/identifiers.html" target="_top">identifier + naming rules</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd> +<p> + Converts <code class="computeroutput"><span class="identifier">u</span></code> to Python + and adds it to the attribute dictionary of the extension class: + </p> +<pre class="programlisting"><span class="identifier">PyObject_SetAttrString</span><span class="special">(</span><span class="keyword">this</span><span class="special">-></span><span class="identifier">ptr</span><span class="special">(),</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">object</span><span class="special">(</span><span class="identifier">u</span><span class="special">).</span><span class="identifier">ptr</span><span class="special">());</span></pre> +</dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Get</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">add_property</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Get</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fget</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span><span class="special">=</span><span class="number">0</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Get</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Set</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">add_property</span><span class="special">(</span> + <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Get</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fget</span><span class="special">,</span> <span class="identifier">Set</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fset</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span><span class="special">=</span><span class="number">0</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + name is an <a class="link" href="glossary.html#ntbs">ntbs</a> which conform to Python's + <a href="http://www.python.org/doc/current/ref/identifiers.html" target="_top">identifier + naming rules</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Creates a new Python <a href="http://www.python.org/2.2.2/descrintro.html#property" target="_top">property</a> + class instance, passing <code class="computeroutput"><span class="identifier">object</span><span class="special">(</span><span class="identifier">fget</span><span class="special">)</span></code> (and <code class="computeroutput"><span class="identifier">object</span><span class="special">(</span><span class="identifier">fset</span><span class="special">)</span></code> in the second form) with an (optional) + docstring <code class="computeroutput"><span class="identifier">doc</span></code> to + its constructor, then adds that property to the Python class object + under construction with the given attribute name. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Allows users to easily expose functions that can be invoked from + Python with attribute access syntax. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Get</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">add_static_property</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Get</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fget</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Get</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Set</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">add_static_property</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Get</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fget</span><span class="special">,</span> <span class="identifier">Set</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fset</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + name is an <a class="link" href="glossary.html#ntbs">ntbs</a> which conforms to Python's + <a href="http://www.python.org/doc/current/ref/identifiers.html" target="_top">identifier + naming rules</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Creates a Boost.Python.StaticProperty object, passing <code class="computeroutput"><span class="identifier">object</span><span class="special">(</span><span class="identifier">fget</span><span class="special">)</span></code> + (and <code class="computeroutput"><span class="identifier">object</span><span class="special">(</span><span class="identifier">fset</span><span class="special">)</span></code> + in the second form) to its constructor, then adds that property + to the Python class under construction with the given attribute + name. StaticProperty is a special subclass of Python's property + class which can be called without an initial self argument. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Allows users to easily expose functions that can be invoked from + Python with static attribute access syntax. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def_readonly</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">D</span> <span class="identifier">T</span><span class="special">::*</span><span class="identifier">pm</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span><span class="special">=</span><span class="number">0</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def_readonly</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">D</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">d</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + name is an <a class="link" href="glossary.html#ntbs">ntbs</a> which conforms to Python's + <a href="http://www.python.org/doc/current/ref/identifiers.html" target="_top">identifier + naming rules</a>. <code class="computeroutput"><span class="identifier">doc</span></code> + is also an <a class="link" href="glossary.html#ntbs">ntbs</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd> +<pre class="programlisting"><span class="keyword">this</span><span class="special">-></span><span class="identifier">add_property</span><span class="special">(</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">pm</span><span class="special">),</span> <span class="identifier">doc</span><span class="special">);</span></pre> +<p> + and + </p> +<pre class="programlisting"><span class="keyword">this</span><span class="special">-></span><span class="identifier">add_static_property</span><span class="special">(</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">d</span><span class="special">));</span></pre> +<p> + respectively. + </p> +</dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Allows users to easily expose a class' data member or free variable + such that it can be inspected from Python with a natural syntax. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def_readwrite</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">D</span> <span class="identifier">T</span><span class="special">::*</span><span class="identifier">pm</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span><span class="special">=</span><span class="number">0</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">D</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def_readwrite</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">D</span><span class="special">&</span> <span class="identifier">d</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd> +<pre class="programlisting"><span class="keyword">this</span><span class="special">-></span><span class="identifier">add_property</span><span class="special">(</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">pm</span><span class="special">),</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">pm</span><span class="special">),</span> <span class="identifier">doc</span><span class="special">);</span></pre> +<p> + and + </p> +<pre class="programlisting"><span class="keyword">this</span><span class="special">-></span><span class="identifier">add_static_property</span><span class="special">(</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">make_getter</span><span class="special">(</span><span class="identifier">d</span><span class="special">),</span> <span class="identifier">make_setter</span><span class="special">(</span><span class="identifier">d</span><span class="special">));</span></pre> +<p> + respectively. + </p> +</dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Allows users to easily expose a class' data or free variable member + such that it can be inspected and set from Python with a natural + syntax. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">PickleSuite</span><span class="special">></span> +<span class="identifier">class_</span><span class="special">&</span> <span class="identifier">def_pickle</span><span class="special">(</span><span class="identifier">PickleSuite</span> <span class="keyword">const</span><span class="special">&);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + PickleSuite must be publically derived from <a class="link" href="topics/pickle_support.html#topics.pickle_support.the_pickle_interface" title="The Pickle Interface">pickle_suite</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Defines a legal combination of the special attributes and methods: + __getinitargs__, __getstate__, __setstate__, __getstate_manages_dict__, + __safe_for_unpickling__, __reduce__ + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Provides an <a class="link" href="topics/pickle_support.html#topics.pickle_support.the_pickle_interface" title="The Pickle Interface">easy + to use high-level interface</a> for establishing complete <a class="link" href="topics/pickle_support.html#topics.pickle_support.the_pickle_interface" title="The Pickle Interface">pickle support</a> + for the wrapped class. The user is protected by compile-time consistency + checks. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">class_</span><span class="special">&</span> <span class="identifier">enable_pickling</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Defines the __reduce__ method and the __safe_for_unpickling__ attribute. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Light-weight alternative to def_pickle(). Enables implementation + of pickle support from Python. + </p></dd> +</dl> +</div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_class_hpp.class_template_bases_t1_t2_tn"></a><a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_bases_t1_t2_tn" title="Class template bases<T1, T2, ...TN>">Class + template bases<T1, T2, ...TN></a> +</h3></div></div></div> +<div class="toc"><dl class="toc"><dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_bases_t1_t2_tn.class_template_bases_synopsis">Class + template bases synopsis</a></span></dt></dl></div> +<p> + An MPL sequence which can be used in class_<...> instantiations indicate + a list of base classes. + </p> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_class_hpp.class_template_bases_t1_t2_tn.class_template_bases_synopsis"></a><a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_bases_t1_t2_tn.class_template_bases_synopsis" title="Class template bases synopsis">Class + template bases synopsis</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="identifier">T1</span> <span class="special">=</span> <span class="identifier">unspecified</span><span class="special">,...</span><span class="identifier">Tn</span> <span class="special">=</span> <span class="identifier">unspecified</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">bases</span> + <span class="special">{};</span> +<span class="special">}}</span> +</pre> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_class_hpp.examples"></a><a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp.examples" title="Examples">Examples</a> +</h3></div></div></div> +<p> + Given a C++ class declaration: + </p> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">Foo</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">Bar</span><span class="special">,</span> <span class="keyword">public</span> <span class="identifier">Baz</span> +<span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">Foo</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">y</span><span class="special">);</span> + <span class="identifier">Foo</span><span class="special">(</span><span class="keyword">double</span><span class="special">);</span> + + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">name</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">m_name</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">void</span> <span class="identifier">name</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*);</span> + + <span class="keyword">double</span> <span class="identifier">value</span><span class="special">;</span> <span class="comment">// public data</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="special">...</span> +<span class="special">};</span> +</pre> +<p> + A corresponding Boost.Python extension class can be created with: + </p> +<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="identifier">class_</span><span class="special"><</span><span class="identifier">Foo</span><span class="special">,</span><span class="identifier">bases</span><span class="special"><</span><span class="identifier">Bar</span><span class="special">,</span><span class="identifier">Baz</span><span class="special">></span> <span class="special">>(</span><span class="string">"Foo"</span><span class="special">,</span> + <span class="string">"This is Foo's docstring."</span> + <span class="string">"It describes our Foo extension class"</span><span class="special">,</span> + + <span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*>(</span><span class="identifier">args</span><span class="special">(</span><span class="string">"x"</span><span class="special">,</span><span class="string">"y"</span><span class="special">),</span> <span class="string">"__init__ docstring"</span><span class="special">)</span> + <span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">init</span><span class="special"><</span><span class="keyword">double</span><span class="special">>())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get_name"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">get_name</span><span class="special">,</span> <span class="identifier">return_internal_reference</span><span class="special"><>())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"set_name"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">set_name</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def_readwrite</span><span class="special">(</span><span class="string">"value"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">value</span><span class="special">);</span> +</pre> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="concepts/objectwrapper.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="high_level_components/boost_python_def_hpp.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components/boost_python_def_hpp.html b/libs/python/doc/html/reference/high_level_components/boost_python_def_hpp.html new file mode 100644 index 0000000000..ce99e9adf6 --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components/boost_python_def_hpp.html @@ -0,0 +1,220 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/def.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="prev" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="next" href="boost_python_def_visitor_hpp.html" title="boost/python/def_visitor.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../high_level_components.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_def_visitor_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_def_hpp"></a><a class="link" href="boost_python_def_hpp.html" title="boost/python/def.hpp">boost/python/def.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_def_hpp.introduction"></a><a class="link" href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">def</span><span class="special">()</span></code> + is the function which can be used to expose C++ functions and callable + objects as Python functions in the <a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.introduction" title="Introduction">current + scope</a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_def_hpp.functions"></a><a class="link" href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.functions" title="Functions">Functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">F</span> <span class="identifier">f</span><span class="special">);</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&);</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">A2</span> <span class="keyword">const</span><span class="special">&);</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Fn</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A3</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">def</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="identifier">fn</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">A2</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">A3</span> <span class="keyword">const</span><span class="special">&);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd> +<p> + name is an <a class="link" href="../glossary.html#ntbs">ntbs</a> which conforms to Python's + <a href="http://www.python.org/doc/current/ref/identifiers.html" target="_top">identifier + naming rules</a>. + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + If <code class="computeroutput"><span class="identifier">Fn</span></code> is [derived + from] <a class="link" href="../object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object">object</a>, + it will be added to the <a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.introduction" title="Introduction">current + scope</a> as a single overload. To be useful, <code class="computeroutput"><span class="identifier">fn</span></code> should be <a href="http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-6" target="_top">callable</a>. + </li> +<li class="listitem"> +<p class="simpara"> + If <code class="computeroutput"><span class="identifier">a1</span></code> is the + result of an <a class="link" href="../function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions" title="overload-dispatch-expressions">overload-dispatch-expression</a>, + only the second form is allowed and <code class="computeroutput"><span class="identifier">fn</span></code> + must be a pointer to function or pointer to member function whose + <a class="link" href="../glossary.html#arity">arity</a> is the same as A1's <a class="link" href="../function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions" title="overload-dispatch-expressions">maximum + arity</a>. + </p> +<p class="simpara"> + <span class="bold"><strong>Effects:</strong></span> For each prefix <code class="computeroutput"><span class="identifier">P</span></code> of <code class="computeroutput"><span class="identifier">Fn</span></code>'s + sequence of argument types, beginning with the one whose length + is <code class="computeroutput"><span class="identifier">A1</span></code>'s <a class="link" href="../function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions" title="overload-dispatch-expressions">minimum + arity</a>, adds a <code class="computeroutput"><span class="identifier">name</span><span class="special">(...)</span></code> function overload to the + <a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.introduction" title="Introduction">current + scope</a>. Each overload generated invokes a1's call-expression + with P, using a copy of a1's call policies. If the longest valid + prefix of A1 contains N types and a1 holds M keywords, an initial + sequence of the keywords are used for all but the first N - M + arguments of each overload. + </p> +</li> +<li class="listitem"> +<p class="simpara"> + Otherwise, fn must be a non-null function or member function + pointer, and a single function overload built around fn is added + to the current scope. If any of a1-a3 are supplied, they may + be selected in any order from the table below. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Mnemonic Name + </p> + </th> +<th> + <p> + Requirements/Type properties + </p> + </th> +<th> + <p> + Effects + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + docstring + </p> + </td> +<td> + <p> + Any <a class="link" href="../glossary.html#ntbs">ntbs</a> + </p> + </td> +<td> + <p> + Value will be bound to the <code class="computeroutput"><span class="identifier">__doc__</span></code> + attribute of the resulting method overload. + </p> + </td> +</tr> +<tr> +<td> + <p> + policies + </p> + </td> +<td> + <p> + A model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a> + </p> + </td> +<td> + <p> + A copy will be used as the call policies of the resulting + method overload. + </p> + </td> +</tr> +<tr> +<td> + <p> + keywords + </p> + </td> +<td> + <p> + The result of a <a class="link" href="../function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions" title="keyword-expressions">keyword-expression</a> + specifying no more arguments than the <a class="link" href="../glossary.html#arity">arity</a> + of <code class="computeroutput"><span class="identifier">fn</span></code>. + </p> + </td> +<td> + <p> + A copy will be used as the call policies of the resulting + method overload. + </p> + </td> +</tr> +</tbody> +</table></div> +</li> +</ul></div> +</dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_def_hpp.example"></a><a class="link" href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">args</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">foo</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"foo"</span><span class="special">;</span> <span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">def_test</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span> <span class="identifier">foo</span><span class="special">,</span> <span class="identifier">args</span><span class="special">(</span><span class="string">"x"</span><span class="special">,</span> <span class="string">"y"</span><span class="special">),</span> <span class="string">"foo's docstring"</span><span class="special">);</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../high_level_components.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_def_visitor_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components/boost_python_def_visitor_hpp.html b/libs/python/doc/html/reference/high_level_components/boost_python_def_visitor_hpp.html new file mode 100644 index 0000000000..1d030d37d4 --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components/boost_python_def_visitor_hpp.html @@ -0,0 +1,208 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/def_visitor.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="prev" href="boost_python_def_hpp.html" title="boost/python/def.hpp"> +<link rel="next" href="boost_python_docstring_options_h.html" title="boost/python/docstring_options.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_def_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_docstring_options_h.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_def_visitor_hpp"></a><a class="link" href="boost_python_def_visitor_hpp.html" title="boost/python/def_visitor.hpp">boost/python/def_visitor.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.class_def_visitor">Class + <code class="computeroutput"><span class="identifier">def_visitor</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_def_visitor_hpp.introduction"></a><a class="link" href="boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/def_visitor.hpp> provides a generic visitation interface + through which the <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_<T, Bases, HeldType, NonCopyable>">class_</a> + def member functionality can be extended non-intrusively to avoid cluttering + the <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_<T, Bases, HeldType, NonCopyable>">class_</a> + interface. It declares the <code class="computeroutput"><span class="identifier">def_visitor</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> class template, which is parameterized + on the derived type <code class="computeroutput"><span class="identifier">DerivedVisitor</span></code>, + which provides the actual <code class="computeroutput"><span class="identifier">def</span></code> + functionality through its <code class="computeroutput"><span class="identifier">visit</span></code> + member functions. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_def_visitor_hpp.class_def_visitor"></a><a class="link" href="boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.class_def_visitor" title="Class def_visitor">Class + <code class="computeroutput"><span class="identifier">def_visitor</span></code></a> +</h3></div></div></div> +<p> + The class <code class="computeroutput"><span class="identifier">def_visitor</span></code> is + a base class paramaterized by its derived class. The <code class="computeroutput"><span class="identifier">def_visitor</span></code> + class is a protocol class. Its derived class, DerivedVisitor, is expected + to have a member function <code class="computeroutput"><span class="identifier">visit</span></code>. + The <code class="computeroutput"><span class="identifier">def_visitor</span></code> class is + never instantiated directly. Instead, an instance of its subclass, DerivedVisitor, + is passed on as an argument to the <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_<T, Bases, HeldType, NonCopyable>">class_</a> + <code class="computeroutput"><span class="identifier">def</span></code> member function. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">DerivedVisitor</span><span class="special">></span> + <span class="keyword">class</span> <span class="identifier">def_visitor</span> <span class="special">{};</span> +<span class="special">}</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd> +<p> + The client supplied class DerivedVisitor template parameter is expected + to: * be privately derived from def_visitor * grant friend access + to class def_visitor_access * define either or both visit member + functions listed in the table below: + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Expression + </p> + </th> +<th> + <p> + Return Type + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Effects + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">visitor</span><span class="special">.</span><span class="identifier">visit</span><span class="special">(</span><span class="identifier">cls</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="keyword">void</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">cls</span></code> is + an instance of a <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_<T, Bases, HeldType, NonCopyable>">class_</a> + being wrapped to Python. <code class="computeroutput"><span class="identifier">visitor</span></code> + is a <code class="computeroutput"><span class="identifier">def_visitor</span></code> + derived class. + </p> + </td> +<td> + <p> + A call to <code class="computeroutput"><span class="identifier">cls</span><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">visitor</span><span class="special">)</span></code> forwards to this member + function. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">visitor</span><span class="special">.</span><span class="identifier">visit</span><span class="special">(</span><span class="identifier">cls</span><span class="special">,</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">options</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="keyword">void</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">cls</span></code> is + a <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_<T, Bases, HeldType, NonCopyable>">class_</a> + instance, name is a C string. <code class="computeroutput"><span class="identifier">visitor</span></code> + is a <code class="computeroutput"><span class="identifier">def_visitor</span></code> + derived class. options is a context specific optional argument. + </p> + </td> +<td> + <p> + A call to <code class="computeroutput"><span class="identifier">cls</span><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">visitor</span><span class="special">)</span></code> or <code class="computeroutput"><span class="identifier">cls</span><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">name</span><span class="special">,</span> <span class="identifier">visitor</span><span class="special">,</span> <span class="identifier">options</span><span class="special">)</span></code> forwards to this member + function. + </p> + </td> +</tr> +</tbody> +</table></div> +</dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_def_visitor_hpp.example"></a><a class="link" href="boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">X</span> <span class="special">{/*...*/};</span> + +<span class="keyword">class</span> <span class="identifier">my_def_visitor</span> <span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">def_visitor</span><span class="special"><</span><span class="identifier">my_def_visitor</span><span class="special">></span> +<span class="special">{</span> + <span class="keyword">friend</span> <span class="keyword">class</span> <span class="identifier">def_visitor_access</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">classT</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">visit</span><span class="special">(</span><span class="identifier">classT</span><span class="special">&</span> <span class="identifier">c</span><span class="special">)</span> <span class="keyword">const</span> + <span class="special">{</span> + <span class="identifier">c</span><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">my_def_visitor</span><span class="special">::</span><span class="identifier">foo</span><span class="special">);</span> + <span class="identifier">c</span><span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"bar"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">my_def_visitor</span><span class="special">::</span><span class="identifier">bar</span><span class="special">);</span> + <span class="special">}</span> + + <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span><span class="identifier">X</span><span class="special">&</span> <span class="identifier">self</span><span class="special">);</span> + <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">bar</span><span class="special">(</span><span class="identifier">X</span><span class="special">&</span> <span class="identifier">self</span><span class="special">);</span> +<span class="special">};</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">my_ext</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">X</span><span class="special">>(</span><span class="string">"X"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">my_def_visitor</span><span class="special">());</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_def_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_docstring_options_h.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components/boost_python_docstring_options_h.html b/libs/python/doc/html/reference/high_level_components/boost_python_docstring_options_h.html new file mode 100644 index 0000000000..2d7f7d7f7f --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components/boost_python_docstring_options_h.html @@ -0,0 +1,363 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/docstring_options.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="prev" href="boost_python_def_visitor_hpp.html" title="boost/python/def_visitor.hpp"> +<link rel="next" href="boost_python_enum_hpp.html" title="boost/python/enum.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_def_visitor_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_enum_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_docstring_options_h"></a><a class="link" href="boost_python_docstring_options_h.html" title="boost/python/docstring_options.hpp">boost/python/docstring_options.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options">Class + <code class="computeroutput"><span class="identifier">docstring_options</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_dostring_options_construct">Class + dostring_options constructors</a></span></dt> +<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options_destruct">Class + docstring_options destructor</a></span></dt> +<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options_modifier">Class + <code class="computeroutput"><span class="identifier">docstring_options</span></code> modifier + functions</a></span></dt> +<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_docstring_options_h.introduction"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Boost.Python supports user-defined docstrings with automatic appending + of C++ signatures. These features are enabled by default. The class docstring_options + is available to selectively suppress the user-defined docstrings, signatures, + or both. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_docstring_options_h.class_docstring_options"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options" title="Class docstring_options">Class + <code class="computeroutput"><span class="identifier">docstring_options</span></code></a> +</h3></div></div></div> +<p> + Controls the appearance of docstrings of wrapped functions and member functions + for the life-time of the instance. The instances are noncopyable to eliminate + the possibility of surprising side effects. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> + + <span class="keyword">class</span> <span class="identifier">docstring_options</span> <span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">noncopyable</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">docstring_options</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">show_all</span><span class="special">=</span><span class="keyword">true</span><span class="special">);</span> + <span class="identifier">docstring_options</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">show_user_defined</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">show_signatures</span><span class="special">);</span> + <span class="identifier">docstring_options</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">show_user_defined</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">show_py_signatures</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">show_cpp_signatures</span><span class="special">);</span> + <span class="special">~</span><span class="identifier">docstring_options</span><span class="special">();</span> + <span class="keyword">void</span> <span class="identifier">disable_user_defined</span><span class="special">();</span> + <span class="keyword">void</span> <span class="identifier">enable_user_defined</span><span class="special">();</span> + <span class="keyword">void</span> <span class="identifier">disable_signatures</span><span class="special">();</span> + <span class="keyword">void</span> <span class="identifier">enable_signatures</span><span class="special">();</span> + <span class="keyword">void</span> <span class="identifier">disable_py_signatures</span><span class="special">();</span> + <span class="keyword">void</span> <span class="identifier">enable_py_signatures</span><span class="special">();</span> + <span class="keyword">void</span> <span class="identifier">disable_cpp_signatures</span><span class="special">();</span> + <span class="keyword">void</span> <span class="identifier">enable_cpp_signatures</span><span class="special">();</span> + <span class="keyword">void</span> <span class="identifier">disable_all</span><span class="special">();</span> + <span class="keyword">void</span> <span class="identifier">enable_all</span><span class="special">();</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_docstring_options_h.class_dostring_options_construct"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_dostring_options_construct" title="Class dostring_options constructors">Class + dostring_options constructors</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">docstring_options</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">show_all</span><span class="special">=</span><span class="keyword">true</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Constructs a docstring_options object which controls the appearance + of function and member-function docstrings defined in the code that + follows. If show_all is true, both the user-defined docstrings and + the automatically generated Python and C++ signatures are shown. + If show_all is false the <code class="computeroutput"><span class="identifier">__doc__</span></code> + attributes are <code class="computeroutput"><span class="identifier">None</span></code>. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">docstring_options</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">show_user_defined</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">show_signatures</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Constructs a <code class="computeroutput"><span class="identifier">docstring_options</span></code> + object which controls the appearance of function and member-function + docstrings defined in the code that follows. Iff <code class="computeroutput"><span class="identifier">show_user_defined</span></code> + is <code class="computeroutput"><span class="keyword">true</span></code>, the user-defined + docstrings are shown. Iff <code class="computeroutput"><span class="identifier">show_signatures</span></code> + is <code class="computeroutput"><span class="keyword">true</span></code>, Python and + C++ signatures are automatically added. If both <code class="computeroutput"><span class="identifier">show_user_defined</span></code> + and <code class="computeroutput"><span class="identifier">show_signatures</span></code> + are <code class="computeroutput"><span class="keyword">false</span></code>, the <code class="computeroutput"><span class="identifier">__doc__</span></code> attributes are <code class="computeroutput"><span class="identifier">None</span></code>. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">docstring_options</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">show_user_defined</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">show_py_signatures</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">show_cpp_signatures</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Constructs a <code class="computeroutput"><span class="identifier">docstring_options</span></code> + object which controls the appearance of function and member-function + docstrings defined in the code that follows. Iff <code class="computeroutput"><span class="identifier">show_user_defined</span></code> + is <code class="computeroutput"><span class="keyword">true</span></code>, the user-defined + docstrings are shown. Iff <code class="computeroutput"><span class="identifier">show_py_signatures</span></code> + is <code class="computeroutput"><span class="keyword">true</span></code>, Python signatures + are automatically added. Iff <code class="computeroutput"><span class="identifier">show_cpp_signatures</span></code> + is true, C++ signatures are automatically added. If all parameters + are <code class="computeroutput"><span class="keyword">false</span></code>, the <code class="computeroutput"><span class="identifier">__doc__</span></code> attributes are <code class="computeroutput"><span class="identifier">None</span></code>. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_docstring_options_h.class_docstring_options_destruct"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options_destruct" title="Class docstring_options destructor">Class + docstring_options destructor</a> +</h3></div></div></div> +<pre class="programlisting"><span class="special">~</span><span class="identifier">docstring_options</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Restores the previous state of the docstring options. In particular, + if <code class="computeroutput"><span class="identifier">docstring_options</span></code> + instances are in nested C++ scopes the settings effective in the + enclosing scope are restored. If the last <code class="computeroutput"><span class="identifier">docstring_options</span></code> + instance goes out of scope the default "all on" settings + are restored. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_docstring_options_h.class_docstring_options_modifier"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options_modifier" title="Class docstring_options modifier functions">Class + <code class="computeroutput"><span class="identifier">docstring_options</span></code> modifier + functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">disable_user_defined</span><span class="special">();</span> +<span class="keyword">void</span> <span class="identifier">enable_user_defined</span><span class="special">();</span> +<span class="keyword">void</span> <span class="identifier">disable_signatures</span><span class="special">();</span> +<span class="keyword">void</span> <span class="identifier">enable_signatures</span><span class="special">();</span> +<span class="keyword">void</span> <span class="identifier">disable_py_signatures</span><span class="special">();</span> +<span class="keyword">void</span> <span class="identifier">enable_py_signatures</span><span class="special">();</span> +<span class="keyword">void</span> <span class="identifier">disable_cpp_signatures</span><span class="special">();</span> +<span class="keyword">void</span> <span class="identifier">enable_cpp_signatures</span><span class="special">();</span> +<span class="keyword">void</span> <span class="identifier">disable_all</span><span class="special">();</span> +<span class="keyword">void</span> <span class="identifier">enable_all</span><span class="special">();</span> +</pre> +<p> + These member functions dynamically change the appearance of docstrings + in the code that follows. The <code class="computeroutput"><span class="special">*</span><span class="identifier">_user_defined</span><span class="special">()</span></code> + and <code class="computeroutput"><span class="special">*</span><span class="identifier">_signatures</span><span class="special">()</span></code> member functions are provided for fine-grained + control. The <code class="computeroutput"><span class="special">*</span><span class="identifier">_all</span><span class="special">()</span></code> member functions are convenient shortcuts + to manipulate all settings simultaneously. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_docstring_options_h.example"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example" title="Example">Example</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example.docstring_options_defined_at_com">Docstring + options defined at compile time</a></span></dt> +<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example.selective_suppressions">Selective + suppressions</a></span></dt> +<dt><span class="section"><a href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example.wrapping_from_multiple_c_scopes">Wrapping + from multiple C++ scopes</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_docstring_options_h.example.docstring_options_defined_at_com"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example.docstring_options_defined_at_com" title="Docstring options defined at compile time">Docstring + options defined at compile time</a> +</h4></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">docstring_options</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span> <span class="special">{}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">demo</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + <span class="identifier">docstring_options</span> <span class="identifier">doc_options</span><span class="special">(</span><span class="identifier">DEMO_DOCSTRING_SHOW_ALL</span><span class="special">);</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span> <span class="identifier">foo</span><span class="special">,</span> <span class="string">"foo doc"</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + If compiled with <code class="computeroutput"><span class="special">-</span><span class="identifier">DDEMO_DOCSTRING_SHOW_ALL</span><span class="special">=</span><span class="keyword">true</span></code>: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">import</span> <span class="identifier">demo</span> +<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo</span><span class="special">.</span><span class="identifier">__doc__</span> +<span class="identifier">foo</span><span class="special">()</span> <span class="special">-></span> <span class="identifier">None</span> <span class="special">:</span> <span class="identifier">foo</span> <span class="identifier">doc</span> +<span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span> + <span class="identifier">foo</span><span class="special">(</span><span class="keyword">void</span><span class="special">)</span> <span class="special">-></span> <span class="keyword">void</span> +</pre> +<p> + If compiled with <code class="computeroutput"><span class="special">-</span><span class="identifier">DDEMO_DOCSTRING_SHOW_ALL</span><span class="special">=</span><span class="keyword">false</span></code>: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">import</span> <span class="identifier">demo</span> +<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo</span><span class="special">.</span><span class="identifier">__doc__</span> +<span class="identifier">None</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_docstring_options_h.example.selective_suppressions"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example.selective_suppressions" title="Selective suppressions">Selective + suppressions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">args</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">docstring_options</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">int</span> <span class="identifier">foo1</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">i</span><span class="special">;</span> <span class="special">}</span> +<span class="keyword">int</span> <span class="identifier">foo2</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">l</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">static_cast</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">l</span><span class="special">);</span> <span class="special">}</span> +<span class="keyword">int</span> <span class="identifier">foo3</span><span class="special">(</span><span class="keyword">float</span> <span class="identifier">f</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">static_cast</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">f</span><span class="special">);</span> <span class="special">}</span> +<span class="keyword">int</span> <span class="identifier">foo4</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">d</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">static_cast</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">d</span><span class="special">);</span> <span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">demo</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + <span class="identifier">docstring_options</span> <span class="identifier">doc_options</span><span class="special">;</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"foo1"</span><span class="special">,</span> <span class="identifier">foo1</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"i"</span><span class="special">),</span> <span class="string">"foo1 doc"</span><span class="special">);</span> + <span class="identifier">doc_options</span><span class="special">.</span><span class="identifier">disable_user_defined</span><span class="special">();</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"foo2"</span><span class="special">,</span> <span class="identifier">foo2</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"l"</span><span class="special">),</span> <span class="string">"foo2 doc"</span><span class="special">);</span> + <span class="identifier">doc_options</span><span class="special">.</span><span class="identifier">disable_signatures</span><span class="special">();</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"foo3"</span><span class="special">,</span> <span class="identifier">foo3</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"f"</span><span class="special">),</span> <span class="string">"foo3 doc"</span><span class="special">);</span> + <span class="identifier">doc_options</span><span class="special">.</span><span class="identifier">enable_user_defined</span><span class="special">();</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"foo4"</span><span class="special">,</span> <span class="identifier">foo4</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"d"</span><span class="special">),</span> <span class="string">"foo4 doc"</span><span class="special">);</span> + <span class="identifier">doc_options</span><span class="special">.</span><span class="identifier">enable_py_signatures</span><span class="special">();</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"foo5"</span><span class="special">,</span> <span class="identifier">foo4</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"d"</span><span class="special">),</span> <span class="string">"foo5 doc"</span><span class="special">);</span> + <span class="identifier">doc_options</span><span class="special">.</span><span class="identifier">disable_py_signatures</span><span class="special">();</span> + <span class="identifier">doc_options</span><span class="special">.</span><span class="identifier">enable_cpp_signatures</span><span class="special">();</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"foo6"</span><span class="special">,</span> <span class="identifier">foo4</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"d"</span><span class="special">),</span> <span class="string">"foo6 doc"</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + Python code: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">import</span> <span class="identifier">demo</span> +<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo1</span><span class="special">.</span><span class="identifier">__doc__</span> +<span class="identifier">foo1</span><span class="special">(</span> <span class="special">(</span><span class="keyword">int</span><span class="special">)</span><span class="identifier">i</span><span class="special">)</span> <span class="special">-></span> <span class="keyword">int</span> <span class="special">:</span> <span class="identifier">foo1</span> <span class="identifier">doc</span> +<span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span> + <span class="identifier">foo1</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span><span class="special">)</span> <span class="special">-></span> <span class="keyword">int</span> +<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo2</span><span class="special">.</span><span class="identifier">__doc__</span> +<span class="identifier">foo2</span><span class="special">(</span> <span class="special">(</span><span class="keyword">int</span><span class="special">)</span><span class="identifier">l</span><span class="special">)</span> <span class="special">-></span> <span class="keyword">int</span> <span class="special">:</span> +<span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span> + <span class="identifier">foo2</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">l</span><span class="special">)</span> <span class="special">-></span> <span class="keyword">int</span> +<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo3</span><span class="special">.</span><span class="identifier">__doc__</span> +<span class="identifier">None</span> +<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo4</span><span class="special">.</span><span class="identifier">__doc__</span> +<span class="identifier">foo4</span> <span class="identifier">doc</span> +<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo5</span><span class="special">.</span><span class="identifier">__doc__</span> +<span class="identifier">foo5</span><span class="special">(</span> <span class="special">(</span><span class="keyword">float</span><span class="special">)</span><span class="identifier">d</span><span class="special">)</span> <span class="special">-></span> <span class="keyword">int</span> <span class="special">:</span> <span class="identifier">foo5</span> <span class="identifier">doc</span> +<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo6</span><span class="special">.</span><span class="identifier">__doc__</span> +<span class="identifier">foo6</span> <span class="identifier">doc</span> +<span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span> + <span class="identifier">foo6</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">d</span><span class="special">)</span> <span class="special">-></span> <span class="keyword">int</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_docstring_options_h.example.wrapping_from_multiple_c_scopes"></a><a class="link" href="boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example.wrapping_from_multiple_c_scopes" title="Wrapping from multiple C++ scopes">Wrapping + from multiple C++ scopes</a> +</h4></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">args</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">docstring_options</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">int</span> <span class="identifier">foo1</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">i</span><span class="special">;</span> <span class="special">}</span> +<span class="keyword">int</span> <span class="identifier">foo2</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">l</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">static_cast</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">l</span><span class="special">);</span> <span class="special">}</span> + +<span class="keyword">int</span> <span class="identifier">bar1</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">i</span><span class="special">;</span> <span class="special">}</span> +<span class="keyword">int</span> <span class="identifier">bar2</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">l</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">static_cast</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">l</span><span class="special">);</span> <span class="special">}</span> + +<span class="keyword">namespace</span> <span class="special">{</span> + + <span class="keyword">void</span> <span class="identifier">wrap_foos</span><span class="special">()</span> + <span class="special">{</span> + <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + <span class="comment">// no docstring_options here</span> + <span class="comment">// -> settings from outer C++ scope are in effect</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"foo1"</span><span class="special">,</span> <span class="identifier">foo1</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"i"</span><span class="special">),</span> <span class="string">"foo1 doc"</span><span class="special">);</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"foo2"</span><span class="special">,</span> <span class="identifier">foo2</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"l"</span><span class="special">),</span> <span class="string">"foo2 doc"</span><span class="special">);</span> + <span class="special">}</span> + + <span class="keyword">void</span> <span class="identifier">wrap_bars</span><span class="special">()</span> + <span class="special">{</span> + <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + <span class="keyword">bool</span> <span class="identifier">show_user_defined</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span> + <span class="keyword">bool</span> <span class="identifier">show_signatures</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">;</span> + <span class="identifier">docstring_options</span> <span class="identifier">doc_options</span><span class="special">(</span><span class="identifier">show_user_defined</span><span class="special">,</span> <span class="identifier">show_signatures</span><span class="special">);</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"bar1"</span><span class="special">,</span> <span class="identifier">bar1</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"i"</span><span class="special">),</span> <span class="string">"bar1 doc"</span><span class="special">);</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"bar2"</span><span class="special">,</span> <span class="identifier">bar2</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"l"</span><span class="special">),</span> <span class="string">"bar2 doc"</span><span class="special">);</span> + <span class="special">}</span> +<span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">demo</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">docstring_options</span> <span class="identifier">doc_options</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span> + <span class="identifier">wrap_foos</span><span class="special">();</span> + <span class="identifier">wrap_bars</span><span class="special">();</span> +<span class="special">}</span> +</pre> +<p> + Python code: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">import</span> <span class="identifier">demo</span> +<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo1</span><span class="special">.</span><span class="identifier">__doc__</span> +<span class="identifier">None</span> +<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">foo2</span><span class="special">.</span><span class="identifier">__doc__</span> +<span class="identifier">None</span> +<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">bar1</span><span class="special">.</span><span class="identifier">__doc__</span> +<span class="identifier">bar1</span> <span class="identifier">doc</span> +<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">demo</span><span class="special">.</span><span class="identifier">bar2</span><span class="special">.</span><span class="identifier">__doc__</span> +<span class="identifier">bar2</span> <span class="identifier">doc</span> +</pre> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_def_visitor_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_enum_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components/boost_python_enum_hpp.html b/libs/python/doc/html/reference/high_level_components/boost_python_enum_hpp.html new file mode 100644 index 0000000000..aad9d99289 --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components/boost_python_enum_hpp.html @@ -0,0 +1,217 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/enum.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="prev" href="boost_python_docstring_options_h.html" title="boost/python/docstring_options.hpp"> +<link rel="next" href="boost_python_errors_hpp.html" title="boost/python/errors.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_docstring_options_h.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_errors_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_enum_hpp"></a><a class="link" href="boost_python_enum_hpp.html" title="boost/python/enum.hpp">boost/python/enum.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum">Class + template <code class="computeroutput"><span class="identifier">enum_</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum_constructors">Class + template <code class="computeroutput"><span class="identifier">enum_</span></code> constructors</a></span></dt> +<dt><span class="section"><a href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum_modifier_fun">Class + template <code class="computeroutput"><span class="identifier">enum_</span></code> modifier functions</a></span></dt> +<dt><span class="section"><a href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_enum_hpp.introduction"></a><a class="link" href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/enum.hpp> defines the interface through which users + expose their C++ enumeration types to Python. It declares the <code class="computeroutput"><span class="identifier">enum_</span></code> class template, which is parameterized + on the enumeration type being exposed. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_enum_hpp.class_template_enum"></a><a class="link" href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum" title="Class template enum_">Class + template <code class="computeroutput"><span class="identifier">enum_</span></code></a> +</h3></div></div></div> +<p> + Creates a Python class derived from Python's <code class="computeroutput"><span class="keyword">int</span></code> + type which is associated with the C++ type passed as its first parameter. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">class</span> <span class="identifier">enum_</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object</span> + <span class="special">{</span> + <span class="identifier">enum_</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span> + <span class="identifier">enum_</span><span class="special"><</span><span class="identifier">T</span><span class="special">>&</span> <span class="identifier">value</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">T</span><span class="special">);</span> + <span class="identifier">enum_</span><span class="special"><</span><span class="identifier">T</span><span class="special">>&</span> <span class="identifier">export_values</span><span class="special">();</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_enum_hpp.class_template_enum_constructors"></a><a class="link" href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum_constructors" title="Class template enum_ constructors">Class + template <code class="computeroutput"><span class="identifier">enum_</span></code> constructors</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">enum_</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span><span class="special">=</span><span class="number">0</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + name is an <a class="link" href="../glossary.html#ntbs">ntbs</a> which conforms to Python's + <a href="http://www.python.org/doc/current/ref/identifiers.html" target="_top">identifier + naming rules</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Constructs an <code class="computeroutput"><span class="identifier">enum_</span></code> + object holding a Python extension type derived from <code class="computeroutput"><span class="keyword">int</span></code> which is named <code class="computeroutput"><span class="identifier">name</span></code>. + The named attribute of the <a class="link" href="boost_python_scope_hpp.html" title="boost/python/scope.hpp">current + scope</a> is bound to the new extension type. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_enum_hpp.class_template_enum_modifier_fun"></a><a class="link" href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum_modifier_fun" title="Class template enum_ modifier functions">Class + template <code class="computeroutput"><span class="identifier">enum_</span></code> modifier functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">enum_</span><span class="special"><</span><span class="identifier">T</span><span class="special">>&</span> <span class="identifier">value</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + name is an <a class="link" href="../glossary.html#ntbs">ntbs</a> which conforms to Python's + <a href="http://www.python.org/doc/current/ref/identifiers.html" target="_top">identifier + naming rules</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + adds an instance of the wrapped enumeration type with value x to + the type's dictionary as the named attribute. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">enum_</span><span class="special"><</span><span class="identifier">T</span><span class="special">>&</span> <span class="identifier">export_values</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + sets attributes in the <a class="link" href="boost_python_scope_hpp.html" title="boost/python/scope.hpp">current + scope</a> with the same names and values as all enumeration values + exposed so far by calling value(). + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_enum_hpp.example"></a><a class="link" href="boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<p> + C++ module definition + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">enum</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="keyword">enum</span> <span class="identifier">color</span> <span class="special">{</span> <span class="identifier">red</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">green</span> <span class="special">=</span> <span class="number">2</span><span class="special">,</span> <span class="identifier">blue</span> <span class="special">=</span> <span class="number">4</span> <span class="special">};</span> + +<span class="identifier">color</span> <span class="identifier">identity_</span><span class="special">(</span><span class="identifier">color</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">enums</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">enum_</span><span class="special"><</span><span class="identifier">color</span><span class="special">>(</span><span class="string">"color"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">value</span><span class="special">(</span><span class="string">"red"</span><span class="special">,</span> <span class="identifier">red</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">value</span><span class="special">(</span><span class="string">"green"</span><span class="special">,</span> <span class="identifier">green</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">export_values</span><span class="special">()</span> + <span class="special">.</span><span class="identifier">value</span><span class="special">(</span><span class="string">"blue"</span><span class="special">,</span> <span class="identifier">blue</span><span class="special">)</span> + <span class="special">;</span> + + <span class="identifier">def</span><span class="special">(</span><span class="string">"identity"</span><span class="special">,</span> <span class="identifier">identity_</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + Interactive Python: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">enums</span> <span class="identifier">import</span> <span class="special">*</span> + +<span class="special">>>></span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">red</span><span class="special">)</span> +<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">red</span> + +<span class="special">>>></span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">red</span><span class="special">)</span> +<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">red</span> + +<span class="special">>>></span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">green</span><span class="special">)</span> +<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">green</span> + +<span class="special">>>></span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">green</span><span class="special">)</span> +<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">green</span> + +<span class="special">>>></span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">blue</span><span class="special">)</span> +<span class="identifier">Traceback</span> <span class="special">(</span><span class="identifier">most</span> <span class="identifier">recent</span> <span class="identifier">call</span> <span class="identifier">last</span><span class="special">):</span> + <span class="identifier">File</span> <span class="string">"<stdin>"</span><span class="special">,</span> <span class="identifier">line</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">in</span> <span class="special">?</span> +<span class="identifier">NameError</span><span class="special">:</span> <span class="identifier">name</span> <span class="char">'blue'</span> <span class="identifier">is</span> <span class="keyword">not</span> <span class="identifier">defined</span> + +<span class="special">>>></span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">blue</span><span class="special">)</span> +<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">blue</span> + +<span class="special">>>></span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">(</span><span class="number">1</span><span class="special">))</span> +<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">red</span> + +<span class="special">>>></span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">(</span><span class="number">2</span><span class="special">))</span> +<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">green</span> + +<span class="special">>>></span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">(</span><span class="number">3</span><span class="special">))</span> +<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> + +<span class="special">>>></span> <span class="identifier">identity</span><span class="special">(</span><span class="identifier">color</span><span class="special">(</span><span class="number">4</span><span class="special">))</span> +<span class="identifier">enums</span><span class="special">.</span><span class="identifier">color</span><span class="special">.</span><span class="identifier">blue</span> + +<span class="special">>>></span> <span class="identifier">identity</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> +<span class="identifier">Traceback</span> <span class="special">(</span><span class="identifier">most</span> <span class="identifier">recent</span> <span class="identifier">call</span> <span class="identifier">last</span><span class="special">):</span> + <span class="identifier">File</span> <span class="string">"<stdin>"</span><span class="special">,</span> <span class="identifier">line</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">in</span> <span class="special">?</span> +<span class="identifier">TypeError</span><span class="special">:</span> <span class="identifier">bad</span> <span class="identifier">argument</span> <span class="identifier">type</span> <span class="keyword">for</span> <span class="identifier">built</span><span class="special">-</span><span class="identifier">in</span> <span class="identifier">operation</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_docstring_options_h.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_errors_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components/boost_python_errors_hpp.html b/libs/python/doc/html/reference/high_level_components/boost_python_errors_hpp.html new file mode 100644 index 0000000000..837041421c --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components/boost_python_errors_hpp.html @@ -0,0 +1,278 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/errors.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="prev" href="boost_python_enum_hpp.html" title="boost/python/enum.hpp"> +<link rel="next" href="boost_python_exception_translato.html" title="boost/python/exception_translator.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_enum_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_exception_translato.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_errors_hpp"></a><a class="link" href="boost_python_errors_hpp.html" title="boost/python/errors.hpp">boost/python/errors.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set">Class + <code class="computeroutput"><span class="identifier">error_already_set</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_errors_hpp.introduction"></a><a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <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. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_errors_hpp.class_error_already_set"></a><a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">Class + <code class="computeroutput"><span class="identifier">error_already_set</span></code></a> +</h3></div></div></div> +<p> + 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 + <a href="http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71" target="_top">PyErr_Occurred()</a> + returns a value convertible to <code class="computeroutput"><span class="keyword">true</span></code>. + Portable code shouldn't throw this exception type directly, but should + instead use <a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.functions" title="Functions">throw_error_already_set()</a>, + below. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">error_already_set</span> <span class="special">{};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_errors_hpp.functions"></a><a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.functions" title="Functions">Functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">bool</span> <span class="identifier">handle_exception</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">f</span><span class="special">)</span> <span class="keyword">throw</span><span class="special">();</span> +<span class="keyword">void</span> <span class="identifier">handle_exception</span><span class="special">()</span> <span class="keyword">throw</span><span class="special">();</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + 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). + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + The first form calls f() inside a try block which first attempts + to use all registered <a class="link" href="boost_python_exception_translato.html" title="boost/python/exception_translator.hpp">exception + translators</a>. If none of those translates the exception, the + catch clauses then set an appropriate Python exception for the C++ + exception caught, returning true if an exception was thrown, false + otherwise. The second form passes a function which rethrows the exception + currently being handled to the first form. + </p></dd> +<dt><span class="term">Postconditions</span></dt> +<dd><p> + No exception is being handled + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + nothing + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + At inter-language boundaries it is important to ensure that no C++ + exceptions escape, since the calling language usually doesn't have + the equipment necessary 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: <a class="link" href="../function_invocation_and_creation/boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.functions" title="Functions">make_function()</a>, + <a class="link" href="../function_invocation_and_creation/boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.functions" title="Functions">make_constructor()</a>, + <a class="link" href="boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.functions" title="Functions">def()</a> + and <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu" title="Class template class_ modifier functions">class_::def()</a>. + 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. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">expect_non_null</span><span class="special">(</span><span class="identifier">T</span><span class="special">*</span> <span class="identifier">x</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + x + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + error_already_set() iff x == 0. + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Simplifies error-handling when calling functions in the Python/C + API which return 0 on error. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">throw_error_already_set</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + throw error_already_set(); + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Simplifies error-handling when calling functions in the Python/C + API which return 0 on error. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">throw_error_already_set</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + throw error_already_set(); + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Many platforms and compilers are not able to consistently catch exceptions + thrown across shared library boundaries. Using this function from + the Boost.Python library ensures that the appropriate catch block + in handle_exception() can catch the exception. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_errors_hpp.example"></a><a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">string</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">errors</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">object</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">handle</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="comment">// Returns a std::string which has the same value as obj's "__name__"</span> +<span class="comment">// attribute.</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">get_name</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span> <span class="identifier">obj</span><span class="special">)</span> +<span class="special">{</span> + <span class="comment">// throws if there's no __name__ attribute</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">expect_non_null</span><span class="special">(</span> + <span class="identifier">PyObject_GetAttrString</span><span class="special">(</span><span class="identifier">obj</span><span class="special">.</span><span class="identifier">ptr</span><span class="special">(),</span> <span class="string">"__name__"</span><span class="special">));</span> + + <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">s</span> <span class="special">=</span> <span class="identifier">PyString_AsString</span><span class="special">(</span><span class="identifier">p</span><span class="special">);</span> + <span class="keyword">if</span> <span class="special">(</span><span class="identifier">s</span> <span class="special">!=</span> <span class="number">0</span><span class="special">)</span> + <span class="identifier">Py_DECREF</span><span class="special">(</span><span class="identifier">p</span><span class="special">);</span> + + <span class="comment">// throws if it's not a Python string</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">result</span><span class="special">(</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">expect_non_null</span><span class="special">(</span> + <span class="identifier">PyString_AsString</span><span class="special">(</span><span class="identifier">p</span><span class="special">)));</span> + + <span class="identifier">Py_DECREF</span><span class="special">(</span><span class="identifier">p</span><span class="special">);</span> <span class="comment">// Done with p</span> + + <span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span> +<span class="special">}</span> + +<span class="comment">//</span> +<span class="comment">// Demonstrate form 1 of handle_exception</span> +<span class="comment">//</span> + +<span class="comment">// Place into result a Python Int object whose value is 1 if a and b have</span> +<span class="comment">// identical "__name__" attributes, 0 otherwise.</span> +<span class="keyword">void</span> <span class="identifier">same_name_impl</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*&</span> <span class="identifier">result</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span> <span class="identifier">b</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">PyInt_FromLong</span><span class="special">(</span> + <span class="identifier">get_name</span><span class="special">(</span><span class="identifier">a</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">get_name</span><span class="special">(</span><span class="identifier">a2</span><span class="special">));</span> +<span class="special">}</span> + +<span class="identifier">object</span> <span class="identifier">borrowed_object</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span><span class="special">(</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">handle</span><span class="special"><>(</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">borrowed</span><span class="special">(</span><span class="identifier">a1</span><span class="special">)));</span> +<span class="special">}</span> + +<span class="comment">// This is an example Python 'C' API interface function</span> +<span class="keyword">extern</span> <span class="string">"C"</span> <span class="identifier">PyObject</span><span class="special">*</span> +<span class="identifier">same_name</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">keywords</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">a1</span><span class="special">;</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">a2</span><span class="special">;</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> + + <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">PyArg_ParseTuple</span><span class="special">(</span><span class="identifier">args</span><span class="special">,</span> <span class="keyword">const_cast</span><span class="special"><</span><span class="keyword">char</span><span class="special">*>(</span><span class="string">"OO"</span><span class="special">),</span> <span class="special">&</span><span class="identifier">a1</span><span class="special">,</span> <span class="special">&</span><span class="identifier">a2</span><span class="special">))</span> + <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> + + <span class="comment">// Use boost::bind to make an object compatible with</span> + <span class="comment">// boost::Function0<void></span> + <span class="keyword">if</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">handle_exception</span><span class="special">(</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special"><</span><span class="keyword">void</span><span class="special">>(</span><span class="identifier">same_name_impl</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">result</span><span class="special">),</span> <span class="identifier">borrowed_object</span><span class="special">(</span><span class="identifier">a1</span><span class="special">),</span> <span class="identifier">borrowed_object</span><span class="special">(</span><span class="identifier">a2</span><span class="special">))))</span> + <span class="special">{</span> + <span class="comment">// an exception was thrown; the Python error was set by</span> + <span class="comment">// handle_exception()</span> + <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> + <span class="special">}</span> + + <span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span> +<span class="special">}</span> + +<span class="comment">//</span> +<span class="comment">// Demonstrate form 2 of handle_exception. Not well-supported by all</span> +<span class="comment">// compilers.</span> +<span class="comment">//</span> +<span class="keyword">extern</span> <span class="string">"C"</span> <span class="identifier">PyObject</span><span class="special">*</span> +<span class="identifier">same_name2</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">keywords</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">a1</span><span class="special">;</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">a2</span><span class="special">;</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> + + <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">PyArg_ParseTuple</span><span class="special">(</span><span class="identifier">args</span><span class="special">,</span> <span class="keyword">const_cast</span><span class="special"><</span><span class="keyword">char</span><span class="special">*>(</span><span class="string">"OO"</span><span class="special">),</span> <span class="special">&</span><span class="identifier">a1</span><span class="special">,</span> <span class="special">&</span><span class="identifier">a2</span><span class="special">))</span> + <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> + + <span class="keyword">try</span> <span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">PyInt_FromLong</span><span class="special">(</span> + <span class="identifier">get_name</span><span class="special">(</span><span class="identifier">borrowed_object</span><span class="special">(</span><span class="identifier">a1</span><span class="special">))</span> <span class="special">==</span> <span class="identifier">get_name</span><span class="special">(</span><span class="identifier">borrowed_object</span><span class="special">(</span><span class="identifier">a2</span><span class="special">)));</span> + <span class="special">}</span> + <span class="keyword">catch</span><span class="special">(...)</span> + <span class="special">{</span> + <span class="comment">// If an exception was thrown, translate it to Python</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">handle_exception</span><span class="special">();</span> + <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> + <span class="special">}</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_enum_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_exception_translato.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components/boost_python_exception_translato.html b/libs/python/doc/html/reference/high_level_components/boost_python_exception_translato.html new file mode 100644 index 0000000000..d4c6991e7a --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components/boost_python_exception_translato.html @@ -0,0 +1,130 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/exception_translator.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="prev" href="boost_python_errors_hpp.html" title="boost/python/errors.hpp"> +<link rel="next" href="boost_python_init_hpp.html" title="boost/python/init.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_errors_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_init_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_exception_translato"></a><a class="link" href="boost_python_exception_translato.html" title="boost/python/exception_translator.hpp">boost/python/exception_translator.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.function_register_exception_tran">Function + <code class="computeroutput"><span class="identifier">register_exception_translator</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_exception_translato.introduction"></a><a class="link" href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + As described <a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.introduction" title="Introduction">here</a>, + 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 <a href="http://www.python.org/doc/current/lib/module-exceptions.html" target="_top">RuntimeError</a> + exception whose representation is 'Unidentifiable C++ Exception'. To produce + better error messages, users can register additional exception translators + as described below. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_exception_translato.function_register_exception_tran"></a><a class="link" href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.function_register_exception_tran" title="Function register_exception_translator">Function + <code class="computeroutput"><span class="identifier">register_exception_translator</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">ExceptionType</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Translate</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">register_exception_translator</span><span class="special">(</span><span class="identifier">Translate</span> <span class="identifier">translate</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd> +<p> + Translate is CopyConstructible, and the following code must be well-formed: + </p> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">ExceptionType</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">translate</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span> <span class="special">}</span></pre> +<p> + . The expression <code class="computeroutput"><span class="identifier">translate</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> must either throw a C++ exception, + or a subsequent call to <code class="computeroutput"><span class="identifier">PyErr_Occurred</span><span class="special">()</span></code> must return 1. + </p> +</dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + 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). + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_exception_translato.example"></a><a class="link" href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">exception_translator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">exception</span><span class="special">></span> + +<span class="keyword">struct</span> <span class="identifier">my_exception</span> <span class="special">:</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span> +<span class="special">{</span> + <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">what</span><span class="special">()</span> <span class="keyword">throw</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"One of my exceptions"</span><span class="special">;</span> <span class="special">}</span> +<span class="special">};</span> + +<span class="keyword">void</span> <span class="identifier">translate</span><span class="special">(</span><span class="identifier">my_exception</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">e</span><span class="special">)</span> +<span class="special">{</span> + <span class="comment">// Use the Python 'C' API to set up an exception object</span> + <span class="identifier">PyErr_SetString</span><span class="special">(</span><span class="identifier">PyExc_RuntimeError</span><span class="special">,</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">());</span> +<span class="special">}</span> + +<span class="keyword">void</span> <span class="identifier">something_which_throws</span><span class="special">()</span> +<span class="special">{</span> + <span class="special">...</span> + <span class="keyword">throw</span> <span class="identifier">my_exception</span><span class="special">();</span> + <span class="special">...</span> +<span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">exception_translator_ext</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + <span class="identifier">register_exception_translator</span><span class="special"><</span><span class="identifier">my_exception</span><span class="special">>(&</span><span class="identifier">translate</span><span class="special">);</span> + + <span class="identifier">def</span><span class="special">(</span><span class="string">"something_which_throws"</span><span class="special">,</span> <span class="identifier">something_which_throws</span><span class="special">);</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_errors_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_init_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components/boost_python_init_hpp.html b/libs/python/doc/html/reference/high_level_components/boost_python_init_hpp.html new file mode 100644 index 0000000000..01a1b57f99 --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components/boost_python_init_hpp.html @@ -0,0 +1,233 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/init.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="prev" href="boost_python_exception_translato.html" title="boost/python/exception_translator.hpp"> +<link rel="next" href="boost_python_iterator_hpp.html" title="boost/python/iterator.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_exception_translato.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_iterator_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_init_hpp"></a><a class="link" href="boost_python_init_hpp.html" title="boost/python/init.hpp">boost/python/init.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init">Class + template <code class="computeroutput"><span class="identifier">init</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_optional">Class + template <code class="computeroutput"><span class="identifier">optional</span></code> </a></span></dt> +<dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_init_hpp.introduction"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"><dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction.init_expressions">init-expressions</a></span></dt></dl></div> +<p> + <boost/python/init.hpp> defines the interface for exposing C++ constructors + to Python as extension class <code class="computeroutput"><span class="identifier">__init__</span></code> + functions. + </p> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_init_hpp.introduction.init_expressions"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction.init_expressions" title="init-expressions">init-expressions</a> +</h4></div></div></div> +<p> + An init-expression is used to describe a family of <code class="computeroutput"><span class="identifier">__init__</span></code> + methods to be generated for an extension class, and the result has the + following properties: + </p> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">docstring</span></dt> +<dd><p> + An <a class="link" href="../glossary.html#ntbs">ntbs</a> whose value will bound to the + method's <code class="computeroutput"><span class="identifier">__doc__</span></code> + attribute + </p></dd> +<dt><span class="term">keywords</span></dt> +<dd><p> + A <a class="link" href="../function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions" title="keyword-expressions">keyword-expression</a> + which will be used to name (a trailing subsequence of) the arguments + to the generated <code class="computeroutput"><span class="identifier">__init__</span></code> + function(s). + </p></dd> +<dt><span class="term">call_policies</span></dt> +<dd><p> + An instance of a model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>. + </p></dd> +<dt><span class="term">argument_types</span></dt> +<dd><p> + 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. + </p></dd> +</dl> +</div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_init_hpp.class_template_init"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init" title="Class template init">Class + template <code class="computeroutput"><span class="identifier">init</span></code></a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init.class_template_init_constructors">Class + template <code class="computeroutput"><span class="identifier">init</span></code> constructors</a></span></dt> +<dt><span class="section"><a href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init.class_template_init_observer_fun">Class + template <code class="computeroutput"><span class="identifier">init</span></code> observer + functions</a></span></dt> +</dl></div> +<p> + 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<...>. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="identifier">T1</span> <span class="special">=</span> <span class="identifier">unspecified</span><span class="special">,...</span><span class="identifier">Tn</span> <span class="special">=</span> <span class="identifier">unspecified</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">init</span> + <span class="special">{</span> + <span class="identifier">init</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Keywords</span><span class="special">></span> <span class="identifier">init</span><span class="special">(</span><span class="identifier">Keywords</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">kw</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Keywords</span><span class="special">></span> <span class="identifier">init</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span><span class="special">,</span> <span class="identifier">Keywords</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">kw</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">CallPolicies</span><span class="special">></span> + <span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">[](</span><span class="identifier">CallPolicies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">)</span> <span class="keyword">const</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_init_hpp.class_template_init.class_template_init_constructors"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init.class_template_init_constructors" title="Class template init constructors">Class + template <code class="computeroutput"><span class="identifier">init</span></code> constructors</a> +</h4></div></div></div> +<pre class="programlisting"><span class="identifier">init</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Keywords</span><span class="special">></span> <span class="identifier">init</span><span class="special">(</span><span class="identifier">Keywords</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">kw</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Keywords</span><span class="special">></span> <span class="identifier">init</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">doc</span><span class="special">,</span> <span class="identifier">Keywords</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">kw</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + If supplied, doc is an <a class="link" href="../glossary.html#ntbs">ntbs</a>. If supplied, + kw is the result of a + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd> +<p> + 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 <a class="link" href="../function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici" title="boost/python/default_call_policies.hpp">default_call_policies</a>. + If Tn is <a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_optional" title="Class template optional">optional<U1, + U2,... Um></a>, the expression's valid prefixes are given + by: + </p> +<pre class="programlisting"><span class="special">(</span><span class="identifier">T1</span><span class="special">,</span> <span class="identifier">T2</span><span class="special">,...</span><span class="identifier">Tn</span><span class="special">-</span><span class="number">1</span><span class="special">),</span> <span class="special">(</span><span class="identifier">T1</span><span class="special">,</span> <span class="identifier">T2</span><span class="special">,...</span><span class="identifier">Tn</span><span class="special">-</span><span class="number">1</span> <span class="special">,</span> <span class="identifier">U1</span><span class="special">),</span> <span class="special">(</span><span class="identifier">T1</span><span class="special">,</span> <span class="identifier">T2</span><span class="special">,...</span><span class="identifier">Tn</span><span class="special">-</span><span class="number">1</span> <span class="special">,</span> <span class="identifier">U1</span><span class="special">,</span> <span class="identifier">U2</span><span class="special">),</span> <span class="special">...(</span><span class="identifier">T1</span><span class="special">,</span> <span class="identifier">T2</span><span class="special">,...</span><span class="identifier">Tn</span><span class="special">-</span><span class="number">1</span> <span class="special">,</span> <span class="identifier">U1</span><span class="special">,</span> <span class="identifier">U2</span><span class="special">,...</span><span class="identifier">Um</span><span class="special">)</span></pre> +<p> + . Otherwise, the expression has one valid prefix given by the template + arguments the user specified. + </p> +</dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_init_hpp.class_template_init.class_template_init_observer_fun"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init.class_template_init_observer_fun" title="Class template init observer functions">Class + template <code class="computeroutput"><span class="identifier">init</span></code> observer + functions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">></span> +<span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">[](</span><span class="identifier">Policies</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">policies</span><span class="special">)</span> <span class="keyword">const</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + Policies is a model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Returns a new <a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction.init_expressions" title="init-expressions">init-expression</a> + with all the same properties as the init object except that its + call policies are replaced by a reference to policies. + </p></dd> +</dl> +</div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_init_hpp.class_template_optional"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_optional" title="Class template optional">Class + template <code class="computeroutput"><span class="identifier">optional</span></code> </a> +</h3></div></div></div> +<p> + A MPL sequence which can be used to specify the optional arguments to an + __init__ function. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="identifier">T1</span> <span class="special">=</span> <span class="identifier">unspecified</span><span class="special">,...</span><span class="identifier">Tn</span> <span class="special">=</span> <span class="identifier">unspecified</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">optional</span> <span class="special">{};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_init_hpp.example"></a><a class="link" href="boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<p> + Given the C++ declarations: + </p> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">;</span> +<span class="keyword">class</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">X</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">Y</span><span class="special">*</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">m_y</span><span class="special">(</span><span class="identifier">y</span><span class="special">)</span> <span class="special">{}</span> + <span class="identifier">X</span><span class="special">(</span><span class="keyword">double</span><span class="special">);</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="identifier">Y</span><span class="special">*</span> <span class="identifier">m_y</span><span class="special">;</span> +<span class="special">};</span> +</pre> +<p> + A corresponing Boost.Python extension class can be created with: + </p> +<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="identifier">class_</span><span class="special"><</span><span class="identifier">X</span><span class="special">>(</span><span class="string">"X"</span><span class="special">,</span> <span class="string">"This is X's docstring."</span><span class="special">,</span> + <span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*>(</span><span class="identifier">args</span><span class="special">(</span><span class="string">"x"</span><span class="special">,</span><span class="string">"y"</span><span class="special">),</span> <span class="string">"X.__init__'s docstring"</span><span class="special">)[</span> + <span class="identifier">with_custodian_and_ward</span><span class="special"><</span><span class="number">1</span><span class="special">,</span><span class="number">3</span><span class="special">>()]</span> + <span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">init</span><span class="special"><</span><span class="keyword">double</span><span class="special">>())</span> + <span class="special">;</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_exception_translato.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_iterator_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components/boost_python_iterator_hpp.html b/libs/python/doc/html/reference/high_level_components/boost_python_iterator_hpp.html new file mode 100644 index 0000000000..685897213e --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components/boost_python_iterator_hpp.html @@ -0,0 +1,398 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/iterator.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="prev" href="boost_python_init_hpp.html" title="boost/python/init.hpp"> +<link rel="next" href="boost_python_module_hpp.html" title="boost/python/module.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_init_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_module_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_iterator_hpp"></a><a class="link" href="boost_python_iterator_hpp.html" title="boost/python/iterator.hpp">boost/python/iterator.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterator">Class + template <code class="computeroutput"><span class="identifier">iterator</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterator_construc">Class + template iterator constructors</a></span></dt> +<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators">Class + template <code class="computeroutput"><span class="identifier">iterators</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators_nested_">Class + template iterators nested types</a></span></dt> +<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators_static_">Class + template iterators static functions</a></span></dt> +<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_iterator_hpp.introduction"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/iterator.hpp> provides types and functions for creating + <a href="http://www.python.org/doc/current/lib/typeiter.html" target="_top">Python + iterators</a> from C++ Containers and Iterators. Note that if your + <code class="computeroutput"><span class="identifier">class_</span></code> supports random-access + iterators, implementing <a href="http://www.python.org/doc/current/ref/sequence-types.html#l2h-128" target="_top">__getitem__</a> + (also known as the Sequence Protocol) may serve you better than using this + facility: Python will automatically create an iterator type for you (see + <a href="http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-35" target="_top"><code class="computeroutput"><span class="identifier">iter</span><span class="special">()</span></code></a>), + and each access can be range-checked, leaving no possiblity of accessing + through an invalidated C++ iterator. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_iterator_hpp.class_template_iterator"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterator" title="Class template iterator">Class + template <code class="computeroutput"><span class="identifier">iterator</span></code></a> +</h3></div></div></div> +<p> + Instances of <code class="computeroutput"><span class="identifier">iterator</span><span class="special"><</span><span class="identifier">C</span><span class="special">,</span><span class="identifier">P</span><span class="special">></span></code> hold a reference to a callable Python + object which, when invoked from Python, expects a single argument c convertible + to C and creates a Python iterator that traverses <code class="computeroutput"><span class="special">[</span><span class="identifier">c</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">c</span><span class="special">.</span><span class="identifier">end</span><span class="special">())</span></code>. The optional <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a> + <code class="computeroutput"><span class="identifier">P</span></code> can be used to control + how elements are returned during iteration. + </p> +<p> + In the table below, c is an instance of Container. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Template Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Semantics + </p> + </th> +<th> + <p> + Default + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + Container + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="special">[</span><span class="identifier">c</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span><span class="identifier">c</span><span class="special">.</span><span class="identifier">end</span><span class="special">()</span></code>) is a valid Iterator range. + </p> + </td> +<td> + <p> + The result will convert its argument to c and call c.begin() + and c.end() to acquire iterators. To invoke Container's const + <code class="computeroutput"><span class="identifier">begin</span><span class="special">()</span></code> + and <code class="computeroutput"><span class="identifier">end</span><span class="special">()</span></code> + functions, make it const. + </p> + </td> +<td> + </td> +</tr> +<tr> +<td> + <p> + NextPolicies + </p> + </td> +<td> + <p> + A default-constructible model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>. + </p> + </td> +<td> + <p> + Applied to the resulting iterators' <code class="computeroutput"><span class="identifier">next</span><span class="special">()</span></code> method. + </p> + </td> +<td> + <p> + An unspecified model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a> + which always makes a copy of the result of deferencing the underlying + C++ iterator + </p> + </td> +</tr> +</tbody> +</table></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> + <span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Container</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">NextPolicies</span> <span class="special">=</span> <span class="identifier">unspecified</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">iterator</span> <span class="special">:</span> <span class="identifier">object</span> + <span class="special">{</span> + <span class="identifier">iterator</span><span class="special">();</span> + <span class="special">};</span> + <span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_iterator_hpp.class_template_iterator_construc"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterator_construc" title="Class template iterator constructors">Class + template iterator constructors</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">iterator</span><span class="special">()</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd> +<p> + Initializes its base class with the result of: + </p> +<pre class="programlisting"><span class="identifier">range</span><span class="special"><</span><span class="identifier">NextPolicies</span><span class="special">>(&</span><span class="identifier">iterators</span><span class="special"><</span><span class="identifier">Container</span><span class="special">>::</span><span class="identifier">begin</span><span class="special">,</span> <span class="special">&</span><span class="identifier">iterators</span><span class="special"><</span><span class="identifier">Container</span><span class="special">>::</span><span class="identifier">end</span><span class="special">)</span></pre> +</dd> +<dt><span class="term">Postconditions</span></dt> +<dd><p> + <code class="computeroutput"><span class="keyword">this</span><span class="special">-></span><span class="identifier">get</span><span class="special">()</span></code> + points to a Python callable object which creates a Python iterator + as described above. + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Provides an easy way to create iterators for the common case where + a C++ class being wrapped provides <code class="computeroutput"><span class="identifier">begin</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">end</span><span class="special">()</span></code>. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_iterator_hpp.class_template_iterators"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators" title="Class template iterators">Class + template <code class="computeroutput"><span class="identifier">iterators</span></code></a> +</h3></div></div></div> +<p> + A utility class template which provides a way to reliably call its argument's + <code class="computeroutput"><span class="identifier">begin</span><span class="special">()</span></code> + and <code class="computeroutput"><span class="identifier">end</span><span class="special">()</span></code> + member functions. Note that there is no portable way to take the address + of a member function of a C++ standard library container, so <code class="computeroutput"><span class="identifier">iterators</span><span class="special"><></span></code> + can be particularly helpful when wrapping them. + </p> +<p> + In the table below, x is an instance of C. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Required Valid Expression + </p> + </th> +<th> + <p> + Type + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + x.begin() + </p> + </td> +<td> + <p> + Convertible to C::const_iterator if C is a const type; convertible + to C::iterator otherwise. + </p> + </td> +</tr> +<tr> +<td> + <p> + x.end() + </p> + </td> +<td> + <p> + Convertible to C::const_iterator if C is a const type; convertible + to C::iterator otherwise. + </p> + </td> +</tr> +</tbody> +</table></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">C</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">iterators</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">C</span><span class="special">::</span><span class="identifier">const_iterator</span> <span class="identifier">iterator</span><span class="special">;</span> + <span class="keyword">static</span> <span class="identifier">iterator</span> <span class="identifier">begin</span><span class="special">(</span><span class="identifier">C</span><span class="special">&</span> <span class="identifier">x</span><span class="special">);</span> + <span class="keyword">static</span> <span class="identifier">iterator</span> <span class="identifier">end</span><span class="special">(</span><span class="identifier">C</span><span class="special">&</span> <span class="identifier">x</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_iterator_hpp.class_template_iterators_nested_"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators_nested_" title="Class template iterators nested types">Class + template iterators nested types</a> +</h3></div></div></div> +<p> + If C is a const type, + </p> +<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">C</span><span class="special">::</span><span class="identifier">const_iterator</span> <span class="identifier">iterator</span><span class="special">;</span></pre> +<p> + Otherwise: + </p> +<pre class="programlisting"><span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">C</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">iterator</span><span class="special">;</span></pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_iterator_hpp.class_template_iterators_static_"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators_static_" title="Class template iterators static functions">Class + template iterators static functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">iterator</span> <span class="identifier">begin</span><span class="special">(</span><span class="identifier">C</span><span class="special">&);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">x</span><span class="special">.</span><span class="identifier">begin</span><span class="special">()</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">iterator</span> <span class="identifier">end</span><span class="special">(</span><span class="identifier">C</span><span class="special">&);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">x</span><span class="special">.</span><span class="identifier">end</span><span class="special">()</span></code> + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_iterator_hpp.functions"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.functions" title="Functions">Functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">NextPolicies</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Target</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Accessor1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Accessor2</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">range</span><span class="special">(</span><span class="identifier">Accessor1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Accessor2</span> <span class="identifier">finish</span><span class="special">);</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">NextPolicies</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Accessor1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Accessor2</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">range</span><span class="special">(</span><span class="identifier">Accessor1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Accessor2</span> <span class="identifier">finish</span><span class="special">);</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Accessor1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Accessor2</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">range</span><span class="special">(</span><span class="identifier">Accessor1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Accessor2</span> <span class="identifier">finish</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + NextPolicies is a default-constructible model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd> +<p> + The first form creates a Python callable object which, when invoked, + converts its argument to a Target object x, and creates a Python + iterator which traverses <code class="computeroutput"><span class="special">[</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">start</span><span class="special">,</span><span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">),</span> <span class="identifier">bind</span><span class="special">(</span><span class="identifier">finish</span><span class="special">,</span><span class="identifier">_1</span><span class="special">)(</span><span class="identifier">x</span><span class="special">))</span></code>, + applying NextPolicies to the iterator's <code class="computeroutput"><span class="identifier">next</span><span class="special">()</span></code> function. The second form is identical + to the first, except that Target is deduced from Accessor1 as follows: + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + If Accessor1 is a function type, Target is the type of its first + argument. + </li> +<li class="listitem"> + If Accessor1 is a data member pointer of the form <code class="computeroutput"><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*)</span></code>, + Target is identical to <code class="computeroutput"><span class="identifier">T</span></code>. + </li> +<li class="listitem"> + If Accessor1 is a member function pointer of the form <code class="computeroutput"><span class="identifier">R</span> <span class="special">(</span><span class="identifier">T</span><span class="special">::*)(</span><span class="identifier">arguments</span><span class="special">...)</span> + <span class="identifier">cv</span><span class="special">-</span><span class="identifier">opt</span></code>, where cv-opt is an optional + cv-qualifier, Target is identical to <code class="computeroutput"><span class="identifier">T</span></code>. + </li> +</ol></div> +<p> + The third form is identical to the second, except that NextPolicies + is an unspecified model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a> + which always makes a copy of the result of deferencing the underlying + C++ iterator + </p> +</dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + The use of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">()</span></code> allows C++ iterators to be accessed + through functions, member functions or data member pointers. Customization + of NextPolicies (e.g. using <a class="link" href="../function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r" title="Class template return_internal_reference">return_internal_reference</a>) + is useful when it is expensive to copy sequence elements of a wrapped + class type. Customization of Target is useful when Accessor1 is a + function object, or when a base class of the intended target type + would otherwise be deduced. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_iterator_hpp.example"></a><a class="link" href="boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">vector</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">demo</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">double</span><span class="special">></span> <span class="special">>(</span><span class="string">"dvec"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"__iter__"</span><span class="special">,</span> <span class="identifier">iterator</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">double</span><span class="special">></span> <span class="special">>())</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_init_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_module_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components/boost_python_module_hpp.html b/libs/python/doc/html/reference/high_level_components/boost_python_module_hpp.html new file mode 100644 index 0000000000..c5e0d72a95 --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components/boost_python_module_hpp.html @@ -0,0 +1,111 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/module.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="prev" href="boost_python_iterator_hpp.html" title="boost/python/iterator.hpp"> +<link rel="next" href="boost_python_operators_hpp.html" title="boost/python/operators.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_iterator_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_operators_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_module_hpp"></a><a class="link" href="boost_python_module_hpp.html" title="boost/python/module.hpp">boost/python/module.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.macros">Macros</a></span></dt> +<dt><span class="section"><a href="boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.examples">Examples</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_module_hpp.introduction"></a><a class="link" href="boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + This header provides the basic facilities needed to create a Boost.Python + extension module. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_module_hpp.macros"></a><a class="link" href="boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.macros" title="Macros">Macros</a> +</h3></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></code> + is used to declare Python <a href="http://www.python.org/doc/2.2/ext/methodTable.html#SECTION003400000000000000000" target="_top">module + initialization functions</a>. The name argument must exactly match + the name of the module to be initialized, and must conform to Python's + <a href="http://www.python.org/doc/2.2/ref/identifiers.html" target="_top">identifier + naming rules</a>. Where you would normally write + </p> +<pre class="programlisting"><span class="keyword">extern</span> <span class="string">"C"</span> <span class="keyword">void</span> <span class="identifier">initname</span><span class="special">()</span> +<span class="special">{</span> + <span class="special">...</span> +<span class="special">}</span> +</pre> +<p> + Boost.Python modules should be initialized with + </p> +<pre class="programlisting"><span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span> +<span class="special">{</span> + <span class="special">...</span> +<span class="special">}</span> +</pre> +<p> + This macro generates two functions in the scope where it is used: <code class="computeroutput"><span class="keyword">extern</span> <span class="string">"C"</span> + <span class="keyword">void</span> <span class="identifier">initname</span><span class="special">()</span></code>, and <code class="computeroutput"><span class="keyword">void</span> + <span class="identifier">init_module_name</span><span class="special">()</span></code>, + whose body must follow the macro invocation. <code class="computeroutput"><span class="identifier">init_name</span></code> + passes <code class="computeroutput"><span class="identifier">init_module_name</span></code> + to <a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.functions" title="Functions">handle_exception()</a> + so that any C++ exceptions generated are safely processeed. During the + body of <code class="computeroutput"><span class="identifier">init_name</span></code>, the + <a class="link" href="boost_python_scope_hpp.html" title="boost/python/scope.hpp">current scope</a> + refers to the module being initialized. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_module_hpp.examples"></a><a class="link" href="boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.examples" title="Examples">Examples</a> +</h3></div></div></div> +<p> + C++ module definition: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">xxx</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">throw</span> <span class="string">"something bad happened"</span> +<span class="special">}</span> +</pre> +<p> + Interactive Python: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">import</span> <span class="identifier">xxx</span> +<span class="identifier">Traceback</span> <span class="special">(</span><span class="identifier">most</span> <span class="identifier">recent</span> <span class="identifier">call</span> <span class="identifier">last</span><span class="special">):</span> + <span class="identifier">File</span> <span class="string">""</span><span class="special">,</span> <span class="identifier">line</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">in</span> <span class="special">?</span> +<span class="identifier">RuntimeError</span><span class="special">:</span> <span class="identifier">Unidentifiable</span> <span class="identifier">C</span><span class="special">++</span> <span class="identifier">Exception</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_iterator_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_operators_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components/boost_python_operators_hpp.html b/libs/python/doc/html/reference/high_level_components/boost_python_operators_hpp.html new file mode 100644 index 0000000000..6e0688e4d9 --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components/boost_python_operators_hpp.html @@ -0,0 +1,1558 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/operators.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="prev" href="boost_python_module_hpp.html" title="boost/python/module.hpp"> +<link rel="next" href="boost_python_scope_hpp.html" title="boost/python/scope.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_module_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_scope_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_operators_hpp"></a><a class="link" href="boost_python_operators_hpp.html" title="boost/python/operators.hpp">boost/python/operators.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t">Class + <code class="computeroutput"><span class="identifier">self_ns</span><span class="special">::</span><span class="identifier">self_t</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_template_other">Class + template <code class="computeroutput"><span class="identifier">other</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_template_detail_operator">Class + template <code class="computeroutput"><span class="identifier">detail</span><span class="special">::</span><span class="identifier">operator_</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.object_self">Object + <code class="computeroutput"><span class="identifier">self</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_operators_hpp.introduction"></a><a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/operators.hpp> provides types and functions for automatically + generating Python <a href="http://www.python.org/doc/ref/specialnames.html" target="_top">special + methods</a> from the corresponding C++ constructs. Most of these constructs + are operator expressions, hence the name. To use the facility, substitute + the <a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.object_self" title="Object self">self</a> + object for an object of the class type being wrapped in the expression + to be exposed, and pass the result to <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu" title="Class template class_ modifier functions">class_<>::def()</a>. + Much of what is exposed in this header should be considered part of the + implementation, so is not documented in detail here. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_operators_hpp.class_self_ns_self_t"></a><a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t" title="Class self_ns::self_t">Class + <code class="computeroutput"><span class="identifier">self_ns</span><span class="special">::</span><span class="identifier">self_t</span></code></a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_inplace_operators"><code class="computeroutput"><span class="identifier">self_t</span></code> inplace operators</a></span></dt> +<dt><span class="section"><a href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_comparison_functions"><code class="computeroutput"><span class="identifier">self_t</span></code> comparison functions</a></span></dt> +<dt><span class="section"><a href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_non_member_operations"><code class="computeroutput"><span class="identifier">self_t</span></code> non-member operations</a></span></dt> +<dt><span class="section"><a href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_unary_operations"><code class="computeroutput"><span class="identifier">self_t</span></code> unary operations</a></span></dt> +<dt><span class="section"><a href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_value_operations"><code class="computeroutput"><span class="identifier">self_t</span></code> value operations</a></span></dt> +</dl></div> +<p> + <code class="computeroutput"><span class="identifier">self_ns</span><span class="special">::</span><span class="identifier">self_t</span></code> is the actual type of the <a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.object_self" title="Object self">self</a> + object. The library isolates <code class="computeroutput"><span class="identifier">self_t</span></code> + in its own namespace, <code class="computeroutput"><span class="identifier">self_ns</span></code>, + in order to prevent the generalized operator templates which operate on + it from being found by argument-dependent lookup in other contexts. This + should be considered an implementation detail, since users should never + have to mention <code class="computeroutput"><span class="identifier">self_t</span></code> + directly. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">self_ns</span> <span class="special">{</span> +<span class="special">{</span> + <span class="identifier">unspecified</span><span class="special">-</span><span class="identifier">type</span><span class="special">-</span><span class="identifier">declaration</span> <span class="identifier">self_t</span><span class="special">;</span> + + <span class="comment">// inplace operators</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">+=(</span><span class="identifier">self_t</span><span class="special">,</span> <span class="identifier">T</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">-=(</span><span class="identifier">self_t</span><span class="special">,</span> <span class="identifier">T</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">*=(</span><span class="identifier">self_t</span><span class="special">,</span> <span class="identifier">T</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">/=(</span><span class="identifier">self_t</span><span class="special">,</span> <span class="identifier">T</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">%=(</span><span class="identifier">self_t</span><span class="special">,</span> <span class="identifier">T</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">>>=(</span><span class="identifier">self_t</span><span class="special">,</span> <span class="identifier">T</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special"><<=(</span><span class="identifier">self_t</span><span class="special">,</span> <span class="identifier">T</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">&=(</span><span class="identifier">self_t</span><span class="special">,</span> <span class="identifier">T</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">^=(</span><span class="identifier">self_t</span><span class="special">,</span> <span class="identifier">T</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">|=(</span><span class="identifier">self_t</span><span class="special">,</span> <span class="identifier">T</span><span class="special">);</span> + + <span class="comment">// comparisons</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">==(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">!=(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special"><(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">>(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special"><=(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">>=(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + + <span class="comment">// non-member operations</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">+(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">-(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">*(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">/(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">%(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">>>(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special"><<(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">&(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">^(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">|(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="identifier">pow</span><span class="special">(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&);</span> + + <span class="comment">// unary operations</span> + <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">-(</span><span class="identifier">self_t</span><span class="special">);</span> + <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">+(</span><span class="identifier">self_t</span><span class="special">);</span> + <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">~(</span><span class="identifier">self_t</span><span class="special">);</span> + <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="keyword">operator</span><span class="special">!(</span><span class="identifier">self_t</span><span class="special">);</span> + + <span class="comment">// value operations</span> + <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="identifier">int_</span><span class="special">(</span><span class="identifier">self_t</span><span class="special">);</span> + <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="identifier">long_</span><span class="special">(</span><span class="identifier">self_t</span><span class="special">);</span> + <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="identifier">float_</span><span class="special">(</span><span class="identifier">self_t</span><span class="special">);</span> + <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="identifier">complex_</span><span class="special">(</span><span class="identifier">self_t</span><span class="special">);</span> + <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="identifier">str</span><span class="special">(</span><span class="identifier">self_t</span><span class="special">);</span> + + <span class="identifier">operator_</span><span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> <span class="identifier">repr</span><span class="special">(</span><span class="identifier">self_t</span><span class="special">);</span> +<span class="special">}}};</span> +</pre> +<p> + The tables below describe the methods generated when the results of the + expressions described are passed as arguments to <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu" title="Class template class_ modifier functions">class_<>::def()</a>. + <code class="computeroutput"><span class="identifier">x</span></code> is an object of the class + type being wrapped. + </p> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_inplace_operators"></a><a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_inplace_operators" title="self_t inplace operators"><code class="computeroutput"><span class="identifier">self_t</span></code> inplace operators</a> +</h4></div></div></div> +<p> + In the table below, If <code class="computeroutput"><span class="identifier">r</span></code> + is an object of type <a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_template_other" title="Class template other">other<T></a>, + <code class="computeroutput"><span class="identifier">y</span></code> is an object of type + <code class="computeroutput"><span class="identifier">T</span></code>; otherwise, <code class="computeroutput"><span class="identifier">y</span></code> is an object of the same type as + <code class="computeroutput"><span class="identifier">r</span></code>. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + C++ Expression + </p> + </th> +<th> + <p> + Python Method Name + </p> + </th> +<th> + <p> + C++ Implementation + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">+=</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__iadd__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">+=</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">-=</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__isub__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">-=</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">*=</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__imul__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">*=</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">/=</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__idiv__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">/=</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">%=</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__imod__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">%=</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">>>=</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__irshift__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">>>=</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special"><<=</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__ilshift__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special"><<=</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">&=</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__iand__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">&=</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">^=</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__ixor__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">^=</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">|=</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__ior__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">|=</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +</tbody> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_comparison_functions"></a><a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_comparison_functions" title="self_t comparison functions"><code class="computeroutput"><span class="identifier">self_t</span></code> comparison functions</a> +</h4></div></div></div> +<p> + In the tables below, if <code class="computeroutput"><span class="identifier">r</span></code> + is of type <a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t" title="Class self_ns::self_t">self_t</a>, + <code class="computeroutput"><span class="identifier">y</span></code> is an object of the + same type as <code class="computeroutput"><span class="identifier">x</span></code>; if <code class="computeroutput"><span class="identifier">l</span></code> or <code class="computeroutput"><span class="identifier">r</span></code> + is an object of type <a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_template_other" title="Class template other">other<T></a>, + <code class="computeroutput"><span class="identifier">y</span></code> is an object of type + <code class="computeroutput"><span class="identifier">T</span></code>; otherwise, <code class="computeroutput"><span class="identifier">y</span></code> is an object of the same type as + <code class="computeroutput"><span class="identifier">l</span></code> or <code class="computeroutput"><span class="identifier">r</span></code>. + <code class="computeroutput"><span class="identifier">l</span></code> is never of type <a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t" title="Class self_ns::self_t">self_t</a>. + </p> +<p> + The column of Python Expressions illustrates the expressions that will + be supported in Python for objects convertible to the types of x and + y. The secondary operation arises due to Python's <a href="http://www.python.org/doc/ref/customization.html#l2h-89" target="_top">reflection + rules</a> for rich comparison operators, and are only used when the + corresponding operation is not defined as a method of the y object. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + C++ Expression + </p> + </th> +<th> + <p> + Python Method Name + </p> + </th> +<th> + <p> + C++ Implementation + </p> + </th> +<th> + <p> + Python Expression (primary, secondary) + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">==</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__eq__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">==</span> + <span class="identifier">y</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">==</span> + <span class="identifier">y</span></code>, <code class="computeroutput"><span class="identifier">y</span> <span class="special">==</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special">==</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__eq__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">==</span> + <span class="identifier">x</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">==</span> + <span class="identifier">x</span></code>, <code class="computeroutput"><span class="identifier">x</span> <span class="special">==</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">!=</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__nq__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">!=</span> + <span class="identifier">y</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">!=</span> + <span class="identifier">y</span></code>, <code class="computeroutput"><span class="identifier">y</span> <span class="special">!=</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special">!=</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__nq__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">!=</span> + <span class="identifier">x</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">!=</span> + <span class="identifier">x</span></code>, <code class="computeroutput"><span class="identifier">x</span> <span class="special">!=</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special"><</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__lt__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special"><</span> + <span class="identifier">y</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special"><</span> + <span class="identifier">y</span></code>, <code class="computeroutput"><span class="identifier">y</span> <span class="special">></span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special"><</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__gt__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special"><</span> + <span class="identifier">x</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">></span> + <span class="identifier">x</span></code>, <code class="computeroutput"><span class="identifier">x</span> <span class="special"><</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">></span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__gt__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">></span> + <span class="identifier">y</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">></span> + <span class="identifier">y</span></code>, <code class="computeroutput"><span class="identifier">y</span> <span class="special"><</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special">></span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__lt__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">></span> + <span class="identifier">x</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special"><</span> + <span class="identifier">x</span></code>, <code class="computeroutput"><span class="identifier">x</span> <span class="special">></span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special"><=</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__le__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special"><=</span> + <span class="identifier">y</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special"><=</span> + <span class="identifier">y</span></code>, <code class="computeroutput"><span class="identifier">y</span> <span class="special">>=</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special"><=</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__ge__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special"><=</span> + <span class="identifier">x</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">>=</span> + <span class="identifier">x</span></code>, <code class="computeroutput"><span class="identifier">x</span> <span class="special"><=</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">>=</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__ge__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">>=</span> + <span class="identifier">y</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">>=</span> + <span class="identifier">y</span></code>, <code class="computeroutput"><span class="identifier">y</span> <span class="special"><=</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special"><=</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__le__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">>=</span> + <span class="identifier">x</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special"><=</span> + <span class="identifier">x</span></code>, <code class="computeroutput"><span class="identifier">x</span> <span class="special">>=</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +</tbody> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_non_member_operations"></a><a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_non_member_operations" title="self_t non-member operations"><code class="computeroutput"><span class="identifier">self_t</span></code> non-member operations</a> +</h4></div></div></div> +<p> + The operations whose names begin with "__r" below will only + be called if the left-hand operand does not already support the given + operation, as described <a href="http://www.python.org/doc/current/ref/numeric-types.html#l2h-152" target="_top">here</a>. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + C++ Expression + </p> + </th> +<th> + <p> + Python Method Name + </p> + </th> +<th> + <p> + C++ Implementation + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">+</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__add__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">+</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special">+</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__radd__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">+</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">-</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__sub__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">-</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special">-</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__rsub__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">-</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">*</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__mult__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">*</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special">*</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__rmult__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">*</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">/</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__div__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">/</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special">/</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__rdiv__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">/</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">%</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__mod__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">%</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special">%</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__rmod__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">%</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">>></span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__rshift__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">>></span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special">>></span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__rrshift__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">>></span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special"><<</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__lshift__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special"><<</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special"><<</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__rlshift__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special"><<</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">&</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__and__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">&</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special">&</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__rand__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">&</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">^</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__xor__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">^</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special">^</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__rxor__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">^</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">self</span> <span class="special">|</span> + <span class="identifier">r</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__or__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">|</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">l</span> <span class="special">|</span> + <span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__ror__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">|</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">pow</span><span class="special">(</span><span class="identifier">self</span><span class="special">,</span> + <span class="identifier">r</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__pow__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">x</span> <span class="special">**</span> + <span class="identifier">y</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">pow</span><span class="special">(</span><span class="identifier">l</span><span class="special">,</span> + <span class="identifier">self</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__rpow__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">y</span> <span class="special">**</span> + <span class="identifier">x</span></code> + </p> + </td> +</tr> +</tbody> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_unary_operations"></a><a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_unary_operations" title="self_t unary operations"><code class="computeroutput"><span class="identifier">self_t</span></code> unary operations</a> +</h4></div></div></div> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + C++ Expression + </p> + </th> +<th> + <p> + Python Method Name + </p> + </th> +<th> + <p> + C++ Implementation + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + <code class="computeroutput"><span class="special">-</span><span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__neg__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="special">-</span><span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="special">+</span><span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__pos__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="special">+</span><span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="special">~</span><span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__invert__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="special">~</span><span class="identifier">x</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="keyword">not</span> <span class="identifier">self</span></code> + or <code class="computeroutput"><span class="special">!</span><span class="identifier">self</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__nonzero__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="special">!!</span><span class="identifier">x</span></code> + </p> + </td> +</tr> +</tbody> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_value_operations"></a><a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t.self_t_value_operations" title="self_t value operations"><code class="computeroutput"><span class="identifier">self_t</span></code> value operations</a> +</h4></div></div></div> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + C++ Expression + </p> + </th> +<th> + <p> + Python Method Name + </p> + </th> +<th> + <p> + C++ Implementation + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">int_</span><span class="special">(</span><span class="identifier">self</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__int__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="keyword">long</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">long_</span><span class="special">(</span><span class="identifier">self</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__long__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">PyLong_FromLong</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">float_</span><span class="special">(</span><span class="identifier">self</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__float__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="keyword">double</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">complex_</span><span class="special">(</span><span class="identifier">self</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__complex__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">complex</span><span class="special"><</span><span class="keyword">double</span><span class="special">>(</span><span class="identifier">x</span><span class="special">)</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">str</span><span class="special">(</span><span class="identifier">self</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__str__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">lexical_cast</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">>(</span><span class="identifier">x</span><span class="special">)</span></code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">repr</span><span class="special">(</span><span class="identifier">self</span><span class="special">)</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">__repr__</span></code> + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">lexical_cast</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">>(</span><span class="identifier">x</span><span class="special">)</span></code> + </p> + </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_operators_hpp.class_template_other"></a><a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_template_other" title="Class template other">Class + template <code class="computeroutput"><span class="identifier">other</span></code></a> +</h3></div></div></div> +<p> + Instances of <code class="computeroutput"><span class="identifier">other</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> + can be used in operator expressions with <a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.object_self" title="Object self">self</a>; + the result is equivalent to the same expression with a <code class="computeroutput"><span class="identifier">T</span></code> + object in place of <code class="computeroutput"><span class="identifier">other</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>. Use <code class="computeroutput"><span class="identifier">other</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> to prevent construction of a <code class="computeroutput"><span class="identifier">T</span></code> object in case it is heavyweight, when + no constructor is available, or simply for clarity. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">other</span> + <span class="special">{</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_operators_hpp.class_template_detail_operator"></a><a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_template_detail_operator" title="Class template detail::operator_">Class + template <code class="computeroutput"><span class="identifier">detail</span><span class="special">::</span><span class="identifier">operator_</span></code></a> +</h3></div></div></div> +<p> + Instantiations of <code class="computeroutput"><span class="identifier">detail</span><span class="special">::</span><span class="identifier">operator_</span><span class="special"><></span></code> are used as the return type of + operator expressions involving <a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.object_self" title="Object self">self</a>. + This should be considered an implementation detail and is only documented + here as a way of showing how the result of self-expressions match calls + to <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu" title="Class template class_ modifier functions"><code class="computeroutput"><span class="identifier">class_</span><span class="special"><>::</span><span class="identifier">def</span><span class="special">()</span></code></a>. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">detail</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="identifier">unspecified</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">operator_</span> + <span class="special">{</span> + <span class="special">};</span> +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_operators_hpp.object_self"></a><a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.object_self" title="Object self">Object + <code class="computeroutput"><span class="identifier">self</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">using</span> <span class="identifier">self_ns</span><span class="special">::</span><span class="identifier">self</span><span class="special">;</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_operators_hpp.example"></a><a class="link" href="boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">operators</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">operators</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">struct</span> <span class="identifier">number</span> + <span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">integer_arithmetic</span><span class="special"><</span><span class="identifier">number</span><span class="special">></span> +<span class="special">{</span> + <span class="keyword">explicit</span> <span class="identifier">number</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">x_</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">x</span><span class="special">(</span><span class="identifier">x_</span><span class="special">)</span> <span class="special">{}</span> + <span class="keyword">operator</span> <span class="keyword">long</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">number</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">+=(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">)</span> + <span class="special">{</span> <span class="identifier">x</span> <span class="special">+=</span> <span class="identifier">rhs</span><span class="special">;</span> <span class="keyword">return</span> <span class="special">*</span><span class="keyword">this</span><span class="special">;</span> <span class="special">}</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">number</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">-=(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">)</span> + <span class="special">{</span> <span class="identifier">x</span> <span class="special">-=</span> <span class="identifier">rhs</span><span class="special">;</span> <span class="keyword">return</span> <span class="special">*</span><span class="keyword">this</span><span class="special">;</span> <span class="special">}</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">number</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">*=(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">)</span> + <span class="special">{</span> <span class="identifier">x</span> <span class="special">*=</span> <span class="identifier">rhs</span><span class="special">;</span> <span class="keyword">return</span> <span class="special">*</span><span class="keyword">this</span><span class="special">;</span> <span class="special">}</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">number</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">/=(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">)</span> + <span class="special">{</span> <span class="identifier">x</span> <span class="special">/=</span> <span class="identifier">rhs</span><span class="special">;</span> <span class="keyword">return</span> <span class="special">*</span><span class="keyword">this</span><span class="special">;</span> <span class="special">}</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">number</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">%=(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">)</span> + <span class="special">{</span> <span class="identifier">x</span> <span class="special">%=</span> <span class="identifier">rhs</span><span class="special">;</span> <span class="keyword">return</span> <span class="special">*</span><span class="keyword">this</span><span class="special">;</span> <span class="special">}</span> + + <span class="keyword">long</span> <span class="identifier">x</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">demo</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">number</span><span class="special">>(</span><span class="string">"number"</span><span class="special">,</span> <span class="identifier">init</span><span class="special"><</span><span class="keyword">long</span><span class="special">>())</span> + <span class="comment">// interoperate with self</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">+=</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">+</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">-=</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">-</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">*=</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">*</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">/=</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">/</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">%=</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">%</span> <span class="identifier">self</span><span class="special">)</span> + + <span class="comment">// Convert to Python int</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">int_</span><span class="special">(</span><span class="identifier">self</span><span class="special">))</span> + + <span class="comment">// interoperate with long</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">+=</span> <span class="keyword">long</span><span class="special">())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">+</span> <span class="keyword">long</span><span class="special">())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="keyword">long</span><span class="special">()</span> <span class="special">+</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">-=</span> <span class="keyword">long</span><span class="special">())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">-</span> <span class="keyword">long</span><span class="special">())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="keyword">long</span><span class="special">()</span> <span class="special">-</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">*=</span> <span class="keyword">long</span><span class="special">())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">*</span> <span class="keyword">long</span><span class="special">())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="keyword">long</span><span class="special">()</span> <span class="special">*</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">/=</span> <span class="keyword">long</span><span class="special">())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">/</span> <span class="keyword">long</span><span class="special">())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="keyword">long</span><span class="special">()</span> <span class="special">/</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">%=</span> <span class="keyword">long</span><span class="special">())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">self</span> <span class="special">%</span> <span class="keyword">long</span><span class="special">())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="keyword">long</span><span class="special">()</span> <span class="special">%</span> <span class="identifier">self</span><span class="special">)</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_module_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_scope_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components/boost_python_scope_hpp.html b/libs/python/doc/html/reference/high_level_components/boost_python_scope_hpp.html new file mode 100644 index 0000000000..966bfe48d8 --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components/boost_python_scope_hpp.html @@ -0,0 +1,160 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/scope.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="prev" href="boost_python_operators_hpp.html" title="boost/python/operators.hpp"> +<link rel="next" href="boost_python_stl_iterator_hpp.html" title="boost/python/stl_iterator.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_operators_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_stl_iterator_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_scope_hpp"></a><a class="link" href="boost_python_scope_hpp.html" title="boost/python/scope.hpp">boost/python/scope.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.class_scope">Class + <code class="computeroutput"><span class="identifier">scope</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.class_scope_constructors_and_des">Class + scope constructors and destructor</a></span></dt> +<dt><span class="section"><a href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_scope_hpp.introduction"></a><a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Defines facilities for querying and controlling the Python scope (namespace) + which will contain new wrapped classes and functions. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_scope_hpp.class_scope"></a><a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.class_scope" title="Class scope">Class + <code class="computeroutput"><span class="identifier">scope</span></code></a> +</h3></div></div></div> +<p> + 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 + it to the associated global Python object. Constructing a scope object + with an argument changes the associated global Python object to the one + held by the argument, until the lifetime of the scope object ends, at which + time the associated global Python object reverts to what it was before + the scope object was constructed. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">scope</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">scope</span><span class="special">(</span><span class="identifier">scope</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="identifier">scope</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="identifier">scope</span><span class="special">();</span> + <span class="special">~</span><span class="identifier">scope</span><span class="special">()</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">=(</span><span class="identifier">scope</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_scope_hpp.class_scope_constructors_and_des"></a><a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.class_scope_constructors_and_des" title="Class scope constructors and destructor">Class + scope constructors and destructor</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">scope</span><span class="special">(</span><span class="identifier">scope</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">);</span> +<span class="keyword">explicit</span> <span class="identifier">scope</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">);</span> +</pre> +<p> + 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. + </p> +<pre class="programlisting"><span class="identifier">scope</span><span class="special">();</span></pre> +<p> + 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. + </p> +<pre class="programlisting"><span class="special">~</span><span class="identifier">scope</span><span class="special">()</span></pre> +<p> + Sets the current associated Python object to the stored object. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_scope_hpp.example"></a><a class="link" href="boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<p> + The following example shows how scope setting can be used to define nested + classes. + </p> +<p> + C++ Module definition: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">scope</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="keyword">void</span> <span class="identifier">f</span><span class="special">()</span> <span class="special">{}</span> + + <span class="keyword">struct</span> <span class="identifier">Y</span> <span class="special">{</span> <span class="keyword">int</span> <span class="identifier">g</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="number">42</span><span class="special">;</span> <span class="special">}</span> <span class="special">};</span> +<span class="special">};</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">nested</span><span class="special">)</span> +<span class="special">{</span> + <span class="comment">// add some constants to the current (module) scope</span> + <span class="identifier">scope</span><span class="special">().</span><span class="identifier">attr</span><span class="special">(</span><span class="string">"yes"</span><span class="special">)</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> + <span class="identifier">scope</span><span class="special">().</span><span class="identifier">attr</span><span class="special">(</span><span class="string">"no"</span><span class="special">)</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> + + <span class="comment">// Change the current scope </span> + <span class="identifier">scope</span> <span class="identifier">outer</span> + <span class="special">=</span> <span class="identifier">class_</span><span class="special"><</span><span class="identifier">X</span><span class="special">>(</span><span class="string">"X"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">)</span> + <span class="special">;</span> + + <span class="comment">// Define a class Y in the current scope, X</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">Y</span><span class="special">>(</span><span class="string">"Y"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"g"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">Y</span><span class="special">::</span><span class="identifier">g</span><span class="special">)</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + Interactive Python: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">import</span> <span class="identifier">nested</span> +<span class="special">>>></span> <span class="identifier">nested</span><span class="special">.</span><span class="identifier">yes</span> +<span class="number">1</span> +<span class="special">>>></span> <span class="identifier">y</span> <span class="special">=</span> <span class="identifier">nested</span><span class="special">.</span><span class="identifier">X</span><span class="special">.</span><span class="identifier">Y</span><span class="special">()</span> +<span class="special">>>></span> <span class="identifier">y</span><span class="special">.</span><span class="identifier">g</span><span class="special">()</span> +<span class="number">42</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_operators_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_stl_iterator_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components/boost_python_stl_iterator_hpp.html b/libs/python/doc/html/reference/high_level_components/boost_python_stl_iterator_hpp.html new file mode 100644 index 0000000000..850387b1f3 --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components/boost_python_stl_iterator_hpp.html @@ -0,0 +1,311 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/stl_iterator.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="prev" href="boost_python_scope_hpp.html" title="boost/python/scope.hpp"> +<link rel="next" href="boost_python_wrapper_hpp.html" title="boost/python/wrapper.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_scope_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_wrapper_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_stl_iterator_hpp"></a><a class="link" href="boost_python_stl_iterator_hpp.html" title="boost/python/stl_iterator.hpp">boost/python/stl_iterator.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterato">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat0">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code> + constructors</a></span></dt> +<dt><span class="section"><a href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat1">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code> + modifiers</a></span></dt> +<dt><span class="section"><a href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat2">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code> + observers</a></span></dt> +<dt><span class="section"><a href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_stl_iterator_hpp.introduction"></a><a class="link" href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/stl_iterator.hpp> provides types for creating C++ Iterators + from <a href="http://www.python.org/doc/current/lib/typeiter.html" target="_top">Python + iterables</a>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterato"></a><a class="link" href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterato" title="Class template stl_input_iterator">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code></a> +</h3></div></div></div> +<p> + Instances of <code class="computeroutput"><span class="identifier">stl_input_iterator</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> hold a Python iterator and adapt it + for use with STL algorithms. <code class="computeroutput"><span class="identifier">stl_input_iterator</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> satisfies the requirements for an Input + Iterator. + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Template Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Semantics + </p> + </th> +<th> + <p> + Default + </p> + </th> +</tr></thead> +<tbody><tr> +<td> + <p> + ValueType + </p> + </td> +<td> + <p> + ValueType must be CopyConstructible. + </p> + </td> +<td> + <p> + Dereferencing an instance of <code class="computeroutput"><span class="identifier">stl_input_iterator</span><span class="special"><</span><span class="identifier">ValueType</span><span class="special">></span></code> will return an rvalue of + type ValueType. + </p> + </td> +<td> + <p> + None + </p> + </td> +</tr></tbody> +</table></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">ValueType</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">stl_input_iterator</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ptrdiff_t</span> <span class="identifier">difference_type</span><span class="special">;</span> + <span class="keyword">typedef</span> <span class="identifier">ValueType</span> <span class="identifier">value_type</span><span class="special">;</span> + <span class="keyword">typedef</span> <span class="identifier">ValueType</span><span class="special">*</span> <span class="identifier">pointer</span><span class="special">;</span> + <span class="keyword">typedef</span> <span class="identifier">ValueType</span> <span class="identifier">reference</span><span class="special">;</span> + <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">input_iterator_tag</span> <span class="identifier">iterator_category</span><span class="special">;</span> + + <span class="identifier">stl_input_iterator</span><span class="special">();</span> + <span class="identifier">stl_input_iterator</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">ob</span><span class="special">);</span> + + <span class="identifier">stl_input_iterator</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">++();</span> + <span class="identifier">stl_input_iterator</span> <span class="keyword">operator</span><span class="special">++(</span><span class="keyword">int</span><span class="special">);</span> + + <span class="identifier">ValueType</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">friend</span> <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">==(</span><span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">lhs</span><span class="special">,</span> <span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> + <span class="keyword">friend</span> <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">!=(</span><span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">lhs</span><span class="special">,</span> <span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="identifier">object</span> <span class="identifier">it</span><span class="special">;</span> <span class="comment">// For exposition only</span> + <span class="identifier">object</span> <span class="identifier">ob</span><span class="special">;</span> <span class="comment">// For exposition only</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat0"></a><a class="link" href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat0" title="Class template stl_input_iterator constructors">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code> + constructors</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">stl_input_iterator</span><span class="special">()</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Creates a past-the-end input iterator, useful for signifying the + end of a sequence. + </p></dd> +<dt><span class="term">Postconditions</span></dt> +<dd><p> + <code class="computeroutput"><span class="keyword">this</span></code> is past-the-end + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + Nothing. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">stl_input_iterator</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">ob</span><span class="special">)</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Calls ob.attr("__iter__")() and stores the resulting Python + iterator object in this->it. Then, calls this->it.attr("next")() + and stores the result in this->ob. If the sequence is exhausted, + sets this->ob to object(). + </p></dd> +<dt><span class="term">Postconditions</span></dt> +<dd><p> + this is a dereferenceable or past-the-end. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat1"></a><a class="link" href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat1" title="Class template stl_input_iterator modifiers">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code> + modifiers</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">stl_input_iterator</span> <span class="special">&</span><span class="keyword">operator</span><span class="special">++()</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Calls this->it.attr("next")() and stores the result + in this->ob. If the sequence is exhausted, sets this->ob to + object(). + </p></dd> +<dt><span class="term">Postconditions</span></dt> +<dd><p> + this is a dereferenceable or past-the-end. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">stl_input_iterator</span> <span class="special">&</span><span class="keyword">operator</span><span class="special">++(</span><span class="keyword">int</span><span class="special">)</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">stl_input_iterator</span> <span class="identifier">tmp</span> <span class="special">=</span> + <span class="special">*</span><span class="keyword">this</span><span class="special">;</span> <span class="special">++*</span><span class="keyword">this</span><span class="special">;</span> <span class="keyword">return</span> <span class="identifier">tmp</span><span class="special">;</span></code> + </p></dd> +<dt><span class="term">Postconditions</span></dt> +<dd><p> + this is a dereferenceable or past-the-end. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat2"></a><a class="link" href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat2" title="Class template stl_input_iterator observers">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code> + observers</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">ValueType</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Returns the current element in the sequence. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">extract</span><span class="special"><</span><span class="identifier">ValueType</span><span class="special">>(</span><span class="keyword">this</span><span class="special">-></span><span class="identifier">ob</span><span class="special">);</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">friend</span> <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">==(</span><span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">lhs</span><span class="special">,</span> <span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">)</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Returns true if both iterators are dereferenceable or if both iterators + are past-the-end, false otherwise. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">(</span><span class="identifier">lhs</span><span class="special">.</span><span class="identifier">ob</span> <span class="special">==</span> <span class="identifier">object</span><span class="special">())</span> <span class="special">==</span> <span class="special">(</span><span class="identifier">rhs</span><span class="special">.</span><span class="identifier">ob</span> <span class="special">==</span> <span class="identifier">object</span><span class="special">())</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">friend</span> <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">!=(</span><span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">lhs</span><span class="special">,</span> <span class="identifier">stl_input_iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">)</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Returns false if both iterators are dereferenceable or if both iterators + are past-the-end, true otherwise. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">!(</span><span class="identifier">lhs</span> + <span class="special">==</span> <span class="identifier">rhs</span><span class="special">)</span></code> + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_stl_iterator_hpp.example"></a><a class="link" href="boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">object</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">stl_iterator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">list</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">sequence_to_int_list</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">ob</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">stl_input_iterator</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">begin</span><span class="special">(</span><span class="identifier">ob</span><span class="special">),</span> <span class="identifier">end</span><span class="special">;</span> + <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">begin</span><span class="special">,</span> <span class="identifier">end</span><span class="special">);</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_scope_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_wrapper_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/high_level_components/boost_python_wrapper_hpp.html b/libs/python/doc/html/reference/high_level_components/boost_python_wrapper_hpp.html new file mode 100644 index 0000000000..dac3c40bb8 --- /dev/null +++ b/libs/python/doc/html/reference/high_level_components/boost_python_wrapper_hpp.html @@ -0,0 +1,222 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/wrapper.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../high_level_components.html" title="Chapter 2. High Level Components"> +<link rel="prev" href="boost_python_stl_iterator_hpp.html" title="boost/python/stl_iterator.hpp"> +<link rel="next" href="../object_wrappers.html" title="Chapter 3. Object Wrappers"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_stl_iterator_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../object_wrappers.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="high_level_components.boost_python_wrapper_hpp"></a><a class="link" href="boost_python_wrapper_hpp.html" title="boost/python/wrapper.hpp">boost/python/wrapper.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_override">Class + <code class="computeroutput"><span class="identifier">override</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_override_observer_function">Class + <code class="computeroutput"><span class="identifier">override</span></code> observer functions</a></span></dt> +<dt><span class="section"><a href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper">Class + template <code class="computeroutput"><span class="identifier">wrapper</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper_observer_">Class + template <code class="computeroutput"><span class="identifier">wrapper</span></code> observer + functions</a></span></dt> +<dt><span class="section"><a href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_wrapper_hpp.introduction"></a><a class="link" href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + To wrap a class T such that its virtual functions can be "overridden + in Python"—so that the corresponding method of a Python derived + class will be called when the virtual function is invoked from C++—you + must create a C++ wrapper class derived from <code class="computeroutput"><span class="identifier">T</span></code> + that overrides those virtual functions so that they call into Python. This + header contains classes that can be used to make that job easier. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_wrapper_hpp.class_override"></a><a class="link" href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_override" title="Class override">Class + <code class="computeroutput"><span class="identifier">override</span></code></a> +</h3></div></div></div> +<p> + Encapsulates a Python override of a C++ virtual function. An override object + either holds a callable Python object or <code class="computeroutput"><span class="identifier">None</span></code>. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">override</span> <span class="special">:</span> <span class="identifier">object</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">></span> + <span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">(</span><span class="identifier">A0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> + <span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">(</span><span class="identifier">A0</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="special">...</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="special">...</span><span class="keyword">class</span> <span class="identifier">An</span><span class="special">></span> + <span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">(</span><span class="identifier">A0</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">,</span> <span class="special">...</span><span class="identifier">An</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">};</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_wrapper_hpp.class_override_observer_function"></a><a class="link" href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_override_observer_function" title="Class override observer functions">Class + <code class="computeroutput"><span class="identifier">override</span></code> observer functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">></span> +<span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">(</span><span class="identifier">A0</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> +<span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">(</span><span class="identifier">A0</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="special">...</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,</span> <span class="special">...</span><span class="keyword">class</span> <span class="identifier">An</span><span class="special">></span> +<span class="identifier">unspecified</span> <span class="keyword">operator</span><span class="special">(</span><span class="identifier">A0</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">,</span> <span class="special">...</span><span class="identifier">An</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + If *this holds a callable Python object, it is invoked with the specified + arguments in the manner specified here. Otherwise, throws <a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a>. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An object of unspecified type that holds the Python result of the + invocation and, when converted to a C++ type R, attempts to convert + that result object to R. If that conversion fails, throws <a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a>. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_wrapper_hpp.class_template_wrapper"></a><a class="link" href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper" title="Class template wrapper">Class + template <code class="computeroutput"><span class="identifier">wrapper</span></code></a> +</h3></div></div></div> +<p> + Deriving your wrapper class from both <code class="computeroutput"><span class="identifier">T</span></code> + and <code class="computeroutput"><span class="identifier">wrapper</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> + makes writing that derived class easier. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">wrapper</span> + <span class="special">{</span> + <span class="keyword">protected</span><span class="special">:</span> + <span class="identifier">override</span> <span class="identifier">get_override</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">};</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_wrapper_hpp.class_template_wrapper_observer_"></a><a class="link" href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper_observer_" title="Class template wrapper observer functions">Class + template <code class="computeroutput"><span class="identifier">wrapper</span></code> observer + functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">override</span> <span class="identifier">get_override</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + name is a <a class="link" href="../glossary.html#ntbs">ntbs</a>. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + If <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + is the C++ base class subobject of a Python derived class instance + that overrides the named function, returns an override object that + delegates to the Python override. Otherwise, returns an override + object that holds <code class="computeroutput"><span class="identifier">None</span></code>. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="high_level_components.boost_python_wrapper_hpp.example"></a><a class="link" href="boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">wrapper</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">call</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="comment">// Class with one pure virtual function</span> +<span class="keyword">struct</span> <span class="identifier">P</span> +<span class="special">{</span> + <span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">P</span><span class="special">(){}</span> + <span class="keyword">virtual</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">f</span><span class="special">()</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> + <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">g</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"P::g()"</span><span class="special">;</span> <span class="special">}</span> +<span class="special">};</span> + +<span class="keyword">struct</span> <span class="identifier">PCallback</span> <span class="special">:</span> <span class="identifier">P</span><span class="special">,</span> <span class="identifier">wrapper</span><span class="special"><</span><span class="identifier">P</span><span class="special">></span> +<span class="special">{</span> + <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">f</span><span class="special">()</span> + <span class="special">{</span> + <span class="keyword">return</span> <span class="keyword">this</span><span class="special">-></span><span class="identifier">get_override</span><span class="special">(</span><span class="string">"f"</span><span class="special">)();</span> + <span class="special">}</span> +<span class="special">};</span> + +<span class="comment">// Class with one non-pure virtual function</span> +<span class="keyword">struct</span> <span class="identifier">A</span> +<span class="special">{</span> + <span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">A</span><span class="special">(){}</span> + <span class="keyword">virtual</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">f</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"A::f()"</span><span class="special">;</span> <span class="special">}</span> +<span class="special">};</span> + +<span class="keyword">struct</span> <span class="identifier">ACallback</span> <span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">wrapper</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span> +<span class="special">{</span> + <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">f</span><span class="special">()</span> + <span class="special">{</span> + <span class="keyword">if</span> <span class="special">(</span><span class="identifier">override</span> <span class="identifier">f</span> <span class="special">=</span> <span class="keyword">this</span><span class="special">-></span><span class="identifier">get_override</span><span class="special">(</span><span class="string">"f"</span><span class="special">))</span> + <span class="keyword">return</span> <span class="identifier">f</span><span class="special">();</span> + <span class="keyword">return</span> <span class="identifier">A</span><span class="special">::</span><span class="identifier">f</span><span class="special">();</span> + <span class="special">}</span> + + <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">default_f</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">this</span><span class="special">-></span><span class="identifier">A</span><span class="special">::</span><span class="identifier">f</span><span class="special">();</span> <span class="special">}</span> +<span class="special">};</span> + +<span class="identifier">BOOST_PYTHON_MODULE_INIT</span><span class="special">(</span><span class="identifier">polymorphism</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">PCallback</span><span class="special">,</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">noncopyable</span><span class="special">>(</span><span class="string">"P"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">pure_virtual</span><span class="special">(&</span><span class="identifier">P</span><span class="special">::</span><span class="identifier">f</span><span class="special">))</span> + <span class="special">;</span> + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">ACallback</span><span class="special">,</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">noncopyable</span><span class="special">>(</span><span class="string">"A"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">A</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="special">&</span><span class="identifier">ACallback</span><span class="special">::</span><span class="identifier">default_f</span><span class="special">)</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_stl_iterator_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../object_wrappers.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/index.html b/libs/python/doc/html/reference/index.html new file mode 100644 index 0000000000..9dd9a84581 --- /dev/null +++ b/libs/python/doc/html/reference/index.html @@ -0,0 +1,639 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Boost.Python Reference Manual</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python Reference Manual"> +<link rel="next" href="concepts.html" title="Chapter 1. Concepts"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"><a accesskey="n" href="concepts.html"><img src="../images/next.png" alt="Next"></a></div> +<div class="book"> +<div class="titlepage"> +<div> +<div><h1 class="title"> +<a name="reference"></a>Boost.Python Reference Manual</h1></div> +<div><div class="authorgroup"> +<div class="author"><h3 class="author"> +<span class="firstname">David</span> <span class="surname">Abrahams</span> +</h3></div> +<div class="author"><h3 class="author"> +<span class="firstname">Stefan</span> <span class="surname">Seefeld</span> +</h3></div> +</div></div> +<div><p class="copyright">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld</p></div> +<div><div class="legalnotice"> +<a name="reference.legal"></a><p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></div> +</div> +<hr> +</div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="chapter"><a href="concepts.html">1. Concepts</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="concepts.html#concepts.callpolicies">CallPolicies</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="concepts.html#concepts.callpolicies.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="concepts.html#concepts.callpolicies.callpolicies_composition">CallPolicies + Composition</a></span></dt> +<dt><span class="section"><a href="concepts.html#concepts.callpolicies.concept_requirements">Concept + Requirements</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="concepts/dereferenceable.html">Dereferenceable</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="concepts/dereferenceable.html#concepts.dereferenceable.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="concepts/dereferenceable.html#concepts.dereferenceable.concept_requirements">Concept + Requirements</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="concepts/extractor.html">Extractor</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="concepts/extractor.html#concepts.extractor.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="concepts/extractor.html#concepts.extractor.concept_requirements">Concept Requirements</a></span></dt> +<dt><span class="section"><a href="concepts/extractor.html#concepts.extractor.notes">Notes</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="concepts/holdergenerator.html">HolderGenerator</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="concepts/holdergenerator.html#concepts.holdergenerator.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="concepts/holdergenerator.html#concepts.holdergenerator.concept_requirements">Concept + Requirements</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="concepts/resultconverter.html">ResultConverter</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="concepts/resultconverter.html#concepts.resultconverter.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="concepts/resultconverter.html#concepts.resultconverter.resultconverter_concept_requirem">ResultConverter + Concept Requirements</a></span></dt> +<dt><span class="section"><a href="concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept">ResultConverterGenerator + Concept Requirements</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="concepts/objectwrapper.html">ObjectWrapper</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="concepts/objectwrapper.html#concepts.objectwrapper.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="concepts/objectwrapper.html#concepts.objectwrapper.objectwrapper_concept_requiremen">ObjectWrapper + Concept Requirements</a></span></dt> +<dt><span class="section"><a href="concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements">TypeWrapper + Concept Requirements</a></span></dt> +<dt><span class="section"><a href="concepts/objectwrapper.html#concepts.objectwrapper.caveat">Caveat</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="high_level_components.html">2. High Level Components</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp">boost/python/class.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel">Class + template <code class="computeroutput"><span class="identifier">class_</span><span class="special"><</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">Bases</span><span class="special">,</span> <span class="identifier">HeldType</span><span class="special">,</span> <span class="identifier">NonCopyable</span><span class="special">></span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_bases_t1_t2_tn">Class + template bases<T1, T2, ...TN></a></span></dt> +<dt><span class="section"><a href="high_level_components.html#high_level_components.boost_python_class_hpp.examples">Examples</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_def_hpp.html">boost/python/def.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_def_hpp.html#high_level_components.boost_python_def_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_def_visitor_hpp.html">boost/python/def_visitor.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.class_def_visitor">Class + <code class="computeroutput"><span class="identifier">def_visitor</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_def_visitor_hpp.html#high_level_components.boost_python_def_visitor_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html">boost/python/docstring_options.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options">Class + <code class="computeroutput"><span class="identifier">docstring_options</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_dostring_options_construct">Class + dostring_options constructors</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options_destruct">Class + docstring_options destructor</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.class_docstring_options_modifier">Class + <code class="computeroutput"><span class="identifier">docstring_options</span></code> modifier + functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_docstring_options_h.html#high_level_components.boost_python_docstring_options_h.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_enum_hpp.html">boost/python/enum.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum">Class + template <code class="computeroutput"><span class="identifier">enum_</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum_constructors">Class + template <code class="computeroutput"><span class="identifier">enum_</span></code> constructors</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.class_template_enum_modifier_fun">Class + template <code class="computeroutput"><span class="identifier">enum_</span></code> modifier functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_enum_hpp.html#high_level_components.boost_python_enum_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_errors_hpp.html">boost/python/errors.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set">Class + <code class="computeroutput"><span class="identifier">error_already_set</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_exception_translato.html">boost/python/exception_translator.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.function_register_exception_tran">Function + <code class="computeroutput"><span class="identifier">register_exception_translator</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_init_hpp.html">boost/python/init.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_init">Class + template <code class="computeroutput"><span class="identifier">init</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.class_template_optional">Class + template <code class="computeroutput"><span class="identifier">optional</span></code> </a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_init_hpp.html#high_level_components.boost_python_init_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html">boost/python/iterator.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterator">Class + template <code class="computeroutput"><span class="identifier">iterator</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterator_construc">Class + template iterator constructors</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators">Class + template <code class="computeroutput"><span class="identifier">iterators</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators_nested_">Class + template iterators nested types</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.class_template_iterators_static_">Class + template iterators static functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_iterator_hpp.html#high_level_components.boost_python_iterator_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_module_hpp.html">boost/python/module.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.macros">Macros</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_module_hpp.html#high_level_components.boost_python_module_hpp.examples">Examples</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html">boost/python/operators.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_self_ns_self_t">Class + <code class="computeroutput"><span class="identifier">self_ns</span><span class="special">::</span><span class="identifier">self_t</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_template_other">Class + template <code class="computeroutput"><span class="identifier">other</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.class_template_detail_operator">Class + template <code class="computeroutput"><span class="identifier">detail</span><span class="special">::</span><span class="identifier">operator_</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.object_self">Object + <code class="computeroutput"><span class="identifier">self</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_operators_hpp.html#high_level_components.boost_python_operators_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_scope_hpp.html">boost/python/scope.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.class_scope">Class + <code class="computeroutput"><span class="identifier">scope</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.class_scope_constructors_and_des">Class + scope constructors and destructor</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_scope_hpp.html#high_level_components.boost_python_scope_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html">boost/python/stl_iterator.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterato">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat0">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code> + constructors</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat1">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code> + modifiers</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.class_template_stl_input_iterat2">Class + template <code class="computeroutput"><span class="identifier">stl_input_iterator</span></code> + observers</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_stl_iterator_hpp.html#high_level_components.boost_python_stl_iterator_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html">boost/python/wrapper.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_override">Class + <code class="computeroutput"><span class="identifier">override</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_override_observer_function">Class + <code class="computeroutput"><span class="identifier">override</span></code> observer functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper">Class + template <code class="computeroutput"><span class="identifier">wrapper</span></code></a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper_observer_">Class + template <code class="computeroutput"><span class="identifier">wrapper</span></code> observer + functions</a></span></dt> +<dt><span class="section"><a href="high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.example">Example</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="object_wrappers.html">3. Object Wrappers</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers.html#object_wrappers.boost_python_dict_hpp">boost/python/dict.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers.html#object_wrappers.boost_python_dict_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers.html#object_wrappers.boost_python_dict_hpp.class_dict">Class + <code class="computeroutput"><span class="identifier">dict</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers.html#object_wrappers.boost_python_dict_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_list_hpp.html">boost_python_list.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.class_list">Class + <code class="computeroutput"><span class="identifier">list</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_long_hpp.html">boost/python/long.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_long_hpp.html#object_wrappers.boost_python_long_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_long_hpp.html#object_wrappers.boost_python_long_hpp.class_long">Class + <code class="computeroutput"><span class="identifier">long_</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_long_hpp.html#object_wrappers.boost_python_long_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_numeric_hpp.html">boost/python/numeric.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.class_array">Class + <code class="computeroutput"><span class="identifier">array</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.class_array_observer_functions">Class + <code class="computeroutput"><span class="identifier">array</span></code> observer functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.class_array_static_functions">Class + <code class="computeroutput"><span class="identifier">array</span></code> static functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html">boost/python/object.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_slice_nil">Class + <code class="computeroutput"><span class="identifier">slice_nil</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_attribute_policies">Class + <code class="computeroutput"><span class="identifier">const_attribute_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_attribute_policies_s">Class + <code class="computeroutput"><span class="identifier">const_attribute_policies</span></code> + static functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_attribute_policies">Class + <code class="computeroutput"><span class="identifier">attribute_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_attribute_policies_static_">Class + <code class="computeroutput"><span class="identifier">attribute_policies</span></code> static + functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_objattribute_policie">Class + <code class="computeroutput"><span class="identifier">const_objattribute_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_objattribute_polici0">Class + <code class="computeroutput"><span class="identifier">const_objattribute_policies</span></code> + static functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_objattribute_policies">Class + <code class="computeroutput"><span class="identifier">objattribute_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_objattribute_policies_stat">Class + <code class="computeroutput"><span class="identifier">objattribute_policies</span></code> static + functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_item_policies">Class + <code class="computeroutput"><span class="identifier">const_item_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_item_policies_static">Class + <code class="computeroutput"><span class="identifier">const_item_policies</span></code> static + functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_item_policies">Class + <code class="computeroutput"><span class="identifier">item_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_item_policies_static_funct">Class + <code class="computeroutput"><span class="identifier">item_policies</span></code> static functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_slice_policies">Class + <code class="computeroutput"><span class="identifier">const_slice_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_slice_policies_stati">Class + <code class="computeroutput"><span class="identifier">const_slice_policies</span></code> static + functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_slice_policies">Class + <code class="computeroutput"><span class="identifier">slice_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_slice_policies_static_func">Class + <code class="computeroutput"><span class="identifier">slice_policies</span></code> static functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_object_operators">Class + template <code class="computeroutput"><span class="identifier">object_operators</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_object_operators_">Class + template <code class="computeroutput"><span class="identifier">object_operators</span></code> + observer functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object">Class + <code class="computeroutput"><span class="identifier">object</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object_constructors_and_de">Class + <code class="computeroutput"><span class="identifier">object</span></code> constructors and destructor</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object_modifiers">Class + <code class="computeroutput"><span class="identifier">object</span></code> modifiers</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_proxy">Class + template <code class="computeroutput"><span class="identifier">proxy</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_proxy_observer_fu">Class + template <code class="computeroutput"><span class="identifier">proxy</span></code> observer functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_proxy_modifier_fu">Class + template <code class="computeroutput"><span class="identifier">proxy</span></code> modifier functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_str_hpp.html">boost/python/str.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_str_hpp.html#object_wrappers.boost_python_str_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_str_hpp.html#object_wrappers.boost_python_str_hpp.class_str">Class + <code class="computeroutput"><span class="identifier">str</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_str_hpp.html#object_wrappers.boost_python_str_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_slice_hpp.html">boost/python/slice.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice">Class + <code class="computeroutput"><span class="identifier">slice</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_constructors">Class + <code class="computeroutput"><span class="identifier">slice</span></code> constructors</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_observer_functions">Class + <code class="computeroutput"><span class="identifier">slice</span></code> observer functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_tuple_hpp.html">boost/python/tuple.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.class_tuple">Class + <code class="computeroutput"><span class="identifier">tuple</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.function_make_tuple">Function + <code class="computeroutput"><span class="identifier">make_tuple</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.example">Example</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="function_invocation_and_creation.html">4. Function Invocation and Creation</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp">boost/python/args.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.class_arg">Class + <code class="computeroutput"><span class="identifier">arg</span></code></a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.class_arg_constructor">Class + <code class="computeroutput"><span class="identifier">arg</span></code> constructor</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.class_arg_operator">Class + <code class="computeroutput"><span class="identifier">arg</span></code> operator=</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.keyword_expression_operator">Keyword-expression + operator,</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation.html#function_invocation_and_creation.boost_python_args_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_hpp.html">boost/python/call.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.function_call">Function + <code class="computeroutput"><span class="identifier">call</span></code></a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_method_hpp.html">boost/python/call_method.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.function_call_method">Function + <code class="computeroutput"><span class="identifier">call_method</span></code></a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_data_members_hpp.html">boost/python/data_members.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_data_members_hpp.html#function_invocation_and_creation.boost_python_data_members_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_make_function_hpp.html">boost/python/make_function.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_make_function_hpp.html#function_invocation_and_creation.boost_python_make_function_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_overloads_hpp.html">boost/python/overloads.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.overloaddispatcher_concept">OverloadDispatcher + Concept</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.macros">Macros</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html">boost/python/ptr.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code></a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_t">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> + types</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_c">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> + constructors and destructor</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_o">Class + template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> + observer functions</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions">Metafunctions</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_raw_function_hpp.html">boost/python/raw_function.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.function_raw_function">Function + <code class="computeroutput"><span class="identifier">raw_function</span></code></a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/boost_python_raw_function_hpp.html#function_invocation_and_creation.boost_python_raw_function_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/function_documentation.html">Function + documentation</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat">boost/python/function_doc_signature.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp">boost/python/pytype_function.hpp</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_callpolicies.html">Models + of CallPolicies</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici">boost/python/default_call_policies.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp">boost/python/return_arg.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref">boost/python/return_internal_reference.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy">boost/python/return_value_policy.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_">boost/python/with_custodian_and_ward.hpp</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconverter.html">Models + of ResultConverter</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_indirect_">boost/python/to_python_indirect.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconverter.html#function_invocation_and_creation.models_of_resultconverter.boost_python_to_python_value_hpp">boost/python/to_python_value.hpp</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html">Models + of ResultConverterGenerator</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_const_referenc">boost/python/copy_const_reference.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_copy_non_const_refe">boost/python/copy_non_const_reference.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_manage_new_object_h">boost/python/manage_new_object.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_">boost/python/reference_existing_object.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_by_value_hpp">boost/python/return_by_value.hpp</a></span></dt> +<dt><span class="section"><a href="function_invocation_and_creation/models_of_resultconvertergenerat.html#function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_return_opaque_point">boost/python/return_opaque_pointer.hpp</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="to_from_python_type_conversion.html">5. To/From Python Type Conversion</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp">boost/python/extract.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract">Class + template <code class="computeroutput"><span class="identifier">extract</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract_construct">Class + template <code class="computeroutput"><span class="identifier">extract</span></code> constructors + and destructor</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract_observer_">Class + template <code class="computeroutput"><span class="identifier">extract</span></code> observer + functions</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_implicit_hpp.html">boost/python/implicit.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_implicit_hpp.html#to_from_python_type_conversion.boost_python_implicit_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_implicit_hpp.html#to_from_python_type_conversion.boost_python_implicit_hpp.function_template_implicit_conve">Function + template <code class="computeroutput"><span class="identifier">implicit_convertible</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_implicit_hpp.html#to_from_python_type_conversion.boost_python_implicit_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html">boost/python/lvalue_from_pytype.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_lvalue_from_pytyp">Class + template <code class="computeroutput"><span class="identifier">lvalue_from_pytype</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_identity">Class + template <code class="computeroutput"><span class="identifier">extract_identity</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_member">Class + template <code class="computeroutput"><span class="identifier">extract_member</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_opaque_pointer_conv.html">boost/python/opaque_pointer_converter.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.class_template_opaque_constructo">Class + template <code class="computeroutput"><span class="identifier">opaque</span></code> constructor</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.macro_boost_python_opaque_specia">Macro + <code class="computeroutput"><span class="identifier">BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</span><span class="special">(</span><span class="identifier">Pointee</span><span class="special">)</span></code></a></span></dt> +</dl></dd> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_to_python_converter.html">boost/python/to_python_converter.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert">Class + template <code class="computeroutput"><span class="identifier">to_python_converter</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html">boost/python/register_ptr_to_python.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html#to_from_python_type_conversion.boost_python_register_ptr_to_pyt.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html#to_from_python_type_conversion.boost_python_register_ptr_to_pyt.function_register_ptr_to_python">Function + <code class="computeroutput"><span class="identifier">register_ptr_to_python</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html#to_from_python_type_conversion.boost_python_register_ptr_to_pyt.example">Example</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="embedding.html">6. Embedding</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp">boost/python/exec.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.function_eval">Function + <code class="computeroutput"><span class="identifier">eval</span></code></a></span></dt> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.function_exec">Function + <code class="computeroutput"><span class="identifier">exec</span></code></a></span></dt> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.function_exec_file">Function + <code class="computeroutput"><span class="identifier">exec_file</span></code></a></span></dt> +<dt><span class="section"><a href="embedding.html#embedding.boost_python_exec_hpp.examples">Examples</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="embedding/boost_python_import_hpp.html">boost/python/import.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="embedding/boost_python_import_hpp.html#embedding.boost_python_import_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="embedding/boost_python_import_hpp.html#embedding.boost_python_import_hpp.function_import">Function + <code class="computeroutput"><span class="identifier">import</span></code></a></span></dt> +<dt><span class="section"><a href="embedding/boost_python_import_hpp.html#embedding.boost_python_import_hpp.examples">Examples</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="utility_and_infrastructure.html">7. Utility and Infrastructure</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_">boost/python/has_back_reference.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_.class_template_has_back_referenc">Class + template <code class="computeroutput"><span class="identifier">has_back_reference</span></code></a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_.examples">Examples</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_instance_holder_hpp.html">boost/python/instance_holder.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder">Class + template <code class="computeroutput"><span class="identifier">instance_holder</span></code></a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.examples">Examples</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_pointee_hpp.html">boost/python/pointee.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_pointee_hpp.html#utility_and_infrastructure.boost_python_pointee_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_pointee_hpp.html#utility_and_infrastructure.boost_python_pointee_hpp.class_template_pointee">Class + template <code class="computeroutput"><span class="identifier">pointee</span></code></a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_pointee_hpp.html#utility_and_infrastructure.boost_python_pointee_hpp.examples">Examples</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_handle_hpp.html">boost/python/handle.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.class_template_handle">Class + template <code class="computeroutput"><span class="identifier">handle</span></code></a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.function_borrowed">Function + <code class="computeroutput"><span class="identifier">borrowed</span></code></a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.function_allow_null">Function + <code class="computeroutput"><span class="identifier">allow_null</span></code></a></span></dt> +</dl></dd> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_type_id_hpp.html">boost/python/type_id.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info">Class + template <code class="computeroutput"><span class="identifier">type_info</span></code></a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_ssize_t_hpp.html">boost/python/ssize_t.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_ssize_t_hpp.html#utility_and_infrastructure.boost_python_ssize_t_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_ssize_t_hpp.html#utility_and_infrastructure.boost_python_ssize_t_hpp.typedefs">Typedefs</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_ssize_t_hpp.html#utility_and_infrastructure.boost_python_ssize_t_hpp.constants">Constants</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="topics.html">8. Topics</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met">Calling Python + Functions and Methods</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met.argument_handling">Argument + Handling</a></span></dt> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met.result_handling">Result + Handling</a></span></dt> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met.rationale">Rationale</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="topics/pickle_support.html">Pickle support</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="topics/pickle_support.html#topics.pickle_support.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="topics/pickle_support.html#topics.pickle_support.the_pickle_interface">The Pickle + Interface</a></span></dt> +<dt><span class="section"><a href="topics/pickle_support.html#topics.pickle_support.example">Example</a></span></dt> +<dt><span class="section"><a href="topics/pickle_support.html#topics.pickle_support.pitfall_and_safety_guard">Pitfall + and Safety Guard</a></span></dt> +<dt><span class="section"><a href="topics/pickle_support.html#topics.pickle_support.practical_advice">Practical Advice</a></span></dt> +<dt><span class="section"><a href="topics/pickle_support.html#topics.pickle_support.light_weight_alternative_pickle_">Light-weight + alternative: pickle support implemented in Python</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="topics/indexing_support.html">Indexing support</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="topics/indexing_support.html#topics.indexing_support.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="topics/indexing_support.html#topics.indexing_support.the_indexing_interface">The + Indexing Interface</a></span></dt> +<dt><span class="section"><a href="topics/indexing_support.html#topics.indexing_support.index_suite_sub_classes">index_suite + sub-classes</a></span></dt> +<dt><span class="section"><a href="topics/indexing_support.html#topics.indexing_support.indexing_suite_class"><code class="computeroutput"><span class="identifier">indexing_suite</span></code> class</a></span></dt> +<dt><span class="section"><a href="topics/indexing_support.html#topics.indexing_support.class_vector_indexing_suite">class + <code class="computeroutput"><span class="identifier">vector_indexing_suite</span></code></a></span></dt> +<dt><span class="section"><a href="topics/indexing_support.html#topics.indexing_support.class_map_indexing_suite">class + <code class="computeroutput"><span class="identifier">map_indexing_suite</span></code></a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="glossary.html">9. Glossary</a></span></dt> +</dl> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"><p><small>Last revised: December 14, 2015 at 09:15:16 GMT</small></p></td> +<td align="right"><div class="copyright-footer"></div></td> +</tr></table> +<hr> +<div class="spirit-nav"><a accesskey="n" href="concepts.html"><img src="../images/next.png" alt="Next"></a></div> +</body> +</html> diff --git a/libs/python/doc/html/reference/object_wrappers.html b/libs/python/doc/html/reference/object_wrappers.html new file mode 100644 index 0000000000..2206097b7d --- /dev/null +++ b/libs/python/doc/html/reference/object_wrappers.html @@ -0,0 +1,260 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 3. Object Wrappers</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="index.html" title="Boost.Python Reference Manual"> +<link rel="prev" href="high_level_components/boost_python_wrapper_hpp.html" title="boost/python/wrapper.hpp"> +<link rel="next" href="object_wrappers/boost_python_list_hpp.html" title="boost_python_list.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="high_level_components/boost_python_wrapper_hpp.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="object_wrappers/boost_python_list_hpp.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="object_wrappers"></a>Chapter 3. Object Wrappers</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="object_wrappers.html#object_wrappers.boost_python_dict_hpp">boost/python/dict.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers.html#object_wrappers.boost_python_dict_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers.html#object_wrappers.boost_python_dict_hpp.class_dict">Class + <code class="computeroutput"><span class="identifier">dict</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers.html#object_wrappers.boost_python_dict_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_list_hpp.html">boost_python_list.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.class_list">Class + <code class="computeroutput"><span class="identifier">list</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_long_hpp.html">boost/python/long.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_long_hpp.html#object_wrappers.boost_python_long_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_long_hpp.html#object_wrappers.boost_python_long_hpp.class_long">Class + <code class="computeroutput"><span class="identifier">long_</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_long_hpp.html#object_wrappers.boost_python_long_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_numeric_hpp.html">boost/python/numeric.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.class_array">Class + <code class="computeroutput"><span class="identifier">array</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.class_array_observer_functions">Class + <code class="computeroutput"><span class="identifier">array</span></code> observer functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.class_array_static_functions">Class + <code class="computeroutput"><span class="identifier">array</span></code> static functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html">boost/python/object.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_slice_nil">Class + <code class="computeroutput"><span class="identifier">slice_nil</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_attribute_policies">Class + <code class="computeroutput"><span class="identifier">const_attribute_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_attribute_policies_s">Class + <code class="computeroutput"><span class="identifier">const_attribute_policies</span></code> + static functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_attribute_policies">Class + <code class="computeroutput"><span class="identifier">attribute_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_attribute_policies_static_">Class + <code class="computeroutput"><span class="identifier">attribute_policies</span></code> static + functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_objattribute_policie">Class + <code class="computeroutput"><span class="identifier">const_objattribute_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_objattribute_polici0">Class + <code class="computeroutput"><span class="identifier">const_objattribute_policies</span></code> + static functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_objattribute_policies">Class + <code class="computeroutput"><span class="identifier">objattribute_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_objattribute_policies_stat">Class + <code class="computeroutput"><span class="identifier">objattribute_policies</span></code> static + functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_item_policies">Class + <code class="computeroutput"><span class="identifier">const_item_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_item_policies_static">Class + <code class="computeroutput"><span class="identifier">const_item_policies</span></code> static + functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_item_policies">Class + <code class="computeroutput"><span class="identifier">item_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_item_policies_static_funct">Class + <code class="computeroutput"><span class="identifier">item_policies</span></code> static functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_slice_policies">Class + <code class="computeroutput"><span class="identifier">const_slice_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_slice_policies_stati">Class + <code class="computeroutput"><span class="identifier">const_slice_policies</span></code> static + functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_slice_policies">Class + <code class="computeroutput"><span class="identifier">slice_policies</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_slice_policies_static_func">Class + <code class="computeroutput"><span class="identifier">slice_policies</span></code> static functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_object_operators">Class + template <code class="computeroutput"><span class="identifier">object_operators</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_object_operators_">Class + template <code class="computeroutput"><span class="identifier">object_operators</span></code> + observer functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object">Class + <code class="computeroutput"><span class="identifier">object</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object_constructors_and_de">Class + <code class="computeroutput"><span class="identifier">object</span></code> constructors and destructor</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object_modifiers">Class + <code class="computeroutput"><span class="identifier">object</span></code> modifiers</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_proxy">Class + template <code class="computeroutput"><span class="identifier">proxy</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_proxy_observer_fu">Class + template <code class="computeroutput"><span class="identifier">proxy</span></code> observer functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_proxy_modifier_fu">Class + template <code class="computeroutput"><span class="identifier">proxy</span></code> modifier functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_str_hpp.html">boost/python/str.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_str_hpp.html#object_wrappers.boost_python_str_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_str_hpp.html#object_wrappers.boost_python_str_hpp.class_str">Class + <code class="computeroutput"><span class="identifier">str</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_str_hpp.html#object_wrappers.boost_python_str_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_slice_hpp.html">boost/python/slice.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice">Class + <code class="computeroutput"><span class="identifier">slice</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_constructors">Class + <code class="computeroutput"><span class="identifier">slice</span></code> constructors</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_observer_functions">Class + <code class="computeroutput"><span class="identifier">slice</span></code> observer functions</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="object_wrappers/boost_python_tuple_hpp.html">boost/python/tuple.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="object_wrappers/boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.class_tuple">Class + <code class="computeroutput"><span class="identifier">tuple</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.function_make_tuple">Function + <code class="computeroutput"><span class="identifier">make_tuple</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers/boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.example">Example</a></span></dt> +</dl></dd> +</dl> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="object_wrappers.boost_python_dict_hpp"></a><a class="link" href="object_wrappers.html#object_wrappers.boost_python_dict_hpp" title="boost/python/dict.hpp">boost/python/dict.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="object_wrappers.html#object_wrappers.boost_python_dict_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="object_wrappers.html#object_wrappers.boost_python_dict_hpp.class_dict">Class + <code class="computeroutput"><span class="identifier">dict</span></code></a></span></dt> +<dt><span class="section"><a href="object_wrappers.html#object_wrappers.boost_python_dict_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_dict_hpp.introduction"></a><a class="link" href="object_wrappers.html#object_wrappers.boost_python_dict_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Exposes a <a class="link" href="concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + for the Python <a href="http://www.python.org/dev/doc/devel/lib/typesmapping.html" target="_top"><code class="computeroutput"><span class="identifier">dict</span></code></a> type. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_dict_hpp.class_dict"></a><a class="link" href="object_wrappers.html#object_wrappers.boost_python_dict_hpp.class_dict" title="Class dict">Class + <code class="computeroutput"><span class="identifier">dict</span></code></a> +</h3></div></div></div> +<p> + Exposes the <a href="http://www.python.org/dev/doc/devel/lib/typesmapping.html" target="_top">mapping + protocol</a> of Python's built-in <code class="computeroutput"><span class="identifier">dict</span></code> + type. The semantics of the constructors and member functions defined below + can be fully understood by reading the <a class="link" href="concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + concept definition. Since <code class="computeroutput"><span class="identifier">dict</span></code> + is publicly derived from <a class="link" href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object"><code class="computeroutput"><span class="identifier">object</span></code></a>, the public <code class="computeroutput"><span class="identifier">object</span></code> interface applies to <code class="computeroutput"><span class="identifier">dict</span></code> instances as well. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">dict</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object</span> + <span class="special">{</span> + <span class="identifier">dict</span><span class="special">();</span> + + <span class="keyword">template</span><span class="special"><</span> <span class="keyword">class</span> <span class="identifier">T</span> <span class="special">></span> + <span class="identifier">dict</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">data</span><span class="special">);</span> + + <span class="comment">// modifiers</span> + <span class="keyword">void</span> <span class="identifier">clear</span><span class="special">();</span> + <span class="identifier">dict</span> <span class="identifier">copy</span><span class="special">();</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="identifier">tuple</span> <span class="identifier">popitem</span><span class="special">();</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">object</span> <span class="identifier">setdefault</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">k</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="identifier">object</span> <span class="identifier">setdefault</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">d</span><span class="special">);</span> + + <span class="keyword">void</span> <span class="identifier">update</span><span class="special">(</span><span class="identifier">object_cref</span> <span class="identifier">E</span><span class="special">);</span> + + <span class="keyword">template</span><span class="special"><</span> <span class="keyword">class</span> <span class="identifier">T</span> <span class="special">></span> + <span class="keyword">void</span> <span class="identifier">update</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">E</span><span class="special">);</span> + + <span class="comment">// observers</span> + <span class="identifier">list</span> <span class="identifier">values</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">object</span> <span class="identifier">get</span><span class="special">(</span><span class="identifier">object_cref</span> <span class="identifier">k</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">object</span> <span class="identifier">get</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">k</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">object</span> <span class="identifier">get</span><span class="special">(</span><span class="identifier">object_cref</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">object_cref</span> <span class="identifier">d</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">object</span> <span class="identifier">get</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">d</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">bool</span> <span class="identifier">has_key</span><span class="special">(</span><span class="identifier">object_cref</span> <span class="identifier">k</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span><span class="special"><</span> <span class="keyword">class</span> <span class="identifier">T</span> <span class="special">></span> + <span class="keyword">bool</span> <span class="identifier">has_key</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">k</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">list</span> <span class="identifier">items</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">object</span> <span class="identifier">iteritems</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">object</span> <span class="identifier">iterkeys</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">object</span> <span class="identifier">itervalues</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">list</span> <span class="identifier">keys</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_dict_hpp.example"></a><a class="link" href="object_wrappers.html#object_wrappers.boost_python_dict_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">dict</span> <span class="identifier">swap_object_dict</span><span class="special">(</span><span class="identifier">object</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">dict</span> <span class="identifier">d</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">dict</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">extract</span><span class="special"><</span><span class="identifier">dict</span><span class="special">>(</span><span class="identifier">target</span><span class="special">.</span><span class="identifier">attr</span><span class="special">(</span><span class="string">"__dict__"</span><span class="special">));</span> + <span class="identifier">target</span><span class="special">.</span><span class="identifier">attr</span><span class="special">(</span><span class="string">"__dict__"</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">d</span><span class="special">;</span> + <span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span> +<span class="special">}</span> +</pre> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="high_level_components/boost_python_wrapper_hpp.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="object_wrappers/boost_python_list_hpp.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/object_wrappers/boost_python_list_hpp.html b/libs/python/doc/html/reference/object_wrappers/boost_python_list_hpp.html new file mode 100644 index 0000000000..361fbbb098 --- /dev/null +++ b/libs/python/doc/html/reference/object_wrappers/boost_python_list_hpp.html @@ -0,0 +1,120 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost_python_list.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../object_wrappers.html" title="Chapter 3. Object Wrappers"> +<link rel="prev" href="../object_wrappers.html" title="Chapter 3. Object Wrappers"> +<link rel="next" href="boost_python_long_hpp.html" title="boost/python/long.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../object_wrappers.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_long_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="object_wrappers.boost_python_list_hpp"></a><a class="link" href="boost_python_list_hpp.html" title="boost_python_list.hpp">boost_python_list.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.class_list">Class + <code class="computeroutput"><span class="identifier">list</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_list_hpp.introduction"></a><a class="link" href="boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Exposes a <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + for the Python <a href="http://www.python.org/doc/current/lib/typesseq-mutable.html" target="_top">list</a> + type. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_list_hpp.class_list"></a><a class="link" href="boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.class_list" title="Class list">Class + <code class="computeroutput"><span class="identifier">list</span></code></a> +</h3></div></div></div> +<p> + Exposes the <a href="http://www.python.org/doc/current/lib/typesseq-mutable.html" target="_top">mapping + protocol</a> of Python's built-in <code class="computeroutput"><span class="identifier">list</span></code> + type. The semantics of the constructors and member functions defined below + can be fully understood by reading the <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + concept definition. Since <code class="computeroutput"><span class="identifier">list</span></code> + is publicly derived from <a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object"><code class="computeroutput"><span class="identifier">object</span></code></a>, the public <code class="computeroutput"><span class="identifier">object</span></code> interface applies to <code class="computeroutput"><span class="identifier">list</span></code> instances as well. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">list</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">list</span><span class="special">();</span> <span class="comment">// new list</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">explicit</span> <span class="identifier">list</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sequence</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">append</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">count</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">extend</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">index</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">insert</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">index</span><span class="special">,</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">);</span> <span class="comment">// insert object before index</span> + + <span class="identifier">object</span> <span class="identifier">pop</span><span class="special">();</span> <span class="comment">// remove and return item at index (default last)</span> + <span class="identifier">object</span> <span class="identifier">pop</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">index</span><span class="special">);</span> + <span class="identifier">object</span> <span class="identifier">pop</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">index</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">remove</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span> + + <span class="keyword">void</span> <span class="identifier">reverse</span><span class="special">();</span> <span class="comment">// reverse *IN PLACE*</span> + + <span class="keyword">void</span> <span class="identifier">sort</span><span class="special">();</span> <span class="comment">// sort *IN PLACE*; if given, cmpfunc(x, y) -> -1, 0, 1</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">sort</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_list_hpp.example"></a><a class="link" href="boost_python_list_hpp.html#object_wrappers.boost_python_list_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="comment">// Return the number of zeroes in the list</span> +<span class="keyword">long</span> <span class="identifier">zeroes</span><span class="special">(</span><span class="identifier">list</span> <span class="identifier">l</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">l</span><span class="special">.</span><span class="identifier">count</span><span class="special">(</span><span class="number">0</span><span class="special">);</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../object_wrappers.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_long_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/object_wrappers/boost_python_long_hpp.html b/libs/python/doc/html/reference/object_wrappers/boost_python_long_hpp.html new file mode 100644 index 0000000000..3162e5b944 --- /dev/null +++ b/libs/python/doc/html/reference/object_wrappers/boost_python_long_hpp.html @@ -0,0 +1,97 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/long.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../object_wrappers.html" title="Chapter 3. Object Wrappers"> +<link rel="prev" href="boost_python_list_hpp.html" title="boost_python_list.hpp"> +<link rel="next" href="boost_python_numeric_hpp.html" title="boost/python/numeric.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_list_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_numeric_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="object_wrappers.boost_python_long_hpp"></a><a class="link" href="boost_python_long_hpp.html" title="boost/python/long.hpp">boost/python/long.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_long_hpp.html#object_wrappers.boost_python_long_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_long_hpp.html#object_wrappers.boost_python_long_hpp.class_long">Class + <code class="computeroutput"><span class="identifier">long_</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_long_hpp.html#object_wrappers.boost_python_long_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_long_hpp.introduction"></a><a class="link" href="boost_python_long_hpp.html#object_wrappers.boost_python_long_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Exposes a <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + for the Python <a href="http://www.python.org/doc/current/lib/typesnumeric.html" target="_top">long</a> + integer type. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_long_hpp.class_long"></a><a class="link" href="boost_python_long_hpp.html#object_wrappers.boost_python_long_hpp.class_long" title="Class long_">Class + <code class="computeroutput"><span class="identifier">long_</span></code></a> +</h3></div></div></div> +<p> + Exposes the <a href="http://www.python.org/doc/current/lib/typesnumeric.html" target="_top">numeric + type protocol</a> of Python's built-in <code class="computeroutput"><span class="keyword">long</span></code> + type. The semantics of the constructors and member functions defined below + can be fully understood by reading the <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + concept definition. Since <code class="computeroutput"><span class="identifier">long_</span></code> + is publicly derived from <a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object"><code class="computeroutput"><span class="identifier">object</span></code></a>, the public <code class="computeroutput"><span class="identifier">object</span></code> interface applies to <code class="computeroutput"><span class="identifier">long_</span></code> instances as well. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">long_</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">long_</span><span class="special">();</span> <span class="comment">// new long_</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">explicit</span> <span class="identifier">long_</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> + <span class="identifier">long_</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">,</span> <span class="identifier">U</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">base</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_long_hpp.example"></a><a class="link" href="boost_python_long_hpp.html#object_wrappers.boost_python_long_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="comment">// compute a factorial without overflowing</span> +<span class="identifier">python</span><span class="special">::</span><span class="identifier">long_</span> <span class="identifier">fact</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">n</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">if</span> <span class="special">(</span><span class="identifier">n</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> + <span class="keyword">return</span> <span class="identifier">python</span><span class="special">::</span><span class="identifier">long_</span><span class="special">(</span><span class="number">1</span><span class="special">);</span> + <span class="keyword">else</span> + <span class="keyword">return</span> <span class="identifier">n</span> <span class="special">*</span> <span class="identifier">fact</span><span class="special">(</span><span class="identifier">n</span> <span class="special">-</span> <span class="number">1</span><span class="special">);</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_list_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_numeric_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/object_wrappers/boost_python_numeric_hpp.html b/libs/python/doc/html/reference/object_wrappers/boost_python_numeric_hpp.html new file mode 100644 index 0000000000..d45ed95d21 --- /dev/null +++ b/libs/python/doc/html/reference/object_wrappers/boost_python_numeric_hpp.html @@ -0,0 +1,259 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/numeric.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../object_wrappers.html" title="Chapter 3. Object Wrappers"> +<link rel="prev" href="boost_python_long_hpp.html" title="boost/python/long.hpp"> +<link rel="next" href="boost_python_object_hpp.html" title="boost/python/object.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_long_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_object_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="object_wrappers.boost_python_numeric_hpp"></a><a class="link" href="boost_python_numeric_hpp.html" title="boost/python/numeric.hpp">boost/python/numeric.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.class_array">Class + <code class="computeroutput"><span class="identifier">array</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.class_array_observer_functions">Class + <code class="computeroutput"><span class="identifier">array</span></code> observer functions</a></span></dt> +<dt><span class="section"><a href="boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.class_array_static_functions">Class + <code class="computeroutput"><span class="identifier">array</span></code> static functions</a></span></dt> +<dt><span class="section"><a href="boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_numeric_hpp.introduction"></a><a class="link" href="boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Exposes a <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + for the Python <a href="http://www.python.org/dev/doc/devel/lib/typesmapping.html" target="_top">array</a> + type. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_numeric_hpp.class_array"></a><a class="link" href="boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.class_array" title="Class array">Class + <code class="computeroutput"><span class="identifier">array</span></code></a> +</h3></div></div></div> +<p> + Provides access to the array types of <a href="http://www.pfdubois.com/numpy/" target="_top">Numerical + Python</a>'s <a href="http://www.pfdubois.com/numpy/#Numeric" target="_top">Numeric</a> + and <a href="http://stsdas.stsci.edu/numarray/index.html" target="_top">NumArray</a> + 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 <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + concept definition. Since array is publicly derived from object, the public + object interface applies to array instances as well. + </p> +<p> + The default behavior is to use numarray.NDArray as the associated Python + type if the numarray module is installed in the default location. Otherwise + it falls back to use Numeric.ArrayType. If neither extension module is + installed, overloads of wrapped C++ functions with numeric::array parameters + will never be matched, 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. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">numeric</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">array</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">object</span> <span class="identifier">astype</span><span class="special">();</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Type</span><span class="special">></span> + <span class="identifier">object</span> <span class="identifier">astype</span><span class="special">(</span><span class="identifier">Type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">type_</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Type</span><span class="special">></span> + <span class="identifier">array</span> <span class="identifier">new_</span><span class="special">(</span><span class="identifier">Type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">type_</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Sequence</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">resize</span><span class="special">(</span><span class="identifier">Sequence</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">);</span> + <span class="keyword">void</span> <span class="identifier">resize</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">x1</span><span class="special">);</span> + <span class="keyword">void</span> <span class="identifier">resize</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">x1</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">x2</span><span class="special">);</span> + <span class="special">...</span> + <span class="keyword">void</span> <span class="identifier">resize</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">x1</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">x2</span><span class="special">,...</span><span class="keyword">long</span> <span class="identifier">xn</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Sequence</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">setshape</span><span class="special">(</span><span class="identifier">Sequence</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">);</span> + <span class="keyword">void</span> <span class="identifier">setshape</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">x1</span><span class="special">);</span> + <span class="keyword">void</span> <span class="identifier">setshape</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">x1</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">x2</span><span class="special">);</span> + <span class="special">...</span> + <span class="keyword">void</span> <span class="identifier">setshape</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">x1</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">x2</span><span class="special">,...</span><span class="keyword">long</span> <span class="identifier">xn</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Indices</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Values</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">put</span><span class="special">(</span><span class="identifier">Indices</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">indices</span><span class="special">,</span> <span class="identifier">Values</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">values</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Sequence</span><span class="special">></span> + <span class="identifier">object</span> <span class="identifier">take</span><span class="special">(</span><span class="identifier">Sequence</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sequence</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">axis</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">File</span><span class="special">></span> + <span class="keyword">void</span> <span class="identifier">tofile</span><span class="special">(</span><span class="identifier">File</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">f</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">object</span> <span class="identifier">factory</span><span class="special">();</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Sequence</span><span class="special">></span> + <span class="identifier">object</span> <span class="identifier">factory</span><span class="special">(</span><span class="identifier">Sequence</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Sequence</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Typecode</span><span class="special">></span> + <span class="identifier">object</span> <span class="identifier">factory</span><span class="special">(</span><span class="identifier">Sequence</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">Typecode</span> <span class="keyword">const</span><span class="special">&,</span> <span class="keyword">bool</span> <span class="identifier">copy</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">savespace</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Sequence</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Typecode</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Type</span><span class="special">></span> + <span class="identifier">object</span> <span class="identifier">factory</span><span class="special">(</span><span class="identifier">Sequence</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">Typecode</span> <span class="keyword">const</span><span class="special">&,</span> <span class="keyword">bool</span> <span class="identifier">copy</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">savespace</span><span class="special">,</span> <span class="identifier">Type</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Sequence</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Typecode</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Type</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Shape</span><span class="special">></span> + <span class="identifier">object</span> <span class="identifier">factory</span><span class="special">(</span><span class="identifier">Sequence</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">Typecode</span> <span class="keyword">const</span><span class="special">&,</span> <span class="keyword">bool</span> <span class="identifier">copy</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">savespace</span><span class="special">,</span> <span class="identifier">Type</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">Shape</span> <span class="keyword">const</span><span class="special">&);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">></span> + <span class="keyword">explicit</span> <span class="identifier">array</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x1</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="keyword">explicit</span> <span class="identifier">array</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x1</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x2</span><span class="special">);</span> + <span class="special">...</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,...</span><span class="keyword">class</span> <span class="identifier">Tn</span><span class="special">></span> + <span class="keyword">explicit</span> <span class="identifier">array</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x1</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x2</span><span class="special">,...</span><span class="identifier">Tn</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">xn</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">set_module_and_type</span><span class="special">();</span> + <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">set_module_and_type</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">package_path</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">type_name</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span> + <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">get_module_name</span><span class="special">();</span> + + <span class="identifier">object</span> <span class="identifier">argmax</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">axis</span><span class="special">=-</span><span class="number">1</span><span class="special">);</span> + + <span class="identifier">object</span> <span class="identifier">argmin</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">axis</span><span class="special">=-</span><span class="number">1</span><span class="special">);</span> + + <span class="identifier">object</span> <span class="identifier">argsort</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">axis</span><span class="special">=-</span><span class="number">1</span><span class="special">);</span> + + <span class="keyword">void</span> <span class="identifier">byteswap</span><span class="special">();</span> + + <span class="identifier">object</span> <span class="identifier">copy</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">object</span> <span class="identifier">diagonal</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">offset</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">axis1</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">axis2</span> <span class="special">=</span> <span class="number">1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">void</span> <span class="identifier">info</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">bool</span> <span class="identifier">is_c_array</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">bool</span> <span class="identifier">isbyteswapped</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">void</span> <span class="identifier">sort</span><span class="special">();</span> + <span class="identifier">object</span> <span class="identifier">trace</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">offset</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">axis1</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">axis2</span> <span class="special">=</span> <span class="number">1</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">object</span> <span class="identifier">type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">char</span> <span class="identifier">typecode</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">object</span> <span class="identifier">getflat</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">long</span> <span class="identifier">getrank</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">object</span> <span class="identifier">getshape</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">bool</span> <span class="identifier">isaligned</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">bool</span> <span class="identifier">iscontiguous</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">long</span> <span class="identifier">itemsize</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">long</span> <span class="identifier">nelements</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">object</span> <span class="identifier">nonzero</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">void</span> <span class="identifier">ravel</span><span class="special">();</span> + <span class="identifier">object</span> <span class="identifier">repeat</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">repeats</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">axis</span><span class="special">=</span><span class="number">0</span><span class="special">);</span> + <span class="keyword">void</span> <span class="identifier">setflat</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">flat</span><span class="special">);</span> + <span class="keyword">void</span> <span class="identifier">swapaxes</span><span class="special">(</span><span class="keyword">long</span> <span class="identifier">axis1</span><span class="special">,</span> <span class="keyword">long</span> <span class="identifier">axis2</span><span class="special">);</span> + <span class="identifier">str</span> <span class="identifier">tostring</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">void</span> <span class="identifier">transpose</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">axes</span> <span class="special">=</span> <span class="identifier">object</span><span class="special">());</span> + <span class="identifier">object</span> <span class="identifier">view</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_numeric_hpp.class_array_observer_functions"></a><a class="link" href="boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.class_array_observer_functions" title="Class array observer functions">Class + <code class="computeroutput"><span class="identifier">array</span></code> observer functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">object</span> <span class="identifier">factory</span><span class="special">();</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Sequence</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">factory</span><span class="special">(</span><span class="identifier">Sequence</span> <span class="keyword">const</span><span class="special">&);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Sequence</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Typecode</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">factory</span><span class="special">(</span><span class="identifier">Sequence</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">Typecode</span> <span class="keyword">const</span><span class="special">&,</span> <span class="keyword">bool</span> <span class="identifier">copy</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">savespace</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Sequence</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Typecode</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Type</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">factory</span><span class="special">(</span><span class="identifier">Sequence</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">Typecode</span> <span class="keyword">const</span><span class="special">&,</span> <span class="keyword">bool</span> <span class="identifier">copy</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">savespace</span><span class="special">,</span> <span class="identifier">Type</span> <span class="keyword">const</span><span class="special">&);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Sequence</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Typecode</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Type</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Shape</span><span class="special">></span> +<span class="identifier">object</span> <span class="identifier">factory</span><span class="special">(</span><span class="identifier">Sequence</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">Typecode</span> <span class="keyword">const</span><span class="special">&,</span> <span class="keyword">bool</span> <span class="identifier">copy</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">savespace</span><span class="special">,</span> <span class="identifier">Type</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">Shape</span> <span class="keyword">const</span><span class="special">&);</span> +</pre> +<p> + 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. + </p> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Type</span><span class="special">></span> +<span class="identifier">array</span> <span class="identifier">new_</span><span class="special">(</span><span class="identifier">Type</span> <span class="keyword">const</span><span class="special">&)</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<p> + This function maps to the underlying array type's new() function. It is + not called "new" because that is a keyword in C++. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_numeric_hpp.class_array_static_functions"></a><a class="link" href="boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.class_array_static_functions" title="Class array static functions">Class + <code class="computeroutput"><span class="identifier">array</span></code> static functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">set_module_and_type</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">package_path</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">type_name</span><span class="special">);</span> +<span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">set_module_and_type</span><span class="special">();</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + package_path and type_name, if supplied, is an <a class="link" href="../glossary.html#ntbs">ntbs</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + The first form sets the package path of the module that 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. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">get_module_name</span><span class="special">()</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Returns the name of the module containing the class that will be + held by new <code class="computeroutput"><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">array</span></code> + instances. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_numeric_hpp.example"></a><a class="link" href="boost_python_numeric_hpp.html#object_wrappers.boost_python_numeric_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">numeric</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">tuple</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="comment">// sets the first element in a 2d numeric array</span> +<span class="keyword">void</span> <span class="identifier">set_first_element</span><span class="special">(</span><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">array</span><span class="special">&</span> <span class="identifier">y</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">value</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">y</span><span class="special">[</span><span class="identifier">make_tuple</span><span class="special">(</span><span class="number">0</span><span class="special">,</span><span class="number">0</span><span class="special">)]</span> <span class="special">=</span> <span class="identifier">value</span><span class="special">;</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_long_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_object_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/object_wrappers/boost_python_object_hpp.html b/libs/python/doc/html/reference/object_wrappers/boost_python_object_hpp.html new file mode 100644 index 0000000000..36b53ba2ff --- /dev/null +++ b/libs/python/doc/html/reference/object_wrappers/boost_python_object_hpp.html @@ -0,0 +1,1148 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/object.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../object_wrappers.html" title="Chapter 3. Object Wrappers"> +<link rel="prev" href="boost_python_numeric_hpp.html" title="boost/python/numeric.hpp"> +<link rel="next" href="boost_python_str_hpp.html" title="boost/python/str.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_numeric_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_str_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="object_wrappers.boost_python_object_hpp"></a><a class="link" href="boost_python_object_hpp.html" title="boost/python/object.hpp">boost/python/object.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_slice_nil">Class + <code class="computeroutput"><span class="identifier">slice_nil</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_attribute_policies">Class + <code class="computeroutput"><span class="identifier">const_attribute_policies</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_attribute_policies_s">Class + <code class="computeroutput"><span class="identifier">const_attribute_policies</span></code> + static functions</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_attribute_policies">Class + <code class="computeroutput"><span class="identifier">attribute_policies</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_attribute_policies_static_">Class + <code class="computeroutput"><span class="identifier">attribute_policies</span></code> static + functions</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_objattribute_policie">Class + <code class="computeroutput"><span class="identifier">const_objattribute_policies</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_objattribute_polici0">Class + <code class="computeroutput"><span class="identifier">const_objattribute_policies</span></code> + static functions</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_objattribute_policies">Class + <code class="computeroutput"><span class="identifier">objattribute_policies</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_objattribute_policies_stat">Class + <code class="computeroutput"><span class="identifier">objattribute_policies</span></code> static + functions</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_item_policies">Class + <code class="computeroutput"><span class="identifier">const_item_policies</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_item_policies_static">Class + <code class="computeroutput"><span class="identifier">const_item_policies</span></code> static + functions</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_item_policies">Class + <code class="computeroutput"><span class="identifier">item_policies</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_item_policies_static_funct">Class + <code class="computeroutput"><span class="identifier">item_policies</span></code> static functions</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_slice_policies">Class + <code class="computeroutput"><span class="identifier">const_slice_policies</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_slice_policies_stati">Class + <code class="computeroutput"><span class="identifier">const_slice_policies</span></code> static + functions</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_slice_policies">Class + <code class="computeroutput"><span class="identifier">slice_policies</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_slice_policies_static_func">Class + <code class="computeroutput"><span class="identifier">slice_policies</span></code> static functions</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_object_operators">Class + template <code class="computeroutput"><span class="identifier">object_operators</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_object_operators_">Class + template <code class="computeroutput"><span class="identifier">object_operators</span></code> + observer functions</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object">Class + <code class="computeroutput"><span class="identifier">object</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object_constructors_and_de">Class + <code class="computeroutput"><span class="identifier">object</span></code> constructors and destructor</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object_modifiers">Class + <code class="computeroutput"><span class="identifier">object</span></code> modifiers</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_proxy">Class + template <code class="computeroutput"><span class="identifier">proxy</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_proxy_observer_fu">Class + template <code class="computeroutput"><span class="identifier">proxy</span></code> observer functions</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_proxy_modifier_fu">Class + template <code class="computeroutput"><span class="identifier">proxy</span></code> modifier functions</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.introduction"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + 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. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_slice_nil"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_slice_nil" title="Class slice_nil">Class + <code class="computeroutput"><span class="identifier">slice_nil</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">slice_nil</span><span class="special">;</span> +<span class="keyword">static</span> <span class="keyword">const</span> <span class="identifier">_</span> <span class="special">=</span> <span class="identifier">slice_nil</span><span class="special">();</span> +</pre> +<p> + A type that can be used to get the effect of leaving out an index in a + Python slice expression: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">x</span><span class="special">[:-</span><span class="number">1</span><span class="special">]</span> +<span class="special">>>></span> <span class="identifier">x</span><span class="special">[::-</span><span class="number">1</span><span class="special">]</span> +</pre> +<p> + C++ equivalent: + </p> +<pre class="programlisting"><span class="identifier">x</span><span class="special">.</span><span class="identifier">slice</span><span class="special">(</span><span class="identifier">_</span><span class="special">,-</span><span class="number">1</span><span class="special">)</span> +<span class="identifier">x</span><span class="special">[</span><span class="identifier">slice</span><span class="special">(</span><span class="identifier">_</span><span class="special">,</span><span class="identifier">_</span><span class="special">,-</span><span class="number">1</span><span class="special">)]</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_const_attribute_policies"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_attribute_policies" title="Class const_attribute_policies">Class + <code class="computeroutput"><span class="identifier">const_attribute_policies</span></code></a> +</h3></div></div></div> +<p> + The policies which are used for proxies representing an attribute access + to a const object. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">api</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">const_attribute_policies</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">key_type</span><span class="special">;</span> + <span class="keyword">static</span> <span class="identifier">object</span> <span class="identifier">get</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">key</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_const_attribute_policies_s"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_attribute_policies_s" title="Class const_attribute_policies static functions">Class + <code class="computeroutput"><span class="identifier">const_attribute_policies</span></code> + static functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">object</span> <span class="identifier">get</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">key</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + key is an <a class="link" href="../glossary.html#ntbs">ntbs</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + accesses the attribute of target named by key. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An object managing the result of the attribute access. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="../high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a> + if a Python exception is raised. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_attribute_policies"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_attribute_policies" title="Class attribute_policies">Class + <code class="computeroutput"><span class="identifier">attribute_policies</span></code></a> +</h3></div></div></div> +<p> + The policies which are used for proxies representing an attribute access + to a mutable object. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">api</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">attribute_policies</span> <span class="special">:</span> <span class="identifier">const_attribute_policies</span> + <span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">set</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">key</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span> + <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">del</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">target</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">key</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_attribute_policies_static_"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_attribute_policies_static_" title="Class attribute_policies static functions">Class + <code class="computeroutput"><span class="identifier">attribute_policies</span></code> static + functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">set</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">key</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + key is an <a class="link" href="../glossary.html#ntbs">ntbs</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + sets the attribute of target named by key to value. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="../high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a> + if a Python exception is raised. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">del</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">target</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">key</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + key is an <a class="link" href="../glossary.html#ntbs">ntbs</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + deletes the attribute of target named by key. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="../high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a> + if a Python exception is raised. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_const_objattribute_policie"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_objattribute_policie" title="Class const_objattribute_policies">Class + <code class="computeroutput"><span class="identifier">const_objattribute_policies</span></code></a> +</h3></div></div></div> +<p> + The policies which are used for proxies representing an attribute access + to a const object when the attribute name is given as a const object. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">api</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">const_objattribute_policies</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key_type</span><span class="special">;</span> + <span class="keyword">static</span> <span class="identifier">object</span> <span class="identifier">get</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_const_objattribute_polici0"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_objattribute_polici0" title="Class const_objattribute_policies static functions">Class + <code class="computeroutput"><span class="identifier">const_objattribute_policies</span></code> + static functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">object</span> <span class="identifier">get</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + key is an object holding a string. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + accesses the attribute of target named by key. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An object managing the result of the attribute access. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="../high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a> + if a Python exception is raised. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_objattribute_policies"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_objattribute_policies" title="Class objattribute_policies">Class + <code class="computeroutput"><span class="identifier">objattribute_policies</span></code></a> +</h3></div></div></div> +<p> + The policies which are used for proxies representing an attribute access + to a mutable object when the attribute name is given as a const object. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">api</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">objattribute_policies</span> <span class="special">:</span> <span class="identifier">const_objattribute_policies</span> + <span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">set</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span> + <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">del</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">target</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_objattribute_policies_stat"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_objattribute_policies_stat" title="Class objattribute_policies static functions">Class + <code class="computeroutput"><span class="identifier">objattribute_policies</span></code> static + functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">set</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + key is an object holding a string. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + sets the attribute of target named by key to value. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="../high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a> + if a Python exception is raised. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">del</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">target</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + key is an object holding a string. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + deletes the attribute of target named by key. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="../high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a> + if a Python exception is raised. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_const_item_policies"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_item_policies" title="Class const_item_policies">Class + <code class="computeroutput"><span class="identifier">const_item_policies</span></code></a> +</h3></div></div></div> +<p> + The policies which are used for proxies representing an item access (via + the Python bracket operators []) to a const object. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">api</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">const_item_policies</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">object</span> <span class="identifier">key_type</span><span class="special">;</span> + <span class="keyword">static</span> <span class="identifier">object</span> <span class="identifier">get</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_const_item_policies_static"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_item_policies_static" title="Class const_item_policies static functions">Class + <code class="computeroutput"><span class="identifier">const_item_policies</span></code> static + functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">object</span> <span class="identifier">get</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + accesses the item of target specified by key. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An object managing the result of the item access. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="../high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a> + if a Python exception is raised. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_item_policies"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_item_policies" title="Class item_policies">Class + <code class="computeroutput"><span class="identifier">item_policies</span></code></a> +</h3></div></div></div> +<p> + The policies which are used for proxies representing an item access (via + the Python bracket operators []) to a mutable object. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">api</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">item_policies</span> <span class="special">:</span> <span class="identifier">const_item_policies</span> + <span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">set</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span> + <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">del</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_item_policies_static_funct"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_item_policies_static_funct" title="Class item_policies static functions">Class + <code class="computeroutput"><span class="identifier">item_policies</span></code> static functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">set</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + sets the item of target specified by key to value. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="../high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a> + if a Python exception is raised. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">del</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + deletes the item of target specified by key. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="../high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a> + if a Python exception is raised. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_const_slice_policies"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_slice_policies" title="Class const_slice_policies">Class + <code class="computeroutput"><span class="identifier">const_slice_policies</span></code></a> +</h3></div></div></div> +<p> + The policies which are used for proxies representing an slice access (via + the Python slice notation [x:y]) to a const object. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">api</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">const_slice_policies</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special"><</span><span class="identifier">handle</span><span class="special"><>,</span> <span class="identifier">handle</span><span class="special"><></span> <span class="special">></span> <span class="identifier">key_type</span><span class="special">;</span> + <span class="keyword">static</span> <span class="identifier">object</span> <span class="identifier">get</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">key_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_const_slice_policies_stati"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_const_slice_policies_stati" title="Class const_slice_policies static functions">Class + <code class="computeroutput"><span class="identifier">const_slice_policies</span></code> static + functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">object</span> <span class="identifier">get</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">key_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + accesses the slice of target specified by key. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An object managing the result of the slice access. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="../high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a> + if a Python exception is raised. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_slice_policies"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_slice_policies" title="Class slice_policies">Class + <code class="computeroutput"><span class="identifier">slice_policies</span></code></a> +</h3></div></div></div> +<p> + The policies which are used for proxies representing an slice access to + a mutable object. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">api</span> +<span class="special">{</span> + <span class="keyword">struct</span> <span class="identifier">slice_policies</span> <span class="special">:</span> <span class="identifier">const_slice_policies</span> + <span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">set</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">key_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span> + <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">del</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">key_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_slice_policies_static_func"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_slice_policies_static_func" title="Class slice_policies static functions">Class + <code class="computeroutput"><span class="identifier">slice_policies</span></code> static functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">set</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">key_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">,</span> <span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + sets the slice of target specified by key to value. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="../high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a> + if a Python exception is raised. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">del</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">target</span><span class="special">,</span> <span class="identifier">key_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + deletes the slice of target specified by key. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="../high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a> + if a Python exception is raised. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_template_object_operators"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_object_operators" title="Class template object_operators">Class + template <code class="computeroutput"><span class="identifier">object_operators</span></code></a> +</h3></div></div></div> +<p> + 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. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">api</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> + <span class="keyword">class</span> <span class="identifier">object_operators</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="comment">// function call</span> + <span class="comment">//</span> + <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">()()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">></span> + <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> + <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="special">...</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,...</span><span class="keyword">class</span> <span class="identifier">An</span><span class="special">></span> + <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&,...</span><span class="identifier">An</span> <span class="keyword">const</span><span class="special">&)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">detail</span><span class="special">::</span><span class="identifier">args_proxy</span> <span class="keyword">operator</span><span class="special">*</span> <span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">args_proxy</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">args</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">args_proxy</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">args</span><span class="special">,</span> + <span class="identifier">detail</span><span class="special">::</span><span class="identifier">kwds_proxy</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">kwds</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="comment">// truth value testing</span> + <span class="comment">//</span> + <span class="keyword">typedef</span> <span class="identifier">unspecified</span> <span class="identifier">bool_type</span><span class="special">;</span> + <span class="keyword">operator</span> <span class="identifier">bool_type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="comment">// Attribute access</span> + <span class="comment">//</span> + <span class="identifier">proxy</span><span class="special"><</span><span class="identifier">const_object_attribute</span><span class="special">></span> <span class="identifier">attr</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">proxy</span><span class="special"><</span><span class="identifier">object_attribute</span><span class="special">></span> <span class="identifier">attr</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*);</span> + <span class="identifier">proxy</span><span class="special"><</span><span class="identifier">const_object_objattribute</span><span class="special">></span> <span class="identifier">attr</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">proxy</span><span class="special"><</span><span class="identifier">object_objattribute</span><span class="special">></span> <span class="identifier">attr</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&);</span> + + <span class="comment">// item access</span> + <span class="comment">//</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">proxy</span><span class="special"><</span><span class="identifier">const_object_item</span><span class="special">></span> <span class="keyword">operator</span><span class="special">[](</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">proxy</span><span class="special"><</span><span class="identifier">object_item</span><span class="special">></span> <span class="keyword">operator</span><span class="special">[](</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> + + <span class="comment">// slicing</span> + <span class="comment">//</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">></span> + <span class="identifier">proxy</span><span class="special"><</span><span class="identifier">const_object_slice</span><span class="special">></span> <span class="identifier">slice</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">V</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">end</span><span class="special">)</span> <span class="keyword">const</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">></span> + <span class="identifier">proxy</span><span class="special"><</span><span class="identifier">object_slice</span><span class="special">></span> <span class="identifier">slice</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">V</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">end</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_template_object_operators_"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_object_operators_" title="Class template object_operators observer functions">Class + template <code class="computeroutput"><span class="identifier">object_operators</span></code> + observer functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">object</span> <span class="keyword">operator</span><span class="special">()()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">></span> +<span class="identifier">object</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> +<span class="identifier">object</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="special">...</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,...</span><span class="keyword">class</span> <span class="identifier">An</span><span class="special">></span> +<span class="identifier">object</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a2</span><span class="special">,...</span><span class="identifier">An</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">aN</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">call</span><span class="special"><</span><span class="identifier">object</span><span class="special">>(</span><span class="identifier">object</span><span class="special">(*</span><span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">U</span><span class="special">*>(</span><span class="keyword">this</span><span class="special">)).</span><span class="identifier">ptr</span><span class="special">(),</span> + <span class="identifier">a1</span><span class="special">,</span> + <span class="identifier">a2</span><span class="special">,...</span><span class="identifier">aN</span><span class="special">)</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">object</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">args_proxy</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">args</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">call</span> <span class="identifier">object</span> + <span class="identifier">with</span> <span class="identifier">arguments</span> + <span class="identifier">given</span> <span class="identifier">by</span> + <span class="identifier">the</span> <span class="identifier">tuple</span> + <span class="identifier">args</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">object</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">args_proxy</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">args</span><span class="special">,</span> + <span class="identifier">detail</span><span class="special">::</span><span class="identifier">kwds_proxy</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">kwds</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">call</span> <span class="identifier">object</span> + <span class="identifier">with</span> <span class="identifier">arguments</span> + <span class="identifier">given</span> <span class="identifier">by</span> + <span class="identifier">the</span> <span class="identifier">tuple</span> + <span class="identifier">args</span><span class="special">,</span> + <span class="keyword">and</span> <span class="identifier">named</span> + <span class="identifier">arguments</span> <span class="identifier">given</span> + <span class="identifier">by</span> <span class="identifier">the</span> + <span class="identifier">dictionary</span> <span class="identifier">kwds</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">operator</span> <span class="identifier">bool_type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Tests truth value of <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">call</span><span class="special"><</span><span class="identifier">object</span><span class="special">>(</span><span class="identifier">object</span><span class="special">(*</span><span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">U</span><span class="special">*>(</span><span class="keyword">this</span><span class="special">)).</span><span class="identifier">ptr</span><span class="special">(),</span> + <span class="identifier">a1</span><span class="special">,</span> + <span class="identifier">a2</span><span class="special">,...</span><span class="identifier">aN</span><span class="special">)</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">proxy</span><span class="special"><</span><span class="identifier">const_object_attribute</span><span class="special">></span> <span class="identifier">attr</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">proxy</span><span class="special"><</span><span class="identifier">object_attribute</span><span class="special">></span> <span class="identifier">attr</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + name is an <a class="link" href="../glossary.html#ntbs">ntbs</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + accesses the named attribute of *this. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + a proxy object which binds <code class="computeroutput"><span class="identifier">object</span><span class="special">(*</span><span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">U</span><span class="special">*>(</span><span class="keyword">this</span><span class="special">))</span></code> as its target, and name as its + key. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">proxy</span><span class="special"><</span><span class="identifier">const_object_objattribute</span><span class="special">></span> <span class="identifier">attr</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">object</span><span class="special">&</span> <span class="identifier">name</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">proxy</span><span class="special"><</span><span class="identifier">object_objattribute</span><span class="special">></span> <span class="identifier">attr</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">object</span><span class="special">&</span> <span class="identifier">name</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + name is a object holding a string. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + accesses the named attribute of <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + a proxy object which binds <code class="computeroutput"><span class="identifier">object</span><span class="special">(*</span><span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">U</span><span class="special">*>(</span><span class="keyword">this</span><span class="special">))</span></code> as its target, and name as its + key. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> +<span class="identifier">proxy</span><span class="special"><</span><span class="identifier">const_object_item</span><span class="special">></span> <span class="keyword">operator</span><span class="special">[](</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> +<span class="identifier">proxy</span><span class="special"><</span><span class="identifier">object_item</span><span class="special">></span> <span class="keyword">operator</span><span class="special">[](</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + accesses the item of <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> indicated by key. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + a proxy object which binds <code class="computeroutput"><span class="identifier">object</span><span class="special">(*</span><span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">U</span><span class="special">*>(</span><span class="keyword">this</span><span class="special">))</span></code> as its target, and object(key) + as its key. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">></span> +<span class="identifier">proxy</span><span class="special"><</span><span class="identifier">const_object_slice</span><span class="special">></span> <span class="identifier">slice</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">;</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">V</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">finish</span><span class="special">)</span> <span class="keyword">const</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">></span> +<span class="identifier">proxy</span><span class="special"><</span><span class="identifier">object_slice</span><span class="special">></span> <span class="identifier">slice</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">;</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">V</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">finish</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + accesses the slice of <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> indicated by <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="identifier">object</span><span class="special">(</span><span class="identifier">start</span><span class="special">),</span> <span class="identifier">object</span><span class="special">(</span><span class="identifier">finish</span><span class="special">))</span></code>. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + a proxy object which binds <code class="computeroutput"><span class="identifier">object</span><span class="special">(*</span><span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">U</span><span class="special">*>(</span><span class="keyword">this</span><span class="special">))</span></code> as its target, and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="identifier">object</span><span class="special">(</span><span class="identifier">start</span><span class="special">),</span> + <span class="identifier">object</span><span class="special">(</span><span class="identifier">finish</span><span class="special">))</span></code> + as its key. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_object"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object">Class + <code class="computeroutput"><span class="identifier">object</span></code></a> +</h3></div></div></div> +<p> + 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 <code class="computeroutput"><span class="identifier">object_operators</span><span class="special"><</span><span class="identifier">object</span><span class="special">></span></code>, and the free functions defined in + this header. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">api</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">object</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object_operators</span><span class="special"><</span><span class="identifier">object</span><span class="special">></span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">object</span><span class="special">();</span> + <span class="identifier">object</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">explicit</span> <span class="identifier">object</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">);</span> + + <span class="special">~</span><span class="identifier">object</span><span class="special">();</span> + + <span class="identifier">object</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&);</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">ptr</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">bool</span> <span class="identifier">is_none</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_object_constructors_and_de"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object_constructors_and_de" title="Class object constructors and destructor">Class + <code class="computeroutput"><span class="identifier">object</span></code> constructors and destructor</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">object</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Constructs an object managing a reference to the Python None object. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + nothing. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> +<span class="keyword">explicit</span> <span class="identifier">object</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + converts x to python and manages a reference to it. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="../high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set">error_already_set</a> + and sets a Python TypeError exception if no such conversion is possible. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="special">~</span><span class="identifier">object</span><span class="special">();</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + decrements the reference count of the internally-held object. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_object_modifiers"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object_modifiers" title="Class object modifiers">Class + <code class="computeroutput"><span class="identifier">object</span></code> modifiers</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">ptr</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + a pointer to the internally-held Python object. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">is_none</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + result of <code class="computeroutput"><span class="special">(</span><span class="identifier">ptr</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">Py_None</span><span class="special">)</span></code> + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_template_proxy"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_proxy" title="Class template proxy">Class + template <code class="computeroutput"><span class="identifier">proxy</span></code></a> +</h3></div></div></div> +<p> + 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. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">api</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Policies</span><span class="special">></span> + <span class="keyword">class</span> <span class="identifier">proxy</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object_operators</span><span class="special"><</span><span class="identifier">proxy</span><span class="special"><</span><span class="identifier">Policies</span><span class="special">></span> <span class="special">></span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="keyword">operator</span> <span class="identifier">object</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">proxy</span> <span class="keyword">const</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span><span class="identifier">proxy</span> <span class="keyword">const</span><span class="special">&)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">inline</span> <span class="identifier">proxy</span> <span class="keyword">const</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">void</span> <span class="identifier">del</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> + <span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">+=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> + <span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">-=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> + <span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">*=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> + <span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">/=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> + <span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">%=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> + <span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special"><<=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> + <span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">>>=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> + <span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">&=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> + <span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">|=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_template_proxy_observer_fu"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_proxy_observer_fu" title="Class template proxy observer functions">Class + template <code class="computeroutput"><span class="identifier">proxy</span></code> observer functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">operator</span> <span class="identifier">object</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + applies <code class="computeroutput"><span class="identifier">Policies</span><span class="special">::</span><span class="identifier">get</span><span class="special">(</span><span class="identifier">target</span><span class="special">,</span> <span class="identifier">key</span><span class="special">)</span></code> with the proxy's target and key + objects. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.class_template_proxy_modifier_fu"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_template_proxy_modifier_fu" title="Class template proxy modifier functions">Class + template <code class="computeroutput"><span class="identifier">proxy</span></code> modifier functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">proxy</span> <span class="keyword">const</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span><span class="identifier">proxy</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> +<span class="keyword">inline</span> <span class="identifier">proxy</span> <span class="keyword">const</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">Policies</span><span class="special">::</span><span class="identifier">set</span><span class="special">(</span><span class="identifier">target</span><span class="special">,</span> + <span class="identifier">key</span> <span class="special">,</span> + <span class="identifier">object</span><span class="special">(</span><span class="identifier">rhs</span><span class="special">))</span></code> + with the proxy's target and key objects. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> +<span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">+=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> +<span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">-=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> +<span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">*=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> +<span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">/=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> +<span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">%=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> +<span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special"><<=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> +<span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">>>=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> +<span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">&=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> +<span class="identifier">proxy</span> <span class="keyword">operator</span><span class="special">|=(</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + for a given <code class="computeroutput"><span class="keyword">operator</span><span class="error">@</span><span class="special">=</span></code>, + <code class="computeroutput"><span class="identifier">object</span><span class="special">(*</span><span class="keyword">this</span><span class="special">)</span> <span class="error">@</span><span class="special">=</span> <span class="identifier">rhs</span><span class="special">;</span></code> + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">del</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Policies::del(target, key ) with the proxy's target and key objects. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.functions"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.functions" title="Functions">Functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">del</span><span class="special">(</span><span class="identifier">proxy</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">x</span><span class="special">.</span><span class="identifier">del</span><span class="special">()</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">>(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">>=(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special"><(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special"><=(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">==(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">!=(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + returns the result of applying the operator to <code class="computeroutput"><span class="identifier">object</span><span class="special">(</span><span class="identifier">l</span><span class="special">)</span></code> and <code class="computeroutput"><span class="identifier">object</span><span class="special">(</span><span class="identifier">r</span><span class="special">)</span></code>, respectively, in Python. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">+(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">-(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">*(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">/(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">%(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special"><<(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">>>(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">&(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">^(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">L</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span> <span class="keyword">operator</span><span class="special">|(</span><span class="identifier">L</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + returns the result of applying the operator to <code class="computeroutput"><span class="identifier">object</span><span class="special">(</span><span class="identifier">l</span><span class="special">)</span></code> and <code class="computeroutput"><span class="identifier">object</span><span class="special">(</span><span class="identifier">r</span><span class="special">)</span></code>, respectively, in Python. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">+=(</span><span class="identifier">object</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">-=(</span><span class="identifier">object</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">*=(</span><span class="identifier">object</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">/=(</span><span class="identifier">object</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">%=(</span><span class="identifier">object</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span><span class="special">&</span> <span class="keyword">operator</span><span class="special"><<=(</span><span class="identifier">object</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">)</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">>>=(</span><span class="identifier">object</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">&=(</span><span class="identifier">object</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">^=(</span><span class="identifier">object</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">></span> <span class="identifier">object</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">|=(</span><span class="identifier">object</span><span class="special">&</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">R</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">r</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + assigns to <code class="computeroutput"><span class="identifier">l</span></code> the + result of applying the corresponding Python inplace operator to + <code class="computeroutput"><span class="identifier">l</span></code> and <code class="computeroutput"><span class="identifier">object</span><span class="special">(</span><span class="identifier">r</span><span class="special">)</span></code>, + respectively. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + l + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">long</span> <span class="identifier">len</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">obj</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">PyObject_Length</span><span class="special">(</span><span class="identifier">obj</span><span class="special">.</span><span class="identifier">ptr</span><span class="special">())</span></code> + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">len</span><span class="special">()</span></code> + of object. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_object_hpp.example"></a><a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<p> + Python code: + </p> +<pre class="programlisting"><span class="identifier">def</span> <span class="identifier">sum_items</span><span class="special">(</span><span class="identifier">seq</span><span class="special">):</span> + <span class="identifier">result</span> <span class="special">=</span> <span class="number">0</span> + <span class="keyword">for</span> <span class="identifier">x</span> <span class="identifier">in</span> <span class="identifier">seq</span><span class="special">:</span> + <span class="identifier">result</span> <span class="special">+=</span> <span class="identifier">x</span> + <span class="keyword">return</span> <span class="identifier">result</span> +</pre> +<p> + C++ version + </p> +<pre class="programlisting"><span class="identifier">object</span> <span class="identifier">sum_items</span><span class="special">(</span><span class="identifier">object</span> <span class="identifier">seq</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">object</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">object</span><span class="special">(</span><span class="number">0</span><span class="special">);</span> + <span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="identifier">len</span><span class="special">(</span><span class="identifier">seq</span><span class="special">);</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span> + <span class="identifier">result</span> <span class="special">+=</span> <span class="identifier">seq</span><span class="special">[</span><span class="identifier">i</span><span class="special">];</span> + <span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_numeric_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_str_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/object_wrappers/boost_python_slice_hpp.html b/libs/python/doc/html/reference/object_wrappers/boost_python_slice_hpp.html new file mode 100644 index 0000000000..8527f6e2c5 --- /dev/null +++ b/libs/python/doc/html/reference/object_wrappers/boost_python_slice_hpp.html @@ -0,0 +1,305 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/slice.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../object_wrappers.html" title="Chapter 3. Object Wrappers"> +<link rel="prev" href="boost_python_str_hpp.html" title="boost/python/str.hpp"> +<link rel="next" href="boost_python_tuple_hpp.html" title="boost/python/tuple.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_str_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_tuple_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="object_wrappers.boost_python_slice_hpp"></a><a class="link" href="boost_python_slice_hpp.html" title="boost/python/slice.hpp">boost/python/slice.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice">Class + <code class="computeroutput"><span class="identifier">slice</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_constructors">Class + <code class="computeroutput"><span class="identifier">slice</span></code> constructors</a></span></dt> +<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_observer_functions">Class + <code class="computeroutput"><span class="identifier">slice</span></code> observer functions</a></span></dt> +<dt><span class="section"><a href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_slice_hpp.introduction"></a><a class="link" href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Exposes a <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + for the Python <a href="http://www.python.org/doc/2.3.3/api/slice-objects.html" target="_top"><code class="computeroutput"><span class="identifier">slice</span></code></a> type. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_slice_hpp.class_slice"></a><a class="link" href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice" title="Class slice">Class + <code class="computeroutput"><span class="identifier">slice</span></code></a> +</h3></div></div></div> +<p> + Exposes the extended slicing protocol by wrapping the built-in slice type. + The semantics of the constructors and member functions defined below can + be fully understood by reading the <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + concept definition. Since <code class="computeroutput"><span class="identifier">slice</span></code> + is publicly derived from <a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object"><code class="computeroutput"><span class="identifier">object</span></code></a>, the public <code class="computeroutput"><span class="identifier">object</span></code> interface applies to <code class="computeroutput"><span class="identifier">slice</span></code> instances as well. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">slice</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">slice</span><span class="special">();</span> <span class="comment">// create an empty slice, equivalent to [::]</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Int1</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Int2</span><span class="special">></span> + <span class="identifier">slice</span><span class="special">(</span><span class="identifier">Int1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Int2</span> <span class="identifier">stop</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Int1</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Int2</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Int3</span><span class="special">></span> + <span class="identifier">slice</span><span class="special">(</span><span class="identifier">Int1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Int2</span> <span class="identifier">stop</span><span class="special">,</span> <span class="identifier">Int3</span> <span class="identifier">step</span><span class="special">);</span> + + <span class="comment">// Access the parameters this slice was created with.</span> + <span class="identifier">object</span> <span class="identifier">start</span><span class="special">();</span> + <span class="identifier">object</span> <span class="identifier">stop</span><span class="special">();</span> + <span class="identifier">object</span> <span class="identifier">step</span><span class="special">();</span> + + <span class="comment">// The return type of slice::get_indices()</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">RandomAccessIterator</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">range</span> + <span class="special">{</span> + <span class="identifier">RandomAccessIterator</span> <span class="identifier">start</span><span class="special">;</span> + <span class="identifier">RandomAccessIterator</span> <span class="identifier">stop</span><span class="special">;</span> + <span class="keyword">int</span> <span class="identifier">step</span><span class="special">;</span> + <span class="special">};</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">RandomAccessIterator</span><span class="special">></span> + <span class="identifier">range</span><span class="special"><</span><span class="identifier">RandomAccessIterator</span><span class="special">></span> + <span class="identifier">get_indices</span><span class="special">(</span> + <span class="identifier">RandomAccessIterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">begin</span><span class="special">,</span> + <span class="identifier">RandomAccessIterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">end</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_slice_hpp.class_slice_constructors"></a><a class="link" href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_constructors" title="Class slice constructors">Class + <code class="computeroutput"><span class="identifier">slice</span></code> constructors</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">slice</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + constructs a slice with default stop, start, and step values. Equivalent + to the slice object created as part of the Python expression <code class="computeroutput"><span class="identifier">base</span><span class="special">[::]</span></code>. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + nothing + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Int1</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Int2</span><span class="special">></span> +<span class="identifier">slice</span><span class="special">(</span><span class="identifier">Int1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Int2</span> <span class="identifier">stop</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">start</span></code>, <code class="computeroutput"><span class="identifier">stop</span></code>, and <code class="computeroutput"><span class="identifier">step</span></code> + are of type <code class="computeroutput"><span class="identifier">slice_nil</span></code> + or convertible to type <code class="computeroutput"><span class="identifier">object</span></code>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + constructs a new slice with default step value and the provided start + and stop values. Equivalent to the slice object created by the built-in + Python function <code class="computeroutput"><span class="identifier">slice</span><span class="special">(</span><span class="identifier">start</span><span class="special">,</span><span class="identifier">stop</span><span class="special">)</span></code>, or as part of the Python expression + <code class="computeroutput"><span class="identifier">base</span><span class="special">[</span><span class="identifier">start</span><span class="special">:</span><span class="identifier">stop</span><span class="special">]</span></code>. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">error_already_set</span></code> + and sets a Python TypeError exception if no conversion is possible + from the arguments to type object. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Int1</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Int2</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Int3</span><span class="special">></span> +<span class="identifier">slice</span><span class="special">(</span><span class="identifier">Int1</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">Int2</span> <span class="identifier">stop</span><span class="special">,</span> <span class="identifier">Int3</span> <span class="identifier">step</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">start</span></code>, <code class="computeroutput"><span class="identifier">stop</span></code>, and <code class="computeroutput"><span class="identifier">step</span></code> + are <code class="computeroutput"><span class="identifier">slice_nil</span></code> or + convertible to type <code class="computeroutput"><span class="identifier">object</span></code>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + constructs a new slice with start stop and step values. Equivalent + to the slice object created by the built-in Python function <code class="computeroutput"><span class="identifier">slice</span><span class="special">(</span><span class="identifier">start</span><span class="special">,</span><span class="identifier">stop</span><span class="special">,</span><span class="identifier">step</span><span class="special">)</span></code>, + or as part of the Python expression <code class="computeroutput"><span class="identifier">base</span><span class="special">[</span><span class="identifier">start</span><span class="special">:</span><span class="identifier">stop</span><span class="special">:</span><span class="identifier">step</span><span class="special">]</span></code>. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">error_already_set</span></code> + and sets a Python TypeError exception if no conversion is possible + from the arguments to type object. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_slice_hpp.class_slice_observer_functions"></a><a class="link" href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.class_slice_observer_functions" title="Class slice observer functions">Class + <code class="computeroutput"><span class="identifier">slice</span></code> observer functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">object</span> <span class="identifier">slice</span><span class="special">::</span><span class="identifier">start</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">object</span> <span class="identifier">slice</span><span class="special">::</span><span class="identifier">stop</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">object</span> <span class="identifier">slice</span><span class="special">::</span><span class="identifier">step</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + None + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + nothing + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + the parameter that the slice was created with. If the parameter was + omitted or <code class="computeroutput"><span class="identifier">slice_nil</span></code> + was used when the slice was created, than that parameter will be + a reference to <code class="computeroutput"><span class="identifier">PyNone</span></code> + and compare equal to a default-constructed object. In principal, + any object may be used when creating a slice object, but in practice + they are usually integers. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">RandomAccessIterator</span><span class="special">></span> +<span class="identifier">slice</span><span class="special">::</span><span class="identifier">range</span><span class="special"><</span><span class="identifier">RandomAccessIterator</span><span class="special">></span> +<span class="identifier">slice</span><span class="special">::</span><span class="identifier">get_indices</span><span class="special">(</span> + <span class="identifier">RandomAccessIterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">begin</span><span class="special">,</span> + <span class="identifier">RandomAccessIterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">end</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Arguments</span></dt> +<dd><p> + A pair of STL-conforming Random Access Iterators that form a half-open + range. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Create a RandomAccessIterator pair that defines a fully-closed range + within the <code class="computeroutput"><span class="special">[</span><span class="identifier">begin</span><span class="special">,</span><span class="identifier">end</span><span class="special">)</span></code> range of its arguments. This function + translates this slice's indices while accounting for the effects + of any PyNone or negative indices, and non-singular step sizes. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + a <code class="computeroutput"><span class="identifier">slice</span><span class="special">::</span><span class="identifier">range</span></code> that has been initialized + with a non-zero value of step and a pair of RandomAccessIterators + that point within the range of this functions arguments and define + a closed interval. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + Raises a Python TypeError exception if any of this slice's arguments + are neither references to PyNone nor convertible to int. Throws + <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">invalid_argument</span></code> if the resulting + range would be empty. You should always wrap calls to <code class="computeroutput"><span class="identifier">slice</span><span class="special">::</span><span class="identifier">get_indices</span><span class="special">()</span></code> + within <code class="computeroutput"><span class="keyword">try</span> <span class="special">{</span> + <span class="special">...;</span> <span class="special">}</span> + <span class="keyword">catch</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">invalid_argument</span><span class="special">)</span> + <span class="special">{}</span></code> to handle this case and + take appropriate action. + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + closed-interval: If an open interval were used, then for step size + other than 1, the required state for the end iterator would point + beyond the one-past-the-end position or before the beginning of the + specified range. exceptions on empty slice: It is impossible to define + a closed interval over an empty range, so some other form of error + checking would have to be used to prevent undefined behavior. In + the case where the exception is not caught, it will simply be translated + to Python by the default exception handling mechanisms. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_slice_hpp.example"></a><a class="link" href="boost_python_slice_hpp.html#object_wrappers.boost_python_slice_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="comment">// Perform an extended slice of a Python list.</span> +<span class="comment">// Warning: extended slicing was not supported for built-in types prior </span> +<span class="comment">// to Python 2.3</span> +<span class="identifier">list</span> <span class="identifier">odd_elements</span><span class="special">(</span><span class="identifier">list</span> <span class="identifier">l</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">l</span><span class="special">[</span><span class="identifier">slice</span><span class="special">(</span><span class="identifier">_</span><span class="special">,</span><span class="identifier">_</span><span class="special">,</span><span class="number">2</span><span class="special">)];</span> +<span class="special">}</span> + +<span class="comment">// Perform a multidimensional extended slice of a Numeric.array</span> +<span class="identifier">numeric</span><span class="special">::</span><span class="identifier">array</span> <span class="identifier">even_columns</span><span class="special">(</span><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">array</span> <span class="identifier">arr</span><span class="special">)</span> +<span class="special">{</span> + <span class="comment">// select every other column, starting with the second, of a 2-D array.</span> + <span class="comment">// Equivalent to "return arr[:, 1::2]" in Python.</span> + <span class="keyword">return</span> <span class="identifier">arr</span><span class="special">[</span><span class="identifier">make_tuple</span><span class="special">(</span> <span class="identifier">slice</span><span class="special">(),</span> <span class="identifier">slice</span><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="identifier">_</span><span class="special">,</span><span class="number">2</span><span class="special">))];</span> +<span class="special">}</span> + +<span class="comment">// Perform a summation over a slice of a std::vector.</span> +<span class="keyword">double</span> <span class="identifier">partial_sum</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">double</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">Foo</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">slice</span> <span class="identifier">index</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">slice</span><span class="special">::</span><span class="identifier">range</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">double</span><span class="special">>::</span><span class="identifier">const_iterator</span><span class="special">></span> <span class="identifier">bounds</span><span class="special">;</span> + <span class="keyword">try</span> <span class="special">{</span> + <span class="identifier">bounds</span> <span class="special">=</span> <span class="identifier">index</span><span class="special">.</span><span class="identifier">get_indices</span><span class="special"><>(</span><span class="identifier">Foo</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">Foo</span><span class="special">.</span><span class="identifier">end</span><span class="special">());</span> + <span class="special">}</span> + <span class="keyword">catch</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">invalid_argument</span><span class="special">)</span> <span class="special">{</span> + <span class="keyword">return</span> <span class="number">0.0</span><span class="special">;</span> + <span class="special">}</span> + <span class="keyword">double</span> <span class="identifier">sum</span> <span class="special">=</span> <span class="number">0.0</span><span class="special">;</span> + <span class="keyword">while</span> <span class="special">(</span><span class="identifier">bounds</span><span class="special">.</span><span class="identifier">start</span> <span class="special">!=</span> <span class="identifier">bounds</span><span class="special">.</span><span class="identifier">stop</span><span class="special">)</span> <span class="special">{</span> + <span class="identifier">sum</span> <span class="special">+=</span> <span class="special">*</span><span class="identifier">bounds</span><span class="special">.</span><span class="identifier">start</span><span class="special">;</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">advance</span><span class="special">(</span> <span class="identifier">bounds</span><span class="special">.</span><span class="identifier">start</span><span class="special">,</span> <span class="identifier">bounds</span><span class="special">.</span><span class="identifier">step</span><span class="special">);</span> + <span class="special">}</span> + <span class="identifier">sum</span> <span class="special">+=</span> <span class="special">*</span><span class="identifier">bounds</span><span class="special">.</span><span class="identifier">start</span><span class="special">;</span> + <span class="keyword">return</span> <span class="identifier">sum</span><span class="special">;</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_str_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_tuple_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/object_wrappers/boost_python_str_hpp.html b/libs/python/doc/html/reference/object_wrappers/boost_python_str_hpp.html new file mode 100644 index 0000000000..446f76233c --- /dev/null +++ b/libs/python/doc/html/reference/object_wrappers/boost_python_str_hpp.html @@ -0,0 +1,211 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/str.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../object_wrappers.html" title="Chapter 3. Object Wrappers"> +<link rel="prev" href="boost_python_object_hpp.html" title="boost/python/object.hpp"> +<link rel="next" href="boost_python_slice_hpp.html" title="boost/python/slice.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_object_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_slice_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="object_wrappers.boost_python_str_hpp"></a><a class="link" href="boost_python_str_hpp.html" title="boost/python/str.hpp">boost/python/str.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_str_hpp.html#object_wrappers.boost_python_str_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_str_hpp.html#object_wrappers.boost_python_str_hpp.class_str">Class + <code class="computeroutput"><span class="identifier">str</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_str_hpp.html#object_wrappers.boost_python_str_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_str_hpp.introduction"></a><a class="link" href="boost_python_str_hpp.html#object_wrappers.boost_python_str_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Exposes a <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + for the Python <a href="http://www.python.org/dev/doc/devel/lib/string-methods.html" target="_top"><code class="computeroutput"><span class="identifier">str</span></code></a> type. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_str_hpp.class_str"></a><a class="link" href="boost_python_str_hpp.html#object_wrappers.boost_python_str_hpp.class_str" title="Class str">Class + <code class="computeroutput"><span class="identifier">str</span></code></a> +</h3></div></div></div> +<p> + Exposes the <a href="http://www.python.org/dev/doc/devel/lib/string-methods.html" target="_top">string + methods</a> of Python's built-in <code class="computeroutput"><span class="identifier">str</span></code> + type. The semantics of the constructors and member functions defined below, + except for the two-argument constructors which construct str objects from + a range of characters, can be fully understood by reading the <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + concept definition. Since str is publicly derived from <a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object"><code class="computeroutput"><span class="identifier">object</span></code></a>, the public <code class="computeroutput"><span class="identifier">object</span></code> interface applies to <code class="computeroutput"><span class="identifier">str</span></code> instances as well. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">str</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="identifier">str</span><span class="special">();</span> <span class="comment">// new str</span> + + <span class="identifier">str</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">s</span><span class="special">);</span> <span class="comment">// new str</span> + + <span class="identifier">str</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">start</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">finish</span><span class="special">);</span> <span class="comment">// new str</span> + <span class="identifier">str</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">length</span><span class="special">);</span> <span class="comment">// new str</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">explicit</span> <span class="identifier">str</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">other</span><span class="special">);</span> + + <span class="identifier">str</span> <span class="identifier">capitalize</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">str</span> <span class="identifier">center</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">width</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">count</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">count</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">,</span><span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">count</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">,</span><span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">T3</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">end</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">object</span> <span class="identifier">decode</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">object</span> <span class="identifier">decode</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">encoding</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="identifier">object</span> <span class="identifier">decode</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">encoding</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">errors</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">object</span> <span class="identifier">encode</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">object</span> <span class="identifier">encode</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">encoding</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="identifier">object</span> <span class="identifier">encode</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">encoding</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">errors</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">bool</span> <span class="identifier">endswith</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">suffix</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="keyword">bool</span> <span class="identifier">endswith</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">suffix</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span> + <span class="keyword">bool</span> <span class="identifier">endswith</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">suffix</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">T3</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">end</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">str</span> <span class="identifier">expandtabs</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">str</span> <span class="identifier">expandtabs</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">tabsize</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">find</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">find</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">find</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">T3</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">end</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">index</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">index</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">index</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">T3</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">end</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">bool</span> <span class="identifier">isalnum</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">bool</span> <span class="identifier">isalpha</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">bool</span> <span class="identifier">isdigit</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">bool</span> <span class="identifier">islower</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">bool</span> <span class="identifier">isspace</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">bool</span> <span class="identifier">istitle</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">bool</span> <span class="identifier">isupper</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">str</span> <span class="identifier">join</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sequence</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">str</span> <span class="identifier">ljust</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">width</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">str</span> <span class="identifier">lower</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">str</span> <span class="identifier">lstrip</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="identifier">str</span> <span class="identifier">replace</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">old</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">new_</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span> + <span class="identifier">str</span> <span class="identifier">replace</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">old</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">new_</span><span class="special">,</span> <span class="identifier">T3</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">maxsplit</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">rfind</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">rfind</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">rfind</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">T3</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">end</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">rindex</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">rindex</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span> + <span class="keyword">long</span> <span class="identifier">rindex</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sub</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">T3</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">end</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">str</span> <span class="identifier">rjust</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">width</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">str</span> <span class="identifier">rstrip</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">list</span> <span class="identifier">split</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">list</span> <span class="identifier">split</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sep</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="identifier">list</span> <span class="identifier">split</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sep</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">maxsplit</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">list</span> <span class="identifier">splitlines</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">list</span> <span class="identifier">splitlines</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">keepends</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">bool</span> <span class="identifier">startswith</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">prefix</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="keyword">bool</span> <span class="identifier">startswidth</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">prefix</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span> + <span class="keyword">bool</span> <span class="identifier">startswidth</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">prefix</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">start</span><span class="special">,</span> <span class="identifier">T3</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">end</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">str</span> <span class="identifier">strip</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">str</span> <span class="identifier">swapcase</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">str</span> <span class="identifier">title</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="identifier">str</span> <span class="identifier">translate</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">table</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> + <span class="identifier">str</span> <span class="identifier">translate</span><span class="special">(</span><span class="identifier">T1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">table</span><span class="special">,</span> <span class="identifier">T2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">deletechars</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="identifier">str</span> <span class="identifier">upper</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_str_hpp.example"></a><a class="link" href="boost_python_str_hpp.html#object_wrappers.boost_python_str_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">str</span> <span class="identifier">remove_angle_brackets</span><span class="special">(</span><span class="identifier">str</span> <span class="identifier">x</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">strip</span><span class="special">(</span><span class="char">'<'</span><span class="special">).</span><span class="identifier">strip</span><span class="special">(</span><span class="char">'>'</span><span class="special">);</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_object_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_slice_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/object_wrappers/boost_python_tuple_hpp.html b/libs/python/doc/html/reference/object_wrappers/boost_python_tuple_hpp.html new file mode 100644 index 0000000000..836f18da3e --- /dev/null +++ b/libs/python/doc/html/reference/object_wrappers/boost_python_tuple_hpp.html @@ -0,0 +1,119 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/tuple.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../object_wrappers.html" title="Chapter 3. Object Wrappers"> +<link rel="prev" href="boost_python_slice_hpp.html" title="boost/python/slice.hpp"> +<link rel="next" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_slice_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../function_invocation_and_creation.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="object_wrappers.boost_python_tuple_hpp"></a><a class="link" href="boost_python_tuple_hpp.html" title="boost/python/tuple.hpp">boost/python/tuple.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.class_tuple">Class + <code class="computeroutput"><span class="identifier">tuple</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.function_make_tuple">Function + <code class="computeroutput"><span class="identifier">make_tuple</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_tuple_hpp.introduction"></a><a class="link" href="boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Exposes a <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + for the Python <a href="http://www.python.org/doc/current/tut/node7.html#SECTION007300000000000000000%60tuple%60" target="_top">http://www.python.org/doc/current/tut/node7.html#SECTION007300000000000000000%60tuple%60</a> + type. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_tuple_hpp.class_tuple"></a><a class="link" href="boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.class_tuple" title="Class tuple">Class + <code class="computeroutput"><span class="identifier">tuple</span></code></a> +</h3></div></div></div> +<p> + 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 <a class="link" href="../concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements" title="TypeWrapper Concept Requirements">TypeWrapper</a> + concept definition. Since tuple is publicly derived from <a class="link" href="boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object"><code class="computeroutput"><span class="identifier">object</span></code></a>, the public <code class="computeroutput"><span class="identifier">object</span></code> interface applies to <code class="computeroutput"><span class="identifier">tuple</span></code> instances as well. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">tuple</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">object</span> + <span class="special">{</span> + <span class="comment">// tuple() -> an empty tuple</span> + <span class="identifier">tuple</span><span class="special">();</span> + + <span class="comment">// tuple(sequence) -> tuple initialized from sequence's items</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">explicit</span> <span class="identifier">tuple</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">sequence</span><span class="special">)</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_tuple_hpp.function_make_tuple"></a><a class="link" href="boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.function_make_tuple" title="Function make_tuple">Function + <code class="computeroutput"><span class="identifier">make_tuple</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="identifier">tuple</span> <span class="identifier">make_tuple</span><span class="special">();</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">></span> + <span class="identifier">tuple</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a0</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> + <span class="identifier">tuple</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a0</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a1</span><span class="special">);</span> + <span class="special">...</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">,...</span><span class="keyword">class</span> <span class="identifier">An</span><span class="special">></span> + <span class="identifier">tuple</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a0</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a1</span><span class="special">,...</span><span class="identifier">An</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">an</span><span class="special">);</span> +<span class="special">}}</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effect</span></dt> +<dd><p> + Constructs a new tuple object composed of <code class="computeroutput"><span class="identifier">object</span><span class="special">(</span><span class="identifier">a0</span><span class="special">),</span> <span class="identifier">object</span><span class="special">(</span><span class="identifier">a0</span><span class="special">),...</span><span class="identifier">object</span><span class="special">(</span><span class="identifier">an</span><span class="special">)</span></code>. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="object_wrappers.boost_python_tuple_hpp.example"></a><a class="link" href="boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="identifier">tuple</span> <span class="identifier">head_and_tail</span><span class="special">(</span><span class="identifier">object</span> <span class="identifier">sequence</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">sequence</span><span class="special">[</span><span class="number">0</span><span class="special">],</span><span class="identifier">sequence</span><span class="special">[-</span><span class="number">1</span><span class="special">]);</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_slice_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../object_wrappers.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../function_invocation_and_creation.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/reference_HTML.manifest b/libs/python/doc/html/reference/reference_HTML.manifest new file mode 100644 index 0000000000..5a7215133e --- /dev/null +++ b/libs/python/doc/html/reference/reference_HTML.manifest @@ -0,0 +1,59 @@ +index.html +concepts.html +concepts/dereferenceable.html +concepts/extractor.html +concepts/holdergenerator.html +concepts/resultconverter.html +concepts/objectwrapper.html +high_level_components.html +high_level_components/boost_python_def_hpp.html +high_level_components/boost_python_def_visitor_hpp.html +high_level_components/boost_python_docstring_options_h.html +high_level_components/boost_python_enum_hpp.html +high_level_components/boost_python_errors_hpp.html +high_level_components/boost_python_exception_translato.html +high_level_components/boost_python_init_hpp.html +high_level_components/boost_python_iterator_hpp.html +high_level_components/boost_python_module_hpp.html +high_level_components/boost_python_operators_hpp.html +high_level_components/boost_python_scope_hpp.html +high_level_components/boost_python_stl_iterator_hpp.html +high_level_components/boost_python_wrapper_hpp.html +object_wrappers.html +object_wrappers/boost_python_list_hpp.html +object_wrappers/boost_python_long_hpp.html +object_wrappers/boost_python_numeric_hpp.html +object_wrappers/boost_python_object_hpp.html +object_wrappers/boost_python_str_hpp.html +object_wrappers/boost_python_slice_hpp.html +object_wrappers/boost_python_tuple_hpp.html +function_invocation_and_creation.html +function_invocation_and_creation/boost_python_call_hpp.html +function_invocation_and_creation/boost_python_call_method_hpp.html +function_invocation_and_creation/boost_python_data_members_hpp.html +function_invocation_and_creation/boost_python_make_function_hpp.html +function_invocation_and_creation/boost_python_overloads_hpp.html +function_invocation_and_creation/boost_python_ptr_hpp.html +function_invocation_and_creation/boost_python_raw_function_hpp.html +function_invocation_and_creation/function_documentation.html +function_invocation_and_creation/models_of_callpolicies.html +function_invocation_and_creation/models_of_resultconverter.html +function_invocation_and_creation/models_of_resultconvertergenerat.html +to_from_python_type_conversion.html +to_from_python_type_conversion/boost_python_implicit_hpp.html +to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html +to_from_python_type_conversion/boost_python_opaque_pointer_conv.html +to_from_python_type_conversion/boost_python_to_python_converter.html +to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html +embedding.html +embedding/boost_python_import_hpp.html +utility_and_infrastructure.html +utility_and_infrastructure/boost_python_instance_holder_hpp.html +utility_and_infrastructure/boost_python_pointee_hpp.html +utility_and_infrastructure/boost_python_handle_hpp.html +utility_and_infrastructure/boost_python_type_id_hpp.html +utility_and_infrastructure/boost_python_ssize_t_hpp.html +topics.html +topics/pickle_support.html +topics/indexing_support.html +glossary.html diff --git a/libs/python/doc/html/reference/to_from_python_type_conversion.html b/libs/python/doc/html/reference/to_from_python_type_conversion.html new file mode 100644 index 0000000000..804c93c02a --- /dev/null +++ b/libs/python/doc/html/reference/to_from_python_type_conversion.html @@ -0,0 +1,287 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 5. To/From Python Type Conversion</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="index.html" title="Boost.Python Reference Manual"> +<link rel="prev" href="function_invocation_and_creation/models_of_resultconvertergenerat.html" title="Models of ResultConverterGenerator"> +<link rel="next" href="to_from_python_type_conversion/boost_python_implicit_hpp.html" title="boost/python/implicit.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="function_invocation_and_creation/models_of_resultconvertergenerat.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="to_from_python_type_conversion/boost_python_implicit_hpp.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="to_from_python_type_conversion"></a>Chapter 5. To/From Python Type Conversion</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp">boost/python/extract.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract">Class + template <code class="computeroutput"><span class="identifier">extract</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract_construct">Class + template <code class="computeroutput"><span class="identifier">extract</span></code> constructors + and destructor</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract_observer_">Class + template <code class="computeroutput"><span class="identifier">extract</span></code> observer + functions</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_implicit_hpp.html">boost/python/implicit.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_implicit_hpp.html#to_from_python_type_conversion.boost_python_implicit_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_implicit_hpp.html#to_from_python_type_conversion.boost_python_implicit_hpp.function_template_implicit_conve">Function + template <code class="computeroutput"><span class="identifier">implicit_convertible</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_implicit_hpp.html#to_from_python_type_conversion.boost_python_implicit_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html">boost/python/lvalue_from_pytype.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_lvalue_from_pytyp">Class + template <code class="computeroutput"><span class="identifier">lvalue_from_pytype</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_identity">Class + template <code class="computeroutput"><span class="identifier">extract_identity</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_member">Class + template <code class="computeroutput"><span class="identifier">extract_member</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_opaque_pointer_conv.html">boost/python/opaque_pointer_converter.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.class_template_opaque_constructo">Class + template <code class="computeroutput"><span class="identifier">opaque</span></code> constructor</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.macro_boost_python_opaque_specia">Macro + <code class="computeroutput"><span class="identifier">BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</span><span class="special">(</span><span class="identifier">Pointee</span><span class="special">)</span></code></a></span></dt> +</dl></dd> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_to_python_converter.html">boost/python/to_python_converter.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert">Class + template <code class="computeroutput"><span class="identifier">to_python_converter</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html">boost/python/register_ptr_to_python.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html#to_from_python_type_conversion.boost_python_register_ptr_to_pyt.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html#to_from_python_type_conversion.boost_python_register_ptr_to_pyt.function_register_ptr_to_python">Function + <code class="computeroutput"><span class="identifier">register_ptr_to_python</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html#to_from_python_type_conversion.boost_python_register_ptr_to_pyt.example">Example</a></span></dt> +</dl></dd> +</dl> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="to_from_python_type_conversion.boost_python_extract_hpp"></a><a class="link" href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp" title="boost/python/extract.hpp">boost/python/extract.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract">Class + template <code class="computeroutput"><span class="identifier">extract</span></code></a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract_construct">Class + template <code class="computeroutput"><span class="identifier">extract</span></code> constructors + and destructor</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract_observer_">Class + template <code class="computeroutput"><span class="identifier">extract</span></code> observer + functions</a></span></dt> +<dt><span class="section"><a href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_extract_hpp.introduction"></a><a class="link" href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Exposes a mechanism for extracting C++ object values from generalized Python + objects. Note that <code class="computeroutput"><span class="identifier">extract</span><span class="special"><...></span></code> can also be used to "downcast" + an <a class="link" href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object"><code class="computeroutput"><span class="identifier">object</span></code></a> to some specific <a class="link" href="concepts/objectwrapper.html" title="ObjectWrapper">ObjectWrapper</a>. Because invoking + a mutable python type with an argument of the same type (e.g. <code class="computeroutput"><span class="identifier">list</span><span class="special">([</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">]</span></code>) typically makes a copy of the argument + object, this may be the only way to access the <a class="link" href="concepts/objectwrapper.html" title="ObjectWrapper">ObjectWrapper</a>'s + interface on the original object. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract"></a><a class="link" href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract" title="Class template extract">Class + template <code class="computeroutput"><span class="identifier">extract</span></code></a> +</h3></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">extract</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> + can be used to extract a value of an arbitrary C++ type from an instance + of <a class="link" href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object">object</a>. + Two usages are supported: + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">extract</span><span class="special"><</span><span class="identifier">T</span><span class="special">>(</span><span class="identifier">o</span><span class="special">)</span></code> + is a temporary object which is implicitly convertible to <code class="computeroutput"><span class="identifier">T</span></code> (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 <code class="computeroutput"><span class="identifier">T</span></code>, a Python TypeError exception will + be raised. + </li> +<li class="listitem"> + <code class="computeroutput"><span class="identifier">extract</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">x</span><span class="special">(</span><span class="identifier">o</span><span class="special">);</span></code> + constructs an extractor whose <code class="computeroutput"><span class="identifier">check</span><span class="special">()</span></code> member function can be used to ask + whether a conversion is available without causing an exception to be + thrown. + </li> +</ol></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">extract</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">unspecified</span> <span class="identifier">result_type</span><span class="special">;</span> + + <span class="identifier">extract</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*);</span> + <span class="identifier">extract</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&);</span> + + <span class="identifier">result_type</span> <span class="keyword">operator</span><span class="special">()()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">operator</span> <span class="identifier">result_type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="keyword">bool</span> <span class="identifier">check</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract_construct"></a><a class="link" href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract_construct" title="Class template extract constructors and destructor">Class + template <code class="computeroutput"><span class="identifier">extract</span></code> constructors + and destructor</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">extract</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">p</span><span class="special">);</span> +<span class="identifier">extract</span><span class="special">(</span><span class="identifier">object</span> <span class="keyword">const</span><span class="special">&);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + The first form requires that p is non-null. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + 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. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract_observer_"></a><a class="link" href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract_observer_" title="Class template extract observer functions">Class + template <code class="computeroutput"><span class="identifier">extract</span></code> observer + functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">result_type</span> <span class="keyword">operator</span><span class="special">()()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="keyword">operator</span> <span class="identifier">result_type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Converts the stored pointer to result_type, which is either T or + T const&. + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + An object of result_type corresponding to the one referenced by the + stored pointer. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + <a class="link" href="high_level_components/boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.class_error_already_set" title="Class error_already_set"><code class="computeroutput"><span class="identifier">error_already_set</span></code></a> and sets + a <code class="computeroutput"><span class="identifier">TypeError</span></code> if no + such conversion is available. May also emit other unspecified exceptions + thrown by the converter which is actually used. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">check</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Postconditions</span></dt> +<dd><p> + None. In particular, note that a return value of true does not preclude + an exception being thrown from operator result_type() or operator()(). + </p></dd> +<dt><span class="term">Returns</span></dt> +<dd><p> + false only if no conversion from the stored pointer to T is available. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_extract_hpp.example"></a><a class="link" href="to_from_python_type_conversion.html#to_from_python_type_conversion.boost_python_extract_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cstdio</span><span class="special">></span> +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="keyword">int</span> <span class="identifier">Print</span><span class="special">(</span><span class="identifier">str</span> <span class="identifier">s</span><span class="special">)</span> +<span class="special">{</span> + <span class="comment">// extract a C string from the Python string object</span> + <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">c_str</span> <span class="special">=</span> <span class="identifier">extract</span><span class="special"><</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*>(</span><span class="identifier">s</span><span class="special">);</span> + + <span class="comment">// Print it using printf</span> + <span class="identifier">std</span><span class="special">::</span><span class="identifier">printf</span><span class="special">(</span><span class="string">"%s\n"</span><span class="special">,</span> <span class="identifier">c_str</span><span class="special">);</span> + + <span class="comment">// Get the Python string's length and convert it to an int</span> + <span class="keyword">return</span> <span class="identifier">extract</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">s</span><span class="special">.</span><span class="identifier">attr</span><span class="special">(</span><span class="string">"__len__"</span><span class="special">)())</span> +<span class="special">}</span> +</pre> +<p> + The following example shows how extract can be used along with <a class="link" href="high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_<T, Bases, HeldType, NonCopyable>"><code class="computeroutput"><span class="identifier">class_</span><span class="special"><...></span></code></a> + to create and access an instance of a wrapped C++ class. + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="identifier">X</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">v</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span> + <span class="keyword">int</span> <span class="identifier">value</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">v</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="keyword">int</span> <span class="identifier">v</span><span class="special">;</span> +<span class="special">};</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">extract_ext</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">object</span> <span class="identifier">x_class</span><span class="special">(</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">X</span><span class="special">>(</span><span class="string">"X"</span><span class="special">,</span> <span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">>())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"value"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">value</span><span class="special">))</span> + <span class="special">;</span> + + <span class="comment">// Instantiate an X object through the Python interface. </span> + <span class="comment">// Its lifetime is now managed by x_obj.</span> + <span class="identifier">object</span> <span class="identifier">x_obj</span> <span class="special">=</span> <span class="identifier">x_class</span><span class="special">(</span><span class="number">3</span><span class="special">);</span> + + <span class="comment">// Get a reference to the C++ object out of the Python object</span> + <span class="identifier">X</span><span class="special">&</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">extract</span><span class="special"><</span><span class="identifier">X</span><span class="special">&>(</span><span class="identifier">x_obj</span><span class="special">);</span> + <span class="identifier">assert</span><span class="special">(</span><span class="identifier">x</span><span class="special">.</span><span class="identifier">value</span><span class="special">()</span> <span class="special">==</span> <span class="number">3</span><span class="special">);</span> +<span class="special">}</span> +</pre> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="function_invocation_and_creation/models_of_resultconvertergenerat.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="to_from_python_type_conversion/boost_python_implicit_hpp.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_implicit_hpp.html b/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_implicit_hpp.html new file mode 100644 index 0000000000..3a9df09009 --- /dev/null +++ b/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_implicit_hpp.html @@ -0,0 +1,181 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/implicit.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../to_from_python_type_conversion.html" title="Chapter 5. To/From Python Type Conversion"> +<link rel="prev" href="../to_from_python_type_conversion.html" title="Chapter 5. To/From Python Type Conversion"> +<link rel="next" href="boost_python_lvalue_from_pytype_.html" title="boost/python/lvalue_from_pytype.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../to_from_python_type_conversion.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../to_from_python_type_conversion.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_lvalue_from_pytype_.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="to_from_python_type_conversion.boost_python_implicit_hpp"></a><a class="link" href="boost_python_implicit_hpp.html" title="boost/python/implicit.hpp">boost/python/implicit.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_implicit_hpp.html#to_from_python_type_conversion.boost_python_implicit_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_implicit_hpp.html#to_from_python_type_conversion.boost_python_implicit_hpp.function_template_implicit_conve">Function + template <code class="computeroutput"><span class="identifier">implicit_convertible</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_implicit_hpp.html#to_from_python_type_conversion.boost_python_implicit_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_implicit_hpp.introduction"></a><a class="link" href="boost_python_implicit_hpp.html#to_from_python_type_conversion.boost_python_implicit_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">implicitly_convertible</span></code> + allows Boost.Python to implicitly take advantage of a C++ implicit or explicit + conversion when matching Python objects to C++ argument types. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_implicit_hpp.function_template_implicit_conve"></a><a class="link" href="boost_python_implicit_hpp.html#to_from_python_type_conversion.boost_python_implicit_hpp.function_template_implicit_conve" title="Function template implicit_convertible">Function + template <code class="computeroutput"><span class="identifier">implicit_convertible</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Source</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Target</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">implicitly_convertible</span><span class="special">();</span> +</pre> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Parameter + </p> + </th> +<th> + <p> + Description + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + Source + </p> + </td> +<td> + <p> + The source type of the implicit conversion + </p> + </td> +</tr> +<tr> +<td> + <p> + Target + </p> + </td> +<td> + <p> + The target type of the implicit conversion + </p> + </td> +</tr> +</tbody> +</table></div> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + The declaration <code class="computeroutput"><span class="identifier">Target</span> + <span class="identifier">t</span><span class="special">(</span><span class="identifier">s</span><span class="special">);</span></code>, + where s is of type Source, is valid. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + registers an rvalue <code class="computeroutput"><span class="identifier">from_python</span></code> + converter to Target which can succeed for any <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">p</span></code> + iff there exists any registered converter which can produce Source + rvalues + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + C++ users expect to be able to take advantage of the same sort of + interoperability in Python as they do in C++. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_implicit_hpp.example"></a><a class="link" href="boost_python_implicit_hpp.html#to_from_python_type_conversion.boost_python_implicit_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<p> + In C++: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">implicit</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="identifier">X</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">v</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span> + <span class="keyword">operator</span> <span class="keyword">int</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">v</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">int</span> <span class="identifier">v</span><span class="special">;</span> +<span class="special">};</span> + +<span class="keyword">int</span> <span class="identifier">x_value</span><span class="special">(</span><span class="identifier">X</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">v</span><span class="special">;</span> +<span class="special">}</span> + +<span class="identifier">X</span> <span class="identifier">make_x</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">n</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">X</span><span class="special">(</span><span class="identifier">n</span><span class="special">);</span> <span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">implicit_ext</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"x_value"</span><span class="special">,</span> <span class="identifier">x_value</span><span class="special">);</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"make_x"</span><span class="special">,</span> <span class="identifier">make_x</span><span class="special">);</span> + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">X</span><span class="special">>(</span><span class="string">"X"</span><span class="special">,</span> + <span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">>())</span> + <span class="special">;</span> + + <span class="identifier">implicitly_convertible</span><span class="special"><</span><span class="identifier">X</span><span class="special">,</span><span class="keyword">int</span><span class="special">>();</span> + <span class="identifier">implicitly_convertible</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span><span class="identifier">X</span><span class="special">>();</span> +<span class="special">}</span> +</pre> +<p> + In Python: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">implicit_ext</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="identifier">x_value</span><span class="special">(</span><span class="identifier">X</span><span class="special">(</span><span class="number">42</span><span class="special">))</span> +<span class="number">42</span> +<span class="special">>>></span> <span class="identifier">x_value</span><span class="special">(</span><span class="number">42</span><span class="special">)</span> +<span class="number">42</span> +<span class="special">>>></span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">make_x</span><span class="special">(</span><span class="identifier">X</span><span class="special">(</span><span class="number">42</span><span class="special">))</span> +<span class="special">>>></span> <span class="identifier">x_value</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> +<span class="number">42</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../to_from_python_type_conversion.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../to_from_python_type_conversion.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_lvalue_from_pytype_.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html b/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html new file mode 100644 index 0000000000..1f24eb740c --- /dev/null +++ b/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_lvalue_from_pytype_.html @@ -0,0 +1,305 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/lvalue_from_pytype.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../to_from_python_type_conversion.html" title="Chapter 5. To/From Python Type Conversion"> +<link rel="prev" href="boost_python_implicit_hpp.html" title="boost/python/implicit.hpp"> +<link rel="next" href="boost_python_opaque_pointer_conv.html" title="boost/python/opaque_pointer_converter.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_implicit_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../to_from_python_type_conversion.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_opaque_pointer_conv.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="to_from_python_type_conversion.boost_python_lvalue_from_pytype_"></a><a class="link" href="boost_python_lvalue_from_pytype_.html" title="boost/python/lvalue_from_pytype.hpp">boost/python/lvalue_from_pytype.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_lvalue_from_pytyp">Class + template <code class="computeroutput"><span class="identifier">lvalue_from_pytype</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_identity">Class + template <code class="computeroutput"><span class="identifier">extract_identity</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_member">Class + template <code class="computeroutput"><span class="identifier">extract_member</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_lvalue_from_pytype_.introduction"></a><a class="link" href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/lvalue_from_pytype.hpp> supplies a facility for extracting + C++ objects from within Python instances of a given type. This is typically + useful for dealing with "traditional" Python extension types. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_lvalue_from_pytyp"></a><a class="link" href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_lvalue_from_pytyp" title="Class template lvalue_from_pytype">Class + template <code class="computeroutput"><span class="identifier">lvalue_from_pytype</span></code></a> +</h3></div></div></div> +<div class="toc"><dl class="toc"><dt><span class="section"><a href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_lvalue_from_pytyp.class_template_lvalue_from_pytyp">Class + template <code class="computeroutput"><span class="identifier">lvalue_from_pytype</span></code> + constructor</a></span></dt></dl></div> +<p> + Class template lvalue_from_pytype will register from_python converters + which, given an object of the given Python type, can extract references + and pointers to a particular C++ type. Its template arguments are: + </p> +<pre class="programlisting"><span class="identifier">In</span> <span class="identifier">the</span> <span class="identifier">table</span> <span class="identifier">below</span><span class="special">,</span> <span class="identifier">x</span> <span class="identifier">denotes</span> <span class="identifier">an</span> <span class="identifier">object</span> <span class="identifier">of</span> <span class="identifier">type</span> <span class="identifier">PythonObject</span><span class="special">&</span> +</pre> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Semantics + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + Extractor + </p> + </td> +<td> + <p> + a model of <a class="link" href="../concepts/extractor.html" title="Extractor"><code class="computeroutput"><span class="identifier">Extractor</span></code></a> + whose execute function returns a reference type. + </p> + </td> +<td> + <p> + Extracts the lvalue from the Python object once its type has + been confirmed + </p> + </td> +</tr> +<tr> +<td> + <p> + python_type + </p> + </td> +<td> + <p> + A compile-time constant <a href="http://www.python.org/doc/2.2/ext/dnt-type-methods.html" target="_top"><code class="computeroutput"><span class="identifier">PyTypeObject</span><span class="special">*</span></code></a> + </p> + </td> +<td> + <p> + The Python type of instances convertible by this converter. Python + subtypes are also convertible. + </p> + </td> +</tr> +</tbody> +</table></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Extractor</span><span class="special">,</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">python_type</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">lvalue_from_pytype</span> + <span class="special">{</span> + <span class="identifier">lvalue_from_pytype</span><span class="special">();</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_lvalue_from_pytyp.class_template_lvalue_from_pytyp"></a><a class="link" href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_lvalue_from_pytyp.class_template_lvalue_from_pytyp" title="Class template lvalue_from_pytype constructor">Class + template <code class="computeroutput"><span class="identifier">lvalue_from_pytype</span></code> + constructor</a> +</h4></div></div></div> +<pre class="programlisting"><span class="identifier">lvalue_from_pytype</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Registers converters which can convert Python objects of the given + type to lvalues of the type returned by Extractor::execute. + </p></dd> +</dl> +</div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_identity"></a><a class="link" href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_identity" title="Class template extract_identity">Class + template <code class="computeroutput"><span class="identifier">extract_identity</span></code></a> +</h3></div></div></div> +<div class="toc"><dl class="toc"><dt><span class="section"><a href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_identity.class_template_extract_identity_">Class + template <code class="computeroutput"><span class="identifier">extract_identity</span></code> + static functions</a></span></dt></dl></div> +<p> + extract_identity is a model of <a class="link" href="../concepts/extractor.html" title="Extractor"><code class="computeroutput"><span class="identifier">Extractor</span></code></a> which can be used in + the common case where the C++ type to be extracted is the same as the Python + object type. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">InstanceType</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">extract_identity</span> + <span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">InstanceType</span><span class="special">&</span> <span class="identifier">execute</span><span class="special">(</span><span class="identifier">InstanceType</span><span class="special">&</span> <span class="identifier">c</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_identity.class_template_extract_identity_"></a><a class="link" href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_identity.class_template_extract_identity_" title="Class template extract_identity static functions">Class + template <code class="computeroutput"><span class="identifier">extract_identity</span></code> + static functions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="identifier">InstanceType</span><span class="special">&</span> <span class="identifier">execute</span><span class="special">(</span><span class="identifier">InstanceType</span><span class="special">&</span> <span class="identifier">c</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + c + </p></dd> +</dl> +</div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_member"></a><a class="link" href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_member" title="Class template extract_member">Class + template <code class="computeroutput"><span class="identifier">extract_member</span></code></a> +</h3></div></div></div> +<div class="toc"><dl class="toc"><dt><span class="section"><a href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_member.class_template_extract_member_st">Class + template <code class="computeroutput"><span class="identifier">extract_member</span></code> + static functions</a></span></dt></dl></div> +<p> + <code class="computeroutput"><span class="identifier">extract_member</span></code> is a model + of <a class="link" href="../concepts/extractor.html" title="Extractor"><code class="computeroutput"><span class="identifier">Extractor</span></code></a> + which can be used in the common case in the common case where the C++ type + to be extracted is a member of the Python object. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">InstanceType</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">MemberType</span><span class="special">,</span> <span class="identifier">MemberType</span> <span class="special">(</span><span class="identifier">InstanceType</span><span class="special">::*</span><span class="identifier">member</span><span class="special">)></span> + <span class="keyword">struct</span> <span class="identifier">extract_member</span> + <span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">MemberType</span><span class="special">&</span> <span class="identifier">execute</span><span class="special">(</span><span class="identifier">InstanceType</span><span class="special">&</span> <span class="identifier">c</span><span class="special">);</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_member.class_template_extract_member_st"></a><a class="link" href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_extract_member.class_template_extract_member_st" title="Class template extract_member static functions">Class + template <code class="computeroutput"><span class="identifier">extract_member</span></code> + static functions</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">static</span> <span class="identifier">MemberType</span><span class="special">&</span> <span class="identifier">execute</span><span class="special">(</span><span class="identifier">InstanceType</span><span class="special">&</span> <span class="identifier">c</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">c</span><span class="special">.*</span><span class="identifier">member</span></code> + </p></dd> +</dl> +</div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_lvalue_from_pytype_.example"></a><a class="link" href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.example" title="Example">Example</a> +</h3></div></div></div> +<p> + This example presumes that someone has implemented the standard noddy example + module from the Python documentation, and we want to build a module which + manipulates Noddys. Since noddy_NoddyObject is so simple that it carries + no interesting information, the example is a bit contrived: it assumes + you want to keep track of one particular object for some reason. This module + would have to be dynamically linked to the module which defines noddy_NoddyType. + </p> +<p> + In C++: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">handle</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">borrowed</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">lvalue_from_pytype</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="comment">// definition lifted from the Python docs</span> +<span class="keyword">typedef</span> <span class="keyword">struct</span> <span class="special">{</span> + <span class="identifier">PyObject_HEAD</span> +<span class="special">}</span> <span class="identifier">noddy_NoddyObject</span><span class="special">;</span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="keyword">static</span> <span class="identifier">handle</span><span class="special"><</span><span class="identifier">noddy_NoddyObject</span><span class="special">></span> <span class="identifier">cache</span><span class="special">;</span> + +<span class="keyword">bool</span> <span class="identifier">is_cached</span><span class="special">(</span><span class="identifier">noddy_NoddyObject</span><span class="special">*</span> <span class="identifier">x</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">x</span> <span class="special">==</span> <span class="identifier">cache</span><span class="special">.</span><span class="identifier">get</span><span class="special">();</span> +<span class="special">}</span> + +<span class="keyword">void</span> <span class="identifier">set_cache</span><span class="special">(</span><span class="identifier">noddy_NoddyObject</span><span class="special">*</span> <span class="identifier">x</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">cache</span> <span class="special">=</span> <span class="identifier">handle</span><span class="special"><</span><span class="identifier">noddy_NoddyObject</span><span class="special">>(</span><span class="identifier">borrowed</span><span class="special">(</span><span class="identifier">x</span><span class="special">));</span> +<span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">noddy_cache</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"is_cached"</span><span class="special">,</span> <span class="identifier">is_cached</span><span class="special">);</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"set_cache"</span><span class="special">,</span> <span class="identifier">set_cache</span><span class="special">);</span> + + <span class="comment">// register Noddy lvalue converter</span> + <span class="identifier">lvalue_from_pytype</span><span class="special"><</span><span class="identifier">extract_identity</span><span class="special"><</span><span class="identifier">noddy_NoddyObject</span><span class="special">>,&</span><span class="identifier">noddy_NoddyType</span><span class="special">>();</span> +<span class="special">}</span> +</pre> +<p> + In Python: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">import</span> <span class="identifier">noddy</span> +<span class="special">>>></span> <span class="identifier">n</span> <span class="special">=</span> <span class="identifier">noddy</span><span class="special">.</span><span class="identifier">new_noddy</span><span class="special">()</span> +<span class="special">>>></span> <span class="identifier">import</span> <span class="identifier">noddy_cache</span> +<span class="special">>>></span> <span class="identifier">noddy_cache</span><span class="special">.</span><span class="identifier">is_cached</span><span class="special">(</span><span class="identifier">n</span><span class="special">)</span> +<span class="number">0</span> +<span class="special">>>></span> <span class="identifier">noddy_cache</span><span class="special">.</span><span class="identifier">set_cache</span><span class="special">(</span><span class="identifier">n</span><span class="special">)</span> +<span class="special">>>></span> <span class="identifier">noddy_cache</span><span class="special">.</span><span class="identifier">is_cached</span><span class="special">(</span><span class="identifier">n</span><span class="special">)</span> +<span class="number">1</span> +<span class="special">>>></span> <span class="identifier">noddy_cache</span><span class="special">.</span><span class="identifier">is_cached</span><span class="special">(</span><span class="identifier">noddy</span><span class="special">.</span><span class="identifier">new_noddy</span><span class="special">())</span> +<span class="number">0</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_implicit_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../to_from_python_type_conversion.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_opaque_pointer_conv.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_opaque_pointer_conv.html b/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_opaque_pointer_conv.html new file mode 100644 index 0000000000..25b5ac8b9d --- /dev/null +++ b/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_opaque_pointer_conv.html @@ -0,0 +1,118 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/opaque_pointer_converter.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../to_from_python_type_conversion.html" title="Chapter 5. To/From Python Type Conversion"> +<link rel="prev" href="boost_python_lvalue_from_pytype_.html" title="boost/python/lvalue_from_pytype.hpp"> +<link rel="next" href="boost_python_to_python_converter.html" title="boost/python/to_python_converter.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_lvalue_from_pytype_.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../to_from_python_type_conversion.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_to_python_converter.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="to_from_python_type_conversion.boost_python_opaque_pointer_conv"></a><a class="link" href="boost_python_opaque_pointer_conv.html" title="boost/python/opaque_pointer_converter.hpp">boost/python/opaque_pointer_converter.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.class_template_opaque_constructo">Class + template <code class="computeroutput"><span class="identifier">opaque</span></code> constructor</a></span></dt> +<dt><span class="section"><a href="boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.macro_boost_python_opaque_specia">Macro + <code class="computeroutput"><span class="identifier">BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</span><span class="special">(</span><span class="identifier">Pointee</span><span class="special">)</span></code></a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_opaque_pointer_conv.introduction"></a><a class="link" href="boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">opaque</span><span class="special"><></span></code> + registers itself as a converter from Python objects to pointers to undefined + types and vice versa. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">Pointee</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">opaque</span> + <span class="special">{</span> + <span class="identifier">opaque</span><span class="special">();</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_opaque_pointer_conv.class_template_opaque_constructo"></a><a class="link" href="boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.class_template_opaque_constructo" title="Class template opaque constructor">Class + template <code class="computeroutput"><span class="identifier">opaque</span></code> constructor</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">opaque</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + Registers the instance as a <a class="link" href="boost_python_lvalue_from_pytype_.html#to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_lvalue_from_pytyp" title="Class template lvalue_from_pytype"><code class="computeroutput"><span class="identifier">lvalue_from_pytype</span></code></a> converter + from Python objects into opaque pointers. The Python Objects + created are named after the type pointed to by the opaque pointer + being wrapped. + </li> +<li class="listitem"> + Registers the instance as a <a class="link" href="boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert" title="Class template to_python_converter"><code class="computeroutput"><span class="identifier">to_python_converter</span></code></a> + from opaque pointers to Python objects. + </li> +</ul></div></dd> +</dl> +</div> +<div class="note"><table border="0" summary="Note"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../images/note.png"></td> +<th align="left">Note</th> +</tr> +<tr><td align="left" valign="top"><p> + If there is already an instance registered by another module, this instance + doesn't try to register again in order to avoid warnings about multiple + registrations. + </p></td></tr> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_opaque_pointer_conv.macro_boost_python_opaque_specia"></a><a class="link" href="boost_python_opaque_pointer_conv.html#to_from_python_type_conversion.boost_python_opaque_pointer_conv.macro_boost_python_opaque_specia" title="Macro BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID(Pointee)">Macro + <code class="computeroutput"><span class="identifier">BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</span><span class="special">(</span><span class="identifier">Pointee</span><span class="special">)</span></code></a> +</h3></div></div></div> +<p> + This macro must be used to define specializations of the <a class="link" href="../utility_and_infrastructure/boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.functions" title="Functions"><code class="computeroutput"><span class="identifier">type_id</span></code></a> function which can't be + instantiated for incomplete types. + </p> +<div class="note"><table border="0" summary="Note"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../images/note.png"></td> +<th align="left">Note</th> +</tr> +<tr><td align="left" valign="top"><p> + The macro must be invoked in every translation unit which uses the opaque + converter. + </p></td></tr> +</table></div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_lvalue_from_pytype_.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../to_from_python_type_conversion.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_to_python_converter.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html b/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html new file mode 100644 index 0000000000..543c210776 --- /dev/null +++ b/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_register_ptr_to_pyt.html @@ -0,0 +1,166 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/register_ptr_to_python.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../to_from_python_type_conversion.html" title="Chapter 5. To/From Python Type Conversion"> +<link rel="prev" href="boost_python_to_python_converter.html" title="boost/python/to_python_converter.hpp"> +<link rel="next" href="../embedding.html" title="Chapter 6. Embedding"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_to_python_converter.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../to_from_python_type_conversion.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../embedding.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="to_from_python_type_conversion.boost_python_register_ptr_to_pyt"></a><a class="link" href="boost_python_register_ptr_to_pyt.html" title="boost/python/register_ptr_to_python.hpp">boost/python/register_ptr_to_python.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_register_ptr_to_pyt.html#to_from_python_type_conversion.boost_python_register_ptr_to_pyt.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_register_ptr_to_pyt.html#to_from_python_type_conversion.boost_python_register_ptr_to_pyt.function_register_ptr_to_python">Function + <code class="computeroutput"><span class="identifier">register_ptr_to_python</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_register_ptr_to_pyt.html#to_from_python_type_conversion.boost_python_register_ptr_to_pyt.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_register_ptr_to_pyt.introduction"></a><a class="link" href="boost_python_register_ptr_to_pyt.html#to_from_python_type_conversion.boost_python_register_ptr_to_pyt.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/register_ptr_to_python.hpp> supplies <code class="computeroutput"><span class="identifier">register_ptr_to_python</span></code>, a function template + which registers a conversion for smart pointers to Python. The resulting + Python object holds a copy of the converted smart pointer, but behaves + as though it were a wrapped copy of the pointee. If the pointee type has + virtual functions and the class representing its dynamic (most-derived) + type has been wrapped, the Python object will be an instance of the wrapper + for the most-derived type. More than one smart pointer type for a pointee's + class can be registered. + </p> +<p> + Note that in order to convert a Python <code class="computeroutput"><span class="identifier">X</span></code> + object to a <code class="computeroutput"><span class="identifier">smart_ptr</span><span class="special"><</span><span class="identifier">X</span><span class="special">>&</span></code> + (non-const reference), the embedded C++ object must be held by <code class="computeroutput"><span class="identifier">smart_ptr</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span></code>, + and that when wrapped objects are created by calling the constructor from + Python, how they are held is determined by the HeldType parameter to <code class="computeroutput"><span class="identifier">class_</span><span class="special"><...></span></code> + instances. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_register_ptr_to_pyt.function_register_ptr_to_python"></a><a class="link" href="boost_python_register_ptr_to_pyt.html#to_from_python_type_conversion.boost_python_register_ptr_to_pyt.function_register_ptr_to_python" title="Function register_ptr_to_python">Function + <code class="computeroutput"><span class="identifier">register_ptr_to_python</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">P</span><span class="special">></span> +<span class="keyword">void</span> <span class="identifier">register_ptr_to_python</span><span class="special">()</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">P</span></code> is <a class="link" href="../concepts/dereferenceable.html" title="Dereferenceable">Dereferenceable</a>. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + Allows conversions to-python of P instances. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_register_ptr_to_pyt.example"></a><a class="link" href="boost_python_register_ptr_to_pyt.html#to_from_python_type_conversion.boost_python_register_ptr_to_pyt.example" title="Example">Example</a> +</h3></div></div></div> +<p> + Here is an example of a module that contains a class A with virtual functions + and some functions that work with boost::shared_ptr<A>. + </p> +<p> + In C++: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">A</span> +<span class="special">{</span> + <span class="keyword">virtual</span> <span class="keyword">int</span> <span class="identifier">f</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> <span class="special">}</span> +<span class="special">};</span> + +<span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span> <span class="identifier">New</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">A</span><span class="special">>(</span> <span class="keyword">new</span> <span class="identifier">A</span><span class="special">()</span> <span class="special">);</span> <span class="special">}</span> + +<span class="keyword">int</span> <span class="identifier">Ok</span><span class="special">(</span> <span class="keyword">const</span> <span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">A</span><span class="special">>&</span> <span class="identifier">a</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">a</span><span class="special">-></span><span class="identifier">f</span><span class="special">();</span> <span class="special">}</span> + +<span class="keyword">int</span> <span class="identifier">Fail</span><span class="special">(</span> <span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">A</span><span class="special">>&</span> <span class="identifier">a</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">a</span><span class="special">-></span><span class="identifier">f</span><span class="special">();</span> <span class="special">}</span> + +<span class="keyword">struct</span> <span class="identifier">A_Wrapper</span><span class="special">:</span> <span class="identifier">A</span> +<span class="special">{</span> + <span class="identifier">A_Wrapper</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">self_</span><span class="special">):</span> <span class="identifier">self</span><span class="special">(</span><span class="identifier">self_</span><span class="special">)</span> <span class="special">{}</span> + <span class="keyword">int</span> <span class="identifier">f</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">call_method</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">self</span><span class="special">,</span> <span class="string">"f"</span><span class="special">);</span> <span class="special">}</span> + <span class="keyword">int</span> <span class="identifier">default_f</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">A</span><span class="special">::</span><span class="identifier">f</span><span class="special">();</span> <span class="special">}</span> + <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">self</span><span class="special">;</span> +<span class="special">};</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">register_ptr</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">A_Wrapper</span><span class="special">>(</span><span class="string">"A"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">A</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="special">&</span><span class="identifier">A_Wrapper</span><span class="special">::</span><span class="identifier">default_f</span><span class="special">)</span> + <span class="special">;</span> + + <span class="identifier">def</span><span class="special">(</span><span class="string">"New"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">New</span><span class="special">);</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"Ok"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Call</span><span class="special">);</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"Fail"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Fail</span><span class="special">);</span> + + <span class="identifier">register_ptr_to_python</span><span class="special"><</span> <span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span> <span class="special">>();</span> +<span class="special">}</span> +</pre> +<p> + In Python: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">register_ptr</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="identifier">a</span> <span class="special">=</span> <span class="identifier">A</span><span class="special">()</span> +<span class="special">>>></span> <span class="identifier">Ok</span><span class="special">(</span><span class="identifier">a</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">ok</span><span class="special">,</span> <span class="identifier">passed</span> <span class="identifier">as</span> <span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span> +<span class="number">0</span> +<span class="special">>>></span> <span class="identifier">Fail</span><span class="special">(</span><span class="identifier">a</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">passed</span> <span class="identifier">as</span> <span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">A</span><span class="special">>&,</span> <span class="keyword">and</span> <span class="identifier">was</span> <span class="identifier">created</span> <span class="identifier">in</span> <span class="identifier">Python</span><span class="special">!</span> +<span class="identifier">Traceback</span> <span class="special">(</span><span class="identifier">most</span> <span class="identifier">recent</span> <span class="identifier">call</span> <span class="identifier">last</span><span class="special">):</span> + <span class="identifier">File</span> <span class="string">"<stdin>"</span><span class="special">,</span> <span class="identifier">line</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">in</span> <span class="special">?</span> +<span class="identifier">TypeError</span><span class="special">:</span> <span class="identifier">bad</span> <span class="identifier">argument</span> <span class="identifier">type</span> <span class="keyword">for</span> <span class="identifier">built</span><span class="special">-</span><span class="identifier">in</span> <span class="identifier">operation</span> +<span class="special">>>></span> +<span class="special">>>></span> <span class="identifier">na</span> <span class="special">=</span> <span class="identifier">New</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">now</span> <span class="string">"na"</span> <span class="identifier">is</span> <span class="identifier">actually</span> <span class="identifier">a</span> <span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span> +<span class="special">>>></span> <span class="identifier">Ok</span><span class="special">(</span><span class="identifier">a</span><span class="special">)</span> +<span class="number">0</span> +<span class="special">>>></span> <span class="identifier">Fail</span><span class="special">(</span><span class="identifier">a</span><span class="special">)</span> +<span class="number">0</span> +<span class="special">>>></span> +</pre> +<p> + If shared_ptr<A> is registered as follows: + </p> +<pre class="programlisting"><span class="identifier">class_</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">A_Wrapper</span><span class="special">,</span> <span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span> <span class="special">>(</span><span class="string">"A"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">A</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="special">&</span><span class="identifier">A_Wrapper</span><span class="special">::</span><span class="identifier">default_f</span><span class="special">)</span> +<span class="special">;</span> +</pre> +<p> + There will be an error when trying to convert shared_ptr<A> to shared_ptr<A_Wrapper>: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">a</span> <span class="special">=</span> <span class="identifier">New</span><span class="special">()</span> +<span class="identifier">Traceback</span> <span class="special">(</span><span class="identifier">most</span> <span class="identifier">recent</span> <span class="identifier">call</span> <span class="identifier">last</span><span class="special">):</span> +<span class="identifier">File</span> <span class="string">"<stdin>"</span><span class="special">,</span> <span class="identifier">line</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">in</span> <span class="special">?</span> +<span class="identifier">TypeError</span><span class="special">:</span> <span class="identifier">No</span> <span class="identifier">to_python</span> <span class="special">(</span><span class="identifier">by</span><span class="special">-</span><span class="identifier">value</span><span class="special">)</span> <span class="identifier">converter</span> <span class="identifier">found</span> <span class="keyword">for</span> <span class="identifier">C</span><span class="special">++</span> <span class="identifier">type</span><span class="special">:</span> <span class="keyword">class</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special"><</span><span class="keyword">struct</span> <span class="identifier">A</span><span class="special">></span> +<span class="special">>>></span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_to_python_converter.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../to_from_python_type_conversion.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../embedding.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_to_python_converter.html b/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_to_python_converter.html new file mode 100644 index 0000000000..2f17f9df21 --- /dev/null +++ b/libs/python/doc/html/reference/to_from_python_type_conversion/boost_python_to_python_converter.html @@ -0,0 +1,252 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/to_python_converter.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../to_from_python_type_conversion.html" title="Chapter 5. To/From Python Type Conversion"> +<link rel="prev" href="boost_python_opaque_pointer_conv.html" title="boost/python/opaque_pointer_converter.hpp"> +<link rel="next" href="boost_python_register_ptr_to_pyt.html" title="boost/python/register_ptr_to_python.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_opaque_pointer_conv.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../to_from_python_type_conversion.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_register_ptr_to_pyt.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="to_from_python_type_conversion.boost_python_to_python_converter"></a><a class="link" href="boost_python_to_python_converter.html" title="boost/python/to_python_converter.hpp">boost/python/to_python_converter.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert">Class + template <code class="computeroutput"><span class="identifier">to_python_converter</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_to_python_converter.introduction"></a><a class="link" href="boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">to_python_converter</span></code> registers + a conversion from objects of a given C++ type into a Python object. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert"></a><a class="link" href="boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert" title="Class template to_python_converter">Class + template <code class="computeroutput"><span class="identifier">to_python_converter</span></code></a> +</h3></div></div></div> +<div class="toc"><dl class="toc"><dt><span class="section"><a href="boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert.class_template_to_python_convert">Class + template <code class="computeroutput"><span class="identifier">to_python_converter</span></code> + constructor</a></span></dt></dl></div> +<p> + <code class="computeroutput"><span class="identifier">to_python_converter</span></code> adds + a wrapper around a static member function of its second template parameter, + handling low-level details such as insertion into the converter registry. + </p> +<p> + In the table below, x denotes an object of type T + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Description + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + T + </p> + </td> +<td> + </td> +<td> + <p> + The C++ type of the source object in the conversion + </p> + </td> +</tr> +<tr> +<td> + <p> + Conversion + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span> + <span class="identifier">p</span> <span class="special">=</span> + <span class="identifier">Conversion</span><span class="special">::</span><span class="identifier">convert</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code>, + <code class="computeroutput"><span class="keyword">if</span> <span class="identifier">p</span> + <span class="special">==</span> <span class="number">0</span></code>, + <code class="computeroutput"><span class="identifier">PyErr_Occurred</span><span class="special">()</span> <span class="special">!=</span> + <span class="number">0</span></code>. + </p> + </td> +<td> + <p> + A class type whose static member function convert does the real + work of the conversion. + </p> + </td> +</tr> +<tr> +<td> + <p> + bool has_get_pytype=false + </p> + </td> +<td> + <p> + <code class="computeroutput"><span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span> + <span class="identifier">p</span> <span class="special">=</span> + <span class="identifier">Conversion</span><span class="special">::</span><span class="identifier">get_pytype</span><span class="special">()</span></code> + </p> + </td> +<td> + <p> + Optional member - if Conversion has <code class="computeroutput"><span class="identifier">get_pytype</span></code> + member supply <code class="computeroutput"><span class="keyword">true</span></code> + for this parameters. If present <code class="computeroutput"><span class="identifier">get_pytype</span></code> + is used to document the return type of functions using this conversion. + The <code class="computeroutput"><span class="identifier">get_pytype</span></code> + may be implemented using the classes and functions from pytype_function.hpp + NOTE : For backward compatibility this parameter may be passed + after checking if BOOST_PYTHON_SUPPORTS_PY_SIGNATURES is defined + (see <a class="link" href="../function_invocation_and_creation/function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.example" title="Example">here</a>). + </p> + </td> +</tr> +</tbody> +</table></div> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Conversion</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">convertion_has_get_pytype_member</span><span class="special">=</span><span class="keyword">false</span><span class="special">></span> + <span class="keyword">struct</span> <span class="identifier">to_python_converter</span> + <span class="special">{</span> + <span class="identifier">to_python_converter</span><span class="special">();</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert.class_template_to_python_convert"></a><a class="link" href="boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert.class_template_to_python_convert" title="Class template to_python_converter constructor">Class + template <code class="computeroutput"><span class="identifier">to_python_converter</span></code> + constructor</a> +</h4></div></div></div> +<pre class="programlisting"><span class="identifier">to_python_converter</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Registers a <code class="computeroutput"><span class="identifier">to_python</span></code> + converter which uses <code class="computeroutput"><span class="identifier">Conversion</span><span class="special">::</span><span class="identifier">convert</span><span class="special">()</span></code> to do its work. + </p></dd> +</dl> +</div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="to_from_python_type_conversion.boost_python_to_python_converter.example"></a><a class="link" href="boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.example" title="Example">Example</a> +</h3></div></div></div> +<p> + This example presumes that someone has implemented the standard noddy example + module from the Python documentation, and placed the corresponding declarations + in "noddy.h". Because noddy_NoddyObject is the ultimate trivial + extension type, the example is a bit contrived: it wraps a function for + which all information is contained in the type of its return value. + </p> +<p> + In C++: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">reference</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="string">"noddy.h"</span> + +<span class="keyword">struct</span> <span class="identifier">tag</span> <span class="special">{};</span> +<span class="identifier">tag</span> <span class="identifier">make_tag</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">tag</span><span class="special">();</span> <span class="special">}</span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + +<span class="keyword">struct</span> <span class="identifier">tag_to_noddy</span> +<span class="special">{</span> + <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">convert</span><span class="special">(</span><span class="identifier">tag</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">PyObject_New</span><span class="special">(</span><span class="identifier">noddy_NoddyObject</span><span class="special">,</span> <span class="special">&</span><span class="identifier">noddy_NoddyType</span><span class="special">);</span> + <span class="special">}</span> + <span class="keyword">static</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">get_pytype</span><span class="special">()</span> + <span class="special">{</span> + <span class="keyword">return</span> <span class="special">&</span><span class="identifier">noddy_NoddyType</span><span class="special">;</span> + <span class="special">}</span> +<span class="special">};</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">to_python_converter</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"make_tag"</span><span class="special">,</span> <span class="identifier">make_tag</span><span class="special">);</span> + <span class="identifier">to_python_converter</span><span class="special"><</span><span class="identifier">tag</span><span class="special">,</span> <span class="identifier">tag_to_noddy</span><span class="special">,</span> <span class="keyword">true</span><span class="special">>();</span> <span class="comment">//"true" because tag_to_noddy has member get_pytype</span> +<span class="special">}</span> +</pre> +<p> + In Python: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">import</span> <span class="identifier">to_python_converter</span> +<span class="special">>>></span> <span class="identifier">def</span> <span class="identifier">always_none</span><span class="special">():</span> +<span class="special">...</span> <span class="keyword">return</span> <span class="identifier">None</span> +<span class="special">...</span> +<span class="special">>>></span> <span class="identifier">def</span> <span class="identifier">choose_function</span><span class="special">(</span><span class="identifier">x</span><span class="special">):</span> +<span class="special">...</span> <span class="keyword">if</span> <span class="special">(</span><span class="identifier">x</span> <span class="special">%</span> <span class="number">2</span> <span class="special">!=</span> <span class="number">0</span><span class="special">):</span> +<span class="special">...</span> <span class="keyword">return</span> <span class="identifier">to_python_converter</span><span class="special">.</span><span class="identifier">make_tag</span> +<span class="special">...</span> <span class="keyword">else</span><span class="special">:</span> +<span class="special">...</span> <span class="keyword">return</span> <span class="identifier">always_none</span> +<span class="special">...</span> +<span class="special">>>></span> <span class="identifier">a</span> <span class="special">=</span> <span class="special">[</span> <span class="identifier">choose_function</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="keyword">for</span> <span class="identifier">x</span> <span class="identifier">in</span> <span class="identifier">range</span><span class="special">(</span><span class="number">5</span><span class="special">)</span> <span class="special">]</span> +<span class="special">>>></span> <span class="identifier">b</span> <span class="special">=</span> <span class="special">[</span> <span class="identifier">f</span><span class="special">()</span> <span class="keyword">for</span> <span class="identifier">f</span> <span class="identifier">in</span> <span class="identifier">a</span> <span class="special">]</span> +<span class="special">>>></span> <span class="identifier">type</span><span class="special">(</span><span class="identifier">b</span><span class="special">[</span><span class="number">0</span><span class="special">])</span> +<span class="special"><</span><span class="identifier">type</span> <span class="char">'NoneType'</span><span class="special">></span> +<span class="special">>>></span> <span class="identifier">type</span><span class="special">(</span><span class="identifier">b</span><span class="special">[</span><span class="number">1</span><span class="special">])</span> +<span class="special"><</span><span class="identifier">type</span> <span class="char">'Noddy'</span><span class="special">></span> +<span class="special">>>></span> <span class="identifier">type</span><span class="special">(</span><span class="identifier">b</span><span class="special">[</span><span class="number">2</span><span class="special">])</span> +<span class="special"><</span><span class="identifier">type</span> <span class="char">'NoneType'</span><span class="special">></span> +<span class="special">>>></span> <span class="identifier">type</span><span class="special">(</span><span class="identifier">b</span><span class="special">[</span><span class="number">3</span><span class="special">])</span> +<span class="special"><</span><span class="identifier">type</span> <span class="char">'Noddy'</span><span class="special">></span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_opaque_pointer_conv.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../to_from_python_type_conversion.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_register_ptr_to_pyt.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/topics.html b/libs/python/doc/html/reference/topics.html new file mode 100644 index 0000000000..4d2007e3e7 --- /dev/null +++ b/libs/python/doc/html/reference/topics.html @@ -0,0 +1,332 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 8. Topics</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="index.html" title="Boost.Python Reference Manual"> +<link rel="prev" href="utility_and_infrastructure/boost_python_ssize_t_hpp.html" title="boost/python/ssize_t.hpp"> +<link rel="next" href="topics/pickle_support.html" title="Pickle support"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="utility_and_infrastructure/boost_python_ssize_t_hpp.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="topics/pickle_support.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="topics"></a>Chapter 8. Topics</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met">Calling Python + Functions and Methods</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met.argument_handling">Argument + Handling</a></span></dt> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met.result_handling">Result + Handling</a></span></dt> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met.rationale">Rationale</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="topics/pickle_support.html">Pickle support</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="topics/pickle_support.html#topics.pickle_support.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="topics/pickle_support.html#topics.pickle_support.the_pickle_interface">The Pickle + Interface</a></span></dt> +<dt><span class="section"><a href="topics/pickle_support.html#topics.pickle_support.example">Example</a></span></dt> +<dt><span class="section"><a href="topics/pickle_support.html#topics.pickle_support.pitfall_and_safety_guard">Pitfall + and Safety Guard</a></span></dt> +<dt><span class="section"><a href="topics/pickle_support.html#topics.pickle_support.practical_advice">Practical Advice</a></span></dt> +<dt><span class="section"><a href="topics/pickle_support.html#topics.pickle_support.light_weight_alternative_pickle_">Light-weight + alternative: pickle support implemented in Python</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="topics/indexing_support.html">Indexing support</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="topics/indexing_support.html#topics.indexing_support.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="topics/indexing_support.html#topics.indexing_support.the_indexing_interface">The + Indexing Interface</a></span></dt> +<dt><span class="section"><a href="topics/indexing_support.html#topics.indexing_support.index_suite_sub_classes">index_suite + sub-classes</a></span></dt> +<dt><span class="section"><a href="topics/indexing_support.html#topics.indexing_support.indexing_suite_class"><code class="computeroutput"><span class="identifier">indexing_suite</span></code> class</a></span></dt> +<dt><span class="section"><a href="topics/indexing_support.html#topics.indexing_support.class_vector_indexing_suite">class + <code class="computeroutput"><span class="identifier">vector_indexing_suite</span></code></a></span></dt> +<dt><span class="section"><a href="topics/indexing_support.html#topics.indexing_support.class_map_indexing_suite">class + <code class="computeroutput"><span class="identifier">map_indexing_suite</span></code></a></span></dt> +</dl></dd> +</dl> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="topics.calling_python_functions_and_met"></a><a class="link" href="topics.html#topics.calling_python_functions_and_met" title="Calling Python Functions and Methods">Calling Python + Functions and Methods</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met.argument_handling">Argument + Handling</a></span></dt> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met.result_handling">Result + Handling</a></span></dt> +<dt><span class="section"><a href="topics.html#topics.calling_python_functions_and_met.rationale">Rationale</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.calling_python_functions_and_met.introduction"></a><a class="link" href="topics.html#topics.calling_python_functions_and_met.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + The simplest way to call a Python function from C++, given an <a class="link" href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object"><code class="computeroutput"><span class="identifier">object</span></code></a> instance f holding the + function, is simply to invoke its function call operator. + </p> +<pre class="programlisting"><span class="identifier">f</span><span class="special">(</span><span class="string">"tea"</span><span class="special">,</span> <span class="number">4</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span> <span class="comment">// In Python: f('tea', 4, 2)</span></pre> +<p> + And of course, a method of an <a class="link" href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object"><code class="computeroutput"><span class="identifier">object</span></code></a> instance <code class="computeroutput"><span class="identifier">x</span></code> can be invoked by using the function-call + operator of the corresponding attribute: + </p> +<pre class="programlisting"><span class="identifier">x</span><span class="special">.</span><span class="identifier">attr</span><span class="special">(</span><span class="string">"tea"</span><span class="special">)(</span><span class="number">4</span><span class="special">,</span> <span class="number">2</span><span class="special">);</span> <span class="comment">// In Python: x.tea(4, 2)</span></pre> +<p> + If you don't have an <a class="link" href="object_wrappers/boost_python_object_hpp.html#object_wrappers.boost_python_object_hpp.class_object" title="Class object"><code class="computeroutput"><span class="identifier">object</span></code></a> instance, <code class="computeroutput"><span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span></code> provides two families of function + templates, <a class="link" href="function_invocation_and_creation/boost_python_call_hpp.html#function_invocation_and_creation.boost_python_call_hpp.function_call" title="Function call"><code class="computeroutput"><span class="identifier">call</span></code></a> and <a class="link" href="function_invocation_and_creation/boost_python_call_method_hpp.html#function_invocation_and_creation.boost_python_call_method_hpp.function_call_method" title="Function call_method"><code class="computeroutput"><span class="identifier">call_method</span></code></a>, for invoking Python + functions and methods respectively on <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code>s. The interface for calling a Python function + object (or any Python callable object) looks like: + </p> +<pre class="programlisting"><span class="identifier">call</span><span class="special"><</span><span class="identifier">ResultType</span><span class="special">>(</span><span class="identifier">callable_object</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">...</span> <span class="identifier">aN</span><span class="special">);</span></pre> +<p> + Calling a method of a Python object is similarly easy: + </p> +<pre class="programlisting"><span class="identifier">call_method</span><span class="special"><</span><span class="identifier">ResultType</span><span class="special">>(</span><span class="identifier">self_object</span><span class="special">,</span> <span class="string">"method-name"</span><span class="special">,</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">...</span> <span class="identifier">aN</span><span class="special">);</span></pre> +<p> + This comparitively low-level interface is the one you'll use when implementing + C++ virtual functions that can be overridden in Python. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.calling_python_functions_and_met.argument_handling"></a><a class="link" href="topics.html#topics.calling_python_functions_and_met.argument_handling" title="Argument Handling">Argument + Handling</a> +</h3></div></div></div> +<p> + Arguments are converted to Python according to their type. By default, + the arguments <code class="computeroutput"><span class="identifier">a1</span><span class="special">...</span><span class="identifier">aN</span></code> are copied into new Python objects, + but this behavior can be overridden by the use of <a class="link" href="function_invocation_and_creation/boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.functions" title="Functions"><code class="computeroutput"><span class="identifier">ptr</span><span class="special">()</span></code></a> + and <code class="computeroutput"><span class="identifier">ref</span><span class="special">()</span></code>: + </p> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">X</span> <span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">noncopyable</span> +<span class="special">{</span> + <span class="special">...</span> +<span class="special">};</span> + +<span class="keyword">void</span> <span class="identifier">apply</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">callable</span><span class="special">,</span> <span class="identifier">X</span><span class="special">&</span> <span class="identifier">x</span><span class="special">)</span> +<span class="special">{</span> + <span class="comment">// Invoke callable, passing a Python object which holds a reference to x</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">call</span><span class="special"><</span><span class="keyword">void</span><span class="special">>(</span><span class="identifier">callable</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">x</span><span class="special">));</span> +<span class="special">}</span> +</pre> +<p> + In the table below, x denotes the actual argument object and cv denotes + an optional cv-qualification: "const", "volatile", + or "const volatile". + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Argument Type + </p> + </th> +<th> + <p> + Behavior + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + <code class="computeroutput"><span class="identifier">T</span> <span class="identifier">cv</span> + <span class="special">&</span></code> <code class="computeroutput"><span class="identifier">T</span> + <span class="identifier">cv</span></code> + </p> + </td> +<td> + <p> + The Python argument is created by the same means used for the + return value of a wrapped C++ function returning T. When T is + a class type, that normally means *x is copy-constructed into + the new Python object. + </p> + </td> +</tr> +<tr> +<td> + <p> + T* + </p> + </td> +<td> + <p> + If x == 0, the Python argument will be None. Otherwise, the Python + argument is created by the same means used for the return value + of a wrapped C++ function returning T. When T is a class type, + that normally means *x is copy-constructed into the new Python + object. + </p> + </td> +</tr> +<tr> +<td> + <p> + boost::reference_wrapper<T> + </p> + </td> +<td> + <p> + The Python argument contains a pointer to, rather than a copy + of, x.get(). Note: failure to ensure that no Python code holds + a reference to the resulting object beyond the lifetime of *x.get() + may result in a crash! + </p> + </td> +</tr> +<tr> +<td> + <p> + pointer_wrapper<T> + </p> + </td> +<td> + <p> + If x.get() == 0, the Python argument will be None. Otherwise, + the Python argument contains a pointer to, rather than a copy + of, *x.get(). Note: failure to ensure that no Python code holds + a reference to the resulting object beyond the lifetime of *x.get() + may result in a crash! + </p> + </td> +</tr> +</tbody> +</table></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.calling_python_functions_and_met.result_handling"></a><a class="link" href="topics.html#topics.calling_python_functions_and_met.result_handling" title="Result Handling">Result + Handling</a> +</h3></div></div></div> +<p> + In general, <code class="computeroutput"><span class="identifier">call</span><span class="special"><</span><span class="identifier">ResultType</span><span class="special">>()</span></code> + and call_method<ResultType>() return ResultType by exploiting all + lvalue and rvalue from_python converters registered for ResultType and + returning a copy of the result. However, when ResultType is a pointer or + reference type, Boost.Python searches only for lvalue converters. To prevent + dangling pointers and references, an exception will be thrown if the Python + result object has only a single reference count. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.calling_python_functions_and_met.rationale"></a><a class="link" href="topics.html#topics.calling_python_functions_and_met.rationale" title="Rationale">Rationale</a> +</h3></div></div></div> +<p> + In general, to get Python arguments corresponding to a1...aN, a new Python + object must be created for each one; should the C++ object be copied into + that Python object, or should the Python object simply hold a reference/pointer + to the C++ object? In general, the latter approach is unsafe, since the + called function may store a reference to the Python object somewhere. If + the Python object is used after the C++ object is destroyed, we'll crash + Python. + </p> +<p> + In keeping with the philosophy that users on the Python side shouldn't + have to worry about crashing the interpreter, the default behavior is to + copy the C++ object, and to allow a non-copying behavior only if the user + writes boost::ref(a1) instead of a1 directly. At least this way, the user + doesn't get dangerous behavior "by accident". It's also worth + noting that the non-copying ("by-reference") behavior is in general + only available for class types, and will fail at runtime with a Python + exception if used otherwise[1]. + </p> +<p> + However, pointer types present a problem: one approach is to refuse to + compile if any aN has pointer type: after all, a user can always pass *aN + to pass "by-value" or ref(*aN) to indicate a pass-by-reference + behavior. However, this creates a problem for the expected null pointer + to None conversion: it's illegal to dereference a null pointer value. + </p> +<p> + The compromise I've settled on is this: + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + The default behavior is pass-by-value. If you pass a non-null pointer, + the pointee is copied into a new Python object; otherwise the corresponding + Python argument will be None. + </li> +<li class="listitem"> + if you want by-reference behavior, use ptr(aN) if aN is a pointer and + ref(aN) otherwise. If a null pointer is passed to ptr(aN), the corresponding + Python argument will be None. + </li> +</ol></div> +<p> + As for results, we have a similar problem: if ResultType is allowed to + be a pointer or reference type, the lifetime of the object it refers to + is probably being managed by a Python object. When that Python object is + destroyed, our pointer dangles. The problem is particularly bad when the + ResultType is char const* - the corresponding Python String object is typically + uniquely-referenced, meaning that the pointer dangles as soon as call<char + const*>(...) returns. + </p> +<p> + The old Boost.Python v1 deals with this issue by refusing to compile any + uses of call<char const*>(), but this goes both too far and not far + enough. It goes too far because there are cases where the owning Python + string object survives beyond the call (just for instance, when it's the + name of a Python class), and it goes not far enough because we might just + as well have the same problem with a returned pointer or reference of any + other type. + </p> +<p> + In Boost.Python this is dealt with by: + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> + lifting the compile-time restriction on <code class="computeroutput"><span class="keyword">char</span> + <span class="keyword">const</span> <span class="special">*</span></code> + callback returns + </li> +<li class="listitem"> + detecting the case when the reference count on the result Python object + is 1 and throwing an exception inside of <code class="computeroutput"><span class="identifier">call</span><span class="special"><</span><span class="identifier">U</span><span class="special">>(...)</span></code> when <code class="computeroutput"><span class="identifier">U</span></code> + is a pointer or reference type. + </li> +</ol></div> +<p> + This should be acceptably safe because users have to explicitly specify + a pointer/reference for <code class="computeroutput"><span class="identifier">U</span></code> + in <code class="computeroutput"><span class="identifier">call</span><span class="special"><</span><span class="identifier">U</span><span class="special">></span></code>, + and they will be protected against dangles at runtime, at least long enough + to get out of the <code class="computeroutput"><span class="identifier">call</span><span class="special"><</span><span class="identifier">U</span><span class="special">>(...)</span></code> invocation. + </p> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="utility_and_infrastructure/boost_python_ssize_t_hpp.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="topics/pickle_support.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/topics/indexing_support.html b/libs/python/doc/html/reference/topics/indexing_support.html new file mode 100644 index 0000000000..c9eedf66e0 --- /dev/null +++ b/libs/python/doc/html/reference/topics/indexing_support.html @@ -0,0 +1,832 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Indexing support</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../topics.html" title="Chapter 8. Topics"> +<link rel="prev" href="pickle_support.html" title="Pickle support"> +<link rel="next" href="../glossary.html" title="Chapter 9. Glossary"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="pickle_support.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../topics.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../glossary.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="topics.indexing_support"></a><a class="link" href="indexing_support.html" title="Indexing support">Indexing support</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.the_indexing_interface">The + Indexing Interface</a></span></dt> +<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.index_suite_sub_classes">index_suite + sub-classes</a></span></dt> +<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.indexing_suite_class"><code class="computeroutput"><span class="identifier">indexing_suite</span></code> class</a></span></dt> +<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.class_vector_indexing_suite">class + <code class="computeroutput"><span class="identifier">vector_indexing_suite</span></code></a></span></dt> +<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.class_map_indexing_suite">class + <code class="computeroutput"><span class="identifier">map_indexing_suite</span></code></a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.indexing_support.introduction"></a><a class="link" href="indexing_support.html#topics.indexing_support.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Indexing is a <code class="computeroutput"><span class="identifier">Boost</span> <span class="identifier">Python</span></code> + facility for easy exportation of indexable C++ containers to Python. Indexable + containers are containers that allow random access through the <code class="computeroutput"><span class="keyword">operator</span><span class="special">[]</span></code> + (e.g. <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>). + </p> +<p> + While <code class="computeroutput"><span class="identifier">Boost</span> <span class="identifier">Python</span></code> + has all the facilities needed to expose indexable C++ containers such as + the ubiquitous std::vector to Python, the procedure is not as straightforward + as we'd like it to be. Python containers do not map easily to C++ containers. + Emulating Python containers in C++ (see Python Reference Manual, <a href="http://www.python.org/doc/current/ref/sequence-types.html" target="_top">Emulating + container types</a>) using <code class="computeroutput"><span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span></code> + is non trivial. There are a lot of issues to consider before we can map + a C++ container to Python. These involve implementing wrapper functions + for the methods <code class="computeroutput"><span class="identifier">__len__</span></code>, + <code class="computeroutput"><span class="identifier">__getitem__</span></code>, <code class="computeroutput"><span class="identifier">__setitem__</span></code>, <code class="computeroutput"><span class="identifier">__delitem__</span></code>, + <code class="computeroutput"><span class="identifier">__iter__</span></code> and <code class="computeroutput"><span class="identifier">__contains__</span></code>. + </p> +<p> + The goals: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + Make indexable C++ containers behave exactly as one would expect a + Python container to behave. + </li> +<li class="listitem"> +<p class="simpara"> + Provide default reference semantics for container element indexing + (<code class="computeroutput"><span class="identifier">__getitem__</span></code>) such + that c[i] can be mutable. Require: + </p> +<pre class="programlisting"><span class="identifier">val</span> <span class="special">=</span> <span class="identifier">c</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> +<span class="identifier">c</span><span class="special">[</span><span class="identifier">i</span><span class="special">].</span><span class="identifier">m</span><span class="special">()</span> +<span class="identifier">val</span> <span class="special">==</span> <span class="identifier">c</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> +</pre> +<p class="simpara"> + where m is a non-const (mutating) member function (method). + </p> +</li> +<li class="listitem"> + Return safe references from <code class="computeroutput"><span class="identifier">__getitem__</span></code> + such that subsequent adds and deletes to and from the container will + not result in dangling references (will not crash Python). + </li> +<li class="listitem"> + Support slice indexes. + </li> +<li class="listitem"> + Accept Python container arguments (e.g. <code class="computeroutput"><span class="identifier">lists</span></code>, + <code class="computeroutput"><span class="identifier">tuples</span></code>) wherever appropriate. + </li> +<li class="listitem"> + Allow for extensibility through re-definable policy classes. + </li> +<li class="listitem"> + Provide predefined support for the most common STL and STL-like indexable + containers. + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.indexing_support.the_indexing_interface"></a><a class="link" href="indexing_support.html#topics.indexing_support.the_indexing_interface" title="The Indexing Interface">The + Indexing Interface</a> +</h3></div></div></div> +<p> + The <code class="computeroutput"><span class="identifier">indexing_suite</span></code> class + is the base class for the management of C++ containers intended to be integrated + to Python. The objective is make a C++ container look and feel and behave + exactly as we'd expect a Python container. The class automatically wraps + these special Python methods (taken from the Python reference: Emulating + container types): + </p> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">__len__(self)</span></dt> +<dd><p> + Called to implement the built-in function <code class="computeroutput"><span class="identifier">len</span><span class="special">()</span></code>. Should return the length of the + object, an integer <code class="computeroutput"><span class="special">>=</span> <span class="number">0</span></code>. Also, an object that doesn't define + a <code class="computeroutput"><span class="identifier">__nonzero__</span><span class="special">()</span></code> + method and whose <code class="computeroutput"><span class="identifier">__len__</span><span class="special">()</span></code> method returns zero is considered + to be false in a Boolean context. + </p></dd> +<dt><span class="term">__getitem__(self, key)</span></dt> +<dd><p> + Called to implement evaluation of <code class="computeroutput"><span class="identifier">self</span><span class="special">[</span><span class="identifier">key</span><span class="special">]</span></code>. For sequence types, the accepted + keys should be integers and slice objects. Note that the special + interpretation of negative indexes (if the class wishes to emulate + a sequence type) is up to the <code class="computeroutput"><span class="identifier">__getitem__</span><span class="special">()</span></code> method. If key is of an inappropriate + type, <code class="computeroutput"><span class="identifier">TypeError</span></code> may + be raised; if of a value outside the set of indexes for the sequence + (after any special interpretation of negative values), IndexError + should be raised. [Note: for loops expect that an IndexError will + be raised for illegal indexes to allow proper detection of the end + of the sequence.] + </p></dd> +<dt><span class="term">__setitem__(self, key, value)</span></dt> +<dd><p> + Called to implement assignment to self[key]. Same note as for __getitem__(). + This should only be implemented for mappings if the objects support + changes to the values for keys, or if new keys can be added, or for + sequences if elements can be replaced. The same exceptions should + be raised for improper key values as for the __getitem__() method. + </p></dd> +<dt><span class="term">__delitem__(self, key)</span></dt> +<dd><p> + Called to implement deletion of self[key]. Same note as for __getitem__(). + This should only be implemented for mappings if the objects support + removal of keys, or for sequences if elements can be removed from + the sequence. The same exceptions should be raised for improper key + values as for the __getitem__() method. + </p></dd> +<dt><span class="term">__iter__(self)</span></dt> +<dd> +<p> + This method is called when an iterator is required for a container. + This method should return a new iterator object that can iterate + over all the objects in the container. For mappings, it should iterate + over the keys of the container, and should also be made available + as the method iterkeys(). + </p> +<p> + Iterator objects also need to implement this method; they are required + to return themselves. For more information on iterator objects, see + <a href="http://www.python.org/doc/current/lib/typeiter.html" target="_top">Iterator + Types</a> in the <a href="http://www.python.org/doc/current/lib/lib.html" target="_top">Python + Library Reference</a>. + </p> +</dd> +<dt><span class="term">__contains__(self, item)</span></dt> +<dd><p> + Called to implement membership test operators. Should return true + if item is in self, false otherwise. For mapping objects, this should + consider the keys of the mapping rather than the values or the key-item + pairs. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.indexing_support.index_suite_sub_classes"></a><a class="link" href="indexing_support.html#topics.indexing_support.index_suite_sub_classes" title="index_suite sub-classes">index_suite + sub-classes</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.index_suite_sub_classes.vector_index_suite">vector_index_suite</a></span></dt> +<dt><span class="section"><a href="indexing_support.html#topics.indexing_support.index_suite_sub_classes.map_index_suite">map_index_suite</a></span></dt> +</dl></div> +<p> + The <code class="computeroutput"><span class="identifier">indexing_suite</span></code> is not + meant to be used as is. A couple of policy functions must be supplied by + subclasses of <code class="computeroutput"><span class="identifier">indexing_suite</span></code>. + However, a set of indexing_suite subclasses for the standard indexable + STL containers will be provided, In most cases, we can simply use the available + predefined suites. In some cases, we can refine the predefined suites to + suit our needs. + </p> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="topics.indexing_support.index_suite_sub_classes.vector_index_suite"></a><a class="link" href="indexing_support.html#topics.indexing_support.index_suite_sub_classes.vector_index_suite" title="vector_index_suite">vector_index_suite</a> +</h4></div></div></div> +<p> + The <code class="computeroutput"><span class="identifier">vector_indexing_suite</span></code> + class is a predefined <code class="computeroutput"><span class="identifier">indexing_suite</span></code> + derived class designed to wrap <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code> + (and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>-like [i.e. a class with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code> interface]) classes. It provides + all the policies required by the <code class="computeroutput"><span class="identifier">indexing_suite</span></code>. + </p> +<p> + Example usage: + </p> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">X</span> <span class="special">{...};</span> +<span class="special">...</span> +<span class="identifier">class_</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span> <span class="special">>(</span><span class="string">"XVec"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">vector_indexing_suite</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span> <span class="special">>())</span> +<span class="special">;</span> +</pre> +<p> + XVec is now a full-fledged Python container (see the example in full, + along with its python test). + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="topics.indexing_support.index_suite_sub_classes.map_index_suite"></a><a class="link" href="indexing_support.html#topics.indexing_support.index_suite_sub_classes.map_index_suite" title="map_index_suite">map_index_suite</a> +</h4></div></div></div> +<p> + The <code class="computeroutput"><span class="identifier">map_indexing_suite</span></code> + class is a predefined <code class="computeroutput"><span class="identifier">indexing_suite</span></code> + derived class designed to wrap <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span></code> + (and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span></code>-like [i.e. a class with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span></code> interface]) classes. It provides + all the policies required by the <code class="computeroutput"><span class="identifier">indexing_suite</span></code>. + </p> +<p> + Example usage: + </p> +<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">X</span> <span class="special">{...};</span> +<span class="special">...</span> + +<span class="identifier">class_</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span> <span class="special">>(</span><span class="string">"XMap"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">map_indexing_suite</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span> <span class="special">>())</span> +<span class="special">;</span> +</pre> +<p> + By default indexed elements are returned by proxy. This can be disabled + by supplying <code class="computeroutput"><span class="keyword">true</span></code> in the + <code class="computeroutput"><span class="identifier">NoProxy</span></code> template parameter. + XMap is now a full-fledged Python container (see the example in full, + along with its python test). + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.indexing_support.indexing_suite_class"></a><a class="link" href="indexing_support.html#topics.indexing_support.indexing_suite_class" title="indexing_suite class"><code class="computeroutput"><span class="identifier">indexing_suite</span></code> class</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"><dt><span class="section"><a href="indexing_support.html#topics.indexing_support.indexing_suite_class.derivedpolicies">DerivedPolicies</a></span></dt></dl></div> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Template Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Semantics + </p> + </th> +<th> + <p> + Default + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + Container + </p> + </td> +<td> + <p> + A class type + </p> + </td> +<td> + <p> + The container type to be wrapped to Python. + </p> + </td> +<td> + </td> +</tr> +<tr> +<td> + <p> + DerivedPolicies + </p> + </td> +<td> + <p> + A subclass of indexing_suite + </p> + </td> +<td> + <p> + Derived classes provide the policy hooks. See DerivedPolicies + below. + </p> + </td> +<td> + </td> +</tr> +<tr> +<td> + <p> + NoProxy + </p> + </td> +<td> + <p> + A boolean + </p> + </td> +<td> + <p> + By default indexed elements have Python reference semantics and + are returned by proxy. This can be disabled by supplying true + in the NoProxy template parameter. + </p> + </td> +<td> + <p> + false + </p> + </td> +</tr> +<tr> +<td> + <p> + NoSlice + </p> + </td> +<td> + <p> + A boolean + </p> + </td> +<td> + <p> + Do not allow slicing. + </p> + </td> +<td> + <p> + false + </p> + </td> +</tr> +<tr> +<td> + <p> + Data + </p> + </td> +<td> + </td> +<td> + <p> + The container's data type. + </p> + </td> +<td> + <p> + Container::value_type + </p> + </td> +</tr> +<tr> +<td> + <p> + Index + </p> + </td> +<td> + </td> +<td> + <p> + The container's index type. + </p> + </td> +<td> + <p> + Container::size_type + </p> + </td> +</tr> +<tr> +<td> + <p> + Key + </p> + </td> +<td> + </td> +<td> + <p> + The container's key type. + </p> + </td> +<td> + <p> + Container::value_type + </p> + </td> +</tr> +</tbody> +</table></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Container</span><span class="special">,</span> + <span class="keyword">class</span> <span class="identifier">DerivedPolicies</span><span class="special">,</span> + <span class="keyword">bool</span> <span class="identifier">NoProxy</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">,</span> + <span class="keyword">bool</span> <span class="identifier">NoSlice</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">,</span> + <span class="keyword">class</span> <span class="identifier">Data</span> <span class="special">=</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">,</span> + <span class="keyword">class</span> <span class="identifier">Index</span> <span class="special">=</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">size_type</span><span class="special">,</span> + <span class="keyword">class</span> <span class="identifier">Key</span> <span class="special">=</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">></span> +<span class="keyword">class</span> <span class="identifier">indexing_suite</span> <span class="special">:</span> <span class="identifier">unspecified</span> +<span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + <span class="identifier">indexing_suite</span><span class="special">();</span> <span class="comment">// default constructor</span> +<span class="special">}</span> +</pre> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="topics.indexing_support.indexing_suite_class.derivedpolicies"></a><a class="link" href="indexing_support.html#topics.indexing_support.indexing_suite_class.derivedpolicies" title="DerivedPolicies">DerivedPolicies</a> +</h4></div></div></div> +<p> + Derived classes provide the hooks needed by the indexing_suite: + </p> +<pre class="programlisting"><span class="identifier">data_type</span><span class="special">&</span> +<span class="identifier">get_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">);</span> + +<span class="keyword">static</span> <span class="identifier">object</span> +<span class="identifier">get_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">);</span> + +<span class="keyword">static</span> <span class="keyword">void</span> +<span class="identifier">set_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">data_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span><span class="special">);</span> + +<span class="keyword">static</span> <span class="keyword">void</span> +<span class="identifier">set_slice</span><span class="special">(</span> + <span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> + <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">,</span> <span class="identifier">data_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span> +<span class="special">);</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Iter</span><span class="special">></span> +<span class="keyword">static</span> <span class="keyword">void</span> +<span class="identifier">set_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> + <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">,</span> <span class="identifier">Iter</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">Iter</span> <span class="identifier">last</span> +<span class="special">);</span> + +<span class="keyword">static</span> <span class="keyword">void</span> +<span class="identifier">delete_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">);</span> + +<span class="keyword">static</span> <span class="keyword">void</span> +<span class="identifier">delete_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">);</span> + +<span class="keyword">static</span> <span class="identifier">size_t</span> +<span class="identifier">size</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">);</span> + +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> +<span class="keyword">static</span> <span class="keyword">bool</span> +<span class="identifier">contains</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">val</span><span class="special">);</span> + +<span class="keyword">static</span> <span class="identifier">index_type</span> +<span class="identifier">convert_index</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">i</span><span class="special">);</span> + +<span class="keyword">static</span> <span class="identifier">index_type</span> +<span class="identifier">adjust_index</span><span class="special">(</span><span class="identifier">index_type</span> <span class="identifier">current</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> + <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">,</span> <span class="identifier">size_type</span> <span class="identifier">len</span><span class="special">);</span> +</pre> +<p> + Most of these policies are self explanatory. However, convert_index and + adjust_index deserve some explanation. + </p> +<p> + convert_index converts a Python index into a C++ index that the container + can handle. For instance, negative indexes in Python, by convention, + start counting from the right(e.g. C<span class="strikethrough">1</span> + indexes the rightmost element in C). convert_index should handle the + necessary conversion for the C++ container (e.g. convert -1 to C.size()-1). + convert_index should also be able to convert the type of the index (A + dynamic Python type) to the actual type that the C++ container expects. + </p> +<p> + When a container expands or contracts, held indexes to its elements must + be adjusted to follow the movement of data. For instance, if we erase + 3 elements, starting from index 0 from a 5 element vector, what used + to be at index 4 will now be at index 1: + </p> +<pre class="programlisting"><span class="special">[</span><span class="identifier">a</span><span class="special">][</span><span class="identifier">b</span><span class="special">][</span><span class="identifier">c</span><span class="special">][</span><span class="identifier">d</span><span class="special">][</span><span class="identifier">e</span><span class="special">]</span> <span class="special">---></span> <span class="special">[</span><span class="identifier">d</span><span class="special">][</span><span class="identifier">e</span><span class="special">]</span> + <span class="special">^</span> <span class="special">^</span> + <span class="number">4</span> <span class="number">1</span> +</pre> +<p> + adjust_index takes care of the adjustment. Given a current index, the + function should return the adjusted index when data in the container + at index from..to is replaced by len elements. + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.indexing_support.class_vector_indexing_suite"></a><a class="link" href="indexing_support.html#topics.indexing_support.class_vector_indexing_suite" title="class vector_indexing_suite">class + <code class="computeroutput"><span class="identifier">vector_indexing_suite</span></code></a> +</h3></div></div></div> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Template Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Semantics + </p> + </th> +<th> + <p> + Default + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + Container + </p> + </td> +<td> + <p> + A class type + </p> + </td> +<td> + <p> + The container type to be wrapped to Python. + </p> + </td> +<td> + </td> +</tr> +<tr> +<td> + <p> + NoProxy + </p> + </td> +<td> + <p> + A boolean + </p> + </td> +<td> + <p> + By default indexed elements have Python reference semantics and + are returned by proxy. This can be disabled by supplying true + in the NoProxy template parameter. + </p> + </td> +<td> + <p> + false + </p> + </td> +</tr> +<tr> +<td> + <p> + DerivedPolicies + </p> + </td> +<td> + <p> + A subclass of indexing_suite + </p> + </td> +<td> + <p> + The vector_indexing_suite may still be derived to further tweak + any of the predefined policies. Static polymorphism through CRTP + (James Coplien. "Curiously Recurring Template Pattern". + C++ Report, Feb. 1995) enables the base indexing_suite class + to call policy function of the most derived class + </p> + </td> +<td> + </td> +</tr> +</tbody> +</table></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Container</span><span class="special">,</span> + <span class="keyword">bool</span> <span class="identifier">NoProxy</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">,</span> + <span class="keyword">class</span> <span class="identifier">DerivedPolicies</span> <span class="special">=</span> <span class="identifier">unspecified_default</span><span class="special">></span> +<span class="keyword">class</span> <span class="identifier">vector_indexing_suite</span> <span class="special">:</span> <span class="identifier">unspecified_base</span> +<span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + + <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">data_type</span><span class="special">;</span> + <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">key_type</span><span class="special">;</span> + <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">index_type</span><span class="special">;</span> + <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">size_type</span><span class="special">;</span> + <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">difference_type</span> <span class="identifier">difference_type</span><span class="special">;</span> + + <span class="identifier">data_type</span><span class="special">&</span> + <span class="identifier">get_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="identifier">object</span> + <span class="identifier">get_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="keyword">void</span> + <span class="identifier">set_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">data_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="keyword">void</span> + <span class="identifier">set_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> + <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">,</span> <span class="identifier">data_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Iter</span><span class="special">></span> + <span class="keyword">static</span> <span class="keyword">void</span> + <span class="identifier">set_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> + <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">,</span> <span class="identifier">Iter</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">Iter</span> <span class="identifier">last</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="keyword">void</span> + <span class="identifier">delete_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="keyword">void</span> + <span class="identifier">delete_slice</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="identifier">size_t</span> + <span class="identifier">size</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="keyword">bool</span> + <span class="identifier">contains</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">key_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="identifier">index_type</span> + <span class="identifier">convert_index</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">i</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="identifier">index_type</span> + <span class="identifier">adjust_index</span><span class="special">(</span><span class="identifier">index_type</span> <span class="identifier">current</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">from</span><span class="special">,</span> + <span class="identifier">index_type</span> <span class="identifier">to</span><span class="special">,</span> <span class="identifier">size_type</span> <span class="identifier">len</span><span class="special">);</span> +<span class="special">};</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.indexing_support.class_map_indexing_suite"></a><a class="link" href="indexing_support.html#topics.indexing_support.class_map_indexing_suite" title="class map_indexing_suite">class + <code class="computeroutput"><span class="identifier">map_indexing_suite</span></code></a> +</h3></div></div></div> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + Template Parameter + </p> + </th> +<th> + <p> + Requirements + </p> + </th> +<th> + <p> + Semantics + </p> + </th> +<th> + <p> + Default + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + Container + </p> + </td> +<td> + <p> + A class type + </p> + </td> +<td> + <p> + The container type to be wrapped to Python. + </p> + </td> +<td> + </td> +</tr> +<tr> +<td> + <p> + NoProxy + </p> + </td> +<td> + <p> + A boolean + </p> + </td> +<td> + <p> + By default indexed elements have Python reference semantics and + are returned by proxy. This can be disabled by supplying true + in the NoProxy template parameter. + </p> + </td> +<td> + <p> + false + </p> + </td> +</tr> +<tr> +<td> + <p> + DerivedPolicies + </p> + </td> +<td> + <p> + A subclass of indexing_suite + </p> + </td> +<td> + <p> + The vector_indexing_suite may still be derived to further tweak + any of the predefined policies. Static polymorphism through CRTP + (James Coplien. "Curiously Recurring Template Pattern". + C++ Report, Feb. 1995) enables the base indexing_suite class + to call policy function of the most derived class + </p> + </td> +<td> + </td> +</tr> +</tbody> +</table></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Container</span><span class="special">,</span> + <span class="keyword">bool</span> <span class="identifier">NoProxy</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">,</span> + <span class="keyword">class</span> <span class="identifier">DerivedPolicies</span> <span class="special">=</span> <span class="identifier">unspecified_default</span><span class="special">></span> +<span class="keyword">class</span> <span class="identifier">map_indexing_suite</span> <span class="special">:</span> <span class="identifier">unspecified_base</span> +<span class="special">{</span> +<span class="keyword">public</span><span class="special">:</span> + + <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">value_type</span><span class="special">;</span> + <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">::</span><span class="identifier">second_type</span> <span class="identifier">data_type</span><span class="special">;</span> + <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">key_type</span> <span class="identifier">key_type</span><span class="special">;</span> + <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">key_type</span> <span class="identifier">index_type</span><span class="special">;</span> + <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">size_type</span><span class="special">;</span> + <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">Container</span><span class="special">::</span><span class="identifier">difference_type</span> <span class="identifier">difference_type</span><span class="special">;</span> + + <span class="keyword">static</span> <span class="identifier">data_type</span><span class="special">&</span> + <span class="identifier">get_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="keyword">void</span> + <span class="identifier">set_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">data_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="keyword">void</span> + <span class="identifier">delete_item</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">i</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="identifier">size_t</span> + <span class="identifier">size</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="keyword">bool</span> + <span class="identifier">contains</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">key_type</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">key</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="keyword">bool</span> + <span class="identifier">compare_index</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">index_type</span> <span class="identifier">b</span><span class="special">);</span> + + <span class="keyword">static</span> <span class="identifier">index_type</span> + <span class="identifier">convert_index</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&</span> <span class="identifier">container</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">i</span><span class="special">);</span> +<span class="special">};</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="pickle_support.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../topics.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../glossary.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/topics/pickle_support.html b/libs/python/doc/html/reference/topics/pickle_support.html new file mode 100644 index 0000000000..e23ed383e1 --- /dev/null +++ b/libs/python/doc/html/reference/topics/pickle_support.html @@ -0,0 +1,356 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Pickle support</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../topics.html" title="Chapter 8. Topics"> +<link rel="prev" href="../topics.html" title="Chapter 8. Topics"> +<link rel="next" href="indexing_support.html" title="Indexing support"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../topics.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../topics.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="indexing_support.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="topics.pickle_support"></a><a class="link" href="pickle_support.html" title="Pickle support">Pickle support</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="pickle_support.html#topics.pickle_support.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="pickle_support.html#topics.pickle_support.the_pickle_interface">The Pickle + Interface</a></span></dt> +<dt><span class="section"><a href="pickle_support.html#topics.pickle_support.example">Example</a></span></dt> +<dt><span class="section"><a href="pickle_support.html#topics.pickle_support.pitfall_and_safety_guard">Pitfall + and Safety Guard</a></span></dt> +<dt><span class="section"><a href="pickle_support.html#topics.pickle_support.practical_advice">Practical Advice</a></span></dt> +<dt><span class="section"><a href="pickle_support.html#topics.pickle_support.light_weight_alternative_pickle_">Light-weight + alternative: pickle support implemented in Python</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.pickle_support.introduction"></a><a class="link" href="pickle_support.html#topics.pickle_support.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Pickle is a Python module for object serialization, also known as persistence, + marshalling, or flattening. + </p> +<p> + It is often necessary to save and restore the contents of an object to + a file. One approach to this problem is to write a pair of functions that + read and write data from a file in a special format. A powerful alternative + approach is to use Python's pickle module. Exploiting Python's ability + for introspection, the pickle module recursively converts nearly arbitrary + Python objects into a stream of bytes that can be written to a file. + </p> +<p> + The Boost Python Library supports the pickle module through the interface + as described in detail in the <a href="http://www.python.org/doc/current/lib/module-pickle.html" target="_top">Python + Library Reference for pickle</a>. This interface involves the special + methods <code class="computeroutput"><span class="identifier">__getinitargs__</span></code>, + <code class="computeroutput"><span class="identifier">__getstate__</span></code> and <code class="computeroutput"><span class="identifier">__setstate__</span></code> as described in the following. + Note that <code class="computeroutput"><span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span></code> is also fully compatible with + Python's cPickle module. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.pickle_support.the_pickle_interface"></a><a class="link" href="pickle_support.html#topics.pickle_support.the_pickle_interface" title="The Pickle Interface">The Pickle + Interface</a> +</h3></div></div></div> +<p> + At the user level, the Boost.Python pickle interface involves three special + methods: + </p> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">__getinitargs__</span></dt> +<dd> +<p> + When an instance of a Boost.Python extension class is pickled, the + pickler tests if the instance has a <code class="computeroutput"><span class="identifier">__getinitargs__</span></code> + method. This method must return a Python <code class="computeroutput"><span class="identifier">tuple</span></code> + (it is most convenient to use a <a class="link" href="../object_wrappers/boost_python_tuple_hpp.html#object_wrappers.boost_python_tuple_hpp.class_tuple" title="Class tuple"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">tuple</span></code></a>). When the instance + is restored by the unpickler, the contents of this tuple are used + as the arguments for the class constructor. + </p> +<p> + If <code class="computeroutput"><span class="identifier">__getinitargs__</span></code> + is not defined, <code class="computeroutput"><span class="identifier">pickle</span><span class="special">.</span><span class="identifier">load</span></code> + will call the constructor (<code class="computeroutput"><span class="identifier">__init__</span></code>) + without arguments; i.e., the object must be default-constructible. + </p> +</dd> +<dt><span class="term">__getstate__</span></dt> +<dd><p> + When an instance of a <code class="computeroutput"><span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span></code> + extension class is pickled, the pickler tests if the instance has + a <code class="computeroutput"><span class="identifier">__getstate__</span></code> method. + This method should return a Python object representing the state + of the instance. + </p></dd> +<dt><span class="term">__setstate__</span></dt> +<dd><p> + When an instance of a <code class="computeroutput"><span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span></code> + extension class is restored by the unpickler (<code class="computeroutput"><span class="identifier">pickle</span><span class="special">.</span><span class="identifier">load</span></code>), + it is first constructed using the result of <code class="computeroutput"><span class="identifier">__getinitargs__</span></code> + as arguments (see above). Subsequently the unpickler tests if the + new instance has a <code class="computeroutput"><span class="identifier">__setstate__</span></code> + method. If so, this method is called with the result of <code class="computeroutput"><span class="identifier">__getstate__</span></code> (a Python object) + as the argument. + </p></dd> +</dl> +</div> +<p> + The three special methods described above may be <code class="computeroutput"><span class="special">.</span><span class="identifier">def</span><span class="special">()</span></code>'ed + individually by the user. However, <code class="computeroutput"><span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span></code> + provides an easy to use high-level interface via the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">pickle_suite</span></code> + class that also enforces consistency: <code class="computeroutput"><span class="identifier">__getstate__</span></code> + and <code class="computeroutput"><span class="identifier">__setstate__</span></code> must be + defined as pairs. Use of this interface is demonstrated by the following + examples. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.pickle_support.example"></a><a class="link" href="pickle_support.html#topics.pickle_support.example" title="Example">Example</a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="pickle_support.html#topics.pickle_support.example.pickle1_cpp">pickle1.cpp</a></span></dt> +<dt><span class="section"><a href="pickle_support.html#topics.pickle_support.example.pickle2_cpp">pickle2.cpp</a></span></dt> +<dt><span class="section"><a href="pickle_support.html#topics.pickle_support.example.pickle3_cpp">pickle3.cpp</a></span></dt> +</dl></div> +<p> + There are three files in <code class="computeroutput"><span class="identifier">python</span><span class="special">/</span><span class="identifier">test</span></code> + that show how to provide pickle support. + </p> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="topics.pickle_support.example.pickle1_cpp"></a><a class="link" href="pickle_support.html#topics.pickle_support.example.pickle1_cpp" title="pickle1.cpp">pickle1.cpp</a> +</h4></div></div></div> +<p> + The C++ class in this example can be fully restored by passing the appropriate + argument to the constructor. Therefore it is sufficient to define the + pickle interface method <code class="computeroutput"><span class="identifier">__getinitargs__</span></code>. + This is done in the following way: Definition of the C++ pickle function: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">world_pickle_suite</span> <span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">pickle_suite</span> +<span class="special">{</span> + <span class="keyword">static</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">tuple</span> + <span class="identifier">getinitargs</span><span class="special">(</span><span class="identifier">world</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">w</span><span class="special">)</span> + <span class="special">{</span> + <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">w</span><span class="special">.</span><span class="identifier">get_country</span><span class="special">());</span> + <span class="special">}</span> +<span class="special">};</span> +</pre> +<p> + Establishing the Python binding: + </p> +<pre class="programlisting"><span class="identifier">class_</span><span class="special"><</span><span class="identifier">world</span><span class="special">>(</span><span class="string">"world"</span><span class="special">,</span> <span class="identifier">args</span><span class="special"><</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&>())</span> + <span class="comment">// ...</span> + <span class="special">.</span><span class="identifier">def_pickle</span><span class="special">(</span><span class="identifier">world_pickle_suite</span><span class="special">())</span> + <span class="comment">// ...</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="topics.pickle_support.example.pickle2_cpp"></a><a class="link" href="pickle_support.html#topics.pickle_support.example.pickle2_cpp" title="pickle2.cpp">pickle2.cpp</a> +</h4></div></div></div> +<p> + The C++ class in this example contains member data that cannot be restored + by any of the constructors. Therefore it is necessary to provide the + <code class="computeroutput"><span class="identifier">__getstate__</span></code>/<code class="computeroutput"><span class="identifier">__setstate__</span></code> pair of pickle interface + methods: + </p> +<p> + Definition of the C++ pickle functions: + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">world_pickle_suite</span> <span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">pickle_suite</span> + <span class="special">{</span> + <span class="keyword">static</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">tuple</span> + <span class="identifier">getinitargs</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">world</span><span class="special">&</span> <span class="identifier">w</span><span class="special">)</span> + <span class="special">{</span> + <span class="comment">// ...</span> + <span class="special">}</span> + + <span class="keyword">static</span> + <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">tuple</span> + <span class="identifier">getstate</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">world</span><span class="special">&</span> <span class="identifier">w</span><span class="special">)</span> + <span class="special">{</span> + <span class="comment">// ...</span> + <span class="special">}</span> + + <span class="keyword">static</span> + <span class="keyword">void</span> + <span class="identifier">setstate</span><span class="special">(</span><span class="identifier">world</span><span class="special">&</span> <span class="identifier">w</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">tuple</span> <span class="identifier">state</span><span class="special">)</span> + <span class="special">{</span> + <span class="comment">// ...</span> + <span class="special">}</span> + <span class="special">};</span> +</pre> +<p> + Establishing the Python bindings for the entire suite: + </p> +<pre class="programlisting"><span class="identifier">class_</span><span class="special"><</span><span class="identifier">world</span><span class="special">>(</span><span class="string">"world"</span><span class="special">,</span> <span class="identifier">args</span><span class="special"><</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&>())</span> + <span class="comment">// ...</span> + <span class="special">.</span><span class="identifier">def_pickle</span><span class="special">(</span><span class="identifier">world_pickle_suite</span><span class="special">())</span> + <span class="comment">// ...</span> +</pre> +<p> + For simplicity, the <code class="computeroutput"><span class="identifier">__dict__</span></code> + is not included in the result of <code class="computeroutput"><span class="identifier">__getstate__</span></code>. + This is not generally recommended, but a valid approach if it is anticipated + that the object's <code class="computeroutput"><span class="identifier">__dict__</span></code> + will always be empty. Note that the safety guard described below will + catch the cases where this assumption is violated. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="topics.pickle_support.example.pickle3_cpp"></a><a class="link" href="pickle_support.html#topics.pickle_support.example.pickle3_cpp" title="pickle3.cpp">pickle3.cpp</a> +</h4></div></div></div> +<p> + This example is similar to pickle2.cpp. However, the object's <code class="computeroutput"><span class="identifier">__dict__</span></code> is included in the result + of <code class="computeroutput"><span class="identifier">__getstate__</span></code>. This + requires a little more code but is unavoidable if the object's <code class="computeroutput"><span class="identifier">__dict__</span></code> is not always empty. + </p> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.pickle_support.pitfall_and_safety_guard"></a><a class="link" href="pickle_support.html#topics.pickle_support.pitfall_and_safety_guard" title="Pitfall and Safety Guard">Pitfall + and Safety Guard</a> +</h3></div></div></div> +<p> + The pickle protocol described above has an important pitfall that the end + user of a Boost.Python extension module might not be aware of: + </p> +<p> + <span class="bold"><strong><code class="computeroutput"><span class="identifier">__getstate__</span></code> + is defined and the instance's <code class="computeroutput"><span class="identifier">__dict__</span></code> + is not empty.</strong></span> + </p> +<p> + The author of a <code class="computeroutput"><span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span></code> extension class might provide + a <code class="computeroutput"><span class="identifier">__getstate__</span></code> method without + considering the possibilities that: * his class is used in Python as a + base class. Most likely the <code class="computeroutput"><span class="identifier">__dict__</span></code> + of instances of the derived class needs to be pickled in order to restore + the instances correctly. * the user adds items to the instance's <code class="computeroutput"><span class="identifier">__dict__</span></code> directly. Again, the <code class="computeroutput"><span class="identifier">__dict__</span></code> of the instance then needs to + be pickled. + </p> +<p> + To alert the user to this highly unobvious problem, a safety guard is provided. + If <code class="computeroutput"><span class="identifier">__getstate__</span></code> is defined + and the instance's <code class="computeroutput"><span class="identifier">__dict__</span></code> + is not empty, <code class="computeroutput"><span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span></code> tests if the class has an attribute + <code class="computeroutput"><span class="identifier">__getstate_manages_dict__</span></code>. + An exception is raised if this attribute is not defined: + </p> +<pre class="programlisting"><span class="identifier">RuntimeError</span><span class="special">:</span> <span class="identifier">Incomplete</span> <span class="identifier">pickle</span> <span class="identifier">support</span> <span class="special">(</span><span class="identifier">__getstate_manages_dict__</span> <span class="keyword">not</span> <span class="identifier">set</span><span class="special">)</span> +</pre> +<p> + To resolve this problem, it should first be established that the <code class="computeroutput"><span class="identifier">__getstate__</span></code> and <code class="computeroutput"><span class="identifier">__setstate__</span></code> + methods manage the instances's <code class="computeroutput"><span class="identifier">__dict__</span></code> + correctly. Note that this can be done either at the C++ or the Python level. + Finally, the safety guard should intentionally be overridden. E.g. in C++ + (from pickle3.cpp): + </p> +<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">world_pickle_suite</span> <span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">pickle_suite</span> +<span class="special">{</span> + <span class="comment">// ...</span> + + <span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">getstate_manages_dict</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span> +<span class="special">};</span> +</pre> +<p> + Alternatively in Python: + </p> +<pre class="programlisting"><span class="identifier">import</span> <span class="identifier">your_bpl_module</span> +<span class="keyword">class</span> <span class="identifier">your_class</span><span class="special">(</span><span class="identifier">your_bpl_module</span><span class="special">.</span><span class="identifier">your_class</span><span class="special">):</span> + <span class="identifier">__getstate_manages_dict__</span> <span class="special">=</span> <span class="number">1</span> + <span class="identifier">def</span> <span class="identifier">__getstate__</span><span class="special">(</span><span class="identifier">self</span><span class="special">):</span> + <span class="preprocessor"># your</span> <span class="identifier">code</span> <span class="identifier">here</span> + <span class="identifier">def</span> <span class="identifier">__setstate__</span><span class="special">(</span><span class="identifier">self</span><span class="special">,</span> <span class="identifier">state</span><span class="special">):</span> + <span class="preprocessor"># your</span> <span class="identifier">code</span> <span class="identifier">here</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.pickle_support.practical_advice"></a><a class="link" href="pickle_support.html#topics.pickle_support.practical_advice" title="Practical Advice">Practical Advice</a> +</h3></div></div></div> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + In <code class="computeroutput"><span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span></code> extension modules with many + extension classes, providing complete pickle support for all classes + would be a significant overhead. In general complete pickle support + should only be implemented for extension classes that will eventually + be pickled. + </li> +<li class="listitem"> + Avoid using <code class="computeroutput"><span class="identifier">__getstate__</span></code> + if the instance can also be reconstructed by way of <code class="computeroutput"><span class="identifier">__getinitargs__</span></code>. + This automatically avoids the pitfall described above. + </li> +<li class="listitem"> + If <code class="computeroutput"><span class="identifier">__getstate__</span></code> is + required, include the instance's <code class="computeroutput"><span class="identifier">__dict__</span></code> + in the Python object that is returned. + </li> +</ul></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="topics.pickle_support.light_weight_alternative_pickle_"></a><a class="link" href="pickle_support.html#topics.pickle_support.light_weight_alternative_pickle_" title="Light-weight alternative: pickle support implemented in Python">Light-weight + alternative: pickle support implemented in Python</a> +</h3></div></div></div> +<p> + The pickle4.cpp example demonstrates an alternative technique for implementing + pickle support. First we direct Boost.Python via the class_::enable_pickling() + member function to define only the basic attributes required for pickling: + </p> +<pre class="programlisting"><span class="identifier">class_</span><span class="special"><</span><span class="identifier">world</span><span class="special">>(</span><span class="string">"world"</span><span class="special">,</span> <span class="identifier">args</span><span class="special"><</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&>())</span> + <span class="comment">// ...</span> + <span class="special">.</span><span class="identifier">enable_pickling</span><span class="special">()</span> + <span class="comment">// ...</span> +</pre> +<p> + This enables the standard Python pickle interface as described in the Python + documentation. By "injecting" a <code class="computeroutput"><span class="identifier">__getinitargs__</span></code> + method into the definition of the wrapped class we make all instances pickleable: + </p> +<pre class="programlisting"><span class="preprocessor"># import</span> <span class="identifier">the</span> <span class="identifier">wrapped</span> <span class="identifier">world</span> <span class="keyword">class</span> +<span class="identifier">from</span> <span class="identifier">pickle4_ext</span> <span class="identifier">import</span> <span class="identifier">world</span> + +<span class="preprocessor"># definition</span> <span class="identifier">of</span> <span class="identifier">__getinitargs__</span> +<span class="identifier">def</span> <span class="identifier">world_getinitargs</span><span class="special">(</span><span class="identifier">self</span><span class="special">):</span> + <span class="keyword">return</span> <span class="special">(</span><span class="identifier">self</span><span class="special">.</span><span class="identifier">get_country</span><span class="special">(),)</span> + +<span class="preprocessor"># now</span> <span class="identifier">inject</span> <span class="identifier">__getinitargs__</span> <span class="special">(</span><span class="identifier">Python</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">dynamic</span> <span class="identifier">language</span><span class="special">!)</span> +<span class="identifier">world</span><span class="special">.</span><span class="identifier">__getinitargs__</span> <span class="special">=</span> <span class="identifier">world_getinitargs</span> +</pre> +<p> + See also the tutorial section on injecting additional methods from Python. + </p> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../topics.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../topics.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="indexing_support.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/utility_and_infrastructure.html b/libs/python/doc/html/reference/utility_and_infrastructure.html new file mode 100644 index 0000000000..c401f19d97 --- /dev/null +++ b/libs/python/doc/html/reference/utility_and_infrastructure.html @@ -0,0 +1,240 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 7. Utility and Infrastructure</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="index.html" title="Boost.Python Reference Manual"> +<link rel="prev" href="embedding/boost_python_import_hpp.html" title="boost/python/import.hpp"> +<link rel="next" href="utility_and_infrastructure/boost_python_instance_holder_hpp.html" title="boost/python/instance_holder.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="embedding/boost_python_import_hpp.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="utility_and_infrastructure/boost_python_instance_holder_hpp.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="utility_and_infrastructure"></a>Chapter 7. Utility and Infrastructure</h1></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_">boost/python/has_back_reference.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_.class_template_has_back_referenc">Class + template <code class="computeroutput"><span class="identifier">has_back_reference</span></code></a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_.examples">Examples</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_instance_holder_hpp.html">boost/python/instance_holder.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder">Class + template <code class="computeroutput"><span class="identifier">instance_holder</span></code></a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.examples">Examples</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_pointee_hpp.html">boost/python/pointee.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_pointee_hpp.html#utility_and_infrastructure.boost_python_pointee_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_pointee_hpp.html#utility_and_infrastructure.boost_python_pointee_hpp.class_template_pointee">Class + template <code class="computeroutput"><span class="identifier">pointee</span></code></a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_pointee_hpp.html#utility_and_infrastructure.boost_python_pointee_hpp.examples">Examples</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_handle_hpp.html">boost/python/handle.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.class_template_handle">Class + template <code class="computeroutput"><span class="identifier">handle</span></code></a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.function_borrowed">Function + <code class="computeroutput"><span class="identifier">borrowed</span></code></a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.function_allow_null">Function + <code class="computeroutput"><span class="identifier">allow_null</span></code></a></span></dt> +</dl></dd> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_type_id_hpp.html">boost/python/type_id.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info">Class + template <code class="computeroutput"><span class="identifier">type_info</span></code></a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.example">Example</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_ssize_t_hpp.html">boost/python/ssize_t.hpp</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_ssize_t_hpp.html#utility_and_infrastructure.boost_python_ssize_t_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_ssize_t_hpp.html#utility_and_infrastructure.boost_python_ssize_t_hpp.typedefs">Typedefs</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure/boost_python_ssize_t_hpp.html#utility_and_infrastructure.boost_python_ssize_t_hpp.constants">Constants</a></span></dt> +</dl></dd> +</dl> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="utility_and_infrastructure.boost_python_has_back_reference_"></a><a class="link" href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_" title="boost/python/has_back_reference.hpp">boost/python/has_back_reference.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_.class_template_has_back_referenc">Class + template <code class="computeroutput"><span class="identifier">has_back_reference</span></code></a></span></dt> +<dt><span class="section"><a href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_.examples">Examples</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_has_back_reference_.introduction"></a><a class="link" href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/has_back_reference.hpp> defines the predicate metafunction + <code class="computeroutput"><span class="identifier">has_back_reference</span><span class="special"><></span></code>, + which can be specialized by the user to indicate that a wrapped class instance + holds a <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code> + corresponding to a Python object. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_has_back_reference_.class_template_has_back_referenc"></a><a class="link" href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_.class_template_has_back_referenc" title="Class template has_back_reference">Class + template <code class="computeroutput"><span class="identifier">has_back_reference</span></code></a> +</h3></div></div></div> +<p> + A unary metafunction whose value is true iff its argument is a <code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special"><></span></code>. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">WrappedClass</span><span class="special">></span> <span class="keyword">class</span> <span class="identifier">has_back_reference</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">false_</span> <span class="identifier">type</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +<p> + A metafunction that is inspected by Boost.Python to determine how wrapped + classes can be constructed. + </p> +<p> + <code class="computeroutput"><span class="identifier">type</span><span class="special">::</span><span class="identifier">value</span></code> is an integral constant convertible + to bool of unspecified type. Specializations may substitute a true-valued + integral constant wrapper for type iff for each invocation of <code class="computeroutput"><span class="identifier">class_</span><span class="special"><</span><span class="identifier">WrappedClass</span><span class="special">>::</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">init</span><span class="special"><</span> <span class="identifier">type</span><span class="special">-</span><span class="identifier">sequence</span><span class="special">...>())</span></code> + and the implicitly wrapped copy constructor (unless it is noncopyable), + there exists a corresponding constructor <code class="computeroutput"><span class="identifier">WrappedClass</span><span class="special">::</span><span class="identifier">WrappedClass</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*,</span> <span class="identifier">type</span><span class="special">-</span><span class="identifier">sequence</span><span class="special">...)</span></code>. If such a specialization exists, the + WrappedClass constructors will be called with a "back reference" + pointer to the corresponding Python object whenever they are invoked from + Python. The easiest way to provide this nested type is to derive the specialization + from <code class="computeroutput"><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">true_</span></code>. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_has_back_reference_.examples"></a><a class="link" href="utility_and_infrastructure.html#utility_and_infrastructure.boost_python_has_back_reference_.examples" title="Examples">Examples</a> +</h3></div></div></div> +<p> + In C++: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">has_back_reference</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">handle</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">shared_ptr</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> +<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">;</span> + +<span class="keyword">struct</span> <span class="identifier">X</span> +<span class="special">{</span> + <span class="identifier">X</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">self</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">m_self</span><span class="special">(</span><span class="identifier">self</span><span class="special">),</span> <span class="identifier">m_x</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">{}</span> + <span class="identifier">X</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">self</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">m_self</span><span class="special">(</span><span class="identifier">self</span><span class="special">),</span> <span class="identifier">m_x</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span> + <span class="identifier">X</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">self</span><span class="special">,</span> <span class="identifier">X</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">other</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">m_self</span><span class="special">(</span><span class="identifier">self</span><span class="special">),</span> <span class="identifier">m_x</span><span class="special">(</span><span class="identifier">other</span><span class="special">.</span><span class="identifier">m_x</span><span class="special">)</span> <span class="special">{}</span> + + <span class="identifier">handle</span><span class="special"><></span> <span class="identifier">self</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">handle</span><span class="special"><>(</span><span class="identifier">borrowed</span><span class="special">(</span><span class="identifier">m_self</span><span class="special">));</span> <span class="special">}</span> + <span class="keyword">int</span> <span class="identifier">get</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">m_x</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">void</span> <span class="identifier">set</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">m_x</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> + + <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">m_self</span><span class="special">;</span> + <span class="keyword">int</span> <span class="identifier">m_x</span><span class="special">;</span> +<span class="special">};</span> + +<span class="comment">// specialize has_back_reference for X</span> +<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><></span> + <span class="keyword">struct</span> <span class="identifier">has_back_reference</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span> + <span class="special">:</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">true_</span> + <span class="special">{};</span> +<span class="special">}}</span> + +<span class="keyword">struct</span> <span class="identifier">Y</span> +<span class="special">{</span> + <span class="identifier">Y</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">m_x</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">{}</span> + <span class="identifier">Y</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">m_x</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span> + <span class="keyword">int</span> <span class="identifier">get</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">m_x</span><span class="special">;</span> <span class="special">}</span> + <span class="keyword">void</span> <span class="identifier">set</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">m_x</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span> + + <span class="keyword">int</span> <span class="identifier">m_x</span><span class="special">;</span> +<span class="special">};</span> + +<span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">Y</span><span class="special">></span> +<span class="identifier">Y_self</span><span class="special">(</span><span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">Y</span><span class="special">></span> <span class="identifier">self</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">self</span><span class="special">;</span> <span class="special">}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">back_references</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">X</span><span class="special">>(</span><span class="string">"X"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">>())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"self"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">self</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">get</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"set"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">set</span><span class="special">)</span> + <span class="special">;</span> + + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">Y</span><span class="special">,</span> <span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">Y</span><span class="special">></span> <span class="special">>(</span><span class="string">"Y"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="identifier">init</span><span class="special"><</span><span class="keyword">int</span><span class="special">>())</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Y</span><span class="special">::</span><span class="identifier">get</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"set"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">Y</span><span class="special">::</span><span class="identifier">set</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"self"</span><span class="special">,</span> <span class="identifier">Y_self</span><span class="special">)</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + The following Python session illustrates that x.self() returns the same + Python object on which it is invoked, while y.self() must create a new + Python object which refers to the same Y instance. + </p> +<p> + In Python: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">back_references</span> <span class="identifier">import</span> <span class="special">*</span> +<span class="special">>>></span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">X</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> +<span class="special">>>></span> <span class="identifier">x2</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">self</span><span class="special">()</span> +<span class="special">>>></span> <span class="identifier">x2</span> <span class="identifier">is</span> <span class="identifier">x</span> +<span class="number">1</span> +<span class="special">>>></span> <span class="special">(</span><span class="identifier">x</span><span class="special">.</span><span class="identifier">get</span><span class="special">(),</span> <span class="identifier">x2</span><span class="special">.</span><span class="identifier">get</span><span class="special">())</span> +<span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> +<span class="special">>>></span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">set</span><span class="special">(</span><span class="number">10</span><span class="special">)</span> +<span class="special">>>></span> <span class="special">(</span><span class="identifier">x</span><span class="special">.</span><span class="identifier">get</span><span class="special">(),</span> <span class="identifier">x2</span><span class="special">.</span><span class="identifier">get</span><span class="special">())</span> +<span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">10</span><span class="special">)</span> +<span class="special">>>></span> +<span class="special">>>></span> +<span class="special">>>></span> <span class="identifier">y</span> <span class="special">=</span> <span class="identifier">Y</span><span class="special">(</span><span class="number">2</span><span class="special">)</span> +<span class="special">>>></span> <span class="identifier">y2</span> <span class="special">=</span> <span class="identifier">y</span><span class="special">.</span><span class="identifier">self</span><span class="special">()</span> +<span class="special">>>></span> <span class="identifier">y2</span> <span class="identifier">is</span> <span class="identifier">y</span> +<span class="number">0</span> +<span class="special">>>></span> <span class="special">(</span><span class="identifier">y</span><span class="special">.</span><span class="identifier">get</span><span class="special">(),</span> <span class="identifier">y2</span><span class="special">.</span><span class="identifier">get</span><span class="special">())</span> +<span class="special">(</span><span class="number">2</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span> +<span class="special">>>></span> <span class="identifier">y</span><span class="special">.</span><span class="identifier">set</span><span class="special">(</span><span class="number">20</span><span class="special">)</span> +<span class="special">>>></span> <span class="special">(</span><span class="identifier">y</span><span class="special">.</span><span class="identifier">get</span><span class="special">(),</span> <span class="identifier">y2</span><span class="special">.</span><span class="identifier">get</span><span class="special">())</span> +<span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">20</span><span class="special">)</span> +</pre> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="embedding/boost_python_import_hpp.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="utility_and_infrastructure/boost_python_instance_holder_hpp.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_handle_hpp.html b/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_handle_hpp.html new file mode 100644 index 0000000000..f70392dca5 --- /dev/null +++ b/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_handle_hpp.html @@ -0,0 +1,363 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/handle.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../utility_and_infrastructure.html" title="Chapter 7. Utility and Infrastructure"> +<link rel="prev" href="boost_python_pointee_hpp.html" title="boost/python/pointee.hpp"> +<link rel="next" href="boost_python_type_id_hpp.html" title="boost/python/type_id.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_pointee_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../utility_and_infrastructure.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_type_id_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="utility_and_infrastructure.boost_python_handle_hpp"></a><a class="link" href="boost_python_handle_hpp.html" title="boost/python/handle.hpp">boost/python/handle.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.class_template_handle">Class + template <code class="computeroutput"><span class="identifier">handle</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.function_borrowed">Function + <code class="computeroutput"><span class="identifier">borrowed</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.function_allow_null">Function + <code class="computeroutput"><span class="identifier">allow_null</span></code></a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_handle_hpp.introduction"></a><a class="link" href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/handle.hpp> provides class template <code class="computeroutput"><span class="identifier">handle</span></code>, + a smart pointer for managing reference-counted Python objects. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_handle_hpp.class_template_handle"></a><a class="link" href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.class_template_handle" title="Class template handle">Class + template <code class="computeroutput"><span class="identifier">handle</span></code></a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.class_template_handle.class_template_handle_constructo">Class + template <code class="computeroutput"><span class="identifier">handle</span></code> constructors + and destructor</a></span></dt> +<dt><span class="section"><a href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.class_template_handle.class_template_handle_modifiers">Class + template <code class="computeroutput"><span class="identifier">handle</span></code> modifiers</a></span></dt> +<dt><span class="section"><a href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.class_template_handle.class_template_handle_observers">Class + template <code class="computeroutput"><span class="identifier">handle</span></code> observers</a></span></dt> +</dl></div> +<p> + <code class="computeroutput"><span class="identifier">handle</span></code> is a smart pointer + to a Python object type; it holds a pointer of type <code class="computeroutput"><span class="identifier">T</span><span class="special">*</span></code>, where <code class="computeroutput"><span class="identifier">T</span></code> + is its template parameter. T must be either a type derived from <code class="computeroutput"><span class="identifier">PyObject</span></code> or a <a class="link" href="../glossary.html#pod">POD</a> + type whose initial <code class="computeroutput"><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">)</span></code> bytes are layout-compatible with <code class="computeroutput"><span class="identifier">PyObject</span></code>. Use <code class="computeroutput"><span class="identifier">handle</span><span class="special"><></span></code> at the boundary between the Python/'C' + API and high-level code; prefer object for a generalized interface to Python + objects. + </p> +<p> + In this document, the term "upcast" refers to an operation which + converts a pointer <code class="computeroutput"><span class="identifier">Y</span><span class="special">*</span></code> + to a base class <code class="computeroutput"><span class="identifier">pointer</span> <span class="identifier">T</span><span class="special">*</span></code> via + <code class="computeroutput"><span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">T</span><span class="special">*></span></code> + if <code class="computeroutput"><span class="identifier">Y</span></code> is derived from <code class="computeroutput"><span class="identifier">T</span></code>, or via C-style cast (<code class="computeroutput"><span class="identifier">T</span><span class="special">*</span></code>) if + it is not. However, in the latter case the "upcast" is ill-formed + if the initial <code class="computeroutput"><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">)</span></code> + bytes of <code class="computeroutput"><span class="identifier">Y</span></code> are not layout-compatible + with <code class="computeroutput"><span class="identifier">PyObject</span></code>. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> + <span class="keyword">class</span> <span class="identifier">handle</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">unspecified</span><span class="special">-</span><span class="identifier">member</span><span class="special">-</span><span class="identifier">function</span><span class="special">-</span><span class="identifier">pointer</span> <span class="identifier">bool_type</span><span class="special">;</span> + + <span class="keyword">public</span><span class="special">:</span> <span class="comment">// types</span> + <span class="keyword">typedef</span> <span class="identifier">T</span> <span class="identifier">element_type</span><span class="special">;</span> + + <span class="keyword">public</span><span class="special">:</span> <span class="comment">// member functions</span> + <span class="special">~</span><span class="identifier">handle</span><span class="special">();</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">></span> + <span class="keyword">explicit</span> <span class="identifier">handle</span><span class="special">(</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">borrowed</span><span class="special"><</span><span class="identifier">null_ok</span><span class="special"><</span><span class="identifier">Y</span><span class="special">></span> <span class="special">>*</span> <span class="identifier">p</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">></span> + <span class="keyword">explicit</span> <span class="identifier">handle</span><span class="special">(</span><span class="identifier">null_ok</span><span class="special"><</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">borrowed</span><span class="special"><</span><span class="identifier">Y</span><span class="special">></span> <span class="special">>*</span> <span class="identifier">p</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">></span> + <span class="keyword">explicit</span> <span class="identifier">handle</span><span class="special">(</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">borrowed</span><span class="special"><</span><span class="identifier">Y</span><span class="special">>*</span> <span class="identifier">p</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">></span> + <span class="keyword">explicit</span> <span class="identifier">handle</span><span class="special">(</span><span class="identifier">null_ok</span><span class="special"><</span><span class="identifier">Y</span><span class="special">>*</span> <span class="identifier">p</span><span class="special">);</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">></span> + <span class="keyword">explicit</span> <span class="identifier">handle</span><span class="special">(</span><span class="identifier">Y</span><span class="special">*</span> <span class="identifier">p</span><span class="special">);</span> + + <span class="identifier">handle</span><span class="special">();</span> + + <span class="identifier">handle</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span><span class="identifier">handle</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">r</span><span class="special">);</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Y</span><span class="special">></span> + <span class="identifier">handle</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span><span class="identifier">handle</span><span class="special"><</span><span class="identifier">Y</span><span class="special">></span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">r</span><span class="special">);</span> <span class="comment">// never throws</span> + + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Y</span><span class="special">></span> + <span class="identifier">handle</span><span class="special">(</span><span class="identifier">handle</span><span class="special"><</span><span class="identifier">Y</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">r</span><span class="special">);</span> + + <span class="identifier">handle</span><span class="special">(</span><span class="identifier">handle</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">r</span><span class="special">);</span> + + <span class="identifier">T</span><span class="special">*</span> <span class="keyword">operator</span><span class="special">-></span> <span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">T</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">*</span> <span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="identifier">T</span><span class="special">*</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">void</span> <span class="identifier">reset</span><span class="special">();</span> + <span class="identifier">T</span><span class="special">*</span> <span class="identifier">release</span><span class="special">();</span> + + <span class="keyword">operator</span> <span class="identifier">bool_type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> <span class="comment">// never throws</span> + <span class="keyword">private</span><span class="special">:</span> + <span class="identifier">T</span><span class="special">*</span> <span class="identifier">m_p</span><span class="special">;</span> + <span class="special">};</span> + + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">null_ok</span><span class="special">;</span> + <span class="keyword">namespace</span> <span class="identifier">detail</span> <span class="special">{</span> <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">borrowed</span><span class="special">;</span> <span class="special">}</span> +<span class="special">}}</span> +</pre> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="utility_and_infrastructure.boost_python_handle_hpp.class_template_handle.class_template_handle_constructo"></a><a class="link" href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.class_template_handle.class_template_handle_constructo" title="Class template handle constructors and destructor">Class + template <code class="computeroutput"><span class="identifier">handle</span></code> constructors + and destructor</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">handle</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">Py_XDECREF</span><span class="special">(</span><span class="identifier">upcast</span><span class="special"><</span><span class="identifier">PyObject</span><span class="special">*>(</span><span class="identifier">m_p</span><span class="special">))</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">></span> +<span class="keyword">explicit</span> <span class="identifier">handle</span><span class="special">(</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">borrowed</span><span class="special"><</span><span class="identifier">null_ok</span><span class="special"><</span><span class="identifier">Y</span><span class="special">></span> <span class="special">>*</span> <span class="identifier">p</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><pre class="programlisting"><span class="identifier">Py_XINCREF</span><span class="special">(</span><span class="identifier">upcast</span><span class="special"><</span><span class="identifier">PyObject</span><span class="special">*>(</span><span class="identifier">p</span><span class="special">));</span> +<span class="identifier">m_p</span> <span class="special">=</span> <span class="identifier">upcast</span><span class="special"><</span><span class="identifier">T</span><span class="special">*>(</span><span class="identifier">p</span><span class="special">);</span> +</pre></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">></span> +<span class="keyword">explicit</span> <span class="identifier">handle</span><span class="special">(</span><span class="identifier">null_ok</span><span class="special"><</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">borrowed</span><span class="special"><</span><span class="identifier">Y</span><span class="special">></span> <span class="special">>*</span> <span class="identifier">p</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><pre class="programlisting"><span class="identifier">Py_XINCREF</span><span class="special">(</span><span class="identifier">upcast</span><span class="special"><</span><span class="identifier">PyObject</span><span class="special">*>(</span><span class="identifier">p</span><span class="special">));</span> + <span class="identifier">m_p</span> <span class="special">=</span> <span class="identifier">upcast</span><span class="special"><</span><span class="identifier">T</span><span class="special">*>(</span><span class="identifier">p</span><span class="special">);</span> +</pre></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">></span> +<span class="keyword">explicit</span> <span class="identifier">handle</span><span class="special">(</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">borrowed</span><span class="special"><</span><span class="identifier">Y</span><span class="special">>*</span> <span class="identifier">p</span><span class="special">);</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><pre class="programlisting"><span class="identifier">Py_XINCREF</span><span class="special">(</span><span class="identifier">upcast</span><span class="special"><</span><span class="identifier">PyObject</span><span class="special">*>(</span><span class="identifier">p</span><span class="special">));</span> + <span class="identifier">m_p</span> <span class="special">=</span> <span class="identifier">upcast</span><span class="special"><</span><span class="identifier">T</span><span class="special">*>(</span><span class="identifier">expect_non_null</span><span class="special">(</span><span class="identifier">p</span><span class="special">));</span> +</pre></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">></span> +<span class="keyword">explicit</span> <span class="identifier">handle</span><span class="special">(</span><span class="identifier">null_ok</span><span class="special"><</span><span class="identifier">Y</span><span class="special">>*</span> <span class="identifier">p</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">m_p</span> <span class="special">=</span> + <span class="identifier">upcast</span><span class="special"><</span><span class="identifier">T</span><span class="special">*>(</span><span class="identifier">p</span><span class="special">);</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">></span> +<span class="keyword">explicit</span> <span class="identifier">handle</span><span class="special">(</span><span class="identifier">Y</span><span class="special">*</span> <span class="identifier">p</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">m_p</span> <span class="special">=</span> + <span class="identifier">upcast</span><span class="special"><</span><span class="identifier">T</span><span class="special">*>(</span><span class="identifier">expect_non_null</span><span class="special">(</span><span class="identifier">p</span><span class="special">));</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">handle</span><span class="special">();</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">m_p</span> <span class="special">=</span> + <span class="number">0</span><span class="special">;</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Y</span><span class="special">></span> +<span class="identifier">handle</span><span class="special">(</span><span class="identifier">handle</span><span class="special"><</span><span class="identifier">Y</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">r</span><span class="special">);</span> +<span class="identifier">handle</span><span class="special">(</span><span class="identifier">handle</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">r</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + m_p = r.m_p; Py_XINCREF(upcast<PyObject*>(m_p)); + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="utility_and_infrastructure.boost_python_handle_hpp.class_template_handle.class_template_handle_modifiers"></a><a class="link" href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.class_template_handle.class_template_handle_modifiers" title="Class template handle modifiers">Class + template <code class="computeroutput"><span class="identifier">handle</span></code> modifiers</a> +</h4></div></div></div> +<pre class="programlisting"><span class="identifier">handle</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span><span class="identifier">handle</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">r</span><span class="special">);</span> +<span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Y</span><span class="special">></span> +<span class="identifier">handle</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span><span class="identifier">handle</span><span class="special"><</span><span class="identifier">Y</span><span class="special">></span> <span class="keyword">const</span> <span class="special">&</span> <span class="identifier">r</span><span class="special">);</span> <span class="comment">// never throws</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">Py_XINCREF</span><span class="special">(</span><span class="identifier">upcast</span><span class="special"><</span><span class="identifier">PyObject</span><span class="special">*>(</span><span class="identifier">r</span><span class="special">.</span><span class="identifier">m_p</span><span class="special">));</span> + <span class="identifier">Py_XDECREF</span><span class="special">(</span> + <span class="identifier">upcast</span><span class="special"><</span><span class="identifier">PyObject</span><span class="special">*>(</span><span class="identifier">m_p</span><span class="special">));</span> + <span class="identifier">m_p</span> <span class="special">=</span> + <span class="identifier">r</span><span class="special">.</span><span class="identifier">m_p</span><span class="special">;</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">T</span><span class="special">*</span> <span class="identifier">release</span><span class="special">();</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">T</span><span class="special">*</span> + <span class="identifier">x</span> <span class="special">=</span> + <span class="identifier">m_p</span><span class="special">;</span> + <span class="identifier">m_p</span> <span class="special">=</span> + <span class="number">0</span><span class="special">;</span> + <span class="keyword">return</span> <span class="identifier">x</span><span class="special">;</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">reset</span><span class="special">();</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span> + <span class="special">=</span> <span class="identifier">handle</span><span class="special"><</span><span class="identifier">T</span><span class="special">>();</span></code> + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="utility_and_infrastructure.boost_python_handle_hpp.class_template_handle.class_template_handle_observers"></a><a class="link" href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.class_template_handle.class_template_handle_observers" title="Class template handle observers">Class + template <code class="computeroutput"><span class="identifier">handle</span></code> observers</a> +</h4></div></div></div> +<pre class="programlisting"><span class="identifier">T</span><span class="special">*</span> <span class="keyword">operator</span><span class="special">-></span> <span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +<span class="identifier">T</span><span class="special">*</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">m_p</span><span class="special">;</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="identifier">T</span><span class="special">&</span> <span class="keyword">operator</span><span class="special">*</span> <span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="special">*</span><span class="identifier">m_p</span><span class="special">;</span></code> + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">operator</span> <span class="identifier">bool_type</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> <span class="comment">// never throws</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="number">0</span></code> if <code class="computeroutput"><span class="identifier">m_p</span> <span class="special">==</span> + <span class="number">0</span></code>, a pointer convertible + to true otherwise. + </p></dd> +</dl> +</div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_handle_hpp.function_borrowed"></a><a class="link" href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.function_borrowed" title="Function borrowed">Function + <code class="computeroutput"><span class="identifier">borrowed</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> +<span class="identifier">detail</span><span class="special">::</span><span class="identifier">borrowed</span><span class="special"><</span><span class="identifier">T</span><span class="special">>*</span> <span class="identifier">borrowed</span><span class="special">(</span><span class="identifier">T</span><span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="special">(</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">borrowed</span><span class="special"><</span><span class="identifier">T</span><span class="special">>*)</span><span class="identifier">p</span><span class="special">;</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_handle_hpp.function_allow_null"></a><a class="link" href="boost_python_handle_hpp.html#utility_and_infrastructure.boost_python_handle_hpp.function_allow_null" title="Function allow_null">Function + <code class="computeroutput"><span class="identifier">allow_null</span></code></a> +</h3></div></div></div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> +<span class="identifier">null_ok</span><span class="special"><</span><span class="identifier">T</span><span class="special">>*</span> <span class="identifier">allow_null</span><span class="special">(</span><span class="identifier">T</span><span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="special">(</span><span class="identifier">null_ok</span><span class="special"><</span><span class="identifier">T</span><span class="special">>*)</span><span class="identifier">p</span><span class="special">;</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_pointee_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../utility_and_infrastructure.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_type_id_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_instance_holder_hpp.html b/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_instance_holder_hpp.html new file mode 100644 index 0000000000..07cb1f84ec --- /dev/null +++ b/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_instance_holder_hpp.html @@ -0,0 +1,212 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/instance_holder.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../utility_and_infrastructure.html" title="Chapter 7. Utility and Infrastructure"> +<link rel="prev" href="../utility_and_infrastructure.html" title="Chapter 7. Utility and Infrastructure"> +<link rel="next" href="boost_python_pointee_hpp.html" title="boost/python/pointee.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../utility_and_infrastructure.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../utility_and_infrastructure.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_pointee_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="utility_and_infrastructure.boost_python_instance_holder_hpp"></a><a class="link" href="boost_python_instance_holder_hpp.html" title="boost/python/instance_holder.hpp">boost/python/instance_holder.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder">Class + template <code class="computeroutput"><span class="identifier">instance_holder</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.examples">Examples</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_instance_holder_hpp.introduction"></a><a class="link" href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/instance_holder.hpp> provides class <code class="computeroutput"><span class="identifier">instance_holder</span></code>, + the base class for types which hold C++ instances of wrapped classes. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder"></a><a class="link" href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder" title="Class template instance_holder">Class + template <code class="computeroutput"><span class="identifier">instance_holder</span></code></a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_destructor">Class + <code class="computeroutput"><span class="identifier">intance_holder</span></code> destructor</a></span></dt> +<dt><span class="section"><a href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_modifiers">Class + <code class="computeroutput"><span class="identifier">intance_holder</span></code> modifiers</a></span></dt> +<dt><span class="section"><a href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_observers">Class + <code class="computeroutput"><span class="identifier">intance_holder</span></code> observers</a></span></dt> +</dl></div> +<p> + <code class="computeroutput"><span class="identifier">instance_holder</span></code> is an abstract + base class whose concrete derived classes hold C++ class instances within + their Python object wrappers. To allow multiple inheritance in Python from + C++ class wrappers, each such Python object contains a chain of instance_holders. + When an <code class="computeroutput"><span class="identifier">__init__</span></code> function + for a wrapped C++ class is invoked, a new <code class="computeroutput"><span class="identifier">instance_holder</span></code> + instance is created and installed in the Python object using its <code class="computeroutput"><span class="identifier">install</span><span class="special">()</span></code> + function. Each concrete class derived from <code class="computeroutput"><span class="identifier">instance_holder</span></code> + must provide a <code class="computeroutput"><span class="identifier">holds</span><span class="special">()</span></code> + implementation which allows Boost.Python to query it for the type(s) it + is holding. In order to support the held type's wrapped constructor(s), + the class must also provide constructors that can accept an initial <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code> + argument referring to the owning Python object, and which forward the rest + of their arguments to the constructor of the held type. The initial argument + is needed to enable virtual function overriding in Python, and may be ignored, + depending on the specific <code class="computeroutput"><span class="identifier">instance_holder</span></code> + subclass. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">instance_holder</span> <span class="special">:</span> <span class="identifier">noncopyable</span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="comment">// destructor</span> + <span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">instance_holder</span><span class="special">();</span> + + <span class="comment">// instance_holder modifiers</span> + <span class="keyword">void</span> <span class="identifier">install</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">inst</span><span class="special">)</span> <span class="keyword">throw</span><span class="special">();</span> + + <span class="comment">// instance_holder observers</span> + <span class="keyword">virtual</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">holds</span><span class="special">(</span><span class="identifier">type_info</span><span class="special">)</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_destructor"></a><a class="link" href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_destructor" title="Class intance_holder destructor">Class + <code class="computeroutput"><span class="identifier">intance_holder</span></code> destructor</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">instance_holder</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + destroys the object + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_modifiers"></a><a class="link" href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_modifiers" title="Class intance_holder modifiers">Class + <code class="computeroutput"><span class="identifier">intance_holder</span></code> modifiers</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">install</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">inst</span><span class="special">)</span> <span class="keyword">throw</span><span class="special">();</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Requires</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">inst</span></code> is a Python + instance of a wrapped C++ class type, or is a type derived from + a wrapped C++ class type. + </p></dd> +<dt><span class="term">Effects</span></dt> +<dd><p> + installs the new instance at the head of the Python object's chain + of held instances. + </p></dd> +<dt><span class="term">Throws</span></dt> +<dd><p> + nothing + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_observers"></a><a class="link" href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_observers" title="Class intance_holder observers">Class + <code class="computeroutput"><span class="identifier">intance_holder</span></code> observers</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">virtual</span> <span class="keyword">void</span> <span class="special">*</span><span class="identifier">holds</span><span class="special">(</span><span class="identifier">type_info</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + A pointer to an object of the type described by <code class="computeroutput"><span class="identifier">x</span></code> + if <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> + contains such an object, 0 otherwise. + </p></dd> +</dl> +</div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_instance_holder_hpp.examples"></a><a class="link" href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.examples" title="Examples">Examples</a> +</h3></div></div></div> +<p> + The following is a simplified version of the instance holder template used + by Boost.Python to wrap classes held by smart pointers: + </p> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">SmartPtr</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Value</span><span class="special">></span> +<span class="keyword">struct</span> <span class="identifier">pointer_holder</span> <span class="special">:</span> <span class="identifier">instance_holder</span> +<span class="special">{</span> + <span class="comment">// construct from the SmartPtr type</span> + <span class="identifier">pointer_holder</span><span class="special">(</span><span class="identifier">SmartPtr</span> <span class="identifier">p</span><span class="special">)</span> + <span class="special">:</span><span class="identifier">m_p</span><span class="special">(</span><span class="identifier">p</span><span class="special">)</span> + + <span class="comment">// Forwarding constructors for the held type</span> + <span class="identifier">pointer_holder</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*)</span> + <span class="special">:</span><span class="identifier">m_p</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">Value</span><span class="special">())</span> + <span class="special">{</span> + <span class="special">}</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">></span> + <span class="identifier">pointer_holder</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*,</span><span class="identifier">A0</span> <span class="identifier">a0</span><span class="special">)</span> + <span class="special">:</span><span class="identifier">m_p</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">Value</span><span class="special">(</span><span class="identifier">a0</span><span class="special">))</span> + <span class="special">{</span> + <span class="special">}</span> + + <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> + <span class="identifier">pointer_holder</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*,</span><span class="identifier">A0</span> <span class="identifier">a0</span><span class="special">,</span><span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> + <span class="special">:</span><span class="identifier">m_p</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">Value</span><span class="special">(</span><span class="identifier">a0</span><span class="special">,</span><span class="identifier">a1</span><span class="special">))</span> + <span class="special">{</span> + <span class="special">}</span> + <span class="special">...</span> + + <span class="keyword">private</span><span class="special">:</span> <span class="comment">// required holder implementation</span> + <span class="keyword">void</span><span class="special">*</span> <span class="identifier">holds</span><span class="special">(</span><span class="identifier">type_info</span> <span class="identifier">dst_t</span><span class="special">)</span> + <span class="special">{</span> + <span class="comment">// holds an instance of the SmartPtr type...</span> + <span class="keyword">if</span> <span class="special">(</span><span class="identifier">dst_t</span> <span class="special">==</span> <span class="identifier">python</span><span class="special">::</span><span class="identifier">type_id</span><span class="special"><</span><span class="identifier">SmartPtr</span><span class="special">>())</span> + <span class="keyword">return</span> <span class="special">&</span><span class="keyword">this</span><span class="special">-></span><span class="identifier">m_p</span><span class="special">;</span> + + <span class="comment">// ...and an instance of the SmartPtr's element_type, if the</span> + <span class="comment">// pointer is non-null</span> + <span class="keyword">return</span> <span class="identifier">python</span><span class="special">::</span><span class="identifier">type_id</span><span class="special"><</span><span class="identifier">Value</span><span class="special">>()</span> <span class="special">==</span> <span class="identifier">dst_t</span> <span class="special">?</span> <span class="special">&*</span><span class="keyword">this</span><span class="special">-></span><span class="identifier">m_p</span> <span class="special">:</span> <span class="number">0</span><span class="special">;</span> + <span class="special">}</span> + + <span class="keyword">private</span><span class="special">:</span> <span class="comment">// data members</span> + <span class="identifier">SmartPtr</span> <span class="identifier">m_p</span><span class="special">;</span> +<span class="special">};</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="../utility_and_infrastructure.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../utility_and_infrastructure.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_pointee_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_pointee_hpp.html b/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_pointee_hpp.html new file mode 100644 index 0000000000..879afc382b --- /dev/null +++ b/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_pointee_hpp.html @@ -0,0 +1,106 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/pointee.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../utility_and_infrastructure.html" title="Chapter 7. Utility and Infrastructure"> +<link rel="prev" href="boost_python_instance_holder_hpp.html" title="boost/python/instance_holder.hpp"> +<link rel="next" href="boost_python_handle_hpp.html" title="boost/python/handle.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_instance_holder_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../utility_and_infrastructure.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_handle_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="utility_and_infrastructure.boost_python_pointee_hpp"></a><a class="link" href="boost_python_pointee_hpp.html" title="boost/python/pointee.hpp">boost/python/pointee.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_pointee_hpp.html#utility_and_infrastructure.boost_python_pointee_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_pointee_hpp.html#utility_and_infrastructure.boost_python_pointee_hpp.class_template_pointee">Class + template <code class="computeroutput"><span class="identifier">pointee</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_pointee_hpp.html#utility_and_infrastructure.boost_python_pointee_hpp.examples">Examples</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_pointee_hpp.introduction"></a><a class="link" href="boost_python_pointee_hpp.html#utility_and_infrastructure.boost_python_pointee_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/pointee.hpp> introduces a traits metafunction <code class="computeroutput"><span class="keyword">template</span> <span class="identifier">pointee</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> that can be used to extract the "pointed-to" + type from the type of a pointer or smart pointer. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_pointee_hpp.class_template_pointee"></a><a class="link" href="boost_python_pointee_hpp.html#utility_and_infrastructure.boost_python_pointee_hpp.class_template_pointee" title="Class template pointee">Class + template <code class="computeroutput"><span class="identifier">pointee</span></code></a> +</h3></div></div></div> +<p> + <code class="computeroutput"><span class="identifier">pointee</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> + is used by the <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_<T, Bases, HeldType, NonCopyable>"><code class="computeroutput"><span class="identifier">class_</span><span class="special"><...></span></code></a> + template to deduce the type being held when a pointer or smart pointer + type is used as its HeldType argument. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">pointee</span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">T</span><span class="special">::</span><span class="identifier">element_type</span> <span class="identifier">type</span><span class="special">;</span> + <span class="special">};</span> + + <span class="comment">// specialization for pointers</span> + <span class="keyword">template</span> <span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">pointee</span><span class="special"><</span><span class="identifier">T</span><span class="special">*></span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">T</span> <span class="identifier">type</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_pointee_hpp.examples"></a><a class="link" href="boost_python_pointee_hpp.html#utility_and_infrastructure.boost_python_pointee_hpp.examples" title="Examples">Examples</a> +</h3></div></div></div> +<p> + Given a 3rd-party smart pointer type <code class="computeroutput"><span class="identifier">smart_pointer</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>, one might partially specialize <code class="computeroutput"><span class="identifier">pointee</span><span class="special"><</span><span class="identifier">smart_pointer</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="special">></span></code> so that it can be used as the HeldType + for a class wrapper: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">pointee</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> +<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">third_party_lib</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">pointee</span><span class="special"><</span><span class="identifier">smart_pointer</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="special">></span> + <span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">T</span> <span class="identifier">type</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">pointee_demo</span><span class="special">)</span> +<span class="special">{</span> + <span class="identifier">class_</span><span class="special"><</span><span class="identifier">third_party_class</span><span class="special">,</span> <span class="identifier">smart_pointer</span><span class="special"><</span><span class="identifier">third_party_class</span><span class="special">></span> <span class="special">>(</span><span class="string">"third_party_class"</span><span class="special">)</span> + <span class="special">.</span><span class="identifier">def</span><span class="special">(...)</span> + <span class="special">...</span> + <span class="special">;</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_instance_holder_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../utility_and_infrastructure.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_handle_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_ssize_t_hpp.html b/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_ssize_t_hpp.html new file mode 100644 index 0000000000..42b6839e7d --- /dev/null +++ b/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_ssize_t_hpp.html @@ -0,0 +1,90 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/ssize_t.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../utility_and_infrastructure.html" title="Chapter 7. Utility and Infrastructure"> +<link rel="prev" href="boost_python_type_id_hpp.html" title="boost/python/type_id.hpp"> +<link rel="next" href="../topics.html" title="Chapter 8. Topics"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_type_id_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../utility_and_infrastructure.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../topics.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="utility_and_infrastructure.boost_python_ssize_t_hpp"></a><a class="link" href="boost_python_ssize_t_hpp.html" title="boost/python/ssize_t.hpp">boost/python/ssize_t.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_ssize_t_hpp.html#utility_and_infrastructure.boost_python_ssize_t_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_ssize_t_hpp.html#utility_and_infrastructure.boost_python_ssize_t_hpp.typedefs">Typedefs</a></span></dt> +<dt><span class="section"><a href="boost_python_ssize_t_hpp.html#utility_and_infrastructure.boost_python_ssize_t_hpp.constants">Constants</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_ssize_t_hpp.introduction"></a><a class="link" href="boost_python_ssize_t_hpp.html#utility_and_infrastructure.boost_python_ssize_t_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + Python 2.5 introduces a new <code class="computeroutput"><span class="identifier">Py_ssize_t</span></code> + typedef and two related macros (<a href="http://www.python.org/dev/peps/pep-0353/" target="_top">PEP + 353</a>). The <boost/python/ssize_t.hpp> header imports these + definitions into the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span></code> + namespace as <code class="computeroutput"><span class="identifier">ssize_t</span></code>, + <code class="computeroutput"><span class="identifier">ssize_t_max</span></code>, and <code class="computeroutput"><span class="identifier">ssize_t_min</span></code>. Appropriate definitions + are provided for backward compatibility with previous Python versions. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_ssize_t_hpp.typedefs"></a><a class="link" href="boost_python_ssize_t_hpp.html#utility_and_infrastructure.boost_python_ssize_t_hpp.typedefs" title="Typedefs">Typedefs</a> +</h3></div></div></div> +<p> + Imports <code class="computeroutput"><span class="identifier">Py_ssize_t</span></code> into + the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span></code> namespace if available, or provides + an appropriate typedef for backward compatibility: + </p> +<pre class="programlisting"><span class="preprocessor">#if</span> <span class="identifier">PY_VERSION_HEX</span> <span class="special">>=</span> <span class="number">0x02050000</span> +<span class="keyword">typedef</span> <span class="identifier">Py_ssize_t</span> <span class="identifier">ssize_t</span><span class="special">;</span> +<span class="preprocessor">#else</span> +<span class="keyword">typedef</span> <span class="keyword">int</span> <span class="identifier">ssize_t</span><span class="special">;</span> +<span class="preprocessor">#endif</span> +</pre> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_ssize_t_hpp.constants"></a><a class="link" href="boost_python_ssize_t_hpp.html#utility_and_infrastructure.boost_python_ssize_t_hpp.constants" title="Constants">Constants</a> +</h3></div></div></div> +<p> + Imports <code class="computeroutput"><span class="identifier">PY_SSIZE_T_MAX</span></code> + and <code class="computeroutput"><span class="identifier">PY_SSIZE_T_MIN</span></code> as constants + into the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span></code> namespace if available, or provides + appropriate constants for backward compatibility: + </p> +<pre class="programlisting"><span class="preprocessor">#if</span> <span class="identifier">PY_VERSION_HEX</span> <span class="special">>=</span> <span class="number">0x02050000</span> +<span class="identifier">ssize_t</span> <span class="keyword">const</span> <span class="identifier">ssize_t_max</span> <span class="special">=</span> <span class="identifier">PY_SSIZE_T_MAX</span><span class="special">;</span> +<span class="identifier">ssize_t</span> <span class="keyword">const</span> <span class="identifier">ssize_t_min</span> <span class="special">=</span> <span class="identifier">PY_SSIZE_T_MIN</span><span class="special">;</span> +<span class="preprocessor">#else</span> +<span class="identifier">ssize_t</span> <span class="keyword">const</span> <span class="identifier">ssize_t_max</span> <span class="special">=</span> <span class="identifier">INT_MAX</span><span class="special">;</span> +<span class="identifier">ssize_t</span> <span class="keyword">const</span> <span class="identifier">ssize_t_min</span> <span class="special">=</span> <span class="identifier">INT_MIN</span><span class="special">;</span> +<span class="preprocessor">#endif</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_type_id_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../utility_and_infrastructure.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="../topics.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_type_id_hpp.html b/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_type_id_hpp.html new file mode 100644 index 0000000000..2390fd2aac --- /dev/null +++ b/libs/python/doc/html/reference/utility_and_infrastructure/boost_python_type_id_hpp.html @@ -0,0 +1,234 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>boost/python/type_id.hpp</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> +<link rel="up" href="../utility_and_infrastructure.html" title="Chapter 7. Utility and Infrastructure"> +<link rel="prev" href="boost_python_handle_hpp.html" title="boost/python/handle.hpp"> +<link rel="next" href="boost_python_ssize_t_hpp.html" title="boost/python/ssize_t.hpp"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_handle_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../utility_and_infrastructure.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_ssize_t_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="utility_and_infrastructure.boost_python_type_id_hpp"></a><a class="link" href="boost_python_type_id_hpp.html" title="boost/python/type_id.hpp">boost/python/type_id.hpp</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.introduction">Introduction</a></span></dt> +<dt><span class="section"><a href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info">Class + template <code class="computeroutput"><span class="identifier">type_info</span></code></a></span></dt> +<dt><span class="section"><a href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.functions">Functions</a></span></dt> +<dt><span class="section"><a href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.example">Example</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_type_id_hpp.introduction"></a><a class="link" href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.introduction" title="Introduction">Introduction</a> +</h3></div></div></div> +<p> + <boost/python/type_id.hpp> provides types and functions for runtime + type identification like those of of <code class="computeroutput"><span class="special"><</span><span class="identifier">typeinfo</span><span class="special">></span></code>. + It exists mostly to work around certain compiler bugs and platform-dependent + interactions with shared libraries. + </p> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info"></a><a class="link" href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info" title="Class template type_info">Class + template <code class="computeroutput"><span class="identifier">type_info</span></code></a> +</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info.class_template_type_info_constru">Class + template <code class="computeroutput"><span class="identifier">type_info</span></code> constructor</a></span></dt> +<dt><span class="section"><a href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info.class_template_type_info_compari">Class + template <code class="computeroutput"><span class="identifier">type_info</span></code> comparison</a></span></dt> +<dt><span class="section"><a href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info.class_template_type_info_observe">Class + template <code class="computeroutput"><span class="identifier">type_info</span></code> observers</a></span></dt> +</dl></div> +<p> + <code class="computeroutput"><span class="identifier">type_info</span></code> instances identify + a type. As <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">type_info</span></code> is specified to (but unlike + its implementation in some compilers), <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">type_info</span></code> + never represents top-level references or cv-qualification (see section + 5.2.8 in the C++ standard). Unlike <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">type_info</span></code>, + <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">type_info</span></code> instances are copyable, and + comparisons always work reliably across shared library boundaries. + </p> +<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> +<span class="special">{</span> + <span class="keyword">class</span> <span class="identifier">type_info</span> <span class="special">:</span> <span class="identifier">totally_ordered</span><span class="special"><</span><span class="identifier">type_info</span><span class="special">></span> + <span class="special">{</span> + <span class="keyword">public</span><span class="special">:</span> + <span class="comment">// constructor</span> + <span class="identifier">type_info</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">type_info</span> <span class="keyword">const</span><span class="special">&</span> <span class="special">=</span> <span class="keyword">typeid</span><span class="special">(</span><span class="keyword">void</span><span class="special">));</span> + + <span class="comment">// comparisons</span> + <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special"><(</span><span class="identifier">type_info</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">==(</span><span class="identifier">type_info</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> + + <span class="comment">// observers</span> + <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> + <span class="special">};</span> +<span class="special">}}</span> +</pre> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info.class_template_type_info_constru"></a><a class="link" href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info.class_template_type_info_constru" title="Class template type_info constructor">Class + template <code class="computeroutput"><span class="identifier">type_info</span></code> constructor</a> +</h4></div></div></div> +<pre class="programlisting"><span class="identifier">type_info</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">type_info</span> <span class="keyword">const</span><span class="special">&</span> <span class="special">=</span> <span class="keyword">typeid</span><span class="special">(</span><span class="keyword">void</span><span class="special">));</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + constructs a <code class="computeroutput"><span class="identifier">type_info</span></code> + object which identifies the same type as its argument. + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Since it is occasionally necessary to make an array of <code class="computeroutput"><span class="identifier">type_info</span></code> objects a benign default + argument is supplied. Note: this constructor does not correct for + non-conformance of compiler <code class="computeroutput"><span class="keyword">typeid</span><span class="special">()</span></code> implementations. See <code class="computeroutput"><span class="identifier">type_id</span></code>, below. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info.class_template_type_info_compari"></a><a class="link" href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info.class_template_type_info_compari" title="Class template type_info comparison">Class + template <code class="computeroutput"><span class="identifier">type_info</span></code> comparison</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">bool</span> <span class="keyword">operator</span><span class="special"><(</span><span class="identifier">type_info</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">rhs</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + yields a total order over <code class="computeroutput"><span class="identifier">type_info</span></code> + objects. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">==(</span><span class="identifier">type_info</span> <span class="keyword">const</span> <span class="special">&</span><span class="identifier">rhs</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span></pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="keyword">true</span></code> iff the two values + describe the same type. + </p></dd> +<dt><span class="term">Note</span></dt> +<dd><p> + The use of <code class="computeroutput"><span class="identifier">totally_ordered</span><span class="special"><</span><span class="identifier">type_info</span><span class="special">></span></code> as a private base class supplies + operators <code class="computeroutput"><span class="special"><=</span></code>, + <code class="computeroutput"><span class="special">>=</span></code>, <code class="computeroutput"><span class="special">></span></code>, and <code class="computeroutput"><span class="special">!=</span></code> + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info.class_template_type_info_observe"></a><a class="link" href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.class_template_type_info.class_template_type_info_observe" title="Class template type_info observers">Class + template <code class="computeroutput"><span class="identifier">type_info</span></code> observers</a> +</h4></div></div></div> +<pre class="programlisting"><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">name</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + The result of calling <code class="computeroutput"><span class="identifier">name</span><span class="special">()</span></code> on the argument used to construct + the object. + </p></dd> +</dl> +</div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_type_id_hpp.functions"></a><a class="link" href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.functions" title="Functions">Functions</a> +</h3></div></div></div> +<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&</span> <span class="keyword">operator</span><span class="special"><<(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&</span><span class="identifier">s</span><span class="special">,</span> <span class="identifier">type_info</span> <span class="keyword">const</span><span class="special">&</span><span class="identifier">x</span><span class="special">);</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Effects</span></dt> +<dd><p> + Writes a description of the type described by to <code class="computeroutput"><span class="identifier">x</span></code> + into s. + </p></dd> +<dt><span class="term">Rationale</span></dt> +<dd><p> + Not every C++ implementation provides a truly human-readable <code class="computeroutput"><span class="identifier">type_info</span><span class="special">::</span><span class="identifier">name</span><span class="special">()</span></code> + string, but for some we may be able to decode the string and produce + a reasonable representation. + </p></dd> +<dt><span class="term">Note</span></dt> +<dd><p> + On some non-conforming C++ implementations, the code is not actually + as simple as described above; the semantics are adjusted to work + as-if the C++ implementation were conforming. + </p></dd> +</dl> +</div> +<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="identifier">type_info</span> <span class="identifier">type_id</span><span class="special">()</span> +</pre> +<div class="variablelist"> +<p class="title"><b></b></p> +<dl class="variablelist"> +<dt><span class="term">Returns</span></dt> +<dd><p> + <code class="computeroutput"><span class="identifier">type_info</span><span class="special">(</span><span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">))</span></code> + </p></dd> +<dt><span class="term">Note</span></dt> +<dd><p> + On some non-conforming C++ implementations, the code is not actually + as simple as described above; the semantics are adjusted to work + as-if the C++ implementation were conforming. + </p></dd> +</dl> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="utility_and_infrastructure.boost_python_type_id_hpp.example"></a><a class="link" href="boost_python_type_id_hpp.html#utility_and_infrastructure.boost_python_type_id_hpp.example" title="Example">Example</a> +</h3></div></div></div> +<p> + The following example, though silly, illustrates how the type_id facility + might be used + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">type_id</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="comment">// Returns true iff the user passes an int argument</span> +<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> +<span class="keyword">bool</span> <span class="identifier">is_int</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">type_id</span><span class="special">;</span> + <span class="keyword">return</span> <span class="identifier">type_id</span><span class="special"><</span><span class="identifier">T</span><span class="special">>()</span> <span class="special">==</span> <span class="identifier">type_id</span><span class="special"><</span><span class="keyword">int</span><span class="special">>();</span> +<span class="special">}</span> +</pre> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="boost_python_handle_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../utility_and_infrastructure.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_ssize_t_hpp.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/rst.css b/libs/python/doc/html/rst.css new file mode 100644 index 0000000000..1e2ac12214 --- /dev/null +++ b/libs/python/doc/html/rst.css @@ -0,0 +1,149 @@ +@import url("boostbook.css"); +@import url("docutils.css"); +/* Copyright David Abrahams 2006. Distributed under the Boost + Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + */ + +dl.docutils dt { + font-weight: bold } + +img.boost-logo { + border: none; + vertical-align: middle +} + +pre.literal-block span.concept { + font-style: italic; +} + +.nav { +display: inline; +list-style-type: none; +} + +.prevpage { +padding-top: -5px; +text-align: left; +float: left; +} + +.nextpage { +padding-top: -20px; +text-align: right; +float: right; +} + +div.small { + font-size: smaller } + +h2 a { + font-size: 90%; +} +h3 a { + font-size: 80%; +} +h4 a { + font-size: 70%; +} +h5 a { + font-size: 60%; +} + +dl,table +{ + text-align: left; + font-size: 10pt; + line-height: 1.15; +} + + +/*============================================================================= + Tables +=============================================================================*/ + +/* The only clue docutils gives us that tables are logically tables, + and not, e.g., footnotes, is that they have border="1". Therefore + we're keying off of that. We used to manually patch docutils to + add a "table" class to all logical tables, but that proved much too + fragile. +*/ + + table[border="1"] + { + width: 92%; + margin-left: 4%; + margin-right: 4%; + } + + table[border="1"] + { + padding: 4px; + } + + /* Table Cells */ + table[border="1"] tr td + { + padding: 0.5em; + text-align: left; + font-size: 9pt; + } + + table[border="1"] tr th + { + padding: 0.5em 0.5em 0.5em 0.5em; + border: 1pt solid white; + font-size: 80%; + } + + @media screen + { + + /* Tables */ + table[border="1"] tr td + { + border: 1px solid #DCDCDC; + } + + table[border="1"] tr th + { + background-color: #F0F0F0; + border: 1px solid #DCDCDC; + } + + pre, + .screen + { + border: 1px solid #DCDCDC; + } + + td pre + td .screen + { + border: 0px + } + + .sidebar pre + { + border: 0px + } + + } + + pre, + .screen + { + font-size: 9pt; + display: block; + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; + } + + /* Program listings in tables don't get borders */ + td pre, + td .screen + { + margin: 0pc 0pc 0pc 0pc; + padding: 0pc 0pc 0pc 0pc; + } + diff --git a/libs/python/doc/html/support.html b/libs/python/doc/html/support.html new file mode 100644 index 0000000000..dbc9a89bca --- /dev/null +++ b/libs/python/doc/html/support.html @@ -0,0 +1,85 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Chapter 3. Support Resources</title> +<link rel="stylesheet" href="boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python"> +<link rel="up" href="index.html" title="Boost.Python"> +<link rel="prev" href="configuration.html" title="Chapter 2. Configuration"> +<link rel="next" href="faq.html" title="Chapter 4. Frequently Asked Questions (FAQs)"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="configuration.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="faq.html"><img src="images/next.png" alt="Next"></a> +</div> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="support"></a>Chapter 3. Support Resources</h1></div></div></div> +<h3> +<a name="support.h0"></a> + <span class="phrase"><a name="support.synopsis"></a></span><a class="link" href="support.html#support.synopsis">Synopsis</a> + </h3> +<p> + This is a list of available resources for support with Boost.Python problems + and feature requests. Please try to resist emailing the Boost.Python developers + directly for support. Use the following resources instead; the developers are + listening! + </p> +<h3> +<a name="support.h1"></a> + <span class="phrase"><a name="support.support"></a></span><a class="link" href="support.html#support.support">Support</a> + </h3> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + The <a href="http://www.boost.org/more/mailing_lists.htm#cplussig" target="_top">Boost.Python + mailing list</a> is a forum for discussing Python/C++ interoperability, + and Boost.Python in particular. Post your Boost.Python questions here. + </li> +<li class="listitem"> + The <a href="http://www.boost.org/more/mailing_lists.htm#jamboost" target="_top">Boost.Build + mailing list</a> is a forum for discussing Boost's Build System. + </li> +<li class="listitem"> +<p class="simpara"> + The Boost.Python <a href="https://github.com/boostorg/python/issues" target="_top">Issue + tracker</a> + </p> +<div class="note"><table border="0" summary="Note"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td> +<th align="left">Note</th> +</tr> +<tr><td align="left" valign="top"><p> + In the past we used Trac, which still hosts a considerable number of + <a href="https://svn.boost.org/trac/boost/query?status=!closed&component=python+USE+GITHUB" target="_top">open + issues</a>. We hope to be able to either close them or migrate them + to the new issue tracker. + </p></td></tr> +</table></div> +</li> +<li class="listitem"> + The Boost.Python <a href="https://github.com/boostorg/python/wiki" target="_top">Wiki</a> + </li> +<li class="listitem"> + Boost.Python <a href="https://github.com/boostorg/python" target="_top">Source repository</a> + </li> +</ul></div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"></td> +<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David + Abrahams, Stefan Seefeld<p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) + </p> +</div></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="configuration.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="faq.html"><img src="images/next.png" alt="Next"></a> +</div> +</body> +</html> diff --git a/libs/python/doc/html/tutorial/index.html b/libs/python/doc/html/tutorial/index.html new file mode 100644 index 0000000000..2ad0d14864 --- /dev/null +++ b/libs/python/doc/html/tutorial/index.html @@ -0,0 +1,149 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Boost.Python Tutorial</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Boost.Python Tutorial"> +<link rel="next" href="tutorial/hello.html" title="Building Hello World"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> +<hr> +<div class="spirit-nav"><a accesskey="n" href="tutorial/hello.html"><img src="../images/next.png" alt="Next"></a></div> +<div class="article"> +<div class="titlepage"> +<div> +<div><h2 class="title"> +<a name="tutorial"></a>Boost.Python Tutorial</h2></div> +<div><div class="authorgroup"> +<div class="author"><h3 class="author"> +<span class="firstname">Joel</span> <span class="surname">de Guzman</span> +</h3></div> +<div class="author"><h3 class="author"> +<span class="firstname">David</span> <span class="surname">Abrahams</span> +</h3></div> +</div></div> +<div><p class="copyright">Copyright © 2002-2005 Joel + de Guzman, David Abrahams</p></div> +<div><div class="legalnotice"> +<a name="tutorial.legal"></a><p> + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> + </p> +</div></div> +</div> +<hr> +</div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="index.html#tutorial.quickstart">QuickStart</a></span></dt> +<dt><span class="section"><a href="tutorial/hello.html">Building Hello World</a></span></dt> +<dt><span class="section"><a href="tutorial/exposing.html">Exposing Classes</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="tutorial/exposing.html#tutorial.exposing.constructors">Constructors</a></span></dt> +<dt><span class="section"><a href="tutorial/exposing.html#tutorial.exposing.class_data_members">Class Data Members</a></span></dt> +<dt><span class="section"><a href="tutorial/exposing.html#tutorial.exposing.class_properties">Class Properties</a></span></dt> +<dt><span class="section"><a href="tutorial/exposing.html#tutorial.exposing.inheritance">Inheritance</a></span></dt> +<dt><span class="section"><a href="tutorial/exposing.html#tutorial.exposing.class_virtual_functions">Class Virtual + Functions</a></span></dt> +<dt><span class="section"><a href="tutorial/exposing.html#tutorial.exposing.virtual_functions_with_default_i">Virtual + Functions with Default Implementations</a></span></dt> +<dt><span class="section"><a href="tutorial/exposing.html#tutorial.exposing.class_operators_special_function">Class + Operators/Special Functions</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="tutorial/functions.html">Functions</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="tutorial/functions.html#tutorial.functions.call_policies">Call Policies</a></span></dt> +<dt><span class="section"><a href="tutorial/functions.html#tutorial.functions.overloading">Overloading</a></span></dt> +<dt><span class="section"><a href="tutorial/functions.html#tutorial.functions.default_arguments">Default Arguments</a></span></dt> +<dt><span class="section"><a href="tutorial/functions.html#tutorial.functions.auto_overloading">Auto-Overloading</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="tutorial/object.html">Object Interface</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="tutorial/object.html#tutorial.object.basic_interface">Basic Interface</a></span></dt> +<dt><span class="section"><a href="tutorial/object.html#tutorial.object.derived_object_types">Derived Object + types</a></span></dt> +<dt><span class="section"><a href="tutorial/object.html#tutorial.object.extracting_c_objects">Extracting C++ + objects</a></span></dt> +<dt><span class="section"><a href="tutorial/object.html#tutorial.object.enums">Enums</a></span></dt> +<dt><span class="section"><a href="tutorial/object.html#tutorial.object.creating_python_object">Creating <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span></code> + from <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code></a></span></dt> +</dl></dd> +<dt><span class="section"><a href="tutorial/embedding.html">Embedding</a></span></dt> +<dd><dl><dt><span class="section"><a href="tutorial/embedding.html#tutorial.embedding.using_the_interpreter">Using the interpreter</a></span></dt></dl></dd> +<dt><span class="section"><a href="tutorial/iterators.html">Iterators</a></span></dt> +<dt><span class="section"><a href="tutorial/exception.html">Exception Translation</a></span></dt> +<dt><span class="section"><a href="tutorial/techniques.html">General Techniques</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="tutorial/techniques.html#tutorial.techniques.creating_packages">Creating Packages</a></span></dt> +<dt><span class="section"><a href="tutorial/techniques.html#tutorial.techniques.extending_wrapped_objects_in_pyt">Extending + Wrapped Objects in Python</a></span></dt> +<dt><span class="section"><a href="tutorial/techniques.html#tutorial.techniques.reducing_compiling_time">Reducing + Compiling Time</a></span></dt> +</dl></dd> +</dl> +</div> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="tutorial.quickstart"></a><a class="link" href="index.html#tutorial.quickstart" title="QuickStart">QuickStart</a> +</h2></div></div></div> +<p> + The Boost Python Library is a framework for interfacing Python and C++. It + allows you to quickly and seamlessly expose C++ classes functions and objects + to Python, and vice-versa, using no special tools -- just your C++ compiler. + It is designed to wrap C++ interfaces non-intrusively, so that you should not + have to change the C++ code at all in order to wrap it, making Boost.Python + ideal for exposing 3rd-party libraries to Python. The library's use of advanced + metaprogramming techniques simplifies its syntax for users, so that wrapping + code takes on the look of a kind of declarative interface definition language + (IDL). + </p> +<h3> +<a name="tutorial.quickstart.h0"></a> + <span class="phrase"><a name="tutorial.quickstart.hello_world"></a></span><a class="link" href="index.html#tutorial.quickstart.hello_world">Hello + World</a> + </h3> +<p> + Following C/C++ tradition, let's start with the "hello, world". A + C++ Function: + </p> +<pre class="programlisting"><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">greet</span><span class="special">()</span> +<span class="special">{</span> + <span class="keyword">return</span> <span class="string">"hello, world"</span><span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + can be exposed to Python by writing a Boost.Python wrapper: + </p> +<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> + +<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">hello_ext</span><span class="special">)</span> +<span class="special">{</span> + <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> + <span class="identifier">def</span><span class="special">(</span><span class="string">"greet"</span><span class="special">,</span> <span class="identifier">greet</span><span class="special">);</span> +<span class="special">}</span> +</pre> +<p> + That's it. We're done. We can now build this as a shared library. The resulting + DLL is now visible to Python. Here's a sample Python session: + </p> +<pre class="programlisting"><span class="special">>>></span> <span class="keyword">import</span> <span class="identifier">hello_ext</span> +<span class="special">>>></span> <span class="keyword">print</span> <span class="identifier">hello_ext</span><span class="special">.</span><span class="identifier">greet</span><span class="special">()</span> +<span class="identifier">hello</span><span class="special">,</span> <span class="identifier">world</span> +</pre> +<div class="blockquote"><blockquote class="blockquote"><p> + <span class="emphasis"><em><span class="bold"><strong>Next stop... Building your Hello World module + from start to finish...</strong></span></em></span> + </p></blockquote></div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"><p><small>Last revised: December 14, 2015 at 09:15:13 GMT</small></p></td> +<td align="right"><div class="copyright-footer"></div></td> +</tr></table> +<hr> +<div class="spirit-nav"><a accesskey="n" href="tutorial/hello.html"><img src="../images/next.png" alt="Next"></a></div> +</body> +</html> diff --git a/libs/python/doc/tutorial/doc/html/python/embedding.html b/libs/python/doc/html/tutorial/tutorial/embedding.html index 4e1c21857b..3e9816ecdb 100644 --- a/libs/python/doc/tutorial/doc/html/python/embedding.html +++ b/libs/python/doc/html/tutorial/tutorial/embedding.html @@ -2,30 +2,24 @@ <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Embedding</title> -<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css"> -<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> -<link rel="home" href="../index.html" title="Chapter 1. python 2.0"> -<link rel="up" href="../index.html" title="Chapter 1. python 2.0"> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Tutorial"> +<link rel="up" href="../index.html" title="Boost.Python Tutorial"> <link rel="prev" href="object.html" title="Object Interface"> <link rel="next" href="iterators.html" title="Iterators"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table cellpadding="2" width="100%"><tr> -<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td> -<td align="center"><a href="../../../../../../../index.html">Home</a></td> -<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td> -<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> -<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> -<td align="center"><a href="../../../../../../../more/index.htm">More</a></td> -</tr></table> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="object.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="iterators.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="object.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="iterators.html"><img src="../../images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="python.embedding"></a>Embedding</h2></div></div></div> -<div class="toc"><dl><dt><span class="section"><a href="embedding.html#python.using_the_interpreter">Using the interpreter</a></span></dt></dl></div> +<a name="tutorial.embedding"></a><a class="link" href="embedding.html" title="Embedding">Embedding</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"><dt><span class="section"><a href="embedding.html#tutorial.embedding.using_the_interpreter">Using the interpreter</a></span></dt></dl></div> <p> By now you should know how to use Boost.Python to call your C++ code from Python. However, sometimes you may need to do the reverse: call Python code from the @@ -37,11 +31,12 @@ embedding. Therefore you'll need to use the <a href="http://www.python.org/doc/current/api/api.html" target="_top">Python/C API</a> to fill in the gaps. However, Boost.Python already makes embedding a lot easier and, in a future version, it may become unnecessary to touch the - Python/C API at all. So stay tuned... <span class="inlinemediaobject"><img src="../images/smiley.png" alt="smiley"></span> + Python/C API at all. So stay tuned... <span class="inlinemediaobject"><img src="../../images/smiley.png"></span> </p> <h3> -<a name="embedding.building_embedded_programs"></a> - Building embedded programs +<a name="tutorial.embedding.h0"></a> + <span class="phrase"><a name="tutorial.embedding.building_embedded_programs"></a></span><a class="link" href="embedding.html#tutorial.embedding.building_embedded_programs">Building + embedded programs</a> </h3> <p> To be able to embed python into your programs, you have to link to both Boost.Python's @@ -82,8 +77,9 @@ exe embedded_program # name of the executable <find-library>$(PYTHON_EMBEDDED_LIBRARY) ; </pre> <h3> -<a name="embedding.getting_started"></a> - Getting started +<a name="tutorial.embedding.h1"></a> + <span class="phrase"><a name="tutorial.embedding.getting_started"></a></span><a class="link" href="embedding.html#tutorial.embedding.getting_started">Getting + started</a> </h3> <p> Being able to build is nice, but there is nothing to build yet. Embedding the @@ -103,7 +99,7 @@ exe embedded_program # name of the executable </ol></div> <div class="note"><table border="0" summary="Note"> <tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"><p> @@ -120,7 +116,8 @@ exe embedded_program # name of the executable </p></blockquote></div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.using_the_interpreter"></a>Using the interpreter</h3></div></div></div> +<a name="tutorial.embedding.using_the_interpreter"></a><a class="link" href="embedding.html#tutorial.embedding.using_the_interpreter" title="Using the interpreter">Using the interpreter</a> +</h3></div></div></div> <p> As you probably already know, objects in Python are reference-counted. Naturally, the <code class="literal">PyObject</code>s of the Python C API are also reference-counted. @@ -132,8 +129,9 @@ exe embedded_program # name of the executable automate the process. </p> <h3> -<a name="using_the_interpreter.running_python_code"></a> - Running Python code +<a name="tutorial.embedding.using_the_interpreter.h0"></a> + <span class="phrase"><a name="tutorial.embedding.using_the_interpreter.running_python_code"></a></span><a class="link" href="embedding.html#tutorial.embedding.using_the_interpreter.running_python_code">Running + Python code</a> </h3> <p> Boost.python provides three related functions to run Python code from C++. @@ -179,12 +177,13 @@ exe embedded_program # name of the executable a phrase that is well-known in programming circles. </p> <h3> -<a name="using_the_interpreter.manipulating_python_objects"></a> - Manipulating Python objects +<a name="tutorial.embedding.using_the_interpreter.h1"></a> + <span class="phrase"><a name="tutorial.embedding.using_the_interpreter.manipulating_python_objects"></a></span><a class="link" href="embedding.html#tutorial.embedding.using_the_interpreter.manipulating_python_objects">Manipulating + Python objects</a> </h3> <p> Often we'd like to have a class to manipulate Python objects. But we have - already seen such a class above, and in the <a href="object.html" target="_top">previous + already seen such a class above, and in the <a href="../python/object.html" target="_top">previous section</a>: the aptly named <code class="literal">object</code> class and its derivatives. We've already seen that they can be constructed from a <code class="literal">handle</code>. The following examples should further illustrate this fact: @@ -204,8 +203,9 @@ exe embedded_program # name of the executable <span class="keyword">int</span> <span class="identifier">five_squared</span> <span class="special">=</span> <span class="identifier">extract</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">result</span><span class="special">);</span> </pre> <h3> -<a name="using_the_interpreter.exception_handling"></a> - Exception handling +<a name="tutorial.embedding.using_the_interpreter.h2"></a> + <span class="phrase"><a name="tutorial.embedding.using_the_interpreter.exception_handling"></a></span><a class="link" href="embedding.html#tutorial.embedding.using_the_interpreter.exception_handling">Exception + handling</a> </h3> <p> If an exception occurs in the evaluation of the python expression, <a href="../../../../v2/errors.html#error_already_set-spec" target="_top">error_already_set</a> @@ -256,14 +256,13 @@ exe embedded_program # name of the executable <td align="right"><div class="copyright-footer">Copyright © 2002-2005 Joel de Guzman, David Abrahams<p> Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top"> - http://www.boost.org/LICENSE_1_0.txt </a>) + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> </p> </div></td> </tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="object.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="iterators.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="object.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="iterators.html"><img src="../../images/next.png" alt="Next"></a> </div> </body> </html> diff --git a/libs/python/doc/tutorial/doc/html/python/exception.html b/libs/python/doc/html/tutorial/tutorial/exception.html index 7c053a7e86..52cc636018 100644 --- a/libs/python/doc/tutorial/doc/html/python/exception.html +++ b/libs/python/doc/html/tutorial/tutorial/exception.html @@ -2,29 +2,23 @@ <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Exception Translation</title> -<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css"> -<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> -<link rel="home" href="../index.html" title="Chapter 1. python 2.0"> -<link rel="up" href="../index.html" title="Chapter 1. python 2.0"> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Tutorial"> +<link rel="up" href="../index.html" title="Boost.Python Tutorial"> <link rel="prev" href="iterators.html" title="Iterators"> <link rel="next" href="techniques.html" title="General Techniques"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table cellpadding="2" width="100%"><tr> -<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td> -<td align="center"><a href="../../../../../../../index.html">Home</a></td> -<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td> -<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> -<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> -<td align="center"><a href="../../../../../../../more/index.htm">More</a></td> -</tr></table> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="iterators.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="techniques.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="iterators.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="techniques.html"><img src="../../images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="python.exception"></a>Exception Translation</h2></div></div></div> +<a name="tutorial.exception"></a><a class="link" href="exception.html" title="Exception Translation">Exception Translation</a> +</h2></div></div></div> <p> All C++ exceptions must be caught at the boundary with Python code. This boundary is the point where C++ meets Python. Boost.Python provides a default exception @@ -50,14 +44,13 @@ <td align="right"><div class="copyright-footer">Copyright © 2002-2005 Joel de Guzman, David Abrahams<p> Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top"> - http://www.boost.org/LICENSE_1_0.txt </a>) + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> </p> </div></td> </tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="iterators.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="techniques.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="iterators.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="techniques.html"><img src="../../images/next.png" alt="Next"></a> </div> </body> </html> diff --git a/libs/python/doc/tutorial/doc/html/python/exposing.html b/libs/python/doc/html/tutorial/tutorial/exposing.html index 5547b2f205..75692ea455 100644 --- a/libs/python/doc/tutorial/doc/html/python/exposing.html +++ b/libs/python/doc/html/tutorial/tutorial/exposing.html @@ -2,37 +2,34 @@ <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Exposing Classes</title> -<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css"> -<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> -<link rel="home" href="../index.html" title="Chapter 1. python 2.0"> -<link rel="up" href="../index.html" title="Chapter 1. python 2.0"> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Tutorial"> +<link rel="up" href="../index.html" title="Boost.Python Tutorial"> <link rel="prev" href="hello.html" title="Building Hello World"> <link rel="next" href="functions.html" title="Functions"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table cellpadding="2" width="100%"><tr> -<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td> -<td align="center"><a href="../../../../../../../index.html">Home</a></td> -<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td> -<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> -<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> -<td align="center"><a href="../../../../../../../more/index.htm">More</a></td> -</tr></table> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="hello.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="functions.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="hello.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="functions.html"><img src="../../images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="python.exposing"></a>Exposing Classes</h2></div></div></div> -<div class="toc"><dl> -<dt><span class="section"><a href="exposing.html#python.constructors">Constructors</a></span></dt> -<dt><span class="section"><a href="exposing.html#python.class_data_members">Class Data Members</a></span></dt> -<dt><span class="section"><a href="exposing.html#python.class_properties">Class Properties</a></span></dt> -<dt><span class="section"><a href="exposing.html#python.inheritance">Inheritance</a></span></dt> -<dt><span class="section"><a href="exposing.html#python.class_virtual_functions">Class Virtual Functions</a></span></dt> -<dt><span class="section"><a href="exposing.html#python.virtual_functions_with_default_implementations">Virtual Functions with Default Implementations</a></span></dt> -<dt><span class="section"><a href="exposing.html#python.class_operators_special_functions">Class Operators/Special Functions</a></span></dt> +<a name="tutorial.exposing"></a><a class="link" href="exposing.html" title="Exposing Classes">Exposing Classes</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="exposing.html#tutorial.exposing.constructors">Constructors</a></span></dt> +<dt><span class="section"><a href="exposing.html#tutorial.exposing.class_data_members">Class Data Members</a></span></dt> +<dt><span class="section"><a href="exposing.html#tutorial.exposing.class_properties">Class Properties</a></span></dt> +<dt><span class="section"><a href="exposing.html#tutorial.exposing.inheritance">Inheritance</a></span></dt> +<dt><span class="section"><a href="exposing.html#tutorial.exposing.class_virtual_functions">Class Virtual + Functions</a></span></dt> +<dt><span class="section"><a href="exposing.html#tutorial.exposing.virtual_functions_with_default_i">Virtual + Functions with Default Implementations</a></span></dt> +<dt><span class="section"><a href="exposing.html#tutorial.exposing.class_operators_special_function">Class + Operators/Special Functions</a></span></dt> </dl></div> <p> Now let's expose a C++ class to Python. @@ -75,7 +72,8 @@ </pre> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.constructors"></a>Constructors</h3></div></div></div> +<a name="tutorial.exposing.constructors"></a><a class="link" href="exposing.html#tutorial.exposing.constructors" title="Constructors">Constructors</a> +</h3></div></div></div> <p> Our previous example didn't have any explicit constructors. Since <code class="literal">World</code> is declared as a plain struct, it has an implicit default constructor. Boost.Python @@ -142,7 +140,8 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.class_data_members"></a>Class Data Members</h3></div></div></div> +<a name="tutorial.exposing.class_data_members"></a><a class="link" href="exposing.html#tutorial.exposing.class_data_members" title="Class Data Members">Class Data Members</a> +</h3></div></div></div> <p> Data members may also be exposed to Python so that they can be accessed as attributes of the corresponding Python class. Each data member that we wish @@ -185,7 +184,8 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.class_properties"></a>Class Properties</h3></div></div></div> +<a name="tutorial.exposing.class_properties"></a><a class="link" href="exposing.html#tutorial.exposing.class_properties" title="Class Properties">Class Properties</a> +</h3></div></div></div> <p> In C++, classes with public data members are usually frowned upon. Well designed classes that take advantage of encapsulation hide the class' data members. @@ -229,7 +229,8 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.inheritance"></a>Inheritance</h3></div></div></div> +<a name="tutorial.exposing.inheritance"></a><a class="link" href="exposing.html#tutorial.exposing.inheritance" title="Inheritance">Inheritance</a> +</h3></div></div></div> <p> In the previous examples, we dealt with classes that are not polymorphic. This is not often the case. Much of the time, we will be wrapping polymorphic @@ -295,7 +296,7 @@ <code class="literal">return_value_policy<manage_new_object></code> to instruct Python to adopt the pointer to <code class="literal">Base</code> and hold the instance in a new Python <code class="literal">Base</code> object until the the Python object - is destroyed. We will see more of Boost.Python <a class="link" href="functions.html#python.call_policies" title="Call Policies">call + is destroyed. We will see more of Boost.Python <a class="link" href="../">call policies</a> later. </p> <pre class="programlisting"><span class="comment">// Tell Python to take ownership of factory's result</span> @@ -305,7 +306,9 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.class_virtual_functions"></a>Class Virtual Functions</h3></div></div></div> +<a name="tutorial.exposing.class_virtual_functions"></a><a class="link" href="exposing.html#tutorial.exposing.class_virtual_functions" title="Class Virtual Functions">Class Virtual + Functions</a> +</h3></div></div></div> <p> In this section, we will learn how to make functions behave polymorphically through virtual functions. Continuing our example, let us add a virtual function @@ -346,7 +349,8 @@ <div class="sidebar"> <div class="titlepage"></div> <p> - <span class="inlinemediaobject"><img src="../images/alert.png" alt="alert"></span> <span class="bold"><strong>MSVC6/7 Workaround</strong></span> + <span class="inlinemediaobject"><img src="../../images/alert.png"></span> + <span class="bold"><strong>MSVC6/7 Workaround</strong></span> </p> <p> If you are using Microsoft Visual C++ 6 or 7, you have to write <code class="computeroutput"><span class="identifier">f</span></code> as: @@ -373,7 +377,7 @@ </p> <div class="note"><table border="0" summary="Note"> <tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"> @@ -389,7 +393,9 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.virtual_functions_with_default_implementations"></a>Virtual Functions with Default Implementations</h3></div></div></div> +<a name="tutorial.exposing.virtual_functions_with_default_i"></a><a class="link" href="exposing.html#tutorial.exposing.virtual_functions_with_default_i" title="Virtual Functions with Default Implementations">Virtual + Functions with Default Implementations</a> +</h3></div></div></div> <p> We've seen in the previous section how classes with pure virtual functions are wrapped using Boost.Python's <a href="../../../../v2/wrapper.html" target="_top">class @@ -397,7 +403,7 @@ functions instead, the mechanism is a bit different. </p> <p> - Recall that in the <a class="link" href="exposing.html#python.class_virtual_functions" title="Class Virtual Functions">previous + Recall that in the <a class="link" href="../">previous section</a>, we wrapped a class with a pure virtual function that we then implemented in C++, or Python classes derived from it. Our base class: </p> @@ -439,7 +445,8 @@ <div class="sidebar"> <div class="titlepage"></div> <p> - <span class="inlinemediaobject"><img src="../images/alert.png" alt="alert"></span> <span class="bold"><strong>MSVC6/7 Workaround</strong></span> + <span class="inlinemediaobject"><img src="../../images/alert.png"></span> + <span class="bold"><strong>MSVC6/7 Workaround</strong></span> </p> <p> If you are using Microsoft Visual C++ 6 or 7, you have to rewrite the line @@ -487,10 +494,13 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.class_operators_special_functions"></a>Class Operators/Special Functions</h3></div></div></div> +<a name="tutorial.exposing.class_operators_special_function"></a><a class="link" href="exposing.html#tutorial.exposing.class_operators_special_function" title="Class Operators/Special Functions">Class + Operators/Special Functions</a> +</h3></div></div></div> <h3> -<a name="class_operators_special_functions.python_operators"></a> - Python Operators +<a name="tutorial.exposing.class_operators_special_function.h0"></a> + <span class="phrase"><a name="tutorial.exposing.class_operators_special_function.python_operators"></a></span><a class="link" href="exposing.html#tutorial.exposing.class_operators_special_function.python_operators">Python + Operators</a> </h3> <p> C is well known for the abundance of operators. C++ extends this to the extremes @@ -534,8 +544,9 @@ expressions". </p> <h3> -<a name="class_operators_special_functions.special_methods"></a> - Special Methods +<a name="tutorial.exposing.class_operators_special_function.h1"></a> + <span class="phrase"><a name="tutorial.exposing.class_operators_special_function.special_methods"></a></span><a class="link" href="exposing.html#tutorial.exposing.class_operators_special_function.special_methods">Special + Methods</a> </h3> <p> Python has a few more <span class="emphasis"><em>Special Methods</em></span>. Boost.Python @@ -563,7 +574,7 @@ </p> <div class="note"><table border="0" summary="Note"> <tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"><p> @@ -578,14 +589,13 @@ <td align="right"><div class="copyright-footer">Copyright © 2002-2005 Joel de Guzman, David Abrahams<p> Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top"> - http://www.boost.org/LICENSE_1_0.txt </a>) + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> </p> </div></td> </tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="hello.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="functions.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="hello.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="functions.html"><img src="../../images/next.png" alt="Next"></a> </div> </body> </html> diff --git a/libs/python/doc/tutorial/doc/html/python/functions.html b/libs/python/doc/html/tutorial/tutorial/functions.html index ddd5bc7b70..a0dac106c3 100644 --- a/libs/python/doc/tutorial/doc/html/python/functions.html +++ b/libs/python/doc/html/tutorial/tutorial/functions.html @@ -2,34 +2,28 @@ <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Functions</title> -<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css"> -<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> -<link rel="home" href="../index.html" title="Chapter 1. python 2.0"> -<link rel="up" href="../index.html" title="Chapter 1. python 2.0"> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Tutorial"> +<link rel="up" href="../index.html" title="Boost.Python Tutorial"> <link rel="prev" href="exposing.html" title="Exposing Classes"> <link rel="next" href="object.html" title="Object Interface"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table cellpadding="2" width="100%"><tr> -<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td> -<td align="center"><a href="../../../../../../../index.html">Home</a></td> -<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td> -<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> -<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> -<td align="center"><a href="../../../../../../../more/index.htm">More</a></td> -</tr></table> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="exposing.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="object.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="exposing.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="object.html"><img src="../../images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="python.functions"></a>Functions</h2></div></div></div> -<div class="toc"><dl> -<dt><span class="section"><a href="functions.html#python.call_policies">Call Policies</a></span></dt> -<dt><span class="section"><a href="functions.html#python.overloading">Overloading</a></span></dt> -<dt><span class="section"><a href="functions.html#python.default_arguments">Default Arguments</a></span></dt> -<dt><span class="section"><a href="functions.html#python.auto_overloading">Auto-Overloading</a></span></dt> +<a name="tutorial.functions"></a><a class="link" href="functions.html" title="Functions">Functions</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="functions.html#tutorial.functions.call_policies">Call Policies</a></span></dt> +<dt><span class="section"><a href="functions.html#tutorial.functions.overloading">Overloading</a></span></dt> +<dt><span class="section"><a href="functions.html#tutorial.functions.default_arguments">Default Arguments</a></span></dt> +<dt><span class="section"><a href="functions.html#tutorial.functions.auto_overloading">Auto-Overloading</a></span></dt> </dl></div> <p> In this chapter, we'll look at Boost.Python powered functions in closer detail. @@ -69,7 +63,8 @@ Namespaces are one honking great idea -- let's do more of those! </pre> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.call_policies"></a>Call Policies</h3></div></div></div> +<a name="tutorial.functions.call_policies"></a><a class="link" href="functions.html#tutorial.functions.call_policies" title="Call Policies">Call Policies</a> +</h3></div></div></div> <p> In C++, we often deal with arguments and return types such as pointers and references. Such primitive types are rather, ummmm, low level and they really @@ -88,9 +83,9 @@ Namespaces are one honking great idea -- let's do more of those! X object around result reference. This strategy might or might not work out. Here's an example where it didn't </p> -<pre class="programlisting"><span class="special">>>></span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="preprocessor"># x</span> <span class="identifier">refers</span> <span class="identifier">to</span> <span class="identifier">some</span> <span class="identifier">C</span><span class="special">++</span> <span class="identifier">X</span> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">x</span> <span class="identifier">refers</span> <span class="identifier">to</span> <span class="identifier">some</span> <span class="identifier">C</span><span class="special">++</span> <span class="identifier">X</span> <span class="special">>>></span> <span class="identifier">del</span> <span class="identifier">y</span> -<span class="special">>>></span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">some_method</span><span class="special">()</span> <span class="preprocessor"># CRASH</span><span class="special">!</span> +<span class="special">>>></span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">some_method</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">CRASH</span><span class="special">!</span> </pre> <p> What's the problem? @@ -158,9 +153,9 @@ Namespaces are one honking great idea -- let's do more of those! Notice that the data member <code class="literal">z</code> is held by class Y using a raw pointer. Now we have a potential dangling pointer problem inside Y: </p> -<pre class="programlisting"><span class="special">>>></span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="preprocessor"># y</span> <span class="identifier">refers</span> <span class="identifier">to</span> <span class="identifier">z</span> -<span class="special">>>></span> <span class="identifier">del</span> <span class="identifier">z</span> <span class="preprocessor"># Kill</span> <span class="identifier">the</span> <span class="identifier">z</span> <span class="identifier">object</span> -<span class="special">>>></span> <span class="identifier">y</span><span class="special">.</span><span class="identifier">z_value</span><span class="special">()</span> <span class="preprocessor"># CRASH</span><span class="special">!</span> +<pre class="programlisting"><span class="special">>>></span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">#</span> <span class="identifier">y</span> <span class="identifier">refers</span> <span class="identifier">to</span> <span class="identifier">z</span> +<span class="special">>>></span> <span class="identifier">del</span> <span class="identifier">z</span> <span class="special">#</span> <span class="identifier">Kill</span> <span class="identifier">the</span> <span class="identifier">z</span> <span class="identifier">object</span> +<span class="special">>>></span> <span class="identifier">y</span><span class="special">.</span><span class="identifier">z_value</span><span class="special">()</span> <span class="special">#</span> <span class="identifier">CRASH</span><span class="special">!</span> </pre> <p> For reference, here's the implementation of <code class="literal">f</code> again: @@ -200,8 +195,9 @@ Namespaces are one honking great idea -- let's do more of those! </li> </ol></div> <h3> -<a name="call_policies.call_policies"></a> - Call Policies +<a name="tutorial.functions.call_policies.h0"></a> + <span class="phrase"><a name="tutorial.functions.call_policies.call_policies"></a></span><a class="link" href="functions.html#tutorial.functions.call_policies.call_policies">Call + Policies</a> </h3> <p> Call Policies may be used in situations such as the example detailed above. @@ -245,7 +241,7 @@ Namespaces are one honking great idea -- let's do more of those! Here is the list of predefined call policies. A complete reference detailing these can be found <a href="../../../../v2/reference.html#models_of_call_policies" target="_top">here</a>. </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> <span class="bold"><strong>with_custodian_and_ward</strong></span>: Ties lifetimes of the arguments @@ -260,7 +256,7 @@ Namespaces are one honking great idea -- let's do more of those! </li> <li class="listitem"> <span class="bold"><strong>return_value_policy<T> with T one of:</strong></span> - <div class="itemizedlist"><ul class="itemizedlist" type="circle"> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> <li class="listitem"> <span class="bold"><strong>reference_existing_object</strong></span>: naive (dangerous) approach @@ -282,7 +278,8 @@ Namespaces are one honking great idea -- let's do more of those! <div class="sidebar"> <div class="titlepage"></div> <p> - <span class="inlinemediaobject"><img src="../images/smiley.png" alt="smiley"></span> <span class="bold"><strong>Remember the Zen, Luke:</strong></span> + <span class="inlinemediaobject"><img src="../../images/smiley.png"></span> + <span class="bold"><strong>Remember the Zen, Luke:</strong></span> </p> <p> "Explicit is better than implicit" @@ -294,7 +291,8 @@ Namespaces are one honking great idea -- let's do more of those! </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.overloading"></a>Overloading</h3></div></div></div> +<a name="tutorial.functions.overloading"></a><a class="link" href="functions.html#tutorial.functions.overloading" title="Overloading">Overloading</a> +</h3></div></div></div> <p> The following illustrates a scheme for manually wrapping an overloaded member functions. Of course, the same technique can be applied to wrapping overloaded @@ -346,7 +344,8 @@ Namespaces are one honking great idea -- let's do more of those! </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.default_arguments"></a>Default Arguments</h3></div></div></div> +<a name="tutorial.functions.default_arguments"></a><a class="link" href="functions.html#tutorial.functions.default_arguments" title="Default Arguments">Default Arguments</a> +</h3></div></div></div> <p> Boost.Python wraps (member) function pointers. Unfortunately, C++ function pointers carry no default argument info. Take a function <code class="literal">f</code> @@ -368,7 +367,7 @@ Namespaces are one honking great idea -- let's do more of those! </pre> <p> Because of this, when wrapping C++ code, we had to resort to manual wrapping - as outlined in the <a class="link" href="functions.html#python.overloading" title="Overloading">previous section</a>, + as outlined in the <a class="link" href="../">previous section</a>, or writing thin wrappers: </p> <pre class="programlisting"><span class="comment">// write "thin wrappers"</span> @@ -385,7 +384,7 @@ Namespaces are one honking great idea -- let's do more of those! <p> When you want to wrap functions (or member functions) that either: </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> have default arguments, or </li> @@ -394,8 +393,8 @@ Namespaces are one honking great idea -- let's do more of those! </li> </ul></div> <h3> -<a name="default_arguments.boost_python_function_overloads"></a> - BOOST_PYTHON_FUNCTION_OVERLOADS +<a name="tutorial.functions.default_arguments.h0"></a> + <span class="phrase"><a name="tutorial.functions.default_arguments.boost_python_function_overloads"></a></span><a class="link" href="functions.html#tutorial.functions.default_arguments.boost_python_function_overloads">BOOST_PYTHON_FUNCTION_OVERLOADS</a> </h3> <p> Boost.Python now has a way to make it easier. For instance, given a function: @@ -421,8 +420,8 @@ Namespaces are one honking great idea -- let's do more of those! <pre class="programlisting"><span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span> <span class="identifier">foo</span><span class="special">,</span> <span class="identifier">foo_overloads</span><span class="special">());</span> </pre> <h3> -<a name="default_arguments.boost_python_member_function_overloads"></a> - BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS +<a name="tutorial.functions.default_arguments.h1"></a> + <span class="phrase"><a name="tutorial.functions.default_arguments.boost_python_member_function_ove"></a></span><a class="link" href="functions.html#tutorial.functions.default_arguments.boost_python_member_function_ove">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</a> </h3> <p> Objects here, objects there, objects here there everywhere. More frequently @@ -464,8 +463,9 @@ Namespaces are one honking great idea -- let's do more of those! reference</a> for details. </p> <h3> -<a name="default_arguments.init_and_optional"></a> - init and optional +<a name="tutorial.functions.default_arguments.h2"></a> + <span class="phrase"><a name="tutorial.functions.default_arguments.init_and_optional"></a></span><a class="link" href="functions.html#tutorial.functions.default_arguments.init_and_optional">init and + optional</a> </h3> <p> A similar facility is provided for class constructors, again, with default @@ -490,7 +490,8 @@ Namespaces are one honking great idea -- let's do more of those! </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.auto_overloading"></a>Auto-Overloading</h3></div></div></div> +<a name="tutorial.functions.auto_overloading"></a><a class="link" href="functions.html#tutorial.functions.auto_overloading" title="Auto-Overloading">Auto-Overloading</a> +</h3></div></div></div> <p> It was mentioned in passing in the previous section that <code class="literal">BOOST_PYTHON_FUNCTION_OVERLOADS</code> and <code class="literal">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</code> can also be @@ -533,20 +534,21 @@ Namespaces are one honking great idea -- let's do more of those! (0) arguments and a maximum of 3 arguments. </p> <h3> -<a name="auto_overloading.manual_wrapping"></a> - Manual Wrapping +<a name="tutorial.functions.auto_overloading.h0"></a> + <span class="phrase"><a name="tutorial.functions.auto_overloading.manual_wrapping"></a></span><a class="link" href="functions.html#tutorial.functions.auto_overloading.manual_wrapping">Manual + Wrapping</a> </h3> <p> It is important to emphasize however that <span class="bold"><strong>the overloaded functions must have a common sequence of initial arguments</strong></span>. Otherwise, our scheme above will not work. If this is not the case, we have to wrap - our functions <a class="link" href="functions.html#python.overloading" title="Overloading">manually</a>. + our functions <a class="link" href="../">manually</a>. </p> <p> Actually, we can mix and match manual wrapping of overloaded functions and automatic wrapping through <code class="literal">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</code> and its sister, <code class="literal">BOOST_PYTHON_FUNCTION_OVERLOADS</code>. Following - up on our example presented in the section <a class="link" href="functions.html#python.overloading" title="Overloading">on + up on our example presented in the section <a class="link" href="../">on overloading</a>, since the first 4 overload functins have a common sequence of initial arguments, we can use <code class="literal">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</code> to automatically wrap the first three of the <code class="literal">def</code>s and @@ -573,14 +575,13 @@ Namespaces are one honking great idea -- let's do more of those! <td align="right"><div class="copyright-footer">Copyright © 2002-2005 Joel de Guzman, David Abrahams<p> Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top"> - http://www.boost.org/LICENSE_1_0.txt </a>) + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> </p> </div></td> </tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="exposing.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="object.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="exposing.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="object.html"><img src="../../images/next.png" alt="Next"></a> </div> </body> </html> diff --git a/libs/python/doc/tutorial/doc/html/python/hello.html b/libs/python/doc/html/tutorial/tutorial/hello.html index b78573826d..48182e1e70 100644 --- a/libs/python/doc/tutorial/doc/html/python/hello.html +++ b/libs/python/doc/html/tutorial/tutorial/hello.html @@ -2,32 +2,27 @@ <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Building Hello World</title> -<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css"> -<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> -<link rel="home" href="../index.html" title="Chapter 1. python 2.0"> -<link rel="up" href="../index.html" title="Chapter 1. python 2.0"> -<link rel="prev" href="../index.html" title="Chapter 1. python 2.0"> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Tutorial"> +<link rel="up" href="../index.html" title="Boost.Python Tutorial"> +<link rel="prev" href="../index.html" title="Boost.Python Tutorial"> <link rel="next" href="exposing.html" title="Exposing Classes"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table cellpadding="2" width="100%"><tr> -<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td> -<td align="center"><a href="../../../../../../../index.html">Home</a></td> -<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td> -<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> -<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> -<td align="center"><a href="../../../../../../../more/index.htm">More</a></td> -</tr></table> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="../index.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="exposing.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="../index.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="exposing.html"><img src="../../images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="python.hello"></a>Building Hello World</h2></div></div></div> +<a name="tutorial.hello"></a><a class="link" href="hello.html" title="Building Hello World">Building Hello World</a> +</h2></div></div></div> <h3> -<a name="hello.from_start_to_finish"></a> - From Start To Finish +<a name="tutorial.hello.h0"></a> + <span class="phrase"><a name="tutorial.hello.from_start_to_finish"></a></span><a class="link" href="hello.html#tutorial.hello.from_start_to_finish">From + Start To Finish</a> </h3> <p> Now the first thing you'd want to do is to build the Hello World module and @@ -37,7 +32,7 @@ </p> <div class="note"><table border="0" summary="Note"> <tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"> @@ -68,7 +63,7 @@ The tutorial example can be found in the directory: <code class="literal">libs/python/example/tutorial</code>. There, you can find: </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> hello.cpp </li> @@ -92,24 +87,26 @@ platforms. The complete list of Bjam executables can be found <a href="http://sourceforge.net/project/showfiles.php?group_id=7586" target="_top">here</a>. </p> <h3> -<a name="hello.let_s_jam_"></a> - Let's Jam! +<a name="tutorial.hello.h1"></a> + <span class="phrase"><a name="tutorial.hello.let_s_jam"></a></span><a class="link" href="hello.html#tutorial.hello.let_s_jam">Let's + Jam!</a> </h3> <p> - <span class="inlinemediaobject"><img src="../images/jam.png" alt="jam"></span> + <span class="inlinemediaobject"><img src="../../images/jam.png"></span> </p> <p> <a href="../../../../../example/tutorial/Jamroot" target="_top">Here</a> is our minimalist Jamroot file. Simply copy the file and tweak <code class="literal">use-project boost</code> - to where your boost root directory is and your OK. + to where your boost root directory is and you're OK. </p> <p> The comments contained in the Jamrules file above should be sufficient to get you going. </p> <h3> -<a name="hello.running_bjam"></a> - Running bjam +<a name="tutorial.hello.h2"></a> + <span class="phrase"><a name="tutorial.hello.running_bjam"></a></span><a class="link" href="hello.html#tutorial.hello.running_bjam">Running + bjam</a> </h3> <p> <span class="emphasis"><em>bjam</em></span> is run using your operating system's command line @@ -164,7 +161,7 @@ bjam <p> And so on... Finally: </p> -<pre class="programlisting">Creating library <span class="emphasis"><em>path-to-boost_python.dll</em></span> +<pre class="programlisting"> Creating library <span class="emphasis"><em>path-to-boost_python.dll</em></span> Creating library /path-to-hello_ext.exp/ **passed** ... hello.test ...updated 35 targets... @@ -182,14 +179,13 @@ bjam <td align="right"><div class="copyright-footer">Copyright © 2002-2005 Joel de Guzman, David Abrahams<p> Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top"> - http://www.boost.org/LICENSE_1_0.txt </a>) + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> </p> </div></td> </tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="../index.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="exposing.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="../index.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="exposing.html"><img src="../../images/next.png" alt="Next"></a> </div> </body> </html> diff --git a/libs/python/doc/tutorial/doc/html/python/iterators.html b/libs/python/doc/html/tutorial/tutorial/iterators.html index 9fb402b6b5..b3165a351b 100644 --- a/libs/python/doc/tutorial/doc/html/python/iterators.html +++ b/libs/python/doc/html/tutorial/tutorial/iterators.html @@ -2,29 +2,23 @@ <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Iterators</title> -<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css"> -<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> -<link rel="home" href="../index.html" title="Chapter 1. python 2.0"> -<link rel="up" href="../index.html" title="Chapter 1. python 2.0"> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Tutorial"> +<link rel="up" href="../index.html" title="Boost.Python Tutorial"> <link rel="prev" href="embedding.html" title="Embedding"> <link rel="next" href="exception.html" title="Exception Translation"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table cellpadding="2" width="100%"><tr> -<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td> -<td align="center"><a href="../../../../../../../index.html">Home</a></td> -<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td> -<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> -<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> -<td align="center"><a href="../../../../../../../more/index.htm">More</a></td> -</tr></table> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="embedding.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="exception.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="embedding.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="exception.html"><img src="../../images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="python.iterators"></a>Iterators</h2></div></div></div> +<a name="tutorial.iterators"></a><a class="link" href="iterators.html" title="Iterators">Iterators</a> +</h2></div></div></div> <p> In C++, and STL in particular, we see iterators everywhere. Python also has iterators, but these are two very different beasts. @@ -32,7 +26,7 @@ <p> <span class="bold"><strong>C++ iterators:</strong></span> </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> C++ has 5 type categories (random-access, bidirectional, forward, input, output) @@ -47,7 +41,7 @@ <p> <span class="bold"><strong>Python Iterators:</strong></span> </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> 1 category (forward) </li> @@ -89,7 +83,7 @@ <p> We can create a Python savvy iterator using the range function: </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> range(start, finish) </li> @@ -100,7 +94,7 @@ <p> Here, start/finish may be one of: </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> member data pointers </li> @@ -114,7 +108,7 @@ <p> <span class="bold"><strong>iterator</strong></span> </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> iterator<T, Policies>() </li></ul></div> <p> @@ -174,14 +168,13 @@ <td align="right"><div class="copyright-footer">Copyright © 2002-2005 Joel de Guzman, David Abrahams<p> Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top"> - http://www.boost.org/LICENSE_1_0.txt </a>) + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> </p> </div></td> </tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="embedding.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="exception.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="embedding.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="exception.html"><img src="../../images/next.png" alt="Next"></a> </div> </body> </html> diff --git a/libs/python/doc/tutorial/doc/html/python/object.html b/libs/python/doc/html/tutorial/tutorial/object.html index 7bc2aa255d..c9f4f1f58e 100644 --- a/libs/python/doc/tutorial/doc/html/python/object.html +++ b/libs/python/doc/html/tutorial/tutorial/object.html @@ -2,35 +2,32 @@ <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Object Interface</title> -<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css"> -<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> -<link rel="home" href="../index.html" title="Chapter 1. python 2.0"> -<link rel="up" href="../index.html" title="Chapter 1. python 2.0"> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Tutorial"> +<link rel="up" href="../index.html" title="Boost.Python Tutorial"> <link rel="prev" href="functions.html" title="Functions"> <link rel="next" href="embedding.html" title="Embedding"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table cellpadding="2" width="100%"><tr> -<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td> -<td align="center"><a href="../../../../../../../index.html">Home</a></td> -<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td> -<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> -<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> -<td align="center"><a href="../../../../../../../more/index.htm">More</a></td> -</tr></table> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="functions.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="embedding.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="functions.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="embedding.html"><img src="../../images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="python.object"></a>Object Interface</h2></div></div></div> -<div class="toc"><dl> -<dt><span class="section"><a href="object.html#python.basic_interface">Basic Interface</a></span></dt> -<dt><span class="section"><a href="object.html#python.derived_object_types">Derived Object types</a></span></dt> -<dt><span class="section"><a href="object.html#python.extracting_c___objects">Extracting C++ objects</a></span></dt> -<dt><span class="section"><a href="object.html#python.enums">Enums</a></span></dt> -<dt><span class="section"><a href="object.html#python.creating_python_object">Creating <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span></code> from <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code></a></span></dt> +<a name="tutorial.object"></a><a class="link" href="object.html" title="Object Interface">Object Interface</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="object.html#tutorial.object.basic_interface">Basic Interface</a></span></dt> +<dt><span class="section"><a href="object.html#tutorial.object.derived_object_types">Derived Object + types</a></span></dt> +<dt><span class="section"><a href="object.html#tutorial.object.extracting_c_objects">Extracting C++ + objects</a></span></dt> +<dt><span class="section"><a href="object.html#tutorial.object.enums">Enums</a></span></dt> +<dt><span class="section"><a href="object.html#tutorial.object.creating_python_object">Creating <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span></code> + from <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code></a></span></dt> </dl></div> <p> Python is dynamically typed, unlike C++ which is statically typed. Python variables @@ -46,11 +43,12 @@ minimize the learning curve significantly. </p> <p> - <span class="inlinemediaobject"><img src="../images/python.png" alt="python"></span> + <span class="inlinemediaobject"><img src="../../images/python.png"></span> </p> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.basic_interface"></a>Basic Interface</h3></div></div></div> +<a name="tutorial.object.basic_interface"></a><a class="link" href="object.html#tutorial.object.basic_interface" title="Basic Interface">Basic Interface</a> +</h3></div></div></div> <p> Class <code class="literal">object</code> wraps <code class="literal">PyObject*</code>. All the intricacies of dealing with <code class="literal">PyObject</code>s such as managing @@ -92,12 +90,14 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.derived_object_types"></a>Derived Object types</h3></div></div></div> +<a name="tutorial.object.derived_object_types"></a><a class="link" href="object.html#tutorial.object.derived_object_types" title="Derived Object types">Derived Object + types</a> +</h3></div></div></div> <p> Boost.Python comes with a set of derived <code class="literal">object</code> types corresponding to that of Python's: </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> list </li> @@ -168,9 +168,10 @@ <div class="sidebar"> <div class="titlepage"></div> <p> - <span class="inlinemediaobject"><img src="../images/alert.png" alt="alert"></span> <span class="bold"><strong>Beware</strong></span> the common pitfall - of forgetting that the constructors of most of Python's mutable types make - copies, just as in Python. + <span class="inlinemediaobject"><img src="../../images/alert.png"></span> + <span class="bold"><strong>Beware</strong></span> the common pitfall of forgetting + that the constructors of most of Python's mutable types make copies, just + as in Python. </p> </div> <p> @@ -186,8 +187,9 @@ <span class="identifier">d</span><span class="special">[</span><span class="char">'whatever'</span><span class="special">]</span> <span class="special">=</span> <span class="number">3</span><span class="special">;</span> <span class="comment">// modifies the copy</span> </pre> <h3> -<a name="derived_object_types.class__lt_t_gt__as_objects"></a> - class_<T> as objects +<a name="tutorial.object.derived_object_types.h0"></a> + <span class="phrase"><a name="tutorial.object.derived_object_types.class_t_as_objects"></a></span><a class="link" href="object.html#tutorial.object.derived_object_types.class_t_as_objects">class_<T> + as objects</a> </h3> <p> Due to the dynamic nature of Boost.Python objects, any <code class="literal">class_<T></code> @@ -208,7 +210,9 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.extracting_c___objects"></a>Extracting C++ objects</h3></div></div></div> +<a name="tutorial.object.extracting_c_objects"></a><a class="link" href="object.html#tutorial.object.extracting_c_objects" title="Extracting C++ objects">Extracting C++ + objects</a> +</h3></div></div></div> <p> At some point, we will need to get C++ values out of object instances. This can be achieved with the <code class="literal">extract<T></code> function. Consider @@ -243,7 +247,8 @@ <span class="identifier">Vec2</span><span class="special">&</span> <span class="identifier">v</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">();</span> <span class="special">...</span> </pre> <p> - <span class="inlinemediaobject"><img src="../images/tip.png" alt="tip"></span> The astute reader might have noticed that the <code class="literal">extract<T></code> + <span class="inlinemediaobject"><img src="../../images/tip.png"></span> + The astute reader might have noticed that the <code class="literal">extract<T></code> facility in fact solves the mutable copying problem: </p> <pre class="programlisting"><span class="identifier">dict</span> <span class="identifier">d</span> <span class="special">=</span> <span class="identifier">extract</span><span class="special"><</span><span class="identifier">dict</span><span class="special">>(</span><span class="identifier">x</span><span class="special">.</span><span class="identifier">attr</span><span class="special">(</span><span class="string">"__dict__"</span><span class="special">));</span> @@ -252,7 +257,8 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.enums"></a>Enums</h3></div></div></div> +<a name="tutorial.object.enums"></a><a class="link" href="object.html#tutorial.object.enums" title="Enums">Enums</a> +</h3></div></div></div> <p> Boost.Python has a nifty facility to capture and wrap C++ enums. While Python has no <code class="literal">enum</code> type, we'll often want to expose our C++ enums @@ -279,7 +285,7 @@ </p> <div class="note"><table border="0" summary="Note"> <tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"> @@ -317,7 +323,8 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.creating_python_object"></a>Creating <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span></code> from <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code> +<a name="tutorial.object.creating_python_object"></a><a class="link" href="object.html#tutorial.object.creating_python_object" title="Creating boost::python::object from PyObject*">Creating <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span></code> + from <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code></a> </h3></div></div></div> <p> When you want a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span></code> to manage a pointer to <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code> @@ -347,14 +354,13 @@ <td align="right"><div class="copyright-footer">Copyright © 2002-2005 Joel de Guzman, David Abrahams<p> Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top"> - http://www.boost.org/LICENSE_1_0.txt </a>) + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> </p> </div></td> </tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="functions.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="embedding.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> +<a accesskey="p" href="functions.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="embedding.html"><img src="../../images/next.png" alt="Next"></a> </div> </body> </html> diff --git a/libs/python/doc/tutorial/doc/html/python/techniques.html b/libs/python/doc/html/tutorial/tutorial/techniques.html index 34cfc44426..7ba213f130 100644 --- a/libs/python/doc/tutorial/doc/html/python/techniques.html +++ b/libs/python/doc/html/tutorial/tutorial/techniques.html @@ -2,32 +2,28 @@ <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>General Techniques</title> -<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css"> -<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> -<link rel="home" href="../index.html" title="Chapter 1. python 2.0"> -<link rel="up" href="../index.html" title="Chapter 1. python 2.0"> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="../index.html" title="Boost.Python Tutorial"> +<link rel="up" href="../index.html" title="Boost.Python Tutorial"> <link rel="prev" href="exception.html" title="Exception Translation"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table cellpadding="2" width="100%"><tr> -<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td> -<td align="center"><a href="../../../../../../../index.html">Home</a></td> -<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td> -<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> -<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> -<td align="center"><a href="../../../../../../../more/index.htm">More</a></td> -</tr></table> +<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="exception.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a> +<a accesskey="p" href="exception.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="python.techniques"></a>General Techniques</h2></div></div></div> -<div class="toc"><dl> -<dt><span class="section"><a href="techniques.html#python.creating_packages">Creating Packages</a></span></dt> -<dt><span class="section"><a href="techniques.html#python.extending_wrapped_objects_in_python">Extending Wrapped Objects in Python</a></span></dt> -<dt><span class="section"><a href="techniques.html#python.reducing_compiling_time">Reducing Compiling Time</a></span></dt> +<a name="tutorial.techniques"></a><a class="link" href="techniques.html" title="General Techniques">General Techniques</a> +</h2></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="techniques.html#tutorial.techniques.creating_packages">Creating Packages</a></span></dt> +<dt><span class="section"><a href="techniques.html#tutorial.techniques.extending_wrapped_objects_in_pyt">Extending + Wrapped Objects in Python</a></span></dt> +<dt><span class="section"><a href="techniques.html#tutorial.techniques.reducing_compiling_time">Reducing + Compiling Time</a></span></dt> </dl></div> <p> Here are presented some useful techniques that you can use while wrapping code @@ -35,7 +31,8 @@ </p> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.creating_packages"></a>Creating Packages</h3></div></div></div> +<a name="tutorial.techniques.creating_packages"></a><a class="link" href="techniques.html#tutorial.techniques.creating_packages" title="Creating Packages">Creating Packages</a> +</h3></div></div></div> <p> A Python package is a collection of modules that provide to the user a certain functionality. If you're not familiar on how to create packages, a good introduction @@ -95,7 +92,7 @@ </p> <div class="note"><table border="0" summary="Note"> <tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"><p> @@ -224,7 +221,9 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.extending_wrapped_objects_in_python"></a>Extending Wrapped Objects in Python</h3></div></div></div> +<a name="tutorial.techniques.extending_wrapped_objects_in_pyt"></a><a class="link" href="techniques.html#tutorial.techniques.extending_wrapped_objects_in_pyt" title="Extending Wrapped Objects in Python">Extending + Wrapped Objects in Python</a> +</h3></div></div></div> <p> Thanks to Python's flexibility, you can easily add new methods to a class, even after it was already created: @@ -244,7 +243,7 @@ <span class="identifier">A</span> <span class="identifier">C</span> <span class="identifier">instance</span><span class="special">!</span> </pre> <p> - Yes, Python rox. <span class="inlinemediaobject"><img src="../images/smiley.png" alt="smiley"></span> + Yes, Python rox. <span class="inlinemediaobject"><img src="../../images/smiley.png"></span> </p> <p> We can do the same with classes that were wrapped with Boost.Python. Suppose @@ -258,7 +257,7 @@ <span class="special">}</span> </pre> <p> - If we are using the technique from the previous session, <a class="link" href="techniques.html#python.creating_packages" title="Creating Packages">Creating + If we are using the technique from the previous session, <a class="link" href="../">Creating Packages</a>, we can code directly into <code class="literal">geom/__init__.py</code>: </p> <pre class="programlisting"><span class="keyword">from</span> <span class="identifier">_geom</span> <span class="keyword">import</span> <span class="special">*</span> @@ -274,7 +273,7 @@ <span class="bold"><strong>All</strong></span> point instances created from C++ will also have this member function! This technique has several advantages: </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> Cut down compile times to zero for these additional functions </li> @@ -338,7 +337,9 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="python.reducing_compiling_time"></a>Reducing Compiling Time</h3></div></div></div> +<a name="tutorial.techniques.reducing_compiling_time"></a><a class="link" href="techniques.html#tutorial.techniques.reducing_compiling_time" title="Reducing Compiling Time">Reducing + Compiling Time</a> +</h3></div></div></div> <p> If you have ever exported a lot of classes, you know that it takes quite a good time to compile the Boost.Python wrappers. Plus the memory consumption @@ -400,7 +401,7 @@ </p> <div class="note"><table border="0" summary="Note"> <tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"><p> @@ -411,7 +412,7 @@ </table></div> <div class="note"><table border="0" summary="Note"> <tr> -<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"><p> @@ -427,14 +428,13 @@ <td align="right"><div class="copyright-footer">Copyright © 2002-2005 Joel de Guzman, David Abrahams<p> Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top"> - http://www.boost.org/LICENSE_1_0.txt </a>) + file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> </p> </div></td> </tr></table> <hr> <div class="spirit-nav"> -<a accesskey="p" href="exception.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a> +<a accesskey="p" href="exception.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a> </div> </body> </html> diff --git a/libs/python/doc/html/tutorial/tutorial_HTML.manifest b/libs/python/doc/html/tutorial/tutorial_HTML.manifest new file mode 100644 index 0000000000..15d1dc13ad --- /dev/null +++ b/libs/python/doc/html/tutorial/tutorial_HTML.manifest @@ -0,0 +1,9 @@ +index.html +tutorial/hello.html +tutorial/exposing.html +tutorial/functions.html +tutorial/object.html +tutorial/embedding.html +tutorial/iterators.html +tutorial/exception.html +tutorial/techniques.html diff --git a/libs/python/doc/index.html b/libs/python/doc/index.html index e600366fec..d52257577e 100644 --- a/libs/python/doc/index.html +++ b/libs/python/doc/index.html @@ -1,184 +1,13 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../../../boost.css"> - - <title>Boost.Python</title> + <meta http-equiv="refresh" content="0; URL=html/index.html"> </head> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center">Boost.Python</h1> - - <h2 align="center">Index</h2> - </td> - - - <td align="right"> - - <form method="get" action="http://www.google.com/custom"> - <p> - <span id= "search-choice"> - Search - <select name="hq" id="hq"> - <option label="All Documentation" value= - "site:www.boost.org inurl:www.boost.org/libs/python/doc"> - All Documentation - </option> - <option label="Tutorial" value= - "site:www.boost.org inurl:www.boost.org/libs/python/doc/tutorial"> - Tutorial - </option> - <option label="Reference" value= - "site:www.boost.org inurl:www.boost.org/libs/python/doc/v2"> - Reference - </option> - </select> - <br> - </span> - - <span id="search-text"> - <input type="text" name="q" id="q" size="31" maxlength="255" alt="Search Text" /> - </span> - - <br> - <span id= "google"> - <a href= "http://www.google.com/search"> - <img src="../../../more/google_logo_25wht.gif" alt="Google" border="0" /></a>Powered - </span> - - <span id="go"> - <input type="image" name="search" src="../../../more/space.gif" alt="Search" id="search-button" /> - </span> - - <br> - <input type="hidden" name="cof" value= "LW:277;L:http://www.boost.org/boost.png;LH:86;AH:center;GL:0;S:http://www.boost.org;AWFID:9b83d16ce652ed5a;" /> - <input type="hidden" name="sa" value= "Google Search" /> - <input type="hidden" name= "domains" value= "www.boost.org;mail.python.org" /></p> - </form> - - </td> - </tr> -<tr> - - </tr> - </table> - <hr> - - - <h2>Synopsis</h2> - Welcome to version 2 of <b>Boost.Python</b>, a C++ library which enables - seamless interoperability between C++ and the <a href= - "http://www.python.org">Python</a> programming language. The new version - has been rewritten from the ground up, with a more convenient and - flexible interface, and many new capabilities, including support for: - - <ul> - <li>References and Pointers</li> - - <li>Globally Registered Type Coercions</li> - - <li>Automatic Cross-Module Type Conversions</li> - - <li>Efficient Function Overloading</li> - - <li>C++ to Python Exception Translation</li> - - <li>Default Arguments</li> - - <li>Keyword Arguments</li> - - <li>Manipulating Python objects in C++</li> - - <li>Exporting C++ Iterators as Python Iterators</li> - - <li>Documentation Strings</li> - </ul> - The development of these features was funded in part by grants to <a - href="http://www.boost-consulting.com">Boost Consulting</a> from the <a - href="http://www.llnl.gov/">Lawrence Livermore National Laboratories</a> - and by the <a href="http://cci.lbl.gov/">Computational Crystallography - Initiative</a> at Lawrence Berkeley National Laboratories. - - <hr> - - <h2>Contents</h2> - - <dl class="index"> - <dt><a href="tutorial/index.html">Tutorial Introduction</a></dt> - - <dt><a href="building.html">Building and Testing</a></dt> - - <dt><a href="v2/reference.html">Reference Manual</a></dt> - - <dt>Suites:</dt> - <dd> - <ul> - <li><a href="v2/pickle.html">Pickle</a></li> - <li><a href="v2/indexing.html">Indexing</a></li> - </ul> - </dd> - - <dt><a href="v2/configuration.html">Configuration Information</a></dt> - - <dt><a href="v2/platforms.html">Known Working Platforms and - Compilers</a></dt> - - <dt><a href="v2/definitions.html">Definitions</a></dt> - - <dt><a href="projects.html">Projects using Boost.Python</a></dt> - - <dt><a href="support.html">Support Resources</a></dt> - - <dt><a href="v2/faq.html">Frequently Asked Questions (FAQs)</a></dt> - - <dt><a href="http://www.language-binding.net/pyplusplus/pyplusplus.html">Py++ Boost.Python code generator</a></dt> - - <dt><a href="../pyste/index.html">Pyste Boost.Python code generator (no longer maintained)</a></dt> - - <dt><a href="internals.html">Internals Documentation</a></dt> - - <dt><a href="news.html">News/Change Log</a></dt> - - <dt><a href="../todo.html">TODO list</a></dt> - - <dt><a href="v2/progress_reports.html">LLNL Progress Reports</a></dt> - - <dt><a href="v2/acknowledgments.html">Acknowledgments</a></dt> - </dl> - <hr> - - <h2>Articles</h2> - - "<a href="PyConDC_2003/bpl.html">Building Hybrid - Systems With Boost Python</a>", by Dave Abrahams and Ralf - W. Grosse-Kunstleve (<a href="PyConDC_2003/bpl.pdf">PDF</a>) - - <hr> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 26 August, 2003 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002-2003.</i></p> + <body> + Automatic redirection failed, click this + <a href="html/index.html">link</a> <hr> + <p>© Copyright Stefan Seefeld, 2015</p> + <p>Distributed under the Boost Software License, Version 1.0. (See accompanying + file <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p> </body> </html> - diff --git a/libs/python/doc/index.qbk b/libs/python/doc/index.qbk new file mode 100644 index 0000000000..eaf0df9cf3 --- /dev/null +++ b/libs/python/doc/index.qbk @@ -0,0 +1,19 @@ +[library Boost.Python + [quickbook 1.3] + [authors [Abrahams, David], [Seefeld, Stefan]] + [copyright 2002 2003 2004 2005 2015 David Abrahams, Stefan Seefeld] + [category inter-language support] + [id python] + [purpose + Reflects C++ classes and functions into Python + ] + [license + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + [@http://www.boost.org/LICENSE_1_0.txt]) + ] +] + +[/ QuickBook Document version 1.3 ] + +[include preface.qbk] diff --git a/libs/python/doc/news.html b/libs/python/doc/news.html deleted file mode 100644 index da57caeb30..0000000000 --- a/libs/python/doc/news.html +++ /dev/null @@ -1,371 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> - <meta name="generator" content= - "HTML Tidy for Cygwin (vers 1st September 2004), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> - <link rel="stylesheet" type="text/css" href="boost.css"> - - <title>Boost.Python - News/Change Log</title> -</head> - -<body link="#0000FF" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="index.html">Boost.Python</a></h1> - - <h2 align="center">News/Change Log</h2> - </td> - </tr> - </table> - <hr> - - <dl class="page-index"> - - <dt>Current SVN</dt> - <dd> - <ul> - <li>Python 3 support:</li> - <ul> - <li>All the current Boost.Python test cases passed. Extension modules using - Boost.Python expected to support Python 3 smoothly.</li> - <li>Introduced <code>object.contains</code> where <code>x.contains(y)</code> - is equivalent to Python code <code>y in x</code>. - Now <code>dict.has_key</code> is just a wrapper of <code>object.contains</code>. - </li> - <li>When building against Python 3, <code>str.decode</code> will be removed.</li> - <li>When building against Python 3, the original signature of <code>list.sort</code>, which is: - <pre>void sort(object_cref cmpfunc);</pre> - will change to: - <pre>void sort(args_proxy const &args, kwds_proxy const &kwds);</pre> - - This is because in Python 3 <code>list.sort</code> requires all its arguments be keyword arguments. - So you should call it like this: - <pre>x.sort(*tuple(), **dict(make_tuple(make_tuple("reverse", true))));</pre> - - </li> - <li>According to <a href="http://www.python.org/dev/peps/pep-3123/">PEP 3123</a>, - when building Boost.Python against Python older than 2.6, the following macros will - be defined in Boost.Python header: - <pre> -# define Py_TYPE(o) (((PyObject*)(o))->ob_type) -# define Py_REFCNT(o) (((PyObject*)(o))->ob_refcnt) -# define Py_SIZE(o) (((PyVarObject*)(o))->ob_size)</pre> - So extension writers can use these macro directly, to make code clean and compatible with Python 3. - </li> - </ul> - </ul> - </dd> - - <dt>1.39.0 Release</dt> - - <dd> - <ul> - <li>Pythonic signatures are now automatically appended to the - docstrings. - - <li>Use <a href="v2/docstring_options.html" - ><code>docstring_options.hpp</code></a> header - control the content of docstrings. - - <li>This new feature increases the size of the modules by about 14%. - If this is not acceptable it can be turned off by defining the macro - BOOST_PYTHON_NO_PY_SIGNATURES. Modules compiled with and without the macro - defined are compatible. - </li> - <li> If BOOST_PYTHON_NO_PY_SIGNATURES is undefined, this version defines the - macro BOOST_PYTHON_SUPPORTS_PY_SIGNATURES. This allows writing code that will compile - with older version of Boost.Python (see <a href="v2/pytype_function.html#examples">here</a>). - </li> - <li>By defining BOOST_PYTHON_PY_SIGNATURES_PROPER_INIT_SELF_TYPE, and at a cost - of another 14% size increase, proper pythonic type is generated for the "self" - parameter of the __init__ methods. - </li> - - <li> To support this new feature changes were made to the - <a href="v2/to_python_converter.html"><code>to_python_converter.hpp</code></a>, - <a href="v2/default_call_policies.html"><code>default_call_policies</code></a>, - <a href="v2/ResultConverter.html"><code>ResultConverter</code></a>, - <a href="v2/CallPolicies.html"><code>CallPolicies</code></a> and some others. - Efforts were made not to have interface breaking changes. - </li> - - </ul> - </dd> - - <dt>12 May 2007 - 1.34.0 release</dt> - - <dd> - <ul> - <li>C++ signatures are now automatically appended to the - docstrings. - - <li>New <a href="v2/docstring_options.html" - ><code>docstring_options.hpp</code></a> header to - control the content of docstrings. - - <li>Support for converting <code>void*</code> to/from python, - with <code><a - href="v2/opaque.html">opaque_pointer_converter</a></code> - as the return value policy. Thanks to Niall Douglas for the - initial patch. - </ul> - </dd> - - <dt>19 October 2005 - 1.33.1 release</dt> - - <dd> - <ul> - <li><code>wrapper<T></code> can now be used as expected with a - held type of <i>some-smart-pointer</i><code><T></code></li> - - <li>The build now assumes Python 2.4 by default, rather than 2.2</li> - - <li>Support Python that's built without Unicode support</li> - - <li>Support for wrapping classes with overloaded address-of - (<code>&</code>) operators</li> - </ul> - </dd> - - <dt>14 August 2005 - 1.33 release</dt> - - <dd> - <ul> - <li>Support for docstrings on nonstatic properties.</li> - - <li>We now export the client-provided docstrings for - <code>init<optional<> ></code> and - <i>XXX</i><code>_FUNCTION_OVERLOADS()</code> for only the last - overload.</li> - - <li>Fixed some support for Embedded VC++ 4</li> - - <li>Better support for rvalue from-python conversions of shared_ptr: - always return a pointer that holds the owning python object *unless* - the python object contains a NULL shared_ptr holder of the right - type.</li> - - <li>Support for exposing <code>vector<T*></code> with the - indexing suite.</li> - - <li>Support for GCC-3.3 on MacOS.</li> - - <li>updated visual studio project build file to include two new files - (slice.cpp and wrapper.cpp)</li> - - <li>Added search feature to the index page.</li> - - <li>Numerous fixes to the tutorial</li> - - <li>Numerous workarounds for MSVC 6 and 7, GCC 2.96, and EDG - 2.45</li> - </ul> - </dd> - - <dt>11 March 2005</dt> - - <dd> - <ul> - <li>Added a hack that will fool PyDoc into working with Boost.Python, - thanks to Nick Rasmussen</li> - </ul> - </dd> - - <dt>19 November 2004 - 1.32 release</dt> - - <dd> - <ul> - <li>Updated to use the Boost Software License.</li> - - <li>A new, <a href= - "tutorial/doc/html/python/exposing.html#python.class_virtual_functions"> - better method of wrapping classes with virtual functions</a> has been - implemented.</li> - - <li>Support for upcoming GCC symbol export control features have been - folded in, thanks to Niall Douglas.</li> - - <li>Improved support for <code>std::auto_ptr</code>-like types.</li> - - <li>The Visual C++ bug that makes top-level <i>cv-qualification</i> - of function parameter types part of the function type has been worked - around.</li> - - <li>Components used by other libraries have been moved out of - <code>python/detail</code> and into <code>boost/detail</code> to - improve dependency relationships.</li> - - <li>Miscellaneous bug fixes and compiler workarounds.</li> - </ul> - </dd> - - <dt>8 Sept 2004</dt> - - <dd>Support for Python's Bool type, thanks to <a href= - "mailto:dholth-at-fastmail.fm">Daniel Holth</a>.</dd> - - <dt>11 Sept 2003</dt> - - <dd> - <ul> - <li>Changed the response to multiple to-python converters being - registered for the same type from a hard error into warning; - Boost.Python now reports the offending type in the message.</li> - - <li>Added builtin <code>std::wstring</code> conversions</li> - - <li>Added <code>std::out_of_range</code> => Python - <code>IndexError</code> exception conversion, thanks to <a href= - "mailto:RaoulGough-at-yahoo.co.uk">Raoul Gough</a></li> - </ul> - </dd> - - <dt>9 Sept 2003</dt> - - <dd>Added new <code><a href="v2/str.html#str-spec">str</a></code></dd> - - <dt>constructors which take a range of characters, allowing strings - containing nul (<code>'\0'</code>) characters.</dt> - - <dt>8 Sept 2003</dt> - - <dd>Added the ability to create methods from function objects (with an - <code>operator()</code>); see the <a href= - "v2/make_function.html#make_function-spec">make_function</a> docs for - more info.</dd> - - <dt>10 August 2003</dt> - - <dd>Added the new <code>properties</code> unit tests contributed by - <a href="mailto:romany-at-actimize.com">Roman Yakovenko</a> and - documented <code>add_static_property</code> at his urging.</dd> - - <dt>1 August 2003</dt> - - <dd> - Added the new <code>arg</code> class contributed by <a href= - "mailto:nickm-at-sitius.com">Nikolay Mladenov</a> which supplies the - ability to wrap functions that can be called with ommitted arguments in - the middle: - <pre> -void f(int x = 0, double y = 3.14, std::string z = std::string("foo")); - -BOOST_PYTHON_MODULE(test) -{ - def("f", f - , (arg("x", 0), arg("y", 3.14), arg("z", "foo"))); -} - -</pre>And in Python: - <pre> ->>> import test ->>> f(0, z = "bar") ->>> f(z = "bar", y = 0.0) -</pre>Thanks, Nikolay! - </dd> - - <dt>22 July 2003</dt> - - <dd>Killed the dreaded "bad argument type for builtin operation" error. - Argument errors now show the actual and expected argument types!</dd> - - <dt>19 July 2003</dt> - - <dd>Added the new <code><a href= - "v2/return_arg.html">return_arg</a></code> policy from <a href= - "mailto:nickm-at-sitius.com">Nikolay Mladenov</a>. Thanks, Nikolay!</dd> - - <dt>18 March, 2003</dt> - - <dd><a href="mailto:Gottfried.Ganssauge-at-haufe.de">Gottfried - Ganßauge</a> has contributed <a href= - "v2/opaque.html">opaque pointer support</a>.<br> - <a href="mailto:nicodemus-at-globalite.com.br">Bruno da Silva de - Oliveira</a> has contributed the exciting <a href= - "../pyste/index.html">Pyste</a> ("Pie-steh") package.</dd> - - <dt>24 February 2003</dt> - - <dd>Finished improved support for <code>boost::shared_ptr</code>. Now any - wrapped object of C++ class <code>X</code> can be converted automatically - to <code>shared_ptr<X></code>, regardless of how it was wrapped. - The <code>shared_ptr</code> will manage the lifetime of the Python object - which supplied the <code>X</code>, rather than just the <code>X</code> - object itself, and when such a <code>shared_ptr</code> is converted back - to Python, the original Python object will be returned.</dd> - - <dt>19 January 2003</dt> - - <dd>Integrated <code>staticmethod</code> support from <a href= - "mailto:nickm-at-sitius.com">Nikolay Mladenov</a>. Thanks, Nikolay!</dd> - - <dt>29 December 2002</dt> - - <dd>Added Visual Studio project file and instructions from Brett Calcott. - Thanks, Brett!</dd> - - <dt>20 December 2002</dt> - - <dd>Added automatic downcasting for pointers, references, and smart - pointers to polymorphic class types upon conversion to python</dd> - - <dt>18 December 2002</dt> - - <dd>Optimized from_python conversions for wrapped classes by putting the - conversion logic in the shared library instead of registering separate - converters for each class in each extension module</dd> - - <dt>19 November 2002</dt> - - <dd>Removed the need for users to cast base class member function - pointers when used as arguments to <a href= - "v2/class.html#class_-spec-modifiers">add_property</a></dd> - - <dt>13 December 2002</dt> - - <dd>Allow exporting of <a href= - "v2/enum.html#enum_-spec"><code>enum_</code></a> values into enclosing - <a href="v2/scope.html#scope-spec"><code>scope</code></a>.<br> - Fixed unsigned integer conversions to deal correctly with numbers that - are out-of-range of <code>signed long</code>.</dd> - - <dt>14 November 2002</dt> - - <dd>Auto-detection of class data members wrapped with <a href= - "v2/data_members.html#make_getter-spec"><code>make_getter</code></a></dd> - - <dt>13 November 2002</dt> - - <dd>Full Support for <code>std::auto_ptr<></code> added.</dd> - - <dt>October 2002</dt> - - <dd>Ongoing updates and improvements to tutorial documentation</dd> - - <dt>10 October 2002</dt> - - <dd>Boost.Python V2 is released!</dd> - </dl> - <hr> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 19 November 2004 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p> - - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002-2003.</i></p> -</body> -</html> diff --git a/libs/python/doc/preface.qbk b/libs/python/doc/preface.qbk new file mode 100644 index 0000000000..b04d88e7df --- /dev/null +++ b/libs/python/doc/preface.qbk @@ -0,0 +1,26 @@ +[preface Introduction +[quickbook 1.6] +] + +[section Synopsis] + +Welcome to version 2 of Boost.Python, a C++ library which enables seamless interoperability between C++ and the Python programming language. The new version has been rewritten from the ground up, with a more convenient and flexible interface, and many new capabilities, including support for: + + * References and Pointers + * Globally Registered Type Coercions + * Automatic Cross-Module Type Conversions + * Efficient Function Overloading + * C++ to Python Exception Translation + * Default Arguments + * Keyword Arguments + * Manipulating Python objects in C++ + * Exporting C++ Iterators as Python Iterators + * Documentation Strings + +The development of these features was funded in part by grants to Boost Consulting from the Lawrence Livermore National Laboratories and by the Computational Crystallography Initiative at Lawrence Berkeley National Laboratories. + +[endsect] +[section Articles] + +"Building Hybrid Systems With Boost Python", by Dave Abrahams and Ralf W. Grosse-Kunstleve (PDF) +[endsect] diff --git a/libs/python/doc/projects.html b/libs/python/doc/projects.html deleted file mode 100644 index 05eb52326c..0000000000 --- a/libs/python/doc/projects.html +++ /dev/null @@ -1,472 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> - <meta name="generator" content= - "HTML Tidy for Cygwin (vers 1st September 2004), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html"> - <link rel="stylesheet" type="text/css" href="boost.css"> - - <title>Boost.Python - Projects using Boost.Python</title> -</head> - -<body link="#0000FF" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="index.html">Boost.Python</a></h1> - - <h2 align="center">Projects using Boost.Python</h2> - </td> - </tr> - </table> - <hr> - - <h2>Introduction</h2> - - <p>This is a partial list of projects using Boost.Python. If you are using - Boost.Python as your Python/C++ binding solution, we'd be proud to list - your project on this page. Just <a href= - "mailto:c++-sig@python.org">post</a> a short description of your project - and how Boost.Python helps you get the job done, and we'll add it to this - page .</p> - <hr> - - <h3>Data Analysis</h3> - - <dl class="page-index"> - <dt><b><a href="http://www.neuralynx.com">NeuraLab</a></b></dt> - - <dd>Neuralab is a data analysis environment specifically tailored for - neural data from <a href="http://www.neuralynx.com">Neuralynx</a> - acquisition systems. Neuralab combines presentation quality graphics, a - numerical analysis library, and the <a href= - "http://www.python.org">Python</a> scripting engine in a single - application. With Neuralab, Neuralynx users can perform common analysis - tasks with just a few mouse clicks. More advanced users can create custom - Python scripts, which can optionally be assigned to menus and mouse - clicks.</dd> - </dl> - - <dl class="page-index"> - <dt><b>TSLib</b> - <a href="http://www.fortressinv.com">Fortress - Investment Group LLC</a></dt> - - <dd> - Fortress Investment Group has contracted <a href= - "http://www.boost-consulting.com">Boost Consulting</a> to develop core - internal financial analysis tools in C++ and to prepare Python bindings - for them using Boost.Python. - - <p>Tom Barket of Fortress writes:</p> - - <blockquote> - We have a large C++ analytical library specialized for research in - finance and economics, built for speed and mission critical - stability. Yet Python offers us the flexibility to test out new ideas - quickly and increase the productivity of our time versus working in - C++. There are several key features which make Python stand out. Its - elegance, stability, and breadth of resources on the web are all - valuable, but the most important is its extensibility, due to its - open source transparency. Boost.Python makes Python extensibility - extremely simple and straightforward, yet preserves a great deal of - power and control. - </blockquote> - </dd> - </dl> - - <h3>Educational</h3> - - <dl class="page-index"> - <dt><a href="http://edu.kde.org/kig"><b>Kig</b></a></dt> - - <dd> - <p>KDE Interactive Geometry is a high-school level educational tool, - built for the KDE desktop. It is a nice tool to let students work with - geometrical constructions. It is meant to be the most intuitive, yet - featureful application of its kind.</p> - - <p>Versions after 0.6.x (will) support objects built by the user - himself in the Python language. The exporting of the relevant internal - API's were done using Boost.Python, which made the process very - easy.</p> - </dd> - </dl> - - <h3>Enterprise Software</h3> - - <dl class="page-index"> - <dt><b><a href="http://openwbem.sourceforge.net">OpenWBEM</a></b></dt> - - <dd> - The OpenWBEM project is an effort to develop an open-source - implementation of Web Based Enterprise Management suitable for - commercial and non-commercial application - - <p><a href="mailto:dnuffer@sco.com">Dan Nuffer</a> writes:</p> - - <blockquote> - I'm using Boost.Python to wrap the client API of OpenWBEM.This will - make it easier to do rapid prototyping, testing, and scripting when - developing management solutions that use WBEM. - </blockquote> - </dd> - - <dt><b><a href="http://www.transversal.com">Metafaq</a></b></dt> - - <dd> - Metafaq, from <a href="http://www.transversal.com">Transversal, - Inc.</a>, is an enterprise level online knowledge base management - system. - - <p><a href="mailto:ben.young-at-transversal.com">Ben Young</a> - writes:</p> - - <blockquote> - Boost.Python is used in an automated process to generate python - bindings to our api which is exposed though multiple backends and - frontends. This allows us to write quick tests and bespoke scripts to - perform one off tasks without having to go through the full - compilation cycle. - </blockquote> - </dd> - </dl> - - <h3>Games</h3> - - <dl> - <dt><b><a href="http://www.firaxis.com">Civilization IV</a></b></dt> - </dl> - - <blockquote> - “The fourth game in the PC strategy series that has sold over five - million copies, Sid Meier's Civilization IV is a bold step forward for - the franchise, with spectacular new 3D graphics and all-new single and - multiplayer content. Civilization IV will also set a new standard for - user-modification, allowing gamers to create their own add-ons using - Python and XML. - - <p>Sid Meier's Civilization IV will be released for PC in late 2005. For - more information please visit <a href= - "http://www.firaxis.com">http://www.firaxis.com</a> or write <a href= - "mailto:kgilmore@firaxis.com">kgilmore@firaxis.com</a>”</p> - </blockquote> - - <p>Boost.Python is used as the interface layer between the C++ game code - and Python. Python is used for many purposes in the game, including map - generation, interface screens, game events, tools, tutorials, etc. Most - high-level game operations have been exposed to Python in order to give - modders the power they need to customize the game.</p> - - <blockquote> - -Mustafa Thamer, Civ4 Lead Programmer - </blockquote> - - <dl class="page-index"> - <dt><b><a href="http://vegastrike.sourceforge.net">Vega - Strike</a></b></dt> - - <dd> - <a href="http://vegastrike.sourceforge.net">Vega Strike</a> is the 3D - Space Simulator that allows you to trade and bounty hunt in a vast - universe. Players face dangers, decisions, piracy, and aliens. - - <p><a href="http://vegastrike.sourceforge.net">Vega Strike</a> has - decided to base its scripting on python, using boost as the layer - between the class hierarchy in python and the class hierarchy in C++. - The result is a very flexible scripting system that treats units as - native python classes when designing missions or writing AI's.</p> - - <p>A large economic and planetary simulation is currently being run in - the background in python and the results are returned back into C++ in - the form of various factions' spaceships appearing near worlds that - they are simulated to be near in python if the player is in the general - neighborhood.</p> - </dd> - </dl> - - <h3>Graphics</h3> - - <dl class="page-index"> - <dt><b><a href="http://sourceforge.net/projects/pyosg">OpenSceneGraph - Bindings</a></b></dt> - - <dd><a href="mailto:gideon@computer.org">Gideon May</a> has created a set - of bindings for <a href= - "http://www.openscenegraph.org">OpenSceneGraph</a>, a cross-platform - C++/OpenGL library for the real-time visualization.<br> - </dd> - - <dt><b><a href= - "http://www.slac.stanford.edu/grp/ek/hippodraw/index.html">HippoDraw</a></b></dt> - - <dd> - HippoDraw is a data analysis environment consisting of a canvas upon - which graphs such as histograms, scattter plots, etc, are prsented. It - has a highly interactive GUI interface, but some things you need to do - with scripts. HippoDraw can be run as Python extension module so that - all the manipulation can be done from either Python or the GUI. - - <p>Before the web page came online, <a href= - "mailto:Paul_Kunz@SLAC.Stanford.EDU">Paul F. Kunz</a> wrote:</p> - - <blockquote> - Don't have a web page for the project, but the organization's is - <a href= - "http://www.slac.stanford.edu">http://www.slac.stanford.edu</a> (the - first web server site in America, I installed it). - </blockquote>Which was just too cool a piece of trivia to omit.<br> - - </dd> - - <dt><a href="http://www.iplt.org"><b>IPLT</b></a></dt> - - <dd> - <a href="mailto:ansgar.philippsen-at-unibas.ch">Ansgar Philippsen</a> - writes: - - <blockquote> - IPLT is an image processing library and toolbox for the structural - biology electron microscopy community. I would call it a - budding/evolving project, since it is currently not in production - stage, but rather under heavy development. Python is used as the main - scripting/interaction level, but also for rapid prototyping, since - the underlying C++ class library is pretty much fully exposed via - boost.python (at least the high-level interface). The combined power - of C++ and Python for this project turned out to be just awesome. - </blockquote><br> - - </dd> - - <dt><a href= - "http://www.procoders.net/pythonmagick"><b>PythonMagick</b></a></dt> - - <dd>PythonMagick binds the <a href= - "http://www.graphicsmagick.org">GraphicsMagick</a> image manipulation - library to Python.<br> - </dd> - - <dt><a href="http://www.vpython.org"><b>VPython</b></a></dt> - - <dd> - <a href="mailto:Bruce_Sherwood-at-ncsu.edu">Bruce Sherwood</a> writes: - - <blockquote> - VPython is an extension for Python that makes it easy to create - navigable 3D animations, which are generated as a side effect of - computational code. VPython is used in education for various - purposes, including teaching physics and programming, but it has also - been used by research scientists to visualize systems or data in 3D. - </blockquote><br> - - </dd> - </dl> - - <h3>Scientific Computing</h3> - - <dl class="page index"> - <dt><a href="http://camfr.sourceforge.net"><b>CAMFR</b></a></dt> - - <dd> - CAMFR is a photonics and electromagnetics modelling tool. Python is - used for computational steering. - - <p><a href="mailto:Peter.Bienstman@rug.ac.be">Peter Bienstman</a> - writes:</p> - - <blockquote> - Thanks for providing such a great tool! - </blockquote> - </dd> - - <dt><a href="http://cctbx.sourceforge.net"><b>cctbx - Computational - Crystallography Toolbox</b></a></dt> - - <dd> - Computational Crystallography is concerned with the derivation of - atomic models of crystal structures, given experimental X-ray - diffraction data. The cctbx is an open-source library of fundamental - algorithms for crystallographic computations. The core algorithms are - implemented in C++ and accessed through higher-level Python interfaces. - - <p>The cctbx grew together with Boost.Python and is designed from the - ground up as a hybrid Python/C++ system. With one minor exception, - run-time polymorphism is completely handled by Python. C++ compile-time - polymorphism is used to implement performance critical algorithms. The - Python and C++ layers are seamlessly integrated using Boost.Python.</p> - - <p>The SourceForge cctbx project is organized in modules to facilitate - use in non-crystallographic applications. The scitbx module implements - a general purpose array family for scientific applications and pure C++ - ports of FFTPACK and the L-BFGS quasi-Newton minimizer.</p> - </dd> - - <dt><a href="http://www.llnl.gov/CASC/emsolve"><b>EMSolve</b></a></dt> - - <dd>EMSolve is a provably stable, charge conserving, and energy - conserving solver for Maxwell's equations.<br> - </dd> - - <dt><b><a href="http://cern.ch/gaudi">Gaudi</a></b> and <b><a href= - "http://cern.ch/Gaudi/RootPython/">RootPython</a></b></dt> - - <dd> - Gaudi is a framework for particle physics collision data processing - applications developed in the context of the LHCb and ATLAS experiments - at CERN. - - <p><a href="mailto:Pere.Mato@cern.ch">Pere Mato Vila</a> writes:</p> - - <blockquote> - We are using Boost.Python to provide scripting/interactive capability - to our framework. We have a module called "GaudiPython" implemented - using Boost.Python that allows the interaction with any framework - service or algorithm from python. RootPython also uses Boost.Python - to provide a generic "gateway" between the <a href= - "http://root.cern.ch">ROOT</a> framework and python - - <p>Boost.Python is great. We managed very quickly to interface our - framework to python, which is great language. We are trying to - facilitate to our physicists (end-users) a rapid analysis application - development environment based on python. For that, Boost.Python plays - and essential role.</p> - </blockquote> - </dd> - - <dt><b><a href="http://www.esss.com.br">ESSS</a></b></dt> - - <dd> - ESSS (Engineering Simulation and Scientific Software) is a company that - provides engineering solutions and acts in the brazilian and - south-american market providing products and services related to - Computational Fluid Dynamics and Image Analysis. - - <p><a href="mailto:bruno@esss.com.br">Bruno da Silva de Oliveira</a> - writes:</p> - - <blockquote> - Recently we moved our work from working exclusively with C++ to an - hybrid-language approach, using Python and C++, with Boost.Python - providing the layer between the two. The results are great so far! - </blockquote> - - <p>Two projects have been developed so far with this technology:</p> - - <p><b><a href= - "http://www.esss.com.br/index.php?pg=dev_projetos">Simba</a></b> - provides 3D visualization of geological formations gattered from the - simulation of the evolution of oil systems, allowing the user to - analyse various aspects of the simulation, like deformation, pressure - and fluids, along the time of the simulation.</p> - - <p><b><a href= - "http://www.esss.com.br/index.php?pg=dev_projetos">Aero</a></b> aims to - construct a CFD with brazilian technology, which involves various - companies and universities. ESSS is responsible for various of the - application modules, including GUI and post-processing of results.</p> - </dd> - - <dt><b><a href="http://polybori.sourceforge.net/">PolyBoRi</a></b></dt> - - <dd> - <p><a href="mailto:brickenstein@mfo.de" - >Michael Brickenstein</a> writes:</p> - - <blockquote> - <p>The core of PolyBoRi is a C++ library, which provides - high-level data types for Boolean polynomials and monomials, - exponent vectors, as well as for the underlying polynomial - rings and subsets of the powerset of the Boolean variables. As - a unique approach, binary decision diagrams are used as - internal storage type for polynomial structures. On top of - this C++-library we provide a Python interface. This allows - parsing of complex polynomial systems, as well as sophisticated - and extendable strategies for Gröbner basis computation. - Boost.Python has helped us to create this interface in a - very clean way.</p> - </blockquote> - </dd> - - <dt><b><a href="http://pyrap.googlecode.com/">Pyrap</a></b></dt> - <dd> - <p><a href="diepen@astron.nl" - >Ger van Diepen</a> writes:</p> - - <blockquote> - <p>Pyrap is the python interface to the Radio-Astronomical Package - casacore (<a href="http://casacore.googlecode.com/" - >casacore.googlecode.com</a>). Astronomers love pyrap because - it makes it easily possible to get their data (observed with - radio-astronomical telescopes like LOFAR, ASKAP, and eVLA) in numpy - arrays and do basic data inspection and manipulation using the many - python packages that are available.</p> - - <p>Boost.Python made it quite easily possible to create converters for - the various data types, also for numpy arrays and individual elements - of a numpy array. It's nice they work fully recursively. Mapping C++ - functions to Python was straightforward.</p> - </blockquote> - </dd> - - <dt><b><a href="http://www.rdkit.org/" - >RDKit: Cheminformatics and Machine Learning Software</a></b></dt> - - <dd> - A collection of cheminformatics and machine-learning software - written in C++ and Python. - </dd> - </dl> - - <h3>Systems Libraries</h3> - - <dl> - <dt><a href="http://itamarst.org/software"><b>Fusion</b></a></dt> - - <dd> - <p>Fusion is a library that supports implementing protocols in C++ for - use with Twisted, allowing control over memory allocation strategies, - fast method calls internally, etc.. Fusion supports TCP, UDP and - multicast, and is implemented using the Boost.Python python - bindings.</p> - - <p>Fusion is licensed under the MIT license, and available for download - from <a href= - "http://itamarst.org/software">http://itamarst.org/software</a>.</p> - </dd> - </dl> - - <h3>Tools</h3> - - <dl> - <dt><a href="http://www.jayacard.org"><b>Jayacard</b></a></dt> - - <dd> - Jayacard aims at developing a secure portable open source operating - system for contactless smart cards and a complete suite of high quality - development tools to ease smart card OS and application development. - - <p>The core of the smart card reader management is written in C++ but - all the development tools are written in the friendly Python language. - Boost plays the fundamental role of binding the tools to our core smart - card reader library.</p> - </dd> - </dl> - <hr> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 29 May, 2008</p> - - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002-2008.</i></p> -</body> -</html> diff --git a/libs/python/doc/python.qbk b/libs/python/doc/python.qbk new file mode 100644 index 0000000000..b3e7eceb58 --- /dev/null +++ b/libs/python/doc/python.qbk @@ -0,0 +1,64 @@ +[book Boost.Python + [quickbook 1.7] + [authors [Abrahams, David], [Seefeld, Stefan]] + [copyright 2002 - 2015 David Abrahams, Stefan Seefeld] + [category inter-language support] + [id python] + [purpose + Reflects C++ classes and functions into Python + ] + [license + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + [@http://www.boost.org/LICENSE_1_0.txt]) + ] +] + +[def _boost_ [@http://www.boost.org Boost]] +[def _bb_ [@http://www.boost.org/build Boost.Build]] +[def _bb_list_ [@http://www.boost.org/more/mailing_lists.htm#jamboost Boost.Build mailing list]] +[def _bp_list_ [@http://www.boost.org/more/mailing_lists.htm#cplussig Boost.Python mailing list]] +[def _tutorial_ [@tutorial/index.html Tutorial]] +[def _reference_ [@reference/index.html Reference Manual]] +[def _gsg_ Boost [@http://www.boost.org/more/getting_started/ Getting Started Guide]] +[def _extending_ [@https://docs.python.org/2/extending/extending.html extending]] +[def _embedding_ [@https://docs.python.org/2/extending/embedding.html embedding]] + +[h2 Synopsis] + +Welcome to Boost.Python, a C++ library which enables seamless interoperability between C++ and the Python programming language. The library includes support for: + +* References and Pointers +* Globally Registered Type Coercions +* Automatic Cross-Module Type Conversions +* Efficient Function Overloading +* C++ to Python Exception Translation +* Default Arguments +* Keyword Arguments +* Manipulating Python objects in C++ +* Exporting C++ Iterators as Python Iterators +* Documentation Strings + +The development of these features was funded in part by grants to `Boost Consulting` from the [@http://www.llnl.gov Lawrence Livermore National Laboratories] and by the [@http://cci.lbl.gov Computational Crystallography Initiative] at Lawrence Berkeley National Laboratories. + +[section Contents] + +* _tutorial_ +* [link building Building and Testing] +* _reference_ +* [link configuration Configuration Information] +* [link glossary Glossary] +* [link support Support Resources] +* [link faq Frequently Asked Questions (FAQs)] + +[endsect] + +[h2 Articles] + +[@article.html Building Hybrid Systems With Boost Python], by Dave Abrahams and Ralf W. Grosse-Kunstleve + +[include building.qbk] +[include configuration.qbk] +[include support.qbk] +[include faq.qbk] +[include glossary.qbk]
\ No newline at end of file diff --git a/libs/python/doc/reference.qbk b/libs/python/doc/reference.qbk new file mode 100644 index 0000000000..bc5ecf6e94 --- /dev/null +++ b/libs/python/doc/reference.qbk @@ -0,0 +1,21 @@ +[book Boost.Python Reference Manual + [quickbook 1.7] + [authors [Abrahams, David], [Seefeld, Stefan]] + [copyright 2002 2003 2004 2005 2015 David Abrahams, Stefan Seefeld] + [id reference] + [license + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + [@http://www.boost.org/LICENSE_1_0.txt] + ] +] + +[include reference/concepts.qbk] +[include reference/components.qbk] +[include reference/objects.qbk] +[include reference/functions.qbk] +[include reference/conversion.qbk] +[include reference/embedding.qbk] +[include reference/utility.qbk] +[include reference/topics.qbk] +[include glossary.qbk] diff --git a/libs/python/doc/reference/args.qbk b/libs/python/doc/reference/args.qbk new file mode 100644 index 0000000000..253b165c83 --- /dev/null +++ b/libs/python/doc/reference/args.qbk @@ -0,0 +1,62 @@ +[section boost/python/args.hpp] +[section Introduction] +Supplies a family of overloaded functions for specifying argument keywords for wrapped C++ functions. +[section keyword-expressions] +A keyword-expression results in an object which holds a sequence of [link ntbs]\ es, and whose type encodes the number of keywords specified. The keyword-expression may contain default values for some or all of the keywords it holds +[endsect] +[endsect] +[section Class `arg`] +The objects of class arg are keyword-expressions holding one keyword ( size one ) +`` +namespace boost { namespace python +{ + struct arg + { + template <class T> + arg &operator = (T const &value); + explicit arg (char const *name){elements[0].name = name;} + }; + +}} +`` +[endsect] +[section Class `arg` constructor] +``arg(char const* name);`` +[variablelist +[[Requires][The argument must be a [link ntbs].]] +[[Effects][Constructs an arg object holding a keyword with name name.]] +] +[endsect] +[section Class `arg` operator=] +``template <class T> arg &operator = (T const &value);`` +[variablelist +[[Requires][The argument must convertible to python.]] +[[Effects][Assigns default value for the keyword.]] +[[Returns][Reference to `this`.]] +] +[endsect] +[section Keyword-expression operator,] +`` +keyword-expression operator , (keyword-expression, const arg &kw) const +keyword-expression operator , (keyword-expression, const char *name) const; +`` +[variablelist +[[Requires][The argument name must be a [link ntbs].]] +[[Effects][Extends the keyword-expression argument with one more keyword.]] +[[Returns][The extended keyword-expression.]] +] +[endsect] +[section Example] +`` +#include <boost/python/def.hpp> +using namespace boost::python; + +int f(double x, double y, double z=0.0, double w=1.0); + +BOOST_PYTHON_MODULE(xxx) +{ + def("f", f, (arg("x"), "y", arg("z")=0.0, arg("w")=1.0)); +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/call.qbk b/libs/python/doc/reference/call.qbk new file mode 100644 index 0000000000..4003529ef5 --- /dev/null +++ b/libs/python/doc/reference/call.qbk @@ -0,0 +1,26 @@ +[section boost/python/call.hpp] +[section Introduction] + <boost/python/call.hpp> defines the call family of overloaded function templates, used to invoke Python callable objects from C++. +[endsect] +[section Function `call`] +`` +template <class R, class A1, class A2, ... class An> +R call(PyObject* callable, A1 const&, A2 const&, ... An const&) +`` +[variablelist +[[Requires][R is a pointer type, reference type, or a complete type with an accessible copy constructor]] +[[Effects][Invokes callable(a1, a2, ...an) in Python, where a1...an are the arguments to call(), converted to Python objects. ]] +[[Returns][The result of the Python call, converted to the C++ type R.]] +[[Rationale][For a complete semantic description and rationale, see this page. ]] +] +[endsect] +[section Example] +The following C++ function applies a Python callable object to its two arguments and returns the result. If a Python exception is raised or the result can't be converted to a double, an exception is thrown. +`` +double apply2(PyObject* func, double x, double y) +{ + return boost::python::call<double>(func, x, y); +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/call_method.qbk b/libs/python/doc/reference/call_method.qbk new file mode 100644 index 0000000000..926763cebc --- /dev/null +++ b/libs/python/doc/reference/call_method.qbk @@ -0,0 +1,80 @@ +[section boost/python/call_method.hpp] +[section Introduction] +<boost/python/call_method.hpp> defines the call_method family of overloaded function templates, used to invoke callable attributes of Python objects from C++. +[endsect] +[section Function `call_method`] +`` +template <class R, class A1, class A2, ... class An> +R call_method(PyObject* self, char const* method, A1 const&, A2 const&, ... An const&) +`` +[variablelist +[[Requires][`R` is a pointer type, reference type, or a complete type with an accessible copy constructor]] +[[Effects][Invokes `self.method(a1, a2, ...an)` in Python, where `a1...an` are the arguments to `call_method()`, converted to Python objects. For a complete semantic description, see this page.]] +[[Returns][The result of the Python call, converted to the C++ type `R`.]] +[[Rationale][`call_method` is critical to implementing C++ virtual functions which are overridable in Python, as shown by the example below.]] +] +[endsect] +[section Example] +The following C++ illustrates the use of `call_method` in wrapping a class with a virtual function that can be overridden in Python: +C++ Module Definition +`` +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/utility.hpp> +#include <cstring> + +// class to be wrapped +class Base +{ + public: + virtual char const* class_name() const { return "Base"; } + virtual ~Base(); +}; + +bool is_base(Base* b) +{ + return !std::strcmp(b->class_name(), "Base"); +} + +// Wrapper code begins here +using namespace boost::python; + +// Callback class +class Base_callback : public Base +{ + public: + Base_callback(PyObject* self) : m_self(self) {} + + char const* class_name() const { return call_method<char const*>(m_self, "class_name"); } + char const* Base_name() const { return Base::class_name(); } + private: + PyObject* const m_self; +}; + +using namespace boost::python; +BOOST_PYTHON_MODULE(my_module) +{ + def("is_base", is_base); + + class_<Base,Base_callback, noncopyable>("Base") + .def("class_name", &Base_callback::Base_name) + ; + +} +`` +Python code: +`` +>>> from my_module import * +>>> class Derived(Base): +... def __init__(self): +... Base.__init__(self) +... def class_name(self): +... return self.__class__.__name__ +... +>>> is_base(Base()) # calls the class_name() method from C++ +1 +>>> is_base(Derived()) +0 +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/calling.qbk b/libs/python/doc/reference/calling.qbk new file mode 100644 index 0000000000..5be05d4ed9 --- /dev/null +++ b/libs/python/doc/reference/calling.qbk @@ -0,0 +1,65 @@ +[section Calling Python Functions and Methods] +[section Introduction] +The simplest way to call a Python function from C++, given an [link object_wrappers.boost_python_object_hpp.class_object `object`] instance f holding the function, is simply to invoke its function call operator. +``f("tea", 4, 2) // In Python: f('tea', 4, 2)`` + And of course, a method of an [link object_wrappers.boost_python_object_hpp.class_object `object`] instance `x` can be invoked by using the function-call operator of the corresponding attribute: +``x.attr("tea")(4, 2); // In Python: x.tea(4, 2)`` +If you don't have an [link object_wrappers.boost_python_object_hpp.class_object `object`] instance, `Boost.Python` provides two families of function templates, [link function_invocation_and_creation.boost_python_call_hpp.function_call `call`] and [link function_invocation_and_creation.boost_python_call_method_hpp.function_call_method `call_method`], for invoking Python functions and methods respectively on `PyObject*`\ s. The interface for calling a Python function object (or any Python callable object) looks like: +``call<ResultType>(callable_object, a1, a2... aN);`` +Calling a method of a Python object is similarly easy: +``call_method<ResultType>(self_object, "method-name", a1, a2... aN);`` + This comparitively low-level interface is the one you'll use when implementing C++ virtual functions that can be overridden in Python. +[endsect] +[section Argument Handling] +Arguments are converted to Python according to their type. By default, the arguments `a1...aN` are copied into new Python objects, but this behavior can be overridden by the use of [link function_invocation_and_creation.boost_python_ptr_hpp.functions `ptr()`] and `ref()`: +`` +class X : boost::noncopyable +{ + ... +}; + +void apply(PyObject* callable, X& x) +{ + // Invoke callable, passing a Python object which holds a reference to x + boost::python::call<void>(callable, boost::ref(x)); +} +`` + In the table below, x denotes the actual argument object and cv denotes an optional cv-qualification: "const", "volatile", or "const volatile". + +[table +[[Argument Type][Behavior]] +[[`T cv &` +`T cv`][The Python argument is created by the same means used for the return value of a wrapped C++ function returning T. When T is a class type, that normally means *x is copy-constructed into the new Python object.]] +[[T*][If x == 0, the Python argument will be None. Otherwise, the Python argument is created by the same means used for the return value of a wrapped C++ function returning T. When T is a class type, that normally means *x is copy-constructed into the new Python object.]] +[[boost::reference_wrapper<T>][The Python argument contains a pointer to, rather than a copy of, x.get(). Note: failure to ensure that no Python code holds a reference to the resulting object beyond the lifetime of *x.get() may result in a crash!]] +[[pointer_wrapper<T>][If x.get() == 0, the Python argument will be None. Otherwise, the Python argument contains a pointer to, rather than a copy of, *x.get(). Note: failure to ensure that no Python code holds a reference to the resulting object beyond the lifetime of *x.get() may result in a crash!]] +] +[endsect] +[section Result Handling] +In general, `call<ResultType>()` and call_method<ResultType>() return ResultType by exploiting all lvalue and rvalue from_python converters registered for ResultType and returning a copy of the result. However, when ResultType is a pointer or reference type, Boost.Python searches only for lvalue converters. To prevent dangling pointers and references, an exception will be thrown if the Python result object has only a single reference count. +[endsect] +[section Rationale] +In general, to get Python arguments corresponding to a1...aN, a new Python object must be created for each one; should the C++ object be copied into that Python object, or should the Python object simply hold a reference/pointer to the C++ object? In general, the latter approach is unsafe, since the called function may store a reference to the Python object somewhere. If the Python object is used after the C++ object is destroyed, we'll crash Python. + +In keeping with the philosophy that users on the Python side shouldn't have to worry about crashing the interpreter, the default behavior is to copy the C++ object, and to allow a non-copying behavior only if the user writes boost::ref(a1) instead of a1 directly. At least this way, the user doesn't get dangerous behavior "by accident". It's also worth noting that the non-copying ("by-reference") behavior is in general only available for class types, and will fail at runtime with a Python exception if used otherwise[1]. + +However, pointer types present a problem: one approach is to refuse to compile if any aN has pointer type: after all, a user can always pass *aN to pass "by-value" or ref(*aN) to indicate a pass-by-reference behavior. However, this creates a problem for the expected null pointer to None conversion: it's illegal to dereference a null pointer value. + +The compromise I've settled on is this: + +# The default behavior is pass-by-value. If you pass a non-null pointer, the pointee is copied into a new Python object; otherwise the corresponding Python argument will be None. +# if you want by-reference behavior, use ptr(aN) if aN is a pointer and ref(aN) otherwise. If a null pointer is passed to ptr(aN), the corresponding Python argument will be None. + +As for results, we have a similar problem: if ResultType is allowed to be a pointer or reference type, the lifetime of the object it refers to is probably being managed by a Python object. When that Python object is destroyed, our pointer dangles. The problem is particularly bad when the ResultType is char const* - the corresponding Python String object is typically uniquely-referenced, meaning that the pointer dangles as soon as call<char const*>(...) returns. + +The old Boost.Python v1 deals with this issue by refusing to compile any uses of call<char const*>(), but this goes both too far and not far enough. It goes too far because there are cases where the owning Python string object survives beyond the call (just for instance, when it's the name of a Python class), and it goes not far enough because we might just as well have the same problem with a returned pointer or reference of any other type. + +In Boost.Python this is dealt with by: + +# lifting the compile-time restriction on `char const *` callback returns +# detecting the case when the reference count on the result Python object is 1 and throwing an + exception inside of `call<U>(...)` when `U` is a pointer or reference type. + +This should be acceptably safe because users have to explicitly specify a pointer/reference for `U` in `call<U>`, and they will be protected against dangles at runtime, at least long enough to get out of the `call<U>(...)` invocation. +[endsect] +[endsect] diff --git a/libs/python/doc/reference/class.qbk b/libs/python/doc/reference/class.qbk new file mode 100644 index 0000000000..2cdf429921 --- /dev/null +++ b/libs/python/doc/reference/class.qbk @@ -0,0 +1,308 @@ +[section boost/python/class.hpp] +[section 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. It also exposes the `init`, `optional` and `bases` utility class templates, which are used in conjunction with `class_`. + +`<boost/python/class_fwd.hpp>` contains a forward declaration of the `class_` class template. +[endsect] +[section Class template `class_<T, Bases, HeldType, NonCopyable>`] +Creates a Python class associated with the C++ type passed as its first parameter. Although it has four template parameters, only the first one is required. The three optional arguments can actually be supplied *in any order*\ ; Boost.Python determines the role of the argument from its type. +[table + [[Template Parameter][Requirements][Semantics][Default]] + [[`T`][A class type.][The class being wrapped][]] + [[Bases] + [A specialization of [link high_level_components.boost_python_class_hpp.class_template_bases_t1_t2_tn bases<...>] which specifies previously-exposed C++ base classes of `T`.] + [Registers `from_python` conversions from wrapped `T` instances to each of its exposed direct and indirect bases. For each polymorphic base `B`, registers conversions from indirectly-held wrapped `B` instances to `T`.][[link high_level_components.boost_python_class_hpp.class_template_bases_t1_t2_tn bases<>]]] + [[HeldType][Must be `T`, a class derived from `T`, or a [link concepts.dereferenceable.concept_requirements Dereferenceable] type for which `pointee<HeldType>::type` is `T` or a class derived from `T`.][Specifies the type that is actually embedded in a Python object wrapping a `T` instance when `T`\ 's constructor is called or when a `T` or `T*` is converted to Python without the use of [link function_invocation_and_creation.boost_python_ptr_hpp.functions ptr], `ref`, or [link concepts.callpolicies Call Policies] such as [link function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r return_internal_reference]. More details below.][`T`]] + [[NonCopyable][If supplied, must be `boost::noncopyable`.][Suppresses automatic registration of `to_python` conversions which copy `T` instances. Required when `T` has no publicly-accessible copy constructor.][An unspecified type other than boost::noncopyable.]] +] +[section HeldType Semantics] + +# If HeldType is derived from `T`, its exposed constructor(s) must accept an initial `PyObject*` argument which refers back to the Python object that contains the HeldType instance, as shown in this example. This argument is not included in the [link high_level_components.boost_python_init_hpp.introduction.init_expressions init-expression] passed to [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu def(init_expr)], below, nor is it passed explicitly by users when Python instances of `T` are created. This idiom allows C++ virtual functions which will be overridden in Python to access the Python object so the Python method can be invoked. Boost.Python automatically registers additional converters which allow wrapped instances of `T` to be passed to wrapped C++ functions expecting HeldType arguments. +# Because Boost.Python will always allow wrapped instances of `T` to be passed in place of HeldType arguments, specifying a smart pointer for HeldType allows users to pass Python `T` instances where a smart pointer-to-T is expected. Smart pointers such as `std::auto_ptr<>` or `boost::shared_ptr<>` which contain a nested type `element_type` designating the referent type are automatically supported; additional smart pointer types can be supported by specializing `pointee<HeldType>`. +# As in case 1 above, when HeldType is a smart pointer to a class derived from `T`, the initial `PyObject*` argument must be supplied by all of HeldType's exposed constructors. +# Except in cases 1 and 3, users may optionally specify that T itself gets initialized with a similar initial `PyObject*` argument by specializing [link utility_and_infrastructure.boost_python_has_back_reference_.class_template_has_back_referenc has_back_reference<T>]. + +[endsect] +[section Class template `class_` synopsis] +`` + namespace boost { namespace python + { + template <class T + , class Bases = bases<> + , class HeldType = T + , class NonCopyable = unspecified + > + class class_ : public object + { + // Constructors with default __init__ + class_(char const* name); + class_(char const* name, char const* docstring); + + // Constructors, specifying non-default __init__ + template <class Init> + class_(char const* name, Init); + template <class Init> + class_(char const* name, char const* docstring, Init); + + // Exposing additional __init__ functions + template <class Init> + class_& def(Init); + + // defining methods + template <class F> + class_& def(char const* name, F f); + template <class Fn, class A1> + class_& def(char const* name, Fn fn, A1 const&); + template <class Fn, class A1, class A2> + class_& def(char const* name, Fn fn, A1 const&, A2 const&); + template <class Fn, class A1, class A2, class A3> + class_& def(char const* name, Fn fn, A1 const&, A2 const&, A3 const&); + + // declaring method as static + class_& staticmethod(char const* name); + + // exposing operators + template <unspecified> + class_& def(detail::operator_<unspecified>); + + // Raw attribute modification + template <class U> + class_& setattr(char const* name, U const&); + + // exposing data members + template <class D> + class_& def_readonly(char const* name, D T::*pm); + + template <class D> + class_& def_readwrite(char const* name, D T::*pm); + + // exposing static data members + template <class D> + class_& def_readonly(char const* name, D const& d); + template <class D> + class_& def_readwrite(char const* name, D& d); + + // property creation + template <class Get> + void add_property(char const* name, Get const& fget, char const* doc=0); + template <class Get, class Set> + void add_property( + char const* name, Get const& fget, Set const& fset, char const* doc=0); + + template <class Get> + void add_static_property(char const* name, Get const& fget); + template <class Get, class Set> + void add_static_property(char const* name, Get const& fget, Set const& fset); + + // pickle support + template <typename PickleSuite> + self& def_pickle(PickleSuite const&); + self& enable_pickling(); + }; + }} +`` +[endsect] +[section Class template `class_` constructors] +`` + class_(char const* name); + class_(char const* name, char const* docstring); + template <class Init> + class_(char const* name, Init init_spec); + template <class Init> + class_(char const* name, char const* docstring, Init init_spec); +`` + +[variablelist + [[Requires][name is an [link ntbs] which conforms to Python's [@http://www.python.org/doc/current/ref/identifiers.html identifier naming rules]. If docstring is supplied, it must be an [link ntbs]. If `init_spec` is supplied, it must be either the special enumeration constant `no_init` or an [link high_level_components.boost_python_init_hpp.introduction.init_expressions init-expression] compatible with `T`.]] + [[Effects][Constructs a `class_` object holding a Boost.Python extension class named name. The named attribute of the [link high_level_components.boost_python_scope_hpp.introduction current scope] is bound to the new extension class. + +* If supplied, the value of docstring is bound to the `__doc__` attribute of the extension class. +* If `init_spec` is `no_init`, a special `__init__` function is generated which always raises a Python exception. Otherwise, `this->def(init_spec)` is called. +* If `init_spec` is not supplied, `this->def(init<>())` is called.]] + [[Rationale][Allowing the user to specify constructor arguments in the `class_<>` constructor helps her to avoid the common run-time errors which result from invoking wrapped member functions without having exposed an `__init__` function which creates the requisite `T` instance. Types which are not default-constructible will cause a compile-time error unless `Init` is supplied. The user must always supply name as there is currently no portable method to derive the text of the class name from its type.]] +] +[endsect] +[section Class template `class_` modifier functions] +`` + template <class Init> + class_& def(Init init_expr); +`` + +[variablelist + [[Requires][`init_expr` is the result of an [link high_level_components.boost_python_init_hpp.introduction.init_expressions init-expression] compatible with `T`.]] + [[Effects][For each [link high_level_components.boost_python_init_hpp.introduction.init_expressions valid prefix] `P` of `Init`, adds an `__init__(...)` function overload to the extension class accepting P as arguments. Each overload generated constructs an object of HeldType according to the semantics described above, using a copy of init_expr's call policies. If the longest [link high_level_components.boost_python_init_hpp.introduction.init_expressions valid prefix] of Init contains N types and init_expr holds M keywords, an initial sequence of the keywords are used for all but the first N - M arguments of each overload.]] + [[Returns][`*this`]] + [[Rationale][Allows users to easily expose a class' constructor to Python.]] +] +`` + template <class F> + class_& def(char const* name, Fn fn); + template <class Fn, class A1> + class_& def(char const* name, Fn fn, A1 const& a1); + template <class Fn, class A1, class A2> + class_& def(char const* name, Fn fn, A1 const& a1, A2 const& a2); + template <class Fn, class A1, class A2, class A3> + class_& def(char const* name, Fn fn, A1 const& a1, A2 const& a2, A3 const& a3); +`` +[variablelist + [[Requires][name is an [link ntbs] which conforms to Python's [@http://www.python.org/doc/current/ref/identifiers.html identifier naming rules]. + * If a1 is the result of an [link function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions overload-dispatch-expression], only the second form is allowed and fn must be a pointer to function or pointer to member function whose [link arity] is the same as A1's [link function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions maximum arity]. + + [*Effects:] For each prefix `P` of `Fn`\ 's sequence of argument types, beginning with the one whose length is `A1`\ 's [link function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions minimum arity], adds a `name(...)` method overload to the extension class. Each overload generated invokes a1's call-expression with `P`, using a copy of a1's call policies. If the longest valid prefix of `A1` contains `N` types and a1 holds `M` keywords, an initial sequence of the keywords are used for all but the first `N - M` arguments of each overload. + +* Otherwise, a single method overload is built around fn, which must not be null: + + * If fn is a function pointer, its first argument must be of the form U, U cv&, U cv*, or U cv* const&, where T* is convertible to U*, and a1-a3, if supplied, may be selected in any order from the table below. + * Otherwise, if fn is a member function pointer, its target must be T or one of its public base classes, and a1-a3, if supplied, may be selected in any order from the table below. + * Otherwise, Fn must be [derived from] [link object_wrappers.boost_python_object_hpp.class_object object], and a1-a2, if supplied, may be selcted in any order from the first two rows of the table below. To be useful, fn should be [@http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-6 callable]. + [table + [[Mnemonic Name][Requirements/Type properties][Effects]] + [[docstring][Any [link ntbs]][Value will be bound to the __doc__ attribute of the resulting method overload. If an earlier overload supplied a docstring, two newline characters and the new docstring are appended to it.]] + [[policies][A model of [link concepts.callpolicies CallPolicies]][A copy will be used as the call policies of the resulting method overload.]] + [[keywords][The result of a [link function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions keyword-expression] specifying no more arguments than the [link arity] of fn.][A copy will be used as the call policies of the resulting method overload.]] + ] +]] + [[Returns][`*this`]] +] +``class_& staticmethod(char const* name);`` +[variablelist + [[Requires][name is an [link ntbs] which conforms to Python's [@http://www.python.org/doc/current/ref/identifiers.html identifier naming rules], and corresponds to a method whose overloads have all been defined.]] + [[Effects][Replaces the existing named attribute `x` with the result of invoking `staticmethod(x)` in Python. Specifies that the corresponding method is static and therefore no object instance will be passed to it. This is equivalent to the Python statement:]] +] +``setattr(self, name, staticmethod(getattr(self, name)))`` +[variablelist + [[Note][Attempting to invoke def(name,...) after invoking staticmethod(name) will [link raise] a RuntimeError.]] + [[Returns][`*this`]] +] +`` +template <unspecified> +class_& def(detail::operator_<unspecified>); +`` +[variablelist + [[Effects][Adds a Python [@http://www.python.org/doc/ref/specialnames.html special method] as described [link high_level_components.boost_python_operators_hpp here].]] + [[Returns][`*this`]] +] + +`` + template <class U> + class_& setattr(char const* name, U const& u); +`` +[variablelist + [[Requires][name is an [link ntbs] which conforms to Python's [@http://www.python.org/doc/current/ref/identifiers.html identifier naming rules].]] + [[Effects][Converts `u` to Python and adds it to the attribute dictionary of the extension class: + ``PyObject_SetAttrString(this->ptr(), name, object(u).ptr());``]] + [[Returns][`*this`]] +] +`` + template <class Get> + void add_property(char const* name, Get const& fget, char const* doc=0); + template <class Get, class Set> + void add_property( + char const* name, Get const& fget, Set const& fset, char const* doc=0); +`` +[variablelist + [[Requires][name is an [link ntbs] which conform to Python's [@http://www.python.org/doc/current/ref/identifiers.html identifier naming rules].]] + [[Effects][Creates a new Python [@http://www.python.org/2.2.2/descrintro.html#property property] class instance, passing `object(fget)` (and `object(fset)` in the second form) with an (optional) docstring `doc` to its constructor, then adds that property to the Python class object under construction with the given attribute name.]] + [[Returns][`*this`]] + [[Rationale][Allows users to easily expose functions that can be invoked from Python with attribute access syntax.]] +] +`` + template <class Get> + void add_static_property(char const* name, Get const& fget); + template <class Get, class Set> + void add_static_property(char const* name, Get const& fget, Set const& fset); +`` +[variablelist + [[Requires][name is an [link ntbs] which conforms to Python's [@http://www.python.org/doc/current/ref/identifiers.html identifier naming rules].]] + [[Effects][Creates a Boost.Python.StaticProperty object, passing `object(fget)` (and `object(fset)` in the second form) to its constructor, then adds that property to the Python class under construction with the given attribute name. StaticProperty is a special subclass of Python's property class which can be called without an initial self argument.]] + [[Returns][`*this`]] + [[Rationale][Allows users to easily expose functions that can be invoked from Python with static attribute access syntax.]] +] +`` + template <class D> + class_& def_readonly(char const* name, D T::*pm, char const* doc=0); + template <class D> + class_& def_readonly(char const* name, D const& d); +`` +[variablelist + [[Requires][name is an [link ntbs] which conforms to Python's [@http://www.python.org/doc/current/ref/identifiers.html identifier naming rules]. `doc` is also an [link ntbs].]] + [[Effects][``this->add_property(name, make_getter(pm), doc);`` and ``this->add_static_property(name, make_getter(d));`` respectively.]] + [[Returns][`*this`]] + [[Rationale][Allows users to easily expose a class' data member or free variable such that it can be inspected from Python with a natural syntax.]] +] +`` + template <class D> + class_& def_readwrite(char const* name, D T::*pm, char const* doc=0); + template <class D> + class_& def_readwrite(char const* name, D& d); +`` +[variablelist +[[Effects][``this->add_property(name, make_getter(pm), make_setter(pm), doc);`` and ``this->add_static_property(name, make_getter(d), make_setter(d));`` respectively.]] +[[Returns][`*this`]] +[[Rationale][Allows users to easily expose a class' data or free variable member such that it can be inspected and set from Python with a natural syntax.]] +] +`` + template <typename PickleSuite> + class_& def_pickle(PickleSuite const&); +`` +[variablelist +[[Requires][PickleSuite must be publically derived from [link topics.pickle_support.the_pickle_interface pickle_suite].]] +[[Effects][Defines a legal combination of the special attributes and methods: __getinitargs__, __getstate__, __setstate__, __getstate_manages_dict__, __safe_for_unpickling__, __reduce__]] +[[Returns][`*this`]] +[[Rationale][Provides an [link topics.pickle_support.the_pickle_interface easy to use high-level interface] for establishing complete [link topics.pickle_support.the_pickle_interface pickle support] for the wrapped class. The user is protected by compile-time consistency checks.]] +] +``class_& enable_pickling();`` +[variablelist +[[Effects][Defines the __reduce__ method and the __safe_for_unpickling__ attribute.]] +[[Returns][`*this`]] +[[Rationale][Light-weight alternative to def_pickle(). Enables implementation of pickle support from Python.]] +] +[endsect] +[endsect] +[section Class template bases<T1, T2, ...TN>] +An MPL sequence which can be used in class_<...> instantiations indicate a list of base classes. +[section Class template bases synopsis] +`` +namespace boost { namespace python +{ + template <T1 = unspecified,...Tn = unspecified> + struct bases + {}; +}} +`` +[endsect] +[endsect] +[section Examples] +Given a C++ class declaration: +`` +class Foo : public Bar, public Baz +{ + public: + Foo(int x, char const* y); + Foo(double); + + std::string const& name() { return m_name; } + void name(char const*); + + double value; // public data + private: + ... +}; +`` +A corresponding Boost.Python extension class can be created with: +`` +using namespace boost::python; + +class_<Foo,bases<Bar,Baz> >("Foo", + "This is Foo's docstring." + "It describes our Foo extension class", + + init<int,char const*>(args("x","y"), "__init__ docstring") + ) + .def(init<double>()) + .def("get_name", &Foo::get_name, return_internal_reference<>()) + .def("set_name", &Foo::set_name) + .def_readwrite("value", &Foo::value); +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/components.qbk b/libs/python/doc/reference/components.qbk new file mode 100644 index 0000000000..70a2969a1a --- /dev/null +++ b/libs/python/doc/reference/components.qbk @@ -0,0 +1,18 @@ +[chapter High Level Components + [quickbook 1.7] +] + +[include class.qbk] +[include def.qbk] +[include def_visitor.qbk] +[include docstring_options.qbk] +[include enum.qbk] +[include errors.qbk] +[include exception_translator.qbk] +[include init.qbk] +[include iterator.qbk] +[include module.qbk] +[include operators.qbk] +[include scope.qbk] +[include stl_iterator.qbk] +[include wrapper.qbk] diff --git a/libs/python/doc/reference/concepts.qbk b/libs/python/doc/reference/concepts.qbk new file mode 100644 index 0000000000..bb5db53c1b --- /dev/null +++ b/libs/python/doc/reference/concepts.qbk @@ -0,0 +1,134 @@ +[chapter Concepts + [quickbook 1.7] +] + +[section CallPolicies] +[section Introduction] + +Models of the CallPolicies concept are used to specialize the behavior of Python callable objects +generated by Boost.Python to wrapped C++ objects like function and member function pointers, +providing three behaviors: + +# `precall` - Python argument tuple management before the wrapped object is invoked +# `result_converter` - C++ return value handling +# `postcall` - Python argument tuple and result management after the wrapped object is invoked +# `extract_return_type` - metafunction for extracting the return type from a given signature type sequence + +[endsect] +[section CallPolicies Composition] + +In order to allow the use of multiple models of CallPolicies in the same callable object, +Boost.Python's CallPolicies class templates provide a chaining interface which allows them to be +recursively composed. This interface takes the form of an optional template parameter, `Base`, which +defaults to `default_call_policies`. By convention, the `precall` function of the `Base` is invoked after +the `precall` function supplied by the `outer` template, and the `postcall` function of the `Base` is invoked +before the `postcall` function of the `outer` template. If a `result_converter` is supplied by the `outer` +template, it replaces any `result_converter` supplied by the `Base`. For an example, see +`return_internal_reference`. + +[endsect] +[section Concept Requirements] +[table + [[Expression][Type][Result/Semantics]] + [[`x.precall(a)`][convertible to `bool`] + [returns `false` and `PyErr_Occurred() != 0` upon failure, `true` otherwise.]] + [[`P::result_converter`][A model of `ResultConverterGenerator`.] + [An MPL unary Metafunction Class used produce the "preliminary" result object.]] + [[`x.postcall(a, r)`][convertible to `PyObject*`] + [`0` and `PyErr_Occurred() != 0` upon failure. Must "conserve references" even in the event of an exception. In other words, if `r` is not returned, its reference count must be decremented; if another existing object is returned, its reference count must be incremented.]] + [[`P::extract_return_type`][A model of Metafunction.] + [An MPL unary Metafunction used extract the return type from a given signature. By default it is derived from `mpl::front`.]] +] +[endsect] +[endsect] +[section Dereferenceable] +[section Introduction] +Instances of a `Dereferenceable` type can be used like a pointer to access an lvalue. +[endsect] +[section Concept Requirements] +In the table below, `T` is a model of Dereferenceable, and `x` denotes an object of type `T`. In addition, all pointers are `Dereferenceable`. +[table + [[Expression][Result][Operational Semantics]] + [[`get_pointer(x)`][convertible to `pointee<T>::type*`] + [`&*x`, or a null pointer ]] +] +[endsect] +[endsect] +[section Extractor] +[section Introduction] +An Extractor is a class which Boost.Python can use to extract C++ objects from Python objects, and is typically used by facilities that define `from_python` conversions for "traditional" Python extension types. +[endsect] +[section Concept Requirements] +In the table below, `X` denotes a model of `Extractor` and `a` denotes an instance of a Python object type. +[table + [[Expression][Type][Semantics]] + [[`X::execute(a)`][non-void] + [Returns the C++ object being extracted. The execute function must not be overloaded.]] + [[`&a.ob_type`][`PyTypeObject**`] + [Points to the `ob_type` field of an object which is layout-compatible with `PyObject`]] +] +[endsect] +[section Notes] +Informally, an Extractor's execute member must be a non-overloaded static function whose single argument is a Python object type. Acceptable Python object types include those publicly (and unambiguously) derived from PyObject, and POD types which are layout-compatible with PyObject. +[endsect] +[endsect] +[section HolderGenerator] +[section Introduction] +A HolderGenerator is a unary metafunction class which returns types suitable for holding instances of its argument in a wrapped C++ class instance. +[endsect] +[section Concept Requirements] +In the table below, `G` denotes an type which models `HolderGenerator`, and `X` denotes a class type. +[table + [[Expression][Requirements]] + [[`G::apply<X>::type`][A concrete subclass of `instance_holder` which can hold objects of type `X`. ]] +] +[endsect] +[endsect] +[section ResultConverter] +[section Introduction] +A ResultConverter for a type `T` is a type whose instances can be used to convert C++ return values of type `T` `to_python`. A ResultConverterGenerator is an MPL unary metafunction class which, given the return type of a C++ function, returns a ResultConverter for that type. ResultConverters in Boost.Python generally inspect library's registry of converters to find a suitable converter, but converters which don't use the registry are also possible. +[endsect] +[section ResultConverter Concept Requirements] +In the table below, `C` denotes a ResultConverter type for a type `R`, `c` denotes an object of type `C`, and `r` denotes an object of type `R`. +[table + [[Expression][Type][Semantics]] + [[`C c`][] + [Constructs a `c` object.]] + [[`c.convertible()`][convertible to `bool`] + [`false` iff no conversion from any `R` value to a Python object is possible.]] + [[`c(r)`][convertible to `PyObject*`] + [A pointer to a Python object corresponding to `r`, or `0` iff `r` could not be converted `to_python`, in which case `PyErr_Occurred` should return non-zero.]] + [[`c.get_pytype()`][`PyTypeObject const *`] + [A pointer to a Python Type object corresponding to result of the conversion, or `0`. Used for documentation generation. If `0` is returned the generated type in the documentation will be object.]] +] +[endsect] +[section ResultConverterGenerator Concept Requirements] +In the table below, `G` denotes a ResultConverterGenerator type and `R` denotes a possible C++ function return type. +[table + [[Expression][Requirements]] + [[`G::apply<R>::type`][A ResultConverter type for `R`.]] +] +[endsect] +[endsect] +[section ObjectWrapper] +[section 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. +[endsect] +[section ObjectWrapper Concept Requirements] +Models of the ObjectWrapper concept have [link object_wrappers.boost_python_object_hpp.class_object 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 [link concepts.objectwrapper.typewrapper_concept_requirements 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)))()`` (see [link concepts.objectwrapper.caveat caveat] below). +[endsect] +[section TypeWrapper Concept Requirements] +TypeWrapper is a refinement of [link concepts.objectwrapper.objectwrapper_concept_requiremen 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 [link to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract extract<>], only instances of the associated Python type will be considered a match. +[endsect] +[section 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 [link object_wrappers.boost_python_dict_hpp.class_dict dict] member function `items` returns an object of type [link object_wrappers.boost_python_list_hpp.class_list 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, [link object_wrappers.boost_python_dict_hpp.class_dict boost::python::dict] can accept objects of Python type `mydict`. Invoking `items()` on this object can result in an instance of [link object_wrappers.boost_python_list_hpp.class_list 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. +[endsect] +[endsect] diff --git a/libs/python/doc/reference/conversion.qbk b/libs/python/doc/reference/conversion.qbk new file mode 100644 index 0000000000..6f6268b496 --- /dev/null +++ b/libs/python/doc/reference/conversion.qbk @@ -0,0 +1,10 @@ +[chapter To/From Python Type Conversion + [quickbook 1.7] +] + +[include extract.qbk] +[include implicit.qbk] +[include lvalue_from_pytype.qbk] +[include opaque_pointer_converter.qbk] +[include to_python_converter.qbk] +[include register_ptr_to_python.qbk] diff --git a/libs/python/doc/reference/copy_const_reference.qbk b/libs/python/doc/reference/copy_const_reference.qbk new file mode 100644 index 0000000000..9217a29675 --- /dev/null +++ b/libs/python/doc/reference/copy_const_reference.qbk @@ -0,0 +1,58 @@ +[section boost/python/copy_const_reference.hpp] +[section Class `copy_const_reference`] +`copy_const_reference` is a model of [link concepts.resultconverter.resultconvertergenerator_concept 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. +`` +namespace boost { namespace python +{ + struct copy_const_reference + { + template <class T> struct apply; + }; +}} +`` +[endsect] +[section Class `copy_const_reference` metafunctions] +``template <class T> struct apply`` +[variablelist +[[Requires][`T` is `U const&` for some `U`.]] +[[Returns][`typedef to_python_value<T> type;`]] +] +[endsect] +[section Example] +C++ module definition: +`` +#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(my_module) +{ + class_<Bar>("Bar"); + + class_<Foo>("Foo", init<int>()) + .def("get_bar", &Foo::get_bar + , return_value_policy<copy_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 +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/copy_non_const_reference.qbk b/libs/python/doc/reference/copy_non_const_reference.qbk new file mode 100644 index 0000000000..a12d4cfbf8 --- /dev/null +++ b/libs/python/doc/reference/copy_non_const_reference.qbk @@ -0,0 +1,58 @@ +[section boost/python/copy_non_const_reference.hpp] +[section Class `copy_non_const_reference`] +`copy_non_const_reference` is a model of [link concepts.resultconverter.resultconvertergenerator_concept 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. +`` +namespace boost { namespace python +{ + struct copy_non_const_reference + { + template <class T> struct apply; + }; +}} +`` +[endsect] +[section Class `copy_non_const_reference` metafunctions] +``template <class T> struct apply`` +[variablelist +[[Requires][`T` is `U &` for some non-const `U`.]] +[[Returns][`typedef to_python_value<T> type`;]] +] +[endsect] +[section Example] +C++ module definition: +`` +#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(my_module) +{ + class_<Bar>("Bar"); + + class_<Foo>("Foo", init<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 +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/data_members.qbk b/libs/python/doc/reference/data_members.qbk new file mode 100644 index 0000000000..8cc9bb7817 --- /dev/null +++ b/libs/python/doc/reference/data_members.qbk @@ -0,0 +1,98 @@ +[section boost/python/data_members.hpp] +[section Introduction] +`make_getter()` and `make_setter()` are the functions used internally by [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu `class_<>::def_readonly`] and [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu `class_<>::def_readwrite`] to produce Python callable objects which wrap C++ data members. +[endsect] +[section Functions] +`` +template <class C, class D> +object make_getter(D C::*pm); + +template <class C, class D, class Policies> +object make_getter(D C::*pm, Policies const& policies); +`` +[variablelist +[[Requires][Policies is a model of [link concepts.callpolicies `CallPolicies`].]] +[[Effects][Creates a Python callable object which accepts a single argument that can be converted from_python to C*, and returns the corresponding member D member of the C object, converted to_python. If policies is supplied, it will be applied to the function as described here. Otherwise, the library attempts to determine whether D is a user-defined class type, and if so uses return_internal_reference<> +for Policies. Note that this test may inappropriately choose return_internal_reference<> in some cases when D is a smart pointer type. This is a known defect.]] +[[Returns][An instance of object which holds the new Python callable object.]] +] +`` +template <class D> +object make_getter(D const& d); +template <class D, class Policies> +object make_getter(D const& d, Policies const& policies); + +template <class D> +object make_getter(D const* p); +template <class D, class Policies> +object make_getter(D const* p, Policies const& policies); +`` +[variablelist +[[Requires][Policies is a model of CallPolicies.]] +[[Effects][Creates a Python callable object which accepts no arguments and returns d or *p, converted to_python on demand. If policies is supplied, it will be applied to the function as described here. Otherwise, the library attempts to determine whether D is a user-defined class type, and if so uses reference_existing_object for Policies.]] +[[Returns][An instance of object which holds the new Python callable object.]] +] +`` +template <class C, class D> +object make_setter(D C::*pm); + +template <class C, class D, class Policies> +object make_setter(D C::*pm, Policies const& policies); +`` +[variablelist +[[Requires][Policies is a model of CallPolicies.]] +[[Effects][Creates a Python callable object which, when called from Python, expects two arguments which can be converted from_python to C* and D const&, respectively, and sets the corresponding D member of the C object. If policies is supplied, it will be applied to the function as described here.]] +[[Returns][An instance of object which holds the new Python callable object.]] +] +`` +template <class D> +object make_setter(D& d); +template <class D, class Policies> +object make_setter(D& d, Policies const& policies); + +template <class D> +object make_setter(D* p); +template <class D, class Policies> +object make_setter(D* p, Policies const& policies); +`` +[variablelist +[[Requires][Policies is a model of CallPolicies.]] +[[Effects][Creates a Python callable object which accepts one argument, which is converted from Python to D const& and written into d or *p, respectively. If policies is supplied, it will be applied to the function as described here.]] +[[Returns][An instance of object which holds the new Python callable object.]] +] +[endsect] +[section Example] +The code below uses make_getter and make_setter to expose a data member as functions: +`` +#include <boost/python/data_members.hpp> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> + +struct X +{ + X(int x) : y(x) {} + int y; +}; + +using namespace boost::python; + +BOOST_PYTHON_MODULE_INIT(data_members_example) +{ + class_<X>("X", init<int>()) + .def("get", make_getter(&X::y)) + .def("set", make_setter(&X::y)) + ; +} +`` +It can be used this way in Python: +`` +>>> from data_members_example import * +>>> x = X(1) +>>> x.get() +1 +>>> x.set(2) +>>> x.get() +2 +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/def.qbk b/libs/python/doc/reference/def.qbk new file mode 100644 index 0000000000..bf92e17c66 --- /dev/null +++ b/libs/python/doc/reference/def.qbk @@ -0,0 +1,54 @@ +[section boost/python/def.hpp] +[section Introduction] +`def()` is the function which can be used to expose C++ functions and callable objects as Python functions in the [link high_level_components.boost_python_scope_hpp.introduction current scope]. +[endsect] +[section 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&); +`` +[variablelist +[[Requires][name is an [link ntbs] which conforms to Python's [@http://www.python.org/doc/current/ref/identifiers.html identifier naming rules]. + +* If `Fn` is [derived from] [link object_wrappers.boost_python_object_hpp.class_object object], it will be added to the [link high_level_components.boost_python_scope_hpp.introduction current scope] as a single overload. To be useful, `fn` should be [@http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-6 callable]. +* If `a1` is the result of an [link function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions overload-dispatch-expression], only the second form is allowed and `fn` must be a pointer to function or pointer to member function whose [link arity] is the same as A1's [link function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions maximum arity]. + + [*Effects:] For each prefix `P` of `Fn`\ 's sequence of argument types, beginning with the one whose length is `A1`\ 's [link function_invocation_and_creation.boost_python_overloads_hpp.introduction.overload_dispatch_expressions minimum arity], adds a `name(...)` function overload to the [link high_level_components.boost_python_scope_hpp.introduction current scope]. Each overload generated invokes a1's call-expression with P, using a copy of a1's call policies. If the longest valid prefix of A1 contains N types and a1 holds M keywords, an initial sequence of the keywords are used for all but the first N - M arguments of each overload. + +* Otherwise, fn must be a non-null function or member function pointer, and a single function overload built around fn is added to the current scope. If any of a1-a3 are supplied, they may be selected in any order from the table below. + + [table + [[Mnemonic Name][Requirements/Type properties][Effects]] + [[docstring][Any [link ntbs]][Value will be bound to the `__doc__` attribute of the resulting method overload.]] + [[policies][A model of [link concepts.callpolicies CallPolicies]][A copy will be used as the call policies of the resulting method overload.]] + [[keywords][The result of a [link function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions keyword-expression] specifying no more arguments than the [link arity] of `fn`.][A copy will be used as the call policies of the resulting method overload.]] +] +]] +] +[endsect] +[section Example] +`` +#include <boost/python/def.hpp> +#include <boost/python/module.hpp> +#include <boost/python/args.hpp> + +using namespace boost::python; + +char const* foo(int x, int y) { return "foo"; } + +BOOST_PYTHON_MODULE(def_test) +{ + def("foo", foo, args("x", "y"), "foo's docstring"); +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/def_visitor.qbk b/libs/python/doc/reference/def_visitor.qbk new file mode 100644 index 0000000000..773402a3c0 --- /dev/null +++ b/libs/python/doc/reference/def_visitor.qbk @@ -0,0 +1,58 @@ +[section boost/python/def_visitor.hpp] +[section Introduction] +<boost/python/def_visitor.hpp> provides a generic visitation interface through which the [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel class_] def member functionality can be extended non-intrusively to avoid cluttering the [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel class_] interface. It declares the `def_visitor<T>` class template, which is parameterized on the derived type `DerivedVisitor`, which provides the actual `def` functionality through its `visit` member functions. +[endsect] +[section Class `def_visitor`] +The class `def_visitor` is a base class paramaterized by its derived class. The `def_visitor` class is a protocol class. Its derived class, DerivedVisitor, is expected to have a member function `visit`. The `def_visitor` class is never instantiated directly. Instead, an instance of its subclass, DerivedVisitor, is passed on as an argument to the [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel class_] `def` member function. + +`` +namespace boost { namespace python { + + template <class DerivedVisitor> + class def_visitor {}; +} +`` + +[variablelist + [[Requires][The client supplied class DerivedVisitor template parameter is expected to: + * be privately derived from def_visitor + * grant friend access to class def_visitor_access + * define either or both visit member functions listed in the table below: + [table + [[Expression][Return Type][Requirements][Effects]] + [[`visitor.visit(cls)`][`void`] + [`cls` is an instance of a [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel class_] being wrapped to Python. `visitor` is a `def_visitor` derived class.] + [A call to `cls.def(visitor)` forwards to this member function.]] + [[`visitor.visit(cls, name, options)`][`void`] + [`cls` is a [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel class_] instance, name is a C string. `visitor` is a `def_visitor` derived class. options is a context specific optional argument.] + [A call to `cls.def(name, visitor)` or `cls.def(name, visitor, options)` forwards to this member function. ]]] + ]] + ] +[endsect] +[section Example] +`` +class X {/*...*/}; + +class my_def_visitor : boost::python::def_visitor<my_def_visitor> +{ + friend class def_visitor_access; + + template <class classT> + void visit(classT& c) const + { + c.def("foo", &my_def_visitor::foo); + c.def("bar", &my_def_visitor::bar); + } + + static void foo(X& self); + static void bar(X& self); +}; + +BOOST_PYTHON_MODULE(my_ext) +{ + class_<X>("X") + .def(my_def_visitor()); +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/default_call_policies.qbk b/libs/python/doc/reference/default_call_policies.qbk new file mode 100644 index 0000000000..99b969be7d --- /dev/null +++ b/libs/python/doc/reference/default_call_policies.qbk @@ -0,0 +1,58 @@ +[section boost/python/default_call_policies.hpp] +[section Class `default_call_policies`] +`default_call_policies` is a model of [link concepts.callpolicies `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 [link concepts.callpolicies `CallPolicies`] from `default_call_policies`. +`` +namespace boost { namespace python +{ + struct default_call_policies + { + static bool precall(PyObject*); + static PyObject* postcall(PyObject*, PyObject* result); + typedef default_result_converter result_converter; + template <class Sig> struct extract_return_type : mpl::front<Sig>{}; + }; +}} +`` +[endsect] +[section Class `default_call_policies` static functions] +``bool precall(PyObject*);`` +[variablelist +[[Returns][true]] +[[Throws][nothing]] +] +``PyObject* postcall(PyObject*, PyObject* result);`` +[variablelist +[[Returns][result]] +[[Throws][nothing]] +] +[endsect] +[section Class `default_result_converter`] +default_result_converter is a model of [link concepts.resultconverter.resultconvertergenerator_concept `ResultConverterGenerator`] which can be used to wrap C++ functions returning non-pointer types, `char const*`, and `PyObject*`, by-value. +`` +namespace boost { namespace python +{ + struct default_result_converter + { + template <class T> struct apply; + }; +}} +`` +[endsect] +[section Class `default_result_converter` metafunctions] +``template <class T> struct apply`` +[variablelist +[[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;]] +] +[endsect] +[section 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; +}; +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/dict.qbk b/libs/python/doc/reference/dict.qbk new file mode 100644 index 0000000000..e32d35e4ef --- /dev/null +++ b/libs/python/doc/reference/dict.qbk @@ -0,0 +1,71 @@ +[section boost/python/dict.hpp] +[section Introduction] +Exposes a [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] for the Python [@http://www.python.org/dev/doc/devel/lib/typesmapping.html `dict`] type. +[endsect] +[section Class `dict`] +Exposes the [@http://www.python.org/dev/doc/devel/lib/typesmapping.html 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 [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] concept definition. Since `dict` is publicly derived from [link object_wrappers.boost_python_object_hpp.class_object `object`], the public `object` interface applies to `dict` instances as well. +`` +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; + }; +}} +`` +[endsect] +[section 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; +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/docstring_options.qbk b/libs/python/doc/reference/docstring_options.qbk new file mode 100644 index 0000000000..00b5228254 --- /dev/null +++ b/libs/python/doc/reference/docstring_options.qbk @@ -0,0 +1,213 @@ +[section boost/python/docstring_options.hpp] +[section Introduction] +Boost.Python supports user-defined docstrings with automatic appending of C++ signatures. These features are enabled by default. The class docstring_options is available to selectively suppress the user-defined docstrings, signatures, or both. +[endsect] +[section Class `docstring_options`] +Controls the appearance of docstrings of wrapped functions and member functions for the life-time of the instance. The instances are noncopyable to eliminate the possibility of surprising side effects. + +``namespace boost { namespace python { + + class docstring_options : boost::noncopyable + { + public: + docstring_options(bool show_all=true); + docstring_options(bool show_user_defined, bool show_signatures); + docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures); + ~docstring_options(); + void disable_user_defined(); + void enable_user_defined(); + void disable_signatures(); + void enable_signatures(); + void disable_py_signatures(); + void enable_py_signatures(); + void disable_cpp_signatures(); + void enable_cpp_signatures(); + void disable_all(); + void enable_all(); + }; +}} + +`` +[endsect] +[section Class dostring_options constructors] +`` +docstring_options(bool show_all=true); +`` +[variablelist +[[Effects][Constructs a docstring_options object which controls the appearance of function and member-function docstrings defined in the code that follows. If show_all is true, both the user-defined docstrings and the automatically generated Python and C++ signatures are shown. If show_all is false the `__doc__` attributes are `None`.]] +] +`` +docstring_options(bool show_user_defined, bool show_signatures); +`` +[variablelist +[[Effects][Constructs a `docstring_options` object which controls the appearance of function and member-function docstrings defined in the code that follows. Iff `show_user_defined` is `true`, the user-defined docstrings are shown. Iff `show_signatures` is `true`, Python and C++ signatures are automatically added. If both `show_user_defined` and `show_signatures` are `false`, the `__doc__` attributes are `None`.]] +] +`` +docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures); +`` +[variablelist +[[Effects][Constructs a `docstring_options` object which controls the appearance of function and member-function docstrings defined in the code that follows. Iff `show_user_defined` is `true`, the user-defined docstrings are shown. Iff `show_py_signatures` is `true`, Python signatures are automatically added. Iff `show_cpp_signatures` is true, C++ signatures are automatically added. If all parameters are `false`, the `__doc__` attributes are `None`.]] +] +[endsect] +[section Class docstring_options destructor] +``~docstring_options();`` +[variablelist +[[Effects][Restores the previous state of the docstring options. In particular, if `docstring_options` instances are in nested C++ scopes the settings effective in the enclosing scope are restored. If the last `docstring_options` instance goes out of scope the default "all on" settings are restored.]]] +[endsect] +[section Class `docstring_options` modifier functions] +`` +void disable_user_defined(); +void enable_user_defined(); +void disable_signatures(); +void enable_signatures(); +void disable_py_signatures(); +void enable_py_signatures(); +void disable_cpp_signatures(); +void enable_cpp_signatures(); +void disable_all(); +void enable_all(); +`` +These member functions dynamically change the appearance of docstrings in the code that follows. The `*_user_defined()` and `*_signatures()` member functions are provided for fine-grained control. The `*_all()` member functions are convenient shortcuts to manipulate all settings simultaneously. +[endsect] +[section Example] +[section Docstring options defined at compile time] +`` +#include <boost/python/module.hpp> +#include <boost/python/def.hpp> +#include <boost/python/docstring_options.hpp> + +void foo() {} + +BOOST_PYTHON_MODULE(demo) +{ + using namespace boost::python; + docstring_options doc_options(DEMO_DOCSTRING_SHOW_ALL); + def("foo", foo, "foo doc"); +} +`` +If compiled with `-DDEMO_DOCSTRING_SHOW_ALL=true`: +`` +>>> import demo +>>> print demo.foo.__doc__ +foo() -> None : foo doc +C++ signature: + foo(void) -> void +`` +If compiled with `-DDEMO_DOCSTRING_SHOW_ALL=false`: +`` +>>> import demo +>>> print demo.foo.__doc__ +None +`` +[endsect] +[section Selective suppressions] +`` +#include <boost/python/module.hpp> +#include <boost/python/def.hpp> +#include <boost/python/args.hpp> +#include <boost/python/docstring_options.hpp> + +int foo1(int i) { return i; } +int foo2(long l) { return static_cast<int>(l); } +int foo3(float f) { return static_cast<int>(f); } +int foo4(double d) { return static_cast<int>(d); } + +BOOST_PYTHON_MODULE(demo) +{ + using namespace boost::python; + docstring_options doc_options; + def("foo1", foo1, arg("i"), "foo1 doc"); + doc_options.disable_user_defined(); + def("foo2", foo2, arg("l"), "foo2 doc"); + doc_options.disable_signatures(); + def("foo3", foo3, arg("f"), "foo3 doc"); + doc_options.enable_user_defined(); + def("foo4", foo4, arg("d"), "foo4 doc"); + doc_options.enable_py_signatures(); + def("foo5", foo4, arg("d"), "foo5 doc"); + doc_options.disable_py_signatures(); + doc_options.enable_cpp_signatures(); + def("foo6", foo4, arg("d"), "foo6 doc"); +} +`` +Python code: +`` +>>> import demo +>>> print demo.foo1.__doc__ +foo1( (int)i) -> int : foo1 doc +C++ signature: + foo1(int i) -> int +>>> print demo.foo2.__doc__ +foo2( (int)l) -> int : +C++ signature: + foo2(long l) -> int +>>> print demo.foo3.__doc__ +None +>>> print demo.foo4.__doc__ +foo4 doc +>>> print demo.foo5.__doc__ +foo5( (float)d) -> int : foo5 doc +>>> print demo.foo6.__doc__ +foo6 doc +C++ signature: + foo6(double d) -> int +`` +[endsect] +[section Wrapping from multiple C++ scopes] +`` +#include <boost/python/module.hpp> +#include <boost/python/def.hpp> +#include <boost/python/args.hpp> +#include <boost/python/docstring_options.hpp> + +int foo1(int i) { return i; } +int foo2(long l) { return static_cast<int>(l); } + +int bar1(int i) { return i; } +int bar2(long l) { return static_cast<int>(l); } + +namespace { + + void wrap_foos() + { + using namespace boost::python; + // no docstring_options here + // -> settings from outer C++ scope are in effect + def("foo1", foo1, arg("i"), "foo1 doc"); + def("foo2", foo2, arg("l"), "foo2 doc"); + } + + void wrap_bars() + { + using namespace boost::python; + bool show_user_defined = true; + bool show_signatures = false; + docstring_options doc_options(show_user_defined, show_signatures); + def("bar1", bar1, arg("i"), "bar1 doc"); + def("bar2", bar2, arg("l"), "bar2 doc"); + } +} + +BOOST_PYTHON_MODULE(demo) +{ + boost::python::docstring_options doc_options(false); + wrap_foos(); + wrap_bars(); +} +`` +Python code: +`` +>>> import demo +>>> print demo.foo1.__doc__ +None +>>> print demo.foo2.__doc__ +None +>>> print demo.bar1.__doc__ +bar1 doc +>>> print demo.bar2.__doc__ +bar2 doc +`` + +[endsect] +[endsect] +[endsect] diff --git a/libs/python/doc/reference/embedding.qbk b/libs/python/doc/reference/embedding.qbk new file mode 100644 index 0000000000..77461b9bcd --- /dev/null +++ b/libs/python/doc/reference/embedding.qbk @@ -0,0 +1,6 @@ +[chapter Embedding + [quickbook 1.7] +] + +[include exec.qbk] +[include import.qbk] diff --git a/libs/python/doc/reference/enum.qbk b/libs/python/doc/reference/enum.qbk new file mode 100644 index 0000000000..ece2d298c9 --- /dev/null +++ b/libs/python/doc/reference/enum.qbk @@ -0,0 +1,107 @@ +[section boost/python/enum.hpp] +[section 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. +[endsect] +[section Class template `enum_`] +Creates a Python class derived from Python's `int` type which is associated with the C++ type passed as its first parameter. +`` +namespace boost { namespace python +{ + template <class T> + class enum_ : public object + { + enum_(char const* name, char const* doc = 0); + enum_<T>& value(char const* name, T); + enum_<T>& export_values(); + }; +}} +`` +[endsect] +[section Class template `enum_` constructors] +``enum_(char const* name, char const* doc=0);`` +[variablelist +[[Requires][name is an [link ntbs] which conforms to Python's [@http://www.python.org/doc/current/ref/identifiers.html 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 [link high_level_components.boost_python_scope_hpp current scope] is bound to the new extension type.]] +] +[endsect] +[section Class template `enum_` modifier functions] +``enum_<T>& value(char const* name, T x);`` +[variablelist +[[Requires][name is an [link ntbs] which conforms to Python's [@http://www.python.org/doc/current/ref/identifiers.html 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`]] +] +``enum_<T>& export_values();`` +[variablelist +[[Effects][sets attributes in the [link high_level_components.boost_python_scope_hpp current scope] with the same names and values as all enumeration values exposed so far by calling value().]] +[[Returns][`*this`]] +] +[endsect] +[section Example] +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) + .export_values() + .value("blue", blue) + ; + + def("identity", identity_); +} +`` +Interactive Python: +`` +>>> from enums import * + +>>> identity(red) +enums.color.red + +>>> identity(color.red) +enums.color.red + +>>> identity(green) +enums.color.green + +>>> identity(color.green) +enums.color.green + +>>> identity(blue) +Traceback (most recent call last): + File "<stdin>", line 1, in ? +NameError: name 'blue' is not defined + +>>> 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 +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/errors.qbk b/libs/python/doc/reference/errors.qbk new file mode 100644 index 0000000000..2103017cba --- /dev/null +++ b/libs/python/doc/reference/errors.qbk @@ -0,0 +1,142 @@ +[section boost/python/errors.hpp] +[section 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. +[endsect] +[section 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 [@http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71 PyErr_Occurred()] returns a value convertible to `true`. Portable code shouldn't throw this exception type directly, but should instead use [link high_level_components.boost_python_errors_hpp.functions throw_error_already_set()], below. +`` +namespace boost { namespace python +{ + class error_already_set {}; +}} +`` +[endsect] +[section Functions] +`` +template <class T> bool handle_exception(T f) throw(); +void handle_exception() throw(); +`` +[variablelist +[[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 which first attempts to use all registered [link high_level_components.boost_python_exception_translato exception translators]. If none of those translates the exception, the catch clauses then set an appropriate Python exception for the C++ exception caught, returning true if an exception was thrown, 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 necessary 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: [link function_invocation_and_creation.boost_python_make_function_hpp.functions make_function()], [link function_invocation_and_creation.boost_python_make_function_hpp.functions make_constructor()], [link high_level_components.boost_python_def_hpp.functions def()] and [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu 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.]] +] +``template <class T> T* expect_non_null(T* x);`` +[variablelist +[[Returns][x]] +[[Throws][error_already_set() iff x == 0.]] +[[Rationale][Simplifies error-handling when calling functions in the Python/C API which return 0 on error.]] +] +``void throw_error_already_set();`` +[variablelist +[[Effects][throw error_already_set();]] +[[Rationale][Simplifies error-handling when calling functions in the Python/C API which return 0 on error.]] +] +``void throw_error_already_set();`` +[variablelist +[[Effects][throw error_already_set();]] +[[Rationale][Many platforms and compilers are not able to consistently catch exceptions thrown across shared library boundaries. Using this function from the Boost.Python library ensures that the appropriate catch block in handle_exception() can catch the exception.]] +] +[endsect] +[section Example] +`` +#include <string> +#include <boost/python/errors.hpp> +#include <boost/python/object.hpp> +#include <boost/python/handle.hpp> + +// Returns a std::string which has the same value as obj's "__name__" +// attribute. +std::string get_name(boost::python::object obj) +{ + // throws if there's no __name__ attribute + PyObject* p = boost::python::expect_non_null( + PyObject_GetAttrString(obj.ptr(), "__name__")); + + char const* s = PyString_AsString(p); + if (s != 0) + Py_DECREF(p); + + // throws if it's not a Python string + std::string result( + boost::python::expect_non_null( + PyString_AsString(p))); + + Py_DECREF(p); // Done with p + + return result; +} + +// +// Demonstrate form 1 of handle_exception +// + +// Place into result a Python Int object whose value is 1 if a and b have +// identical "__name__" attributes, 0 otherwise. +void same_name_impl(PyObject*& result, boost::python::object a, boost::python::object b) +{ + result = PyInt_FromLong( + get_name(a) == get_name(a2)); +} + +object borrowed_object(PyObject* p) +{ + return boost::python::object( + boost::python::handle<>( + boost::python::borrowed(a1))); +} + +// 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), borrowed_object(a1), borrowed_object(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(borrowed_object(a1)) == get_name(borrowed_object(a2))); + } + catch(...) + { + // If an exception was thrown, translate it to Python + boost::python::handle_exception(); + return 0; + } +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/exception_translator.qbk b/libs/python/doc/reference/exception_translator.qbk new file mode 100644 index 0000000000..e9fb0a899e --- /dev/null +++ b/libs/python/doc/reference/exception_translator.qbk @@ -0,0 +1,51 @@ +[section boost/python/exception_translator.hpp] +[section Introduction] +As described [link high_level_components.boost_python_errors_hpp.introduction 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 [@http://www.python.org/doc/current/lib/module-exceptions.html RuntimeError] exception whose representation is 'Unidentifiable C++ Exception'. To produce better error messages, users can register additional exception translators as described below. +[endsect] +[section Function `register_exception_translator`] +`` +template<class ExceptionType, class Translate> +void register_exception_translator(Translate translate); +`` +[variablelist +[[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).]] +] +[endsect] +[section 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); +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/exec.qbk b/libs/python/doc/reference/exec.qbk new file mode 100644 index 0000000000..2cd46c45b2 --- /dev/null +++ b/libs/python/doc/reference/exec.qbk @@ -0,0 +1,84 @@ +[section boost/python/exec.hpp] +[section Introduction] +Exposes a mechanism for embedding the python interpreter into C++ code. +[endsect] +[section Function `eval`] +`` +object eval(str expression, + object globals = object(), + object locals = object()); +`` +[variablelist +[[Effects][Evaluate Python expression from expression in the context specified by the dictionaries globals and locals. ]] +[[Returns][An instance of object which holds the value of the expression.]] +] +[endsect] +[section Function `exec`] +`` +object exec(str code, + object globals = object(), + object locals = object()); +`` +[variablelist +[[Effects][Execute Python source code from code in the context specified by the dictionaries globals and locals. ]] +[[Returns][ An instance of object which holds the result of executing the code. ]] +] +[endsect] +[section Function `exec_file`] +`` +object exec_file(str filename, + object globals = object(), + object locals = object()); +`` +[variablelist +[[Effects][Execute Python source code from the file named by filename in the context specified by the dictionaries globals and locals.]] +[[Returns][An instance of object which holds the result of executing the code. ]] +] +[endsect] +[section Examples] +The following example demonstrates the use of import and exec to define a function in python, and later call it from within C++. + +`` +#include <iostream> +#include <string> + +using namespace boost::python; + +void greet() +{ + // Retrieve the main module. + object main = import("__main__"); + + // Retrieve the main module's namespace + object global(main.attr("__dict__")); + + // Define greet function in Python. + object result = exec( + "def greet(): \n" + " return 'Hello from Python!' \n", + global, global); + + // Create a reference to it. + object greet = global["greet"]; + + // Call it. + std::string message = extract<std::string>(greet()); + std::cout << message << std::endl; +} + `` + Instead of embedding the python script into a string, we could also store it in an a file... +`` +def greet(): + return 'Hello from Python!' +`` + ... and execute that instead. + +`` + // ... + // Load the greet function from a file. + object result = exec_file(script, global, global); + // ... +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/extract.qbk b/libs/python/doc/reference/extract.qbk new file mode 100644 index 0000000000..2c8ffcdbdb --- /dev/null +++ b/libs/python/doc/reference/extract.qbk @@ -0,0 +1,99 @@ +[section boost/python/extract.hpp] +[section Introduction] +Exposes a mechanism for extracting C++ object values from generalized Python objects. Note that `extract<...>` can also be used to "downcast" an [link object_wrappers.boost_python_object_hpp.class_object `object`] to some specific [link concepts.objectwrapper 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 [link concepts.objectwrapper ObjectWrapper]\ 's interface on the original object. +[endsect] +[section Class template `extract`] +`extract<T>` can be used to extract a value of an arbitrary C++ type from an instance of [link object_wrappers.boost_python_object_hpp.class_object object]. Two usages are supported: + +# `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. +# `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. + +`` +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; + }; +}} +`` +[endsect] +[section Class template `extract` constructors and destructor] +`` +extract(PyObject* p); +extract(object const&); +`` +[variablelist +[[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.]] +] +[endsect] +[section Class template `extract` observer functions] +`` +result_type operator()() const; +operator result_type() const; +`` +[variablelist +[[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][[link high_level_components.boost_python_errors_hpp.class_error_already_set `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;`` +[variablelist +[[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.]] +] +[endsect] +[section Example] +`` +#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 [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel `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& x = extract<X&>(x_obj); + assert(x.value() == 3); +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/function_doc_signature.qbk b/libs/python/doc/reference/function_doc_signature.qbk new file mode 100644 index 0000000000..992f478cc6 --- /dev/null +++ b/libs/python/doc/reference/function_doc_signature.qbk @@ -0,0 +1,129 @@ +[section boost/python/function_doc_signature.hpp] +[section Introduction] +Boost.Python supports docstrings with automatic appending of Pythonic and C++ signatures. This feature is implemented by class `function_doc_signature_generator`. The class uses all of the overloads, supplied arg names and default values, as well as the user-defined docstrings, to generate documentation for a given function. +[endsect] +[section Class `function_doc_signature_generator`] +The class has only one public function which returns a list of strings documenting the overloads of a function. +`` +namespace boost { namespace python { namespace objects { + + class function_doc_signature_generator + { + public: + static list function_doc_signatures(function const *f); + }; + +}}} +`` +[endsect] +[section Example] +`` +#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/raw_function.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) + + +struct X +{ + tuple f(int x = 1, double y = 4.25, char const* z = "wow") + { + return make_tuple(x, y, z); + } +}; + +BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(X_f_overloads, X::f, 0, 3) + +tuple raw_func(tuple args, dict kw) +{ + return make_tuple(args, kw); +} + +BOOST_PYTHON_MODULE(args_ext) +{ + def("f", f, (arg("x")=1, arg("y")=4.25, arg("z")="wow") + , "This is f's docstring" + ); + + def("raw", raw_function(raw_func)); + + def("f1", f, f_overloads("f1's docstring", args("x", "y", "z"))); + + + class_<X>("X", "This is X's docstring", init<>(args("self"))) + .def("f", &X::f + , "This is X.f's docstring" + , args("self","x", "y", "z")) + + ; + +} +`` +Python code: [python] +`` +>>> import args_ext +>>> help(args_ext) +Help on module args_ext: + +NAME + args_ext + +FILE + args_ext.pyd + +CLASSES + Boost.Python.instance(__builtin__.object) + X + + class X(Boost.Python.instance) + | This is X's docstring + | + | Method resolution order: + | X + | Boost.Python.instance + | __builtin__.object + | + | Methods defined here: + | + | __init__(...) + | __init__( (object)self) -> None : + | C++ signature: + | void __init__(struct _object *) + | + | f(...) + | f( (X)self, (int)x, (float)y, (str)z) -> tuple : This is X.f's docstring + | C++ signature: + | class boost::python::tuple f(struct X {lvalue},int,double,char const *) + | + | ................. + | +FUNCTIONS + f(...) + f([ (int)x=1 [, (float)y=4.25 [, (str)z='wow']]]) -> tuple : This is f's docstring + C++ signature: + class boost::python::tuple f([ int=1 [,double=4.25 [,char const *='wow']]]) + + f1(...) + f1([ (int)x [, (float)y [, (str)z]]]) -> tuple : f1's docstring + C++ signature: + class boost::python::tuple f1([ int [,double [,char const *]]]) + + raw(...) + object raw(tuple args, dict kwds) : + C++ signature: + object raw(tuple args, dict kwds) +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/functions.qbk b/libs/python/doc/reference/functions.qbk new file mode 100644 index 0000000000..40b220cd31 --- /dev/null +++ b/libs/python/doc/reference/functions.qbk @@ -0,0 +1,35 @@ +[chapter Function Invocation and Creation + [quickbook 1.7] +] + +[include args.qbk] +[include call.qbk] +[include call_method.qbk] +[include data_members.qbk] +[include make_function.qbk] +[include overloads.qbk] +[include ptr.qbk] +[include raw_function.qbk] +[section Function documentation] +[include function_doc_signature.qbk] +[include pytype_function.qbk] +[endsect] +[section Models of CallPolicies] +[include default_call_policies.qbk] +[include return_arg.qbk] +[include return_internal_reference.qbk] +[include return_value_policy.qbk] +[include with_custodian_and_ward.qbk] +[endsect] +[section Models of ResultConverter] +[include to_python_indirect.qbk] +[include to_python_value.qbk] +[endsect] +[section Models of ResultConverterGenerator] +[include copy_const_reference.qbk] +[include copy_non_const_reference.qbk] +[include manage_new_object.qbk] +[include reference_existing_object.qbk] +[include return_by_value.qbk] +[include return_opaque_pointer.qbk] +[endsect] diff --git a/libs/python/doc/reference/handle.qbk b/libs/python/doc/reference/handle.qbk new file mode 100644 index 0000000000..c7c63abcd9 --- /dev/null +++ b/libs/python/doc/reference/handle.qbk @@ -0,0 +1,190 @@ +[section boost/python/handle.hpp] +[section Introduction] +<boost/python/handle.hpp> provides class template `handle`, a smart pointer for managing reference-counted Python objects. +[endsect] +[section Class template `handle`] +`handle` is a smart pointer to a Python object type; it holds a pointer of type `T*`, where `T` is its template parameter. T must be either a type derived from `PyObject` or a [link pod POD] type whose initial `sizeof(PyObject)` bytes are layout-compatible with `PyObject`. Use `handle<>` at the boundary between the Python/'C' API and high-level code; prefer object for a generalized interface to Python objects. + +In this document, the term "upcast" refers to an operation which converts a pointer `Y*` to a base class `pointer T*` via `static_cast<T*>` if `Y` is derived from `T`, or via C-style cast (`T*`) if it is not. However, in the latter case the "upcast" is ill-formed if the initial `sizeof(PyObject)` bytes of `Y` are not layout-compatible with `PyObject`. + +`` +namespace boost { namespace python +{ + template <class T> + class handle + { + typedef unspecified-member-function-pointer bool_type; + + public: // types + typedef T element_type; + + public: // member functions + ~handle(); + + template <class Y> + explicit handle(detail::borrowed<null_ok<Y> >* p); + + template <class Y> + explicit handle(null_ok<detail::borrowed<Y> >* p); + + template <class Y> + explicit handle(detail::borrowed<Y>* p); + + template <class Y> + explicit handle(null_ok<Y>* p); + + template <class Y> + explicit handle(Y* p); + + handle(); + + handle& operator=(handle const& r); + + template<typename Y> + handle& operator=(handle<Y> const & r); // never throws + + + template <typename Y> + handle(handle<Y> const& r); + + handle(handle const& r); + + T* operator-> () const; + T& operator* () const; + T* get() const; + void reset(); + T* release(); + + operator bool_type() const; // never throws + private: + T* m_p; + }; + + template <class T> struct null_ok; + namespace detail { template <class T> struct borrowed; } +}} +`` +[section Class template `handle` constructors and destructor] +``virtual ~handle();`` +[variablelist +[[Effects][`Py_XDECREF(upcast<PyObject*>(m_p))`]] +] +``template <class Y> +explicit handle(detail::borrowed<null_ok<Y> >* p); +`` +[variablelist +[[Effects][ +``Py_XINCREF(upcast<PyObject*>(p)); +m_p = upcast<T*>(p); +`` +]] +] +``template <class Y> +explicit handle(null_ok<detail::borrowed<Y> >* p);`` +[variablelist +[[Effects][ +``Py_XINCREF(upcast<PyObject*>(p)); + m_p = upcast<T*>(p); +`` +]] +] +``template <class Y> +explicit handle(detail::borrowed<Y>* p);`` +[variablelist +[[Effects][ +``Py_XINCREF(upcast<PyObject*>(p)); + m_p = upcast<T*>(expect_non_null(p)); +`` +]] +] +``template <class Y> +explicit handle(null_ok<Y>* p); +`` +[variablelist +[[Effects][`m_p = upcast<T*>(p);`]] +] +`` +template <class Y> +explicit handle(Y* p); +`` +[variablelist +[[Effects][`m_p = upcast<T*>(expect_non_null(p));`]] +] +`` +handle(); +`` +[variablelist +[[Effects][`m_p = 0;`]] +] +`` +template <typename Y> +handle(handle<Y> const& r); +handle(handle const& r); +`` +[variablelist +[[Effects][m_p = r.m_p; Py_XINCREF(upcast<PyObject*>(m_p));]] +] +[endsect] +[section Class template `handle` modifiers] +`` +handle& operator=(handle const& r); +template<typename Y> +handle& operator=(handle<Y> const & r); // never throws +`` +[variablelist +[[Effects][`Py_XINCREF(upcast<PyObject*>(r.m_p)); Py_XDECREF( upcast<PyObject*>(m_p)); m_p = r.m_p;`]] +] +`` +T* release(); +`` +[variablelist +[[Effects][`T* x = m_p; m_p = 0; return x;`]] +] +`` +void reset(); +`` +[variablelist +[[Effects][`*this = handle<T>();`]] +] +[endsect] +[section Class template `handle` observers] +`` +T* operator-> () const; +T* get() const; +`` +[variablelist +[[Returns][`m_p;`]] +] +`` +T& operator* () const; +`` +[variablelist +[[Returns][`*m_p;`]] +] +`` +operator bool_type() const; // never throws +`` +[variablelist +[[Returns][`0` if `m_p == 0`, a pointer convertible to true otherwise.]] +] +[endsect] +[endsect] +[section Function `borrowed`] +`` +template <class T> +detail::borrowed<T>* borrowed(T* p) +{ + return (detail::borrowed<T>*)p; +} +`` +[endsect] +[section Function `allow_null`] +`` +template <class T> +null_ok<T>* allow_null(T* p) +{ + return (null_ok<T>*)p; +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/has_back_reference.qbk b/libs/python/doc/reference/has_back_reference.qbk new file mode 100644 index 0000000000..f34fc56eda --- /dev/null +++ b/libs/python/doc/reference/has_back_reference.qbk @@ -0,0 +1,115 @@ +[section boost/python/has_back_reference.hpp] +[section Introduction] +<boost/python/has_back_reference.hpp> defines the predicate metafunction `has_back_reference<>`, which can be specialized by the user to indicate that a wrapped class instance holds a `PyObject*` corresponding to a Python object. +[endsect] +[section Class template `has_back_reference`] +A unary metafunction whose value is true iff its argument is a `pointer_wrapper<>`. +`` +namespace boost { namespace python +{ + template<class WrappedClass> class has_back_reference + { + typedef mpl::false_ type; + }; +}} +`` + +A metafunction that is inspected by Boost.Python to determine how wrapped classes can be constructed. + +`type::value` is an integral constant convertible to bool of unspecified type. +Specializations may substitute a true-valued integral constant wrapper for type iff for each invocation of `class_<WrappedClass>::def(init< type-sequence...>())` and the implicitly wrapped copy constructor (unless it is noncopyable), there exists a corresponding constructor `WrappedClass::WrappedClass(PyObject*, type-sequence...)`. If such a specialization exists, the WrappedClass constructors will be called with a "back reference" pointer to the corresponding Python object whenever they are invoked from Python. The easiest way to provide this nested type is to derive the specialization from `mpl::true_`. + +[endsect] +[section Examples] +In C++: +`` +#include <boost/python/class.hpp> +#include <boost/python/module.hpp> +#include <boost/python/has_back_reference.hpp> +#include <boost/python/handle.hpp> +#include <boost/shared_ptr.hpp> + +using namespace boost::python; +using boost::shared_ptr; + +struct X +{ + X(PyObject* self) : m_self(self), m_x(0) {} + X(PyObject* self, int x) : m_self(self), m_x(x) {} + X(PyObject* self, X const& other) : m_self(self), m_x(other.m_x) {} + + handle<> self() { return handle<>(borrowed(m_self)); } + int get() { return m_x; } + void set(int x) { m_x = x; } + + PyObject* m_self; + int m_x; +}; + +// specialize has_back_reference for X +namespace boost { namespace python +{ + template <> + struct has_back_reference<X> + : mpl::true_ + {}; +}} + +struct Y +{ + Y() : m_x(0) {} + Y(int x) : m_x(x) {} + int get() { return m_x; } + void set(int x) { m_x = x; } + + int m_x; +}; + +shared_ptr<Y> +Y_self(shared_ptr<Y> self) { return self; } + +BOOST_PYTHON_MODULE(back_references) +{ + class_<X>("X") + .def(init<int>()) + .def("self", &X::self) + .def("get", &X::get) + .def("set", &X::set) + ; + + class_<Y, shared_ptr<Y> >("Y") + .def(init<int>()) + .def("get", &Y::get) + .def("set", &Y::set) + .def("self", Y_self) + ; +} +`` + The following Python session illustrates that x.self() returns the same Python object on which it is invoked, while y.self() must create a new Python object which refers to the same Y instance. + +In Python: +`` +>>> from back_references import * +>>> x = X(1) +>>> x2 = x.self() +>>> x2 is x +1 +>>> (x.get(), x2.get()) +(1, 1) +>>> x.set(10) +>>> (x.get(), x2.get()) +(10, 10) +>>> +>>> +>>> y = Y(2) +>>> y2 = y.self() +>>> y2 is y +0 +>>> (y.get(), y2.get()) +(2, 2) +>>> y.set(20) +>>> (y.get(), y2.get()) +(20, 20) +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/implicit.qbk b/libs/python/doc/reference/implicit.qbk new file mode 100644 index 0000000000..67ce162ec6 --- /dev/null +++ b/libs/python/doc/reference/implicit.qbk @@ -0,0 +1,69 @@ +[section boost/python/implicit.hpp] +[section Introduction] +`implicitly_convertible` allows Boost.Python to implicitly take advantage of a C++ implicit or explicit conversion when matching Python objects to C++ argument types. +[endsect] +[section Function template `implicit_convertible`] +`` +template <class Source, class Target> +void implicitly_convertible(); +`` +[table +[[Parameter][Description]] +[[Source][The source type of the implicit conversion]] +[[Target][The target type of the implicit conversion]] +] +[variablelist +[[Requires][The declaration `Target t(s);`, where s is of type Source, is valid.]] +[[Effects][registers an rvalue `from_python` converter to Target which can succeed for any `PyObject* p` iff there exists any registered converter which can produce Source rvalues]] +[[Rationale][C++ users expect to be able to take advantage of the same sort of interoperability in Python as they do in C++.]] +] +[endsect] +[section Example] +In C++: +`` +#include <boost/python/class.hpp> +#include <boost/python/implicit.hpp> +#include <boost/python/module.hpp> + +using namespace boost::python; + +struct X +{ + X(int x) : v(x) {} + operator int() const { return v; } + int v; +}; + +int x_value(X const& x) +{ + return x.v; +} + +X make_x(int n) { return X(n); } + +BOOST_PYTHON_MODULE(implicit_ext) +{ + def("x_value", x_value); + def("make_x", make_x); + + class_<X>("X", + init<int>()) + ; + + implicitly_convertible<X,int>(); + implicitly_convertible<int,X>(); +} +`` +In Python: +`` +>>> from implicit_ext import * +>>> x_value(X(42)) +42 +>>> x_value(42) +42 +>>> x = make_x(X(42)) +>>> x_value(x) +42 +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/import.qbk b/libs/python/doc/reference/import.qbk new file mode 100644 index 0000000000..44e3d1ca0c --- /dev/null +++ b/libs/python/doc/reference/import.qbk @@ -0,0 +1,31 @@ +[section boost/python/import.hpp] +[section Introduction] +Exposes a mechanism for importing python modules. +[endsect] +[section Function `import`] +``object import(str name);`` +[variablelist +[[Effects][Imports the module named by name.]] +[[Returns][An instance of object which holds a reference to the imported module.]] +] +[endsect] +[section Examples] +The following example demonstrates the use of import to access a function in python, and later call it from within C++. +`` +#include <iostream> +#include <string> + +using namespace boost::python; + +void print_python_version() +{ + // Load the sys module. + object sys = import("sys"); + + // Extract the python version. + std::string version = extract<std::string>(sys.attr("version")); + std::cout << version << std::endl; +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/indexing.qbk b/libs/python/doc/reference/indexing.qbk new file mode 100644 index 0000000000..0cfc7c7f5d --- /dev/null +++ b/libs/python/doc/reference/indexing.qbk @@ -0,0 +1,271 @@ +[section Indexing support] +[section Introduction] +Indexing is a `Boost Python` facility for easy exportation of indexable C++ containers to Python. Indexable containers are containers that allow random access through the `operator[]` (e.g. `std::vector`). + +While `Boost Python` has all the facilities needed to expose indexable C++ containers such as the ubiquitous std::vector to Python, the procedure is not as straightforward as we'd like it to be. Python containers do not map easily to C++ containers. Emulating Python containers in C++ (see Python Reference Manual, [@http://www.python.org/doc/current/ref/sequence-types.html Emulating container types]) using `Boost.Python` is non trivial. There are a lot of issues to consider before we can map a C++ container to Python. These involve implementing wrapper functions for the methods `__len__`, `__getitem__`, `__setitem__`, `__delitem__`, `__iter__` and `__contains__`. + +The goals: + +* Make indexable C++ containers behave exactly as one would expect a Python container to behave. +* Provide default reference semantics for container element indexing (`__getitem__`) such that c[i] can be mutable. Require: + + `` + val = c[i] + c[i].m() + val == c[i] + `` + + where m is a non-const (mutating) member function (method). +* Return safe references from `__getitem__` such that subsequent adds and deletes to and from the container will not result in dangling references (will not crash Python). +* Support slice indexes. +* Accept Python container arguments (e.g. `lists`, `tuples`) wherever appropriate. +* Allow for extensibility through re-definable policy classes. +* Provide predefined support for the most common STL and STL-like indexable containers. + +[endsect] +[section The Indexing Interface] +The `indexing_suite` class is the base class for the management of C++ containers intended to be integrated to Python. The objective is make a C++ container look and feel and behave exactly as we'd expect a Python container. The class automatically wraps these special Python methods (taken from the Python reference: Emulating container types): + +[variablelist +[[__len__(self)] + [Called to implement the built-in function `len()`. Should return the length of the object, an integer `>= 0`. Also, an object that doesn't define a `__nonzero__()` method and whose `__len__()` method returns zero is considered to be false in a Boolean context.]] +[[__getitem__(self, key)] +[Called to implement evaluation of `self[key]`. For sequence types, the accepted keys should be integers and slice objects. Note that the special interpretation of negative indexes (if the class wishes to emulate a sequence type) is up to the `__getitem__()` method. If key is of an inappropriate type, `TypeError` may be raised; if of a value outside the set of indexes for the sequence (after any special interpretation of negative values), IndexError should be raised. [Note: for loops expect that an IndexError will be raised for illegal indexes to allow proper detection of the end of the sequence.]]] +[[__setitem__(self, key, value)] + [Called to implement assignment to self[key]. Same note as for __getitem__(). This should only be implemented for mappings if the objects support changes to the values for keys, or if new keys can be added, or for sequences if elements can be replaced. The same exceptions should be raised for improper key values as for the __getitem__() method.]] +[[__delitem__(self, key)] + [Called to implement deletion of self[key]. Same note as for __getitem__(). This should only be implemented for mappings if the objects support removal of keys, or for sequences if elements can be removed from the sequence. The same exceptions should be raised for improper key values as for the __getitem__() method.]] +[[__iter__(self)] + [This method is called when an iterator is required for a container. This method should return a new iterator object that can iterate over all the objects in the container. For mappings, it should iterate over the keys of the container, and should also be made available as the method iterkeys(). + +Iterator objects also need to implement this method; they are required to return themselves. For more information on iterator objects, see [@http://www.python.org/doc/current/lib/typeiter.html Iterator Types] in the [@http://www.python.org/doc/current/lib/lib.html Python Library Reference].]] + +[[__contains__(self, item)] + [Called to implement membership test operators. Should return true if item is in self, false otherwise. For mapping objects, this should consider the keys of the mapping rather than the values or the key-item pairs.]] + ] +[endsect] +[section index_suite sub-classes] +The `indexing_suite` is not meant to be used as is. A couple of policy functions must be supplied by subclasses of `indexing_suite`. However, a set of indexing_suite subclasses for the standard indexable STL containers will be provided, In most cases, we can simply use the available predefined suites. In some cases, we can refine the predefined suites to suit our needs. +[section vector_index_suite] +The `vector_indexing_suite` class is a predefined `indexing_suite` derived class designed to wrap `std::vector` (and `std::vector`-like [i.e. a class with `std::vector` interface]) classes. It provides all the policies required by the `indexing_suite`. + +Example usage: +`` +class X {...}; +... +class_<std::vector<X> >("XVec") + .def(vector_indexing_suite<std::vector<X> >()) +; +`` + +XVec is now a full-fledged Python container (see the example in full, along with its python test). +[endsect] +[section map_index_suite] +The `map_indexing_suite` class is a predefined `indexing_suite` derived class designed to wrap `std::map` (and `std::map`-like [i.e. a class with `std::map` interface]) classes. It provides all the policies required by the `indexing_suite`. + +Example usage: + +`` +class X {...}; +... + +class_<std::map<X> >("XMap") + .def(map_indexing_suite<std::map<X> >()) +; +`` + +By default indexed elements are returned by proxy. This can be disabled by supplying `true` in the `NoProxy` template parameter. XMap is now a full-fledged Python container (see the example in full, along with its python test). +[endsect] +[endsect] +[section `indexing_suite` class] +[table +[[Template Parameter][Requirements][Semantics][Default]] +[[Container][A class type][ The container type to be wrapped to Python. ][]] +[[DerivedPolicies][A subclass of indexing_suite][ Derived classes provide the policy hooks. See DerivedPolicies below. ][]] +[[NoProxy][A boolean][ By default indexed elements have Python reference semantics and are returned by proxy. This can be disabled by supplying true in the NoProxy template parameter. ][false]] +[[NoSlice][A boolean][ Do not allow slicing. ][false]] +[[Data][][The container's data type.][Container::value_type]] +[[Index][][The container's index type.][Container::size_type]] +[[Key][][The container's key type.][Container::value_type]] +] +`` +template <class Container, + class DerivedPolicies, + bool NoProxy = false, + bool NoSlice = false, + class Data = typename Container::value_type, + class Index = typename Container::size_type, + class Key = typename Container::value_type> +class indexing_suite : unspecified +{ +public: + indexing_suite(); // default constructor +} +`` +[section DerivedPolicies] + +Derived classes provide the hooks needed by the indexing_suite: +`` +data_type& +get_item(Container& container, index_type i); + +static object +get_slice(Container& container, index_type from, index_type to); + +static void +set_item(Container& container, index_type i, data_type const& v); + +static void +set_slice( + Container& container, index_type from, + index_type to, data_type const& v +); + +template <class Iter> +static void +set_slice(Container& container, index_type from, + index_type to, Iter first, Iter last +); + +static void +delete_item(Container& container, index_type i); + +static void +delete_slice(Container& container, index_type from, index_type to); + +static size_t +size(Container& container); + +template <class T> +static bool +contains(Container& container, T const& val); + +static index_type +convert_index(Container& container, PyObject* i); + +static index_type +adjust_index(index_type current, index_type from, + index_type to, size_type len); +`` + +Most of these policies are self explanatory. However, convert_index and adjust_index deserve some explanation. + +convert_index converts a Python index into a C++ index that the container can handle. For instance, negative indexes in Python, by convention, start counting from the right(e.g. C[-1] indexes the rightmost element in C). convert_index should handle the necessary conversion for the C++ container (e.g. convert -1 to C.size()-1). convert_index should also be able to convert the type of the index (A dynamic Python type) to the actual type that the C++ container expects. + +When a container expands or contracts, held indexes to its elements must be adjusted to follow the movement of data. For instance, if we erase 3 elements, starting from index 0 from a 5 element vector, what used to be at index 4 will now be at index 1: + +`` + [a][b][c][d][e] ---> [d][e] + ^ ^ + 4 1 +`` + +adjust_index takes care of the adjustment. Given a current index, the function should return the adjusted index when data in the container at index from..to is replaced by len elements. +[endsect] +[endsect] +[section class `vector_indexing_suite`] +[table +[[Template Parameter][Requirements][Semantics][Default]] +[[Container][A class type][ The container type to be wrapped to Python. ][]] +[[NoProxy][A boolean][ By default indexed elements have Python reference semantics and are returned by proxy. This can be disabled by supplying true in the NoProxy template parameter. ][false]] +[[DerivedPolicies][A subclass of indexing_suite][ The vector_indexing_suite may still be derived to further tweak any of the predefined policies. Static polymorphism through CRTP (James Coplien. "Curiously Recurring Template Pattern". C++ Report, Feb. 1995) enables the base indexing_suite class to call policy function of the most derived class ][]] +] +`` +template <class Container, + bool NoProxy = false, + class DerivedPolicies = unspecified_default> +class vector_indexing_suite : unspecified_base +{ +public: + + typedef typename Container::value_type data_type; + typedef typename Container::value_type key_type; + typedef typename Container::size_type index_type; + typedef typename Container::size_type size_type; + typedef typename Container::difference_type difference_type; + + data_type& + get_item(Container& container, index_type i); + + static object + get_slice(Container& container, index_type from, index_type to); + + static void + set_item(Container& container, index_type i, data_type const& v); + + static void + set_slice(Container& container, index_type from, + index_type to, data_type const& v); + + template <class Iter> + static void + set_slice(Container& container, index_type from, + index_type to, Iter first, Iter last); + + static void + delete_item(Container& container, index_type i); + + static void + delete_slice(Container& container, index_type from, index_type to); + + static size_t + size(Container& container); + + static bool + contains(Container& container, key_type const& key); + + static index_type + convert_index(Container& container, PyObject* i); + + static index_type + adjust_index(index_type current, index_type from, + index_type to, size_type len); +}; +`` +[endsect] +[section class `map_indexing_suite`] +[table +[[Template Parameter][Requirements][Semantics][Default]] +[[Container][ A class type ][ The container type to be wrapped to Python. ][]] +[[NoProxy][ A boolean ][ By default indexed elements have Python reference semantics and are returned by proxy. This can be disabled by supplying true in the NoProxy template parameter. ][ false ]] +[[DerivedPolicies][ A subclass of indexing_suite ][ The vector_indexing_suite may still be derived to further tweak any of the predefined policies. Static polymorphism through CRTP (James Coplien. "Curiously Recurring Template Pattern". C++ Report, Feb. 1995) enables the base indexing_suite class to call policy function of the most derived class ][]] +] +`` +template <class Container, + bool NoProxy = false, + class DerivedPolicies = unspecified_default> +class map_indexing_suite : unspecified_base +{ +public: + + typedef typename Container::value_type value_type; + typedef typename Container::value_type::second_type data_type; + typedef typename Container::key_type key_type; + typedef typename Container::key_type index_type; + typedef typename Container::size_type size_type; + typedef typename Container::difference_type difference_type; + + static data_type& + get_item(Container& container, index_type i); + + static void + set_item(Container& container, index_type i, data_type const& v); + + static void + delete_item(Container& container, index_type i); + + static size_t + size(Container& container); + + static bool + contains(Container& container, key_type const& key); + + static bool + compare_index(Container& container, index_type a, index_type b); + + static index_type + convert_index(Container& container, PyObject* i); +}; +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/init.qbk b/libs/python/doc/reference/init.qbk new file mode 100644 index 0000000000..7b5a7c11de --- /dev/null +++ b/libs/python/doc/reference/init.qbk @@ -0,0 +1,91 @@ +[section boost/python/init.hpp] +[section Introduction] +<boost/python/init.hpp> defines the interface for exposing C++ constructors to Python as extension class `__init__` functions. +[section 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: +[variablelist +[[docstring][An [link ntbs] whose value will bound to the method's `__doc__` attribute]] +[[keywords][A [link function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions 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 [link concepts.callpolicies 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.]] +] +[endsect] +[endsect] +[section Class template `init`] +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<...>. + +`` +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 + }; +}} +`` +[section 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); +`` +[variablelist +[[Requires][If supplied, doc is an [link 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 [link function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici default_call_policies]. If Tn is [link high_level_components.boost_python_init_hpp.class_template_optional 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 template arguments the user specified. ]] +] +[endsect] +[section Class template `init` observer functions] +`` +template <class Policies> +unspecified operator[](Policies const& policies) const +`` +[variablelist +[[Requires][Policies is a model of [link concepts.callpolicies CallPolicies].]] +[[Effects][Returns a new [link high_level_components.boost_python_init_hpp.introduction.init_expressions init-expression] with all the same properties as the init object except that its call policies are replaced by a reference to policies.]] +] +[endsect] +[endsect] +[section Class template `optional` ] +A MPL sequence which can be used to specify the optional arguments to an __init__ function. +`` +namespace boost { namespace python +{ + template <T1 = unspecified,...Tn = unspecified> + struct optional {}; +}} +`` +[endsect] +[section Example] +Given the C++ declarations: +`` +class Y; +class X +{ + public: + X(int x, Y* y) : m_y(y) {} + X(double); + private: + Y* m_y; +}; +`` +A corresponing 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>()) + ; + +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/instance_holder.qbk b/libs/python/doc/reference/instance_holder.qbk new file mode 100644 index 0000000000..c7c533430a --- /dev/null +++ b/libs/python/doc/reference/instance_holder.qbk @@ -0,0 +1,92 @@ +[section boost/python/instance_holder.hpp] +[section Introduction] +<boost/python/instance_holder.hpp> provides class `instance_holder`, the base class for types which hold C++ instances of wrapped classes. +[endsect] +[section Class template `instance_holder`] +`instance_holder` is an abstract base class whose concrete derived classes hold C++ class instances within their Python object wrappers. To allow multiple inheritance in Python from C++ class wrappers, each such Python object contains a chain of instance_holders. When an `__init__` function for a wrapped C++ class is invoked, a new `instance_holder` instance is created and installed in the Python object using its `install()` function. Each concrete class derived from `instance_holder` must provide a `holds()` implementation which allows Boost.Python to query it for the type(s) it is holding. In order to support the held type's wrapped constructor(s), the class must also provide constructors that can accept an initial `PyObject*` argument referring to the owning Python object, and which forward the rest of their arguments to the constructor of the held type. The initial argument is needed to enable virtual function overriding in Python, and may be ignored, depending on the specific `instance_holder` subclass. +`` +namespace boost { namespace python +{ + class instance_holder : noncopyable + { + public: + // destructor + virtual ~instance_holder(); + + // instance_holder modifiers + void install(PyObject* inst) throw(); + + // instance_holder observers + virtual void* holds(type_info) = 0; + }; +}} +`` +[section Class `intance_holder` destructor] +``virtual ~instance_holder();`` +[variablelist +[[Effects][destroys the object]] +] +[endsect] +[section Class `intance_holder` modifiers] +``void install(PyObject* inst) throw();`` +[variablelist +[[Requires][`inst` is a Python instance of a wrapped C++ class type, or is a type derived from a wrapped C++ class type. ]] +[[Effects][installs the new instance at the head of the Python object's chain of held instances. ]] +[[Throws][nothing]] +] +[endsect] +[section Class `intance_holder` observers] +``virtual void *holds(type_info x) = 0;`` +[variablelist +[[Returns][A pointer to an object of the type described by `x` if `*this` contains such an object, 0 otherwise. ]] +] +[endsect] +[endsect] +[section Examples] +The following is a simplified version of the instance holder template used by Boost.Python to wrap classes held by smart pointers: + +`` +template <class SmartPtr, class Value> +struct pointer_holder : instance_holder +{ + // construct from the SmartPtr type + pointer_holder(SmartPtr p) + :m_p(p) + + // Forwarding constructors for the held type + pointer_holder(PyObject*) + :m_p(new Value()) + { + } + + template<class A0> + pointer_holder(PyObject*,A0 a0) + :m_p(new Value(a0)) + { + } + + template<class A0,class A1> + pointer_holder(PyObject*,A0 a0,A1 a1) + :m_p(new Value(a0,a1)) + { + } + ... + + private: // required holder implementation + void* holds(type_info dst_t) + { + // holds an instance of the SmartPtr type... + if (dst_t == python::type_id<SmartPtr>()) + return &this->m_p; + + // ...and an instance of the SmartPtr's element_type, if the + // pointer is non-null + return python::type_id<Value>() == dst_t ? &*this->m_p : 0; + } + + private: // data members + SmartPtr m_p; +}; + `` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/iterator.qbk b/libs/python/doc/reference/iterator.qbk new file mode 100644 index 0000000000..c4ee68e0b9 --- /dev/null +++ b/libs/python/doc/reference/iterator.qbk @@ -0,0 +1,111 @@ +[section boost/python/iterator.hpp] +[section Introduction] +<boost/python/iterator.hpp> provides types and functions for creating [@http://www.python.org/doc/current/lib/typeiter.html Python iterators] from C++ Containers and Iterators. Note that if your `class_` supports random-access iterators, implementing [@http://www.python.org/doc/current/ref/sequence-types.html#l2h-128 __getitem__] (also known as the Sequence Protocol) may serve you better than using this facility: Python will automatically create an iterator type for you (see [@http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-35 `iter()`]), and each access can be range-checked, leaving no possiblity of accessing through an invalidated C++ iterator. +[endsect] +[section Class template `iterator`] +Instances of `iterator<C,P>` hold a reference to a callable Python object which, when invoked from Python, expects a single argument c convertible to C and creates a Python iterator that traverses `[c.begin(), c.end())`. The optional [link concepts.callpolicies CallPolicies] `P` can be used to control how elements are returned during iteration. + +In the table below, c is an instance of Container. + +[table +[[Template Parameter][Requirements][Semantics][Default]] +[[Container][`[c.begin(),c.end()`) is a valid Iterator range.][The result will convert its argument to c and call c.begin() and c.end() to acquire iterators. To invoke Container's const `begin()` and `end()` functions, make it const.][ ]] +[[NextPolicies][A default-constructible model of [link concepts.callpolicies CallPolicies].][Applied to the resulting iterators' `next()` method.][An unspecified model of [link concepts.callpolicies CallPolicies] which always makes a copy of the result of deferencing the underlying C++ iterator]] +] + +`` +namespace boost { namespace python + { + template <class Container, class NextPolicies = unspecified> + struct iterator : object + { + iterator(); + }; + }} +`` +[endsect] +[section Class template iterator constructors] +``iterator()`` + +[variablelist +[[Effects][Initializes its base class with the result of: +``range<NextPolicies>(&iterators<Container>::begin, &iterators<Container>::end)``]] +[[Postconditions][`this->get()` points to a Python callable object which creates a Python iterator as described above.]] +[[Rationale][Provides an easy way to create iterators for the common case where a C++ class being wrapped provides `begin()` and `end()`.]] +] +[endsect] +[section Class template `iterators`] +A utility class template which provides a way to reliably call its argument's `begin()` and `end()` member functions. Note that there is no portable way to take the address of a member function of a C++ standard library container, so `iterators<>` can be particularly helpful when wrapping them. + +In the table below, x is an instance of C. +[table +[[Required Valid Expression][Type]] +[[x.begin()][Convertible to C::const_iterator if C is a const type; convertible to C::iterator otherwise.]] +[[x.end()][Convertible to C::const_iterator if C is a const type; convertible to C::iterator otherwise.]] +] +`` +namespace boost { namespace python +{ + template <class C> + struct iterators + { + typedef typename C::const_iterator iterator; + static iterator begin(C& x); + static iterator end(C& x); + }; +}} +`` +[endsect] +[section Class template iterators nested types] +If C is a const type,``typedef typename C::const_iterator iterator;`` +Otherwise: ``typedef typename C::iterator iterator;`` +[endsect] +[section Class template iterators static functions] +``static iterator begin(C&);`` +[variablelist [[Returns][`x.begin()`]]] +``static iterator end(C&);`` +[variablelist [[Returns][`x.end()`]]] +[endsect] +[section Functions] +`` +template <class NextPolicies, class Target, class Accessor1, class Accessor2> +object range(Accessor1 start, Accessor2 finish); + +template <class NextPolicies, class Accessor1, class Accessor2> +object range(Accessor1 start, Accessor2 finish); + +template <class Accessor1, class Accessor2> +object range(Accessor1 start, Accessor2 finish); +`` +[variablelist +[[Requires][ NextPolicies is a default-constructible model of [link concepts.callpolicies CallPolicies].]] +[[Effects][The first form creates a Python callable object which, when invoked, converts its argument to a Target object x, and creates a Python iterator which traverses `[bind(start,_1)(x), bind(finish,_1)(x))`, applying NextPolicies to the iterator's `next()` function. +The second form is identical to the first, except that Target is deduced from Accessor1 as follows: + +# If Accessor1 is a function type, Target is the type of its first argument. +# If Accessor1 is a data member pointer of the form `R (T::*)`, Target is identical to `T`. +# If Accessor1 is a member function pointer of the form `R (T::*)(arguments...) cv-opt`, where cv-opt is an optional cv-qualifier, Target is identical to `T`. + +The third form is identical to the second, except that NextPolicies is an unspecified model of [link concepts.callpolicies CallPolicies] which always makes a copy of the result of deferencing the underlying C++ iterator + +]] +[[Rationale][The use of `boost::bind()` allows C++ iterators to be accessed through functions, member functions or data member pointers. Customization of NextPolicies (e.g. using [link function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r return_internal_reference]) is useful when it is expensive to copy sequence elements of a wrapped class type. Customization of Target is useful when Accessor1 is a function object, or when a base class of the intended target type would otherwise be deduced.]] +] +[endsect] +[section Example] +`` +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> + +#include <vector> + +using namespace boost::python; +BOOST_PYTHON_MODULE(demo) +{ + class_<std::vector<double> >("dvec") + .def("__iter__", iterator<std::vector<double> >()) + ; +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/list.qbk b/libs/python/doc/reference/list.qbk new file mode 100644 index 0000000000..fd602c1852 --- /dev/null +++ b/libs/python/doc/reference/list.qbk @@ -0,0 +1,60 @@ +[section boost_python_list.hpp] +[section Introduction] +Exposes a [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] for the Python [@http://www.python.org/doc/current/lib/typesseq-mutable.html list] type. +[endsect] +[section Class `list`] +Exposes the [@http://www.python.org/doc/current/lib/typesseq-mutable.html 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 [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] concept definition. Since `list` is publicly derived from [link object_wrappers.boost_python_object_hpp.class_object `object`], the public `object` interface applies to `list` instances as well.`` +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); + }; +}} +`` +[endsect] +[section Example] +`` +using namespace boost::python; + +// Return the number of zeroes in the list +long zeroes(list l) +{ + return l.count(0); +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/long.qbk b/libs/python/doc/reference/long.qbk new file mode 100644 index 0000000000..dddc3944e2 --- /dev/null +++ b/libs/python/doc/reference/long.qbk @@ -0,0 +1,38 @@ +[section boost/python/long.hpp] +[section Introduction] +Exposes a [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] for the Python [@http://www.python.org/doc/current/lib/typesnumeric.html long] integer type. +[endsect] +[section Class `long_`] +Exposes the [@http://www.python.org/doc/current/lib/typesnumeric.html 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 [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] concept definition. Since `long_` is publicly derived from [link object_wrappers.boost_python_object_hpp.class_object `object`], the public `object` interface applies to `long_` instances as well. +`` +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); + }; +}} +`` +[endsect] +[section 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); +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/lvalue_from_pytype.qbk b/libs/python/doc/reference/lvalue_from_pytype.qbk new file mode 100644 index 0000000000..7b5e907cd8 --- /dev/null +++ b/libs/python/doc/reference/lvalue_from_pytype.qbk @@ -0,0 +1,120 @@ +[section boost/python/lvalue_from_pytype.hpp] +[section Introduction] +<boost/python/lvalue_from_pytype.hpp> supplies a facility for extracting C++ objects from within Python instances of a given type. This is typically useful for dealing with "traditional" Python extension types. +[endsect] +[section Class template `lvalue_from_pytype`] +Class template lvalue_from_pytype will register from_python converters which, given an object of the given Python type, can extract references and pointers to a particular C++ type. Its template arguments are: + + In the table below, x denotes an object of type PythonObject& +[table +[[Parameter][Requirements][Semantics]] +[[Extractor][a model of [link concepts.extractor `Extractor`] whose execute function returns a reference type.][Extracts the lvalue from the Python object once its type has been confirmed]] +[[python_type][A compile-time constant [@http://www.python.org/doc/2.2/ext/dnt-type-methods.html `PyTypeObject*`]][The Python type of instances convertible by this converter. Python subtypes are also convertible.]] +] +`` +namespace boost { namespace python +{ + template <class Extractor, PyTypeObject const* python_type> + struct lvalue_from_pytype + { + lvalue_from_pytype(); + }; +}} +`` +[section Class template `lvalue_from_pytype` constructor] +``lvalue_from_pytype();`` +[variablelist +[[Effects][Registers converters which can convert Python objects of the given type to lvalues of the type returned by Extractor::execute.]] +] +[endsect] +[endsect] +[section Class template `extract_identity`] +extract_identity is a model of [link concepts.extractor `Extractor`] which can be used in the common case where the C++ type to be extracted is the same as the Python object type. +`` +namespace boost { namespace python +{ + template <class InstanceType> + struct extract_identity + { + static InstanceType& execute(InstanceType& c); + }; +}} +`` +[section Class template `extract_identity` static functions] +``InstanceType& execute(InstanceType& c);`` +[variablelist +[[Returns][c]] +] +[endsect] +[endsect] +[section Class template `extract_member`] +`extract_member` is a model of [link concepts.extractor `Extractor`] which can be used in the common case in the common case where the C++ type to be extracted is a member of the Python object. +`` +namespace boost { namespace python +{ + template <class InstanceType, class MemberType, MemberType (InstanceType::*member)> + struct extract_member + { + static MemberType& execute(InstanceType& c); + }; +}} +`` +[section Class template `extract_member` static functions] +``static MemberType& execute(InstanceType& c);`` +[variablelist +[[Returns][`c.*member`]] +] +[endsect] +[endsect] +[section Example] +This example presumes that someone has implemented the standard noddy example module from the Python documentation, and we want to build a module which manipulates Noddys. Since noddy_NoddyObject is so simple that it carries no interesting information, the example is a bit contrived: it assumes you want to keep track of one particular object for some reason. This module would have to be dynamically linked to the module which defines noddy_NoddyType. + +In C++: +`` +#include <boost/python/module.hpp> +#include <boost/python/handle.hpp> +#include <boost/python/borrowed.hpp> +#include <boost/python/lvalue_from_pytype.hpp> + +// definition lifted from the Python docs +typedef struct { + PyObject_HEAD +} noddy_NoddyObject; + +using namespace boost::python; +static handle<noddy_NoddyObject> cache; + +bool is_cached(noddy_NoddyObject* x) +{ + return x == cache.get(); +} + +void set_cache(noddy_NoddyObject* x) +{ + cache = handle<noddy_NoddyObject>(borrowed(x)); +} + +BOOST_PYTHON_MODULE(noddy_cache) +{ + def("is_cached", is_cached); + def("set_cache", set_cache); + + // register Noddy lvalue converter + lvalue_from_pytype<extract_identity<noddy_NoddyObject>,&noddy_NoddyType>(); +} +`` +In Python: +`` +>>> import noddy +>>> n = noddy.new_noddy() +>>> import noddy_cache +>>> noddy_cache.is_cached(n) +0 +>>> noddy_cache.set_cache(n) +>>> noddy_cache.is_cached(n) +1 +>>> noddy_cache.is_cached(noddy.new_noddy()) +0 +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/make_function.qbk b/libs/python/doc/reference/make_function.qbk new file mode 100644 index 0000000000..78c18237b3 --- /dev/null +++ b/libs/python/doc/reference/make_function.qbk @@ -0,0 +1,83 @@ +[section boost/python/make_function.hpp] +[section Introduction] +make_function() and make_constructor() are the functions used internally by def() and class_<>::def() to produce Python callable objects which wrap C++ functions and member functions. +[endsect] +[section Functions] +`` +template <class F> +object make_function(F f) + +template <class F, class Policies> +object make_function(F f, Policies const& policies) + +template <class F, class Policies, class KeywordsOrSignature> +object make_function(F f, Policies const& policies, KeywordsOrSignature const& ks) + +template <class F, class Policies, class Keywords, class Signature> +object make_function(F f, Policies const& policies, Keywords const& kw, Signature const& sig) +`` +[variablelist +[[Requires][F is a function pointer or member function pointer type. If policies are supplied, it must be a model of CallPolicies. If kewords are supplied, it must be the result of a keyword-expression specifying no more arguments than the arity of f.]] +[[Effects][Creates a Python callable object which, when called from Python, converts its arguments to C++ and calls f. If F is a pointer-to-member-function type, the target object of the function call (*this) will be taken from the first Python argument, and subsequent Python arguments will be used as the arguments to f. + +* If policies are supplied, it will be applied to the function as described here. +* If keywords are supplied, the keywords will be applied in order to the final arguments of the resulting function. +* If Signature is supplied, it should be an instance of an MPL front-extensible sequence representing the function's return type followed by its argument types. Pass a Signature when wrapping function object types whose signatures can't be deduced, or when you wish to override the types which will be passed to the wrapped function. ]] +[[Returns][An instance of object which holds the new Python callable object.]] +[[Caveats][An argument of pointer type may be 0 if None is passed from Python. An argument type which is a constant reference may refer to a temporary which was created from the Python object for just the duration of the call to the wrapped function, for example a std::vector conjured up by the conversion process from a Python list. Use a non-const reference argument when a persistent lvalue is required. ]] +] +`` +template <class F> +object make_constructor(F f) + +template <class F, class Policies> +object make_constructor(F f, Policies const& policies) + +template <class F, class Policies, class KeywordsOrSignature> +object make_constructor(F f, Policies const& policies, KeywordsOrSignature const& ks) + +template <class F, class Policies, class Keywords, class Signature> +object make_constructor(F f, Policies const& policies, Keywords const& kw, Signature const& sig) +`` +[variablelist +[[Requires][F is a function pointer type. If policies are supplied, it must be a model of CallPolicies. If kewords are supplied, it must be the result of a keyword-expression specifying no more arguments than the arity of f.]] +[[Effects][Creates a Python callable object which, when called from Python, converts its arguments to C++ and calls f.]] +[[Returns][An instance of object which holds the new Python callable object.]] +] + +[endsect] +[section Example] +C++ function exposed below returns a callable object wrapping one of two functions. +`` +#include <boost/python/make_function.hpp> +#include <boost/python/module.hpp> + +char const* foo() { return "foo"; } +char const* bar() { return "bar"; } + +using namespace boost::python; +object choose_function(bool selector) +{ + if (selector) + return boost::python::make_function(foo); + else + return boost::python::make_function(bar); +} + +BOOST_PYTHON_MODULE(make_function_test) +{ + def("choose_function", choose_function); +} +`` +It can be used this way in Python: +`` +>>> from make_function_test import * +>>> f = choose_function(1) +>>> g = choose_function(0) +>>> f() +'foo' +>>> g() +'bar' +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/manage_new_object.qbk b/libs/python/doc/reference/manage_new_object.qbk new file mode 100644 index 0000000000..95cc6859c7 --- /dev/null +++ b/libs/python/doc/reference/manage_new_object.qbk @@ -0,0 +1,56 @@ +[section boost/python/manage_new_object.hpp] +[section Class `manage_new_object`] +`manage_new_object` is a model of [link concepts.resultconverter.resultconvertergenerator_concept ResultConverterGenerator] which can be used to wrap C++ functions which return a pointer to an object allocated with a new-expression, and expect the caller to take responsibility for deleting that object. +`` +namespace boost { namespace python +{ + struct manage_new_object + { + template <class T> struct apply; + }; +}} +`` +[endsect] +[section Class `manage_new_object` metafunctions] +``template <class T> struct apply`` +[variablelist +[[Requires][`T` is `U*` for some `U`.]] +[[Returns][`typedef to_python_indirect<T> type;`]] +] +[endsect] +[section Example] +In C++: +`` +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/manage_new_object.hpp> +#include <boost/python/return_value_policy.hpp> + + +struct Foo { + Foo(int x) : x(x){} + int get_x() { return x; } + int x; +}; + +Foo* make_foo(int x) { return new Foo(x); } + +// Wrapper code +using namespace boost::python; +BOOST_PYTHON_MODULE(my_module) +{ + def("make_foo", make_foo, return_value_policy<manage_new_object>()) + class_<Foo>("Foo") + .def("get_x", &Foo::get_x) + ; +} +`` +Python code: +`` +>>> from my_module import * +>>> f = make_foo(3) # create a Foo object +>>> f.get_x() +3 +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/module.qbk b/libs/python/doc/reference/module.qbk new file mode 100644 index 0000000000..31c9fec99c --- /dev/null +++ b/libs/python/doc/reference/module.qbk @@ -0,0 +1,41 @@ +[section boost/python/module.hpp] +[section Introduction] +This header provides the basic facilities needed to create a Boost.Python extension module. +[endsect] +[section Macros] +`BOOST_PYTHON_MODULE(name)` is used to declare Python [@http://www.python.org/doc/2.2/ext/methodTable.html#SECTION003400000000000000000 module initialization functions]. The name argument must exactly match the name of the module to be initialized, and must conform to Python's [@http://www.python.org/doc/2.2/ref/identifiers.html identifier naming rules]. Where you would normally write + +`` +extern "C" void initname() +{ + ... +} +`` +Boost.Python modules should be initialized with +`` +BOOST_PYTHON_MODULE(name) +{ + ... +} +`` +This macro generates two functions in the scope where it is used: `extern "C" void initname()`, and `void init_module_name()`, whose body must follow the macro invocation. `init_name` passes `init_module_name` to [link high_level_components.boost_python_errors_hpp.functions handle_exception()] so that any C++ exceptions generated are safely processeed. During the body of `init_name`, the [link high_level_components.boost_python_scope_hpp current scope] refers to the module being initialized. +[endsect] +[section Examples] +C++ module definition: +`` +#include <boost/python/module.hpp> + +BOOST_PYTHON_MODULE(xxx) +{ + throw "something bad happened" +} +`` +Interactive Python: +`` +>>> import xxx +Traceback (most recent call last): + File "", line 1, in ? +RuntimeError: Unidentifiable C++ Exception +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/numeric.qbk b/libs/python/doc/reference/numeric.qbk new file mode 100644 index 0000000000..4ccb0d3879 --- /dev/null +++ b/libs/python/doc/reference/numeric.qbk @@ -0,0 +1,153 @@ +[section boost/python/numeric.hpp] +[section Introduction] +Exposes a [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] for the Python [@http://www.python.org/dev/doc/devel/lib/typesmapping.html array] type. +[endsect] +[section Class `array`] +Provides access to the array types of [@http://www.pfdubois.com/numpy/ Numerical Python]\ 's [@http://www.pfdubois.com/numpy/#Numeric Numeric] and [@http://stsdas.stsci.edu/numarray/index.html 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 [link concepts.objectwrapper.typewrapper_concept_requirements 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 numarray.NDArray as the associated Python type if the numarray module is installed in the default location. Otherwise it falls back to use Numeric.ArrayType. If neither extension module is installed, overloads of wrapped C++ functions with numeric::array parameters will never be matched, 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. +`` +namespace boost { namespace python { namespace numeric +{ + class array : public object + { + public: + object astype(); + template <class Type> + object astype(Type const& type_); + + template <class Type> + array 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 Sequence> + object factory(Sequence const&); + template <class Sequence, class Typecode> + object factory(Sequence const&, Typecode const&, bool copy = true, bool savespace = false); + template <class Sequence, class Typecode, class Type> + object factory(Sequence const&, Typecode const&, bool copy, bool savespace, Type const&); + template <class Sequence, class Typecode, class Type, class Shape> + object factory(Sequence const&, Typecode const&, bool copy, bool savespace, Type const&, Shape const&); + + 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); + static void get_module_name(); + + 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; + }; +}}} +`` +[endsect] +[section Class `array` observer functions] +`` +object factory(); +template <class Sequence> +object factory(Sequence const&); +template <class Sequence, class Typecode> +object factory(Sequence const&, Typecode const&, bool copy = true, bool savespace = false); +template <class Sequence, class Typecode, class Type> +object factory(Sequence const&, Typecode const&, bool copy, bool savespace, Type const&); +template <class Sequence, class Typecode, class Type, class Shape> +object factory(Sequence const&, Typecode const&, bool copy, bool savespace, Type const&, Shape const&); +`` +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> +array 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++. +[endsect] +[section Class `array` static functions] +`` +static void set_module_and_type(char const* package_path, char const* type_name); +static void set_module_and_type(); +`` +[variablelist +[[Requires][package_path and type_name, if supplied, is an [link ntbs].]] +[[Effects][The first form sets the package path of the module that 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.]] +] +``static std::string get_module_name()`` +[variablelist +[[Effects][Returns the name of the module containing the class that will be held by new `numeric::array` instances.]] +] +[endsect] +[section 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; +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/object.qbk b/libs/python/doc/reference/object.qbk new file mode 100644 index 0000000000..26b4840d5d --- /dev/null +++ b/libs/python/doc/reference/object.qbk @@ -0,0 +1,574 @@ +[section boost/python/object.hpp] +[section 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. +[endsect] +[section Class `slice_nil`] +`` +class slice_nil; +static const _ = slice_nil(); +`` +A type that can be used to get the effect of leaving out an index in a Python slice expression: +`` +>>> x[:-1] +>>> x[::-1] +`` +C++ equivalent: +`` +x.slice(_,-1) +x[slice(_,_,-1)] +`` +[endsect] +[section Class `const_attribute_policies`] +The policies which are used for proxies representing an attribute access to a const object. +`` +namespace boost { namespace python { namespace api +{ + struct const_attribute_policies + { + typedef char const* key_type; + static object get(object const& target, char const* key); + }; +}}} +`` +[endsect] +[section Class `const_attribute_policies` static functions] +`` +static object get(object const& target, char const* key); +`` +[variablelist +[[Requires][key is an [link ntbs].]] +[[Effects][accesses the attribute of target named by key.]] +[[Returns][An object managing the result of the attribute access.]] +[[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]] +] +[endsect] +[section Class `attribute_policies`] +The policies which are used for proxies representing an attribute access to a mutable object. +`` +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); + }; +}}} +`` +[endsect] +[section Class `attribute_policies` static functions] +`` +static object const& set(object const& target, char const* key, object const& value); +`` +[variablelist +[[Requires][key is an [link ntbs].]] +[[Effects][sets the attribute of target named by key to value.]] +[[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]] +] +`` +static void del(object const&target, char const* key); +`` +[variablelist +[[Requires][key is an [link ntbs].]] +[[Effects][deletes the attribute of target named by key.]] +[[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]] +] +[endsect] +[section Class `const_objattribute_policies`] +The policies which are used for proxies representing an attribute access to a const object when the attribute name is given as a const object. +`` +namespace boost { namespace python { namespace api +{ + struct const_objattribute_policies + { + typedef object const& key_type; + static object get(object const& target, object const& key); + }; +}}} +`` +[endsect] +[section Class `const_objattribute_policies` static functions] +`` +static object get(object const& target, object const& key); +`` +[variablelist +[[Requires][key is an object holding a string.]] +[[Effects][accesses the attribute of target named by key.]] +[[Returns][An object managing the result of the attribute access.]] +[[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]] +] +[endsect] +[section Class `objattribute_policies`] +The policies which are used for proxies representing an attribute access to a mutable object when the attribute name is given as a const object. +`` +namespace boost { namespace python { namespace api +{ + struct objattribute_policies : const_objattribute_policies + { + static object const& set(object const& target, object const& key, object const& value); + static void del(object const&target, object const& key); + }; +}}} +`` +[endsect] +[section Class `objattribute_policies` static functions] +`` +static object const& set(object const& target, object const& key, object const& value); +`` +[variablelist +[[Requires][key is an object holding a string.]] +[[Effects][sets the attribute of target named by key to value.]] +[[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]] +] +`` +static void del(object const&target, object const& key); +`` +[variablelist +[[Requires][key is an object holding a string.]] +[[Effects][deletes the attribute of target named by key.]] +[[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]] +] +[endsect] +[section Class `const_item_policies`] +The policies which are used for proxies representing an item access (via the Python bracket operators []) to a const object. +`` +namespace boost { namespace python { namespace api +{ + struct const_item_policies + { + typedef object key_type; + static object get(object const& target, object const& key); + }; +}}} +`` +[endsect] +[section Class `const_item_policies` static functions] +`` +static object get(object const& target, object const& key); +`` +[variablelist +[[Effects][accesses the item of target specified by key.]] +[[Returns][An object managing the result of the item access.]] +[[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]] +] +[endsect] +[section Class `item_policies`] +The policies which are used for proxies representing an item access (via the Python bracket operators []) to a mutable object. +`` +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); + }; +}}} +`` +[endsect] +[section Class `item_policies` static functions] +`` +static object const& set(object const& target, object const& key, object const& value); +`` +[variablelist +[[Effects][sets the item of target specified by key to value.]] +[[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]] +] +`` +static void del(object const& target, object const& key); +`` +[variablelist +[[Effects][deletes the item of target specified by key.]] +[[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]] +] +[endsect] +[section 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. +`` +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); + }; +}}} +`` +[endsect] +[section Class `const_slice_policies` static functions] +`` +static object get(object const& target, key_type const& key); +`` +[variablelist +[[Effects][accesses the slice of target specified by key.]] +[[Returns][An object managing the result of the slice access.]] +[[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]] +] +[endsect] +[section Class `slice_policies`] +The policies which are used for proxies representing an slice access to a mutable object. +`` +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); + }; +}}} +`` +[endsect] +[section Class `slice_policies` static functions] +`` +static object const& set(object const& target, key_type const& key, object const& value); +`` +[variablelist +[[Effects][sets the slice of target specified by key to value.]] +[[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]] +] +`` +static void del(object const& target, key_type const& key); +`` +[variablelist +[[Effects][deletes the slice of target specified by key.]] +[[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]] +] +[endsect] +[section Class template `object_operators`] +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. +`` +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; + + detail::args_proxy operator* () const; + object operator()(detail::args_proxy const &args) const; + object operator()(detail::args_proxy const &args, + detail::kwds_proxy const &kwds) 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*); + proxy<const_object_objattribute> attr(object const&) const; + proxy<object_objattribute> attr(object 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); + }; +}}} +`` +[endsect] +[section 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; +`` +[variablelist +[[Effects][`call<object>(object(*static_cast<U*>(this)).ptr(), a1, a2,...aN)`]] +] +``object operator()(detail::args_proxy const &args) const; `` +[variablelist +[[Effects][`call object with arguments given by the tuple args`]] +] +``object operator()(detail::args_proxy const &args, + detail::kwds_proxy const &kwds) const; + +`` +[variablelist +[[Effects][`call object with arguments given by the tuple args, and named arguments given by the dictionary kwds`]] +] +``operator bool_type() const;`` +[variablelist +[[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); +`` +[variablelist +[[Requires][name is an [link 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.]] +] +`` +proxy<const_object_objattribute> attr(const object& name) const; +proxy<object_objattribute> attr(const object& name); +`` +[variablelist +[[Requires][name is a object holding a string.]] +[[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); +`` +[variablelist +[[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); +`` +[variablelist +[[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.]] +] +[endsect] +[section 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. +`` +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; + bool is_none() const; + }; +}}} +`` +[endsect] +[section Class `object` constructors and destructor] +``object();`` +[variablelist +[[Effects][Constructs an object managing a reference to the Python None object.]] +[[Throws][nothing.]] +] +``template <class T> +explicit object(T const& x); +`` +[variablelist +[[Effects][converts x to python and manages a reference to it.]] +[[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] and sets a Python TypeError exception if no such conversion is possible.]] +] +`` +~object(); +`` +[variablelist +[[Effects][decrements the reference count of the internally-held object.]] +] +[endsect] +[section Class `object` modifiers] +``PyObject* ptr() const;`` + +[variablelist +[[Returns] [a pointer to the internally-held Python object.]] +] +``bool is_none() const;`` + +[variablelist +[[Returns] [result of `(ptr() == Py_None)`]] +] +[endsect] +[section 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. +`` +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); + }; +}}} +`` +[endsect] +[section Class template `proxy` observer functions] +``operator object() const;`` +[variablelist +[[Effects][applies `Policies::get(target, key)` with the proxy's target and key objects.]] +] +[endsect] +[section Class template `proxy` modifier functions] +`` +proxy const& operator=(proxy const& rhs) const; +template <class T> +inline proxy const& operator=(T const& rhs) const; +`` +[variablelist +[[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); +`` +[variablelist +[[Effects][for a given `operator@=`, `object(*this) @= rhs;`]] +[[Returns][`*this`]] +] +``void del() const;`` +[variablelist +[[Effects][Policies::del(target, key ) with the proxy's target and key objects.]] +] +[endsect] +[section Functions] +`` +template <class T> +void del(proxy<T> const& x); +`` +[variablelist +[[Effects][`x.del()`]] +] +`` +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); +`` +[variablelist +[[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); +`` +[variablelist +[[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); +`` +[variablelist +[[Effects][assigns to `l` the result of applying the corresponding Python inplace operator to `l` and `object(r)`, respectively.]] +[[Returns][l]] +] +``long len(object const& obj);`` +[variablelist +[[Effects][`PyObject_Length(obj.ptr())`]] +[[Returns][`len()` of object.]] +] +[endsect] +[section 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 < len(seq); ++i) + result += seq[i]; + return result; +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/objects.qbk b/libs/python/doc/reference/objects.qbk new file mode 100644 index 0000000000..80ce257ce4 --- /dev/null +++ b/libs/python/doc/reference/objects.qbk @@ -0,0 +1,12 @@ +[chapter Object Wrappers + [quickbook 1.7] +] + +[include dict.qbk] +[include list.qbk] +[include long.qbk] +[include numeric.qbk] +[include object.qbk] +[include str.qbk] +[include slice.qbk] +[include tuple.qbk] diff --git a/libs/python/doc/reference/opaque_pointer_converter.qbk b/libs/python/doc/reference/opaque_pointer_converter.qbk new file mode 100644 index 0000000000..c87cd36ac9 --- /dev/null +++ b/libs/python/doc/reference/opaque_pointer_converter.qbk @@ -0,0 +1,31 @@ +[section boost/python/opaque_pointer_converter.hpp] +[section Introduction] +`opaque<>` registers itself as a converter from Python objects to pointers to undefined types and vice versa. +`` +namespace boost { namespace python +{ + template<class Pointee> + struct opaque + { + opaque(); + }; +}} +`` +[endsect] +[section Class template `opaque` constructor] +``opaque();`` +[variablelist +[[Effects][ +* Registers the instance as a [link to_from_python_type_conversion.boost_python_lvalue_from_pytype_.class_template_lvalue_from_pytyp `lvalue_from_pytype`] converter from Python objects into opaque pointers. + The Python Objects created are named after the type pointed to by the opaque pointer being wrapped. +* Registers the instance as a [link to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert `to_python_converter`] from opaque pointers to Python objects. +]] +] +[note If there is already an instance registered by another module, this instance doesn't try to register again in order to avoid warnings about multiple registrations.] + +[endsect] +[section Macro `BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID(Pointee)`] +This macro must be used to define specializations of the [link utility_and_infrastructure.boost_python_type_id_hpp.functions `type_id`] function which can't be instantiated for incomplete types. +[note The macro must be invoked in every translation unit which uses the opaque converter.] +[endsect] +[endsect] diff --git a/libs/python/doc/reference/operators.qbk b/libs/python/doc/reference/operators.qbk new file mode 100644 index 0000000000..892d33b7d2 --- /dev/null +++ b/libs/python/doc/reference/operators.qbk @@ -0,0 +1,257 @@ +[section boost/python/operators.hpp] +[section Introduction] +<boost/python/operators.hpp> provides types and functions for automatically generating Python [@http://www.python.org/doc/ref/specialnames.html special methods] from the corresponding C++ constructs. Most of these constructs are operator expressions, hence the name. To use the facility, substitute the [link high_level_components.boost_python_operators_hpp.object_self self] object for an object of the class type being wrapped in the expression to be exposed, and pass the result to [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu class_<>::def()]. Much of what is exposed in this header should be considered part of the implementation, so is not documented in detail here. +[endsect] +[section Class `self_ns::self_t`] +`self_ns::self_t` is the actual type of the [link high_level_components.boost_python_operators_hpp.object_self self] object. The library isolates `self_t` in its own namespace, `self_ns`, in order to prevent the generalized operator templates which operate on it from being found by argument-dependent lookup in other contexts. This should be considered an implementation detail, since users should never have to mention `self_t` directly. +`` +namespace boost { namespace python { namespace self_ns { +{ + unspecified-type-declaration self_t; + + // inplace operators + template <class T> operator_<unspecified> operator+=(self_t, T); + template <class T> operator_<unspecified> operator-=(self_t, T); + template <class T> operator_<unspecified> operator*=(self_t, T); + template <class T> operator_<unspecified> operator/=(self_t, T); + template <class T> operator_<unspecified> operator%=(self_t, T); + template <class T> operator_<unspecified> operator>>=(self_t, T); + template <class T> operator_<unspecified> operator<<=(self_t, T); + template <class T> operator_<unspecified> operator&=(self_t, T); + template <class T> operator_<unspecified> operator^=(self_t, T); + template <class T> operator_<unspecified> operator|=(self_t, T); + + // comparisons + template <class L, class R> operator_<unspecified> operator==(L const&, R const&); + template <class L, class R> operator_<unspecified> operator!=(L const&, R const&); + template <class L, class R> operator_<unspecified> operator<(L const&, R const&); + template <class L, class R> operator_<unspecified> operator>(L const&, R const&); + template <class L, class R> operator_<unspecified> operator<=(L const&, R const&); + template <class L, class R> operator_<unspecified> operator>=(L const&, R const&); + + // non-member operations + template <class L, class R> operator_<unspecified> operator+(L const&, R const&); + template <class L, class R> operator_<unspecified> operator-(L const&, R const&); + template <class L, class R> operator_<unspecified> operator*(L const&, R const&); + template <class L, class R> operator_<unspecified> operator/(L const&, R const&); + template <class L, class R> operator_<unspecified> operator%(L const&, R const&); + template <class L, class R> operator_<unspecified> operator>>(L const&, R const&); + template <class L, class R> operator_<unspecified> operator<<(L const&, R const&); + template <class L, class R> operator_<unspecified> operator&(L const&, R const&); + template <class L, class R> operator_<unspecified> operator^(L const&, R const&); + template <class L, class R> operator_<unspecified> operator|(L const&, R const&); + template <class L, class R> operator_<unspecified> pow(L const&, R const&); + + // unary operations + operator_<unspecified> operator-(self_t); + operator_<unspecified> operator+(self_t); + operator_<unspecified> operator~(self_t); + operator_<unspecified> operator!(self_t); + + // value operations + operator_<unspecified> int_(self_t); + operator_<unspecified> long_(self_t); + operator_<unspecified> float_(self_t); + operator_<unspecified> complex_(self_t); + operator_<unspecified> str(self_t); + + operator_<unspecified> repr(self_t); +}}}; +`` +The tables below describe the methods generated when the results of the expressions described are passed as arguments to [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu class_<>::def()]. `x` is an object of the class type being wrapped. +[section `self_t` inplace operators] +In the table below, If `r` is an object of type [link high_level_components.boost_python_operators_hpp.class_template_other other<T>], `y` is an object of type `T`; otherwise, `y` is an object of the same type as `r`. +[table +[[C++ Expression][Python Method Name][C++ Implementation]] +[[`self += r`][`__iadd__`][`x += y`]] +[[`self -= r`][`__isub__`][`x -= y`]] +[[`self *= r`][`__imul__`][`x *= y`]] +[[`self /= r`][`__idiv__`][`x /= y`]] +[[`self %= r`][`__imod__`][`x %= y`]] +[[`self >>= r`][`__irshift__`][`x >>= y`]] +[[`self <<= r`][`__ilshift__`][`x <<= y`]] +[[`self &= r`][`__iand__`][`x &= y`]] +[[`self ^= r`][`__ixor__`][`x ^= y`]] +[[`self |= r`][`__ior__`][`x |= y`]] +] +[endsect] +[section `self_t` comparison functions] +In the tables below, if `r` is of type [link high_level_components.boost_python_operators_hpp.class_self_ns_self_t self_t], `y` is an object of the same type as `x`; +if `l` or `r` is an object of type [link high_level_components.boost_python_operators_hpp.class_template_other other<T>], `y` is an object of type `T`; +otherwise, `y` is an object of the same type as `l` or `r`. +`l` is never of type [link high_level_components.boost_python_operators_hpp.class_self_ns_self_t self_t]. + +The column of Python Expressions illustrates the expressions that will be supported in Python for objects convertible to the types of x and y. The secondary operation arises due to Python's [@http://www.python.org/doc/ref/customization.html#l2h-89 reflection rules] for rich comparison operators, and are only used when the corresponding operation is not defined as a method of the y object. +[table +[[C++ Expression][Python Method Name][C++ Implementation][Python Expression (primary, secondary)]] +[[`self == r`][`__eq__`][`x == y`][`x == y`, `y == x`]] +[[`l == self`][`__eq__`][`y == x`][`y == x`, `x == y`]] +[[`self != r`][`__nq__`][`x != y`][`x != y`, `y != x`]] +[[`l != self`][`__nq__`][`y != x`][`y != x`, `x != y`]] +[[`self < r`][`__lt__`][`x < y`][`x < y`, `y > x`]] +[[`l < self`][`__gt__`][`y < x`][`y > x`, `x < y`]] +[[`self > r`][`__gt__`][`x > y`][`x > y`, `y < x`]] +[[`l > self`][`__lt__`][`y > x`][`y < x`, `x > y`]] +[[`self <= r`][`__le__`][`x <= y`][`x <= y`, `y >= x`]] +[[`l <= self`][`__ge__`][`y <= x`][`y >= x`, `x <= y`]] +[[`self >= r`][`__ge__`][`x >= y`][`x >= y`, `y <= x`]] +[[`l <= self`][`__le__`][`y >= x`][`y <= x`, `x >= y`]] +] +[endsect] +[section `self_t` non-member operations] +The operations whose names begin with "__r" below will only be called if the left-hand operand does not already support the given operation, as described [@http://www.python.org/doc/current/ref/numeric-types.html#l2h-152 here]. +[table +[[C++ Expression][Python Method Name][C++ Implementation]] +[[`self + r`][`__add__`][`x + y`]] +[[`l + self`][`__radd__`][`y + x`]] +[[`self - r`][`__sub__`][`x - y`]] +[[`l - self`][`__rsub__`][`y - x`]] +[[`self * r`][`__mult__`][`x * y`]] +[[`l * self`][`__rmult__`][`y * x`]] +[[`self / r`][`__div__`][`x / y`]] +[[`l / self`][`__rdiv__`][`y / x`]] +[[`self % r`][`__mod__`][`x % y`]] +[[`l % self`][`__rmod__`][`y % x`]] +[[`self >> r`][`__rshift__`][`x >> y`]] +[[`l >> self`][`__rrshift__`][`y >> x`]] +[[`self << r`][`__lshift__`][`x << y`]] +[[`l << self`][`__rlshift__`][`y << x`]] +[[`self & r`][`__and__`][`x & y`]] +[[`l & self`][`__rand__`][`y & x`]] +[[`self ^ r`][`__xor__`][`x ^ y`]] +[[`l ^ self`][`__rxor__`][`y ^ x`]] +[[`self | r`][`__or__`][`x | y`]] +[[`l | self`][`__ror__`][`y | x`]] +[[`pow(self, r)`][`__pow__`][`x ** y`]] +[[`pow(l, self)`][`__rpow__`][`y ** x`]] +] +[endsect] +[section `self_t` unary operations] +[table +[[C++ Expression][Python Method Name][C++ Implementation]] +[[`-self`][`__neg__`][`-x`]] +[[`+self`][`__pos__`][`+x`]] +[[`~self`][`__invert__`][`~x`]] +[[`not self` or `!self`][`__nonzero__`][`!!x`]] +] +[endsect] +[section `self_t` value operations] +[table +[[C++ Expression][Python Method Name][C++ Implementation]] +[[`int_(self)`][`__int__`][`long(x)`]] +[[`long_(self)`][`__long__`][`PyLong_FromLong(x)`]] +[[`float_(self)`][`__float__`][`double(x)`]] +[[`complex_(self)`][`__complex__`][`std::complex<double>(x)`]] +[[`str(self)`][`__str__`][`lexical_cast<std::string>(x)`]] +[[`repr(self)`][`__repr__`][`lexical_cast<std::string>(x)`]] +] +[endsect] +[endsect] +[section Class template `other`] +Instances of `other<T>` can be used in operator expressions with [link high_level_components.boost_python_operators_hpp.object_self self]; the result is equivalent to the same expression with a `T` object in place of `other<T>`. Use `other<T>` to prevent construction of a `T` object in case it is heavyweight, when no constructor is available, or simply for clarity. +`` +namespace boost { namespace python +{ + template <class T> + struct other + { + }; +}} +`` +[endsect] +[section Class template `detail::operator_`] +Instantiations of `detail::operator_<>` are used as the return type of operator expressions involving [link high_level_components.boost_python_operators_hpp.object_self self]. This should be considered an implementation detail and is only documented here as a way of showing how the result of self-expressions match calls to [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel.class_template_class_modifier_fu `class_<>::def()`]. +`` +namespace boost { namespace python { namespace detail +{ + template <unspecified> + struct operator_ + { + }; +}}} +`` +[endsect] +[section Object `self`] +`` +namespace boost { namespace python +{ + using self_ns::self; +}} +`` +[endsect] +[section Example] +`` +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/operators.hpp> +#include <boost/operators.hpp> + +struct number + : boost::integer_arithmetic<number> +{ + explicit number(long x_) : x(x_) {} + operator long() const { return x; } + + template <class T> + number& operator+=(T const& rhs) + { x += rhs; return *this; } + + template <class T> + number& operator-=(T const& rhs) + { x -= rhs; return *this; } + + template <class T> + number& operator*=(T const& rhs) + { x *= rhs; return *this; } + + template <class T> + number& operator/=(T const& rhs) + { x /= rhs; return *this; } + + template <class T> + number& operator%=(T const& rhs) + { x %= rhs; return *this; } + + long x; +}; + +using namespace boost::python; +BOOST_PYTHON_MODULE(demo) +{ + class_<number>("number", init<long>()) + // interoperate with self + .def(self += self) + .def(self + self) + .def(self -= self) + .def(self - self) + .def(self *= self) + .def(self * self) + .def(self /= self) + .def(self / self) + .def(self %= self) + .def(self % self) + + // Convert to Python int + .def(int_(self)) + + // interoperate with long + .def(self += long()) + .def(self + long()) + .def(long() + self) + .def(self -= long()) + .def(self - long()) + .def(long() - self) + .def(self *= long()) + .def(self * long()) + .def(long() * self) + .def(self /= long()) + .def(self / long()) + .def(long() / self) + .def(self %= long()) + .def(self % long()) + .def(long() % self) + ; +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/overloads.qbk b/libs/python/doc/reference/overloads.qbk new file mode 100644 index 0000000000..819ee680fa --- /dev/null +++ b/libs/python/doc/reference/overloads.qbk @@ -0,0 +1,97 @@ +[section boost/python/overloads.hpp] +[section 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 +[section 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: +[variablelist +[[docstring][An [link ntbs] whose value will bound to the methods' `__doc__` attribute]] +[[keywords][A [link function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions 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.]] +] +[endsect] +[endsect] +[section 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] +`` +* If policies are supplied, it must be an instance of a type which models [link concepts.callpolicies CallPolicies], and will be used as the result's call policies. Otherwise the result's call policies will be an instance of [link function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici `default_call_policies`]. +* If docstring is supplied it must be an [link ntbs], and will be used as the result's docstring. Otherwise the result has an empty docstring. +* If keywords is supplied it must be the result of a [link function_invocation_and_creation.boost_python_args_hpp.introduction.keyword_expressions keyword-expression] whose length is no greater than X's maximum arity, and will be used as the result's keywords. Otherwise the result's keywords will be empty. +[endsect] +[section 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. +[endsect] +[section Example] +`` +#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) + +struct Y {}; +struct X +{ + Y& f(int x, double y = 4.25, char const* z = "wow") + { + return inner; + } + Y inner; +}; + +BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(f_member_overloads, f, 1, 3) + +BOOST_PYTHON_MODULE(args_ext) +{ + def("f", f, + f_overloads( + args("x", "y", "z"), "This is f's docstring" + )); + + + class_<Y>("Y") + ; + + class_<X>("X", "This is X's docstring") + .def("f1", &X::f, + f_member_overloads( + args("x", "y", "z"), "f's docstring" + )[return_internal_reference<>()] + ) + ; +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/pickle.qbk b/libs/python/doc/reference/pickle.qbk new file mode 100644 index 0000000000..7f89c2d1c3 --- /dev/null +++ b/libs/python/doc/reference/pickle.qbk @@ -0,0 +1,159 @@ +[section Pickle support] +[section Introduction] +Pickle is a Python module for object serialization, also known as persistence, marshalling, or flattening. + +It is often necessary to save and restore the contents of an object to a file. One approach to this problem is to write a pair of functions that read and write data from a file in a special format. A powerful alternative approach is to use Python's pickle module. Exploiting Python's ability for introspection, the pickle module recursively converts nearly arbitrary Python objects into a stream of bytes that can be written to a file. + +The Boost Python Library supports the pickle module through the interface as described in detail in the [@http://www.python.org/doc/current/lib/module-pickle.html Python Library Reference for pickle]. This interface involves the special methods `__getinitargs__`, `__getstate__` and `__setstate__` as described in the following. Note that `Boost.Python` is also fully compatible with Python's cPickle module. +[endsect] +[section The Pickle Interface] +At the user level, the Boost.Python pickle interface involves three special methods: +[variablelist +[[__getinitargs__][When an instance of a Boost.Python extension class is pickled, the pickler tests if the instance has a `__getinitargs__` method. This method must return a Python `tuple` (it is most convenient to use a [link object_wrappers.boost_python_tuple_hpp.class_tuple `boost::python::tuple`]). When the instance is restored by the unpickler, the contents of this tuple are used as the arguments for the class constructor. + +If `__getinitargs__` is not defined, `pickle.load` will call the constructor (`__init__`) without arguments; i.e., the object must be default-constructible.]] +[[__getstate__][When an instance of a `Boost.Python` extension class is pickled, the pickler tests if the instance has a `__getstate__` method. This method should return a Python object representing the state of the instance.]] +[[__setstate__][When an instance of a `Boost.Python` extension class is restored by the unpickler (`pickle.load`), it is first constructed using the result of `__getinitargs__` as arguments (see above). Subsequently the unpickler tests if the new instance has a `__setstate__` method. If so, this method is called with the result of `__getstate__` (a Python object) as the argument.]] +] + +The three special methods described above may be `.def()`\ 'ed individually by the user. However, `Boost.Python` provides an easy to use high-level interface via the `boost::python::pickle_suite` class that also enforces consistency: `__getstate__` and `__setstate__` must be defined as pairs. Use of this interface is demonstrated by the following examples. +[endsect] +[section Example] +There are three files in `python/test` that show how to provide pickle support. +[section pickle1.cpp] +The C++ class in this example can be fully restored by passing the appropriate argument to the constructor. Therefore it is sufficient to define the pickle interface method `__getinitargs__`. This is done in the following way: +Definition of the C++ pickle function: +`` +struct world_pickle_suite : boost::python::pickle_suite +{ + static + boost::python::tuple + getinitargs(world const& w) + { + return boost::python::make_tuple(w.get_country()); + } +}; +`` +Establishing the Python binding: +`` +class_<world>("world", args<const std::string&>()) + // ... + .def_pickle(world_pickle_suite()) + // ... +`` +[endsect] +[section pickle2.cpp] +The C++ class in this example contains member data that cannot be restored by any of the constructors. Therefore it is necessary to provide the `__getstate__`/`__setstate__` pair of pickle interface methods: + +Definition of the C++ pickle functions: +`` +struct world_pickle_suite : boost::python::pickle_suite + { + static + boost::python::tuple + getinitargs(const world& w) + { + // ... + } + + static + boost::python::tuple + getstate(const world& w) + { + // ... + } + + static + void + setstate(world& w, boost::python::tuple state) + { + // ... + } + }; +`` +Establishing the Python bindings for the entire suite: +`` + class_<world>("world", args<const std::string&>()) + // ... + .def_pickle(world_pickle_suite()) + // ... + +`` + +For simplicity, the `__dict__` is not included in the result of `__getstate__`. This is not generally recommended, but a valid approach if it is anticipated that the object's `__dict__` will always be empty. Note that the safety guard described below will catch the cases where this assumption is violated. +[endsect] +[section pickle3.cpp] +This example is similar to pickle2.cpp. However, the object's `__dict__` is included in the result of `__getstate__`. This requires a little more code but is unavoidable if the object's `__dict__` is not always empty. +[endsect] +[endsect] +[section Pitfall and Safety Guard] +The pickle protocol described above has an important pitfall that the end user of a Boost.Python extension module might not be aware of: + +[*`__getstate__` is defined and the instance's `__dict__` is not empty.] + +The author of a `Boost.Python` extension class might provide a `__getstate__` method without considering the possibilities that: +* his class is used in Python as a base class. Most likely the `__dict__` of instances of the derived class needs to be pickled in order to restore the instances correctly. +* the user adds items to the instance's `__dict__` directly. Again, the `__dict__` of the instance then needs to be pickled. + +To alert the user to this highly unobvious problem, a safety guard is provided. If `__getstate__` is defined and the instance's `__dict__` is not empty, `Boost.Python` tests if the class has an attribute `__getstate_manages_dict__`. An exception is raised if this attribute is not defined: + +`` + RuntimeError: Incomplete pickle support (__getstate_manages_dict__ not set) +`` + +To resolve this problem, it should first be established that the `__getstate__` and `__setstate__` methods manage the instances's `__dict__` correctly. Note that this can be done either at the C++ or the Python level. Finally, the safety guard should intentionally be overridden. E.g. in C++ (from pickle3.cpp): + +`` +struct world_pickle_suite : boost::python::pickle_suite +{ + // ... + + static bool getstate_manages_dict() { return true; } +}; +`` + +Alternatively in Python: + +`` +import your_bpl_module +class your_class(your_bpl_module.your_class): + __getstate_manages_dict__ = 1 + def __getstate__(self): + # your code here + def __setstate__(self, state): + # your code here + +`` +[endsect] +[section Practical Advice] + +* In `Boost.Python` extension modules with many extension classes, providing complete pickle support for all classes would be a significant overhead. In general complete pickle support should only be implemented for extension classes that will eventually be pickled. +* Avoid using `__getstate__` if the instance can also be reconstructed by way of `__getinitargs__`. This automatically avoids the pitfall described above. +* If `__getstate__` is required, include the instance's `__dict__` in the Python object that is returned. + +[endsect] +[section Light-weight alternative: pickle support implemented in Python] +The pickle4.cpp example demonstrates an alternative technique for implementing pickle support. First we direct Boost.Python via the class_::enable_pickling() member function to define only the basic attributes required for pickling: + +`` + class_<world>("world", args<const std::string&>()) + // ... + .enable_pickling() + // ... +`` +This enables the standard Python pickle interface as described in the Python documentation. By "injecting" a `__getinitargs__` method into the definition of the wrapped class we make all instances pickleable: + +`` + # import the wrapped world class + from pickle4_ext import world + + # definition of __getinitargs__ + def world_getinitargs(self): + return (self.get_country(),) + + # now inject __getinitargs__ (Python is a dynamic language!) + world.__getinitargs__ = world_getinitargs +`` +See also the tutorial section on injecting additional methods from Python. +[endsect] +[endsect] diff --git a/libs/python/doc/reference/pointee.qbk b/libs/python/doc/reference/pointee.qbk new file mode 100644 index 0000000000..525ba5d870 --- /dev/null +++ b/libs/python/doc/reference/pointee.qbk @@ -0,0 +1,47 @@ +[section boost/python/pointee.hpp] +[section Introduction] +<boost/python/pointee.hpp> introduces a traits metafunction `template pointee<T>` that can be used to extract the "pointed-to" type from the type of a pointer or smart pointer. +[endsect] +[section Class template `pointee`] +`pointee<T>` is used by the [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel `class_<...>`] template to deduce the type being held when a pointer or smart pointer type is used as its HeldType argument. +`` +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; + }; +} +`` +[endsect] +[section Examples] +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(...) + ... + ; +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/ptr.qbk b/libs/python/doc/reference/ptr.qbk new file mode 100644 index 0000000000..c39c5ac818 --- /dev/null +++ b/libs/python/doc/reference/ptr.qbk @@ -0,0 +1,118 @@ +[section boost/python/ptr.hpp] +[section Introduction] +<boost/python/ptr.hpp> defines the ptr() function template, which allows users to specify how to convert C++ pointer values to python in the context of implementing overridable virtual functions, invoking Python callable objects, or explicitly converting C++ objects to Python. Normally, when passing pointers to Python callbacks, the pointee is copied to ensure that the Python object never holds a dangling reference. To specify that the new Python object should merely contain a copy of a pointer p, the user can pass ptr(p) instead of passing p directly. This interface is meant to mirror the use of boost::ref(), which can be similarly used to prevent copying of referents. + +ptr(p) returns an instance of [link function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper `pointer_wrapper<>`], which can be detected using the [link function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe `is_pointer_wrapper<>`] metafunction; [link function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer `unwrap_pointer<>`] is a metafunction which extracts the original pointer type from a `pointer_wrapper<>`. These classes can be thought of as implementation details. +[endsect] +[section Functions] +`` +template <class T> +pointer_wrapper<T> ptr(T x); +`` +[variablelist +[[Requires][T is a pointer type.]] +[[Returns][pointer_wrapper<T>(x)]] +[[Throws][nothing.]] +] +[endsect] +[section Class template `pointer_wrapper`] +A "type envelope" which is returned by `ptr()`, used to indicate reference semantics for pointers passed to Python callbacks. +`` +namespace boost { namespace python +{ + template<class Ptr> class pointer_wrapper + { + public: + typedef Ptr type; + + explicit pointer_wrapper(Ptr x); + operator Ptr() const; + Ptr get() const; + }; +}} +`` +[endsect] +[section Class template `pointer_wrapper` types] +`` +typedef Ptr type; +`` +The type of the pointer being wrapped. +[endsect] +[section Class template `pointer_wrapper` constructors and destructor] +`` +explicit pointer_wrapper(Ptr x); +`` +[variablelist +[[Requires][`Ptr` is a pointer type]] +[[Effects][Stores `x` in a the `pointer_wrapper<>`. ]] +[[Throws][nothing.]] +] +[endsect] +[section Class template `pointer_wrapper` observer functions] +`` +operator Ptr() const; +Ptr get() const; +`` +[variablelist +[[Returns][a copy of the stored pointer. ]] +[[Rationale][pointer_wrapper is intended to be a stand-in for the actual pointer type, but sometimes it's better to have an explicit way to retrieve the pointer. ]] +] +[endsect] +[section Metafunctions] +[section Class template `is_pointer_wrapper`] +A unary metafunction whose value is true iff its argument is a pointer_wrapper<>. +`` +namespace boost { namespace python +{ + template<class T> class is_pointer_wrapper + { + static unspecified value = ...; + }; +}} +`` +[variablelist +[[Returns][`true` iff `T` is a specialization of `pointer_wrapper<>`. +value is an integral constant convertible to bool of unspecified type ]] +] +[endsect] +[section Class template `unwrap_pointer`] +A unary metafunction which extracts the wrapped pointer type from a specialization of pointer_wrapper<>. +`` +namespace boost { namespace python +{ + template<class T> class unwrap_pointer + { + typedef unspecified type; + }; +}} +`` +[variablelist +[[Returns][`T::type` if `T` is a specialization of `pointer_wrapper<>`, `T` otherwise ]] +] +[endsect] +[endsect] +[section Example] +This example illustrates the use of ptr() to prevent an object from being copied: +`` +#include <boost/python/call.hpp> +#include <boost/python/ptr.hpp> + +class expensive_to_copy +{ + ... +}; + +void pass_as_arg(expensive_to_copy* x, PyObject* f) +{ + // call the Python function f, passing a Python object built around + // which refers to *x by-pointer. + // + // *** Note: ensuring that *x outlives the argument to f() is *** + // *** up to the user! Failure to do so could result in a crash! *** + + boost::python::call<void>(f, ptr(x)); +} +... +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/pytype_function.qbk b/libs/python/doc/reference/pytype_function.qbk new file mode 100644 index 0000000000..18ceff57b2 --- /dev/null +++ b/libs/python/doc/reference/pytype_function.qbk @@ -0,0 +1,194 @@ +[section boost/python/pytype_function.hpp] +[section Introduction] +To support Pythonic signatures the converters should supply a `get_pytype` function returning a pointer to the associated `PyTypeObject`. See for example [link concepts.resultconverter `ResultConverter`] or [link to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert.class_template_to_python_convert `to_python_converter`]. The classes in this header file are meant to be used when implmenting `get_pytype`. There are also `_direct` versions of the templates of `class T` which should be used with undecorated type parameter, expected to be in the conversion registry when the module loads. +[endsect] +[section Class `wrap_pytype`] +This template generates a static `get_pytype` member returning the template parameter. +`` +namespace boost { namespace python { namespace converter{ + + template < PyTypeObject const *pytype > + class wrap_pytype + { + public: + static PyTypeObject const *get_pytype(){return pytype; } + }; + +}}} +`` +[endsect] +[section Class `registered_pytype`] +This template should be used with template parameters which are (possibly decorated) types exported to python using [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel `class_`]. The generated a static `get_pytype` member returns the corresponding python type. +`` +namespace boost { namespace python { namespace converter{ + + template < class T > + class registered_pytype + { + public: + static PyTypeObject const *get_pytype(); + }; + +}}} +`` +[endsect] +[section Class `expected_from_python_type`] +This template generates a static `get_pytype` member which inspects the registered `from_python` converters for the type `T` and returns a matching python type. +`` +namespace boost { namespace python { namespace converter{ + + template < class T > + class expected_from_python_type + { + public: + static PyTypeObject const *get_pytype(); + }; + +}}} +`` +[endsect] +[section Class `to_python_target_type`] +This template generates a static `get_pytype` member returning the python type to which `T` can be converted. +`` +namespace boost { namespace python { namespace converter{ + + template < class T > + class to_python_target_type + { + public: + static PyTypeObject const *get_pytype(); + }; + +}}} +`` +[endsect] +[section Example] +This example presumes that someone has implemented the standard noddy example module from the Python documentation, and placed the corresponding declarations in "noddy.h". Because `noddy_NoddyObject` is the ultimate trivial extension type, the example is a bit contrived: it wraps a function for which all information is contained in the type of its return value. + +C++ module definition: +`` +#include <boost/python/reference.hpp> +#include <boost/python/module.hpp> +#include "noddy.h" + +struct tag {}; +tag make_tag() { return tag(); } + +using namespace boost::python; + +struct tag_to_noddy +#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //unnecessary overhead if py signatures are not supported +: wrap_pytype<&noddy_NoddyType> //inherits get_pytype from wrap_pytype +#endif +{ + static PyObject* convert(tag const& x) + { + return PyObject_New(noddy_NoddyObject, &noddy_NoddyType); + } +}; + +BOOST_PYTHON_MODULE(to_python_converter) +{ + def("make_tag", make_tag); + to_python_converter<tag, tag_to_noddy +#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //invalid if py signatures are not supported + , true +#endif + >(); //"true" because tag_to_noddy has member get_pytype +} +`` +The following example registers to and from python converters using the templates expected_from_python_type and to_pyhton_target_type. +`` +#include <boost/python/module.hpp> +#include <boost/python/def.hpp> +#include <boost/python/extract.hpp> +#include <boost/python/to_python_converter.hpp> +#include <boost/python/class.hpp> + +using namespace boost::python; + +struct A +{ +}; + +struct B +{ + A a; + B(const A& a_):a(a_){} +}; + +// Converter from A to python int +struct BToPython +#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //unnecessary overhead if py signatures are not supported + : converter::to_python_target_type<A> //inherits get_pytype +#endif +{ + static PyObject* convert(const B& b) + { + return incref(object(b.a).ptr()); + } +}; + +// Conversion from python int to A +struct BFromPython +{ + BFromPython() + { + boost::python::converter::registry::push_back + ( &convertible + , &construct + , type_id< B >() +#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //invalid if py signatures are not supported + , &converter::expected_from_python_type<A>::get_pytype//convertible to A can be converted to B +#endif + ); + } + + static void* convertible(PyObject* obj_ptr) + { + extract<const A&> ex(obj_ptr); + if (!ex.check()) return 0; + return obj_ptr; + } + + static void construct( + PyObject* obj_ptr, + converter::rvalue_from_python_stage1_data* data) + { + void* storage = ( + (converter::rvalue_from_python_storage< B >*)data)-> storage.bytes; + + extract<const A&> ex(obj_ptr); + new (storage) B(ex()); + data->convertible = storage; + } +}; + + +B func(const B& b) { return b ; } + +BOOST_PYTHON_MODULE(pytype_function_ext) +{ + to_python_converter< B , BToPython +#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //invalid if py signatures are not supported + ,true +#endif + >(); //has get_pytype + BFromPython(); + + class_<A>("A") ; + + def("func", &func); + +} + + + +>>> from pytype_function_ext import * +>>> print func.__doc__ +func( (A)arg1) -> A : + C++ signature: + struct B func(struct B) +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/raw_function.qbk b/libs/python/doc/reference/raw_function.qbk new file mode 100644 index 0000000000..705428d138 --- /dev/null +++ b/libs/python/doc/reference/raw_function.qbk @@ -0,0 +1,44 @@ +[section boost/python/raw_function.hpp] +[section Introduction] +`raw_function(...)` is used to convert a function taking a [link object_wrappers.boost_python_tuple_hpp.class_tuple `tuple`] and a [link object_wrappers.boost_python_dict_hpp.class_dict `dict`] into a Python callable object which accepts a variable number of arguments and arbitrary keyword arguments. +[endsect] +[section Function `raw_function`] +`` +template <class F> +object raw_function(F f, std::size_t min_args = 0); +`` +[variablelist +[[Requires][f(tuple(), dict()) is well-formed.]] +[[Returns][a callable object which requires at least min_args arguments. When called, the actual non-keyword arguments will be passed in a tuple as the first argument to f, and the keyword arguments will be passed in a dict as the second argument to f. ]] +] +[endsect] +[section Example] +C++: +`` +#include <boost/python/def.hpp> +#include <boost/python/tuple.hpp> +#include <boost/python/dict.hpp> +#include <boost/python/module.hpp> +#include <boost/python/raw_function.hpp> + +using namespace boost::python; + +tuple raw(tuple args, dict kw) +{ + return make_tuple(args, kw); +} + +BOOST_PYTHON_MODULE(raw_test) +{ + def("raw", raw_function(raw)); +} +`` +Python: +`` +>>> from raw_test import * + +>>> raw(3, 4, foo = 'bar', baz = 42) +((3, 4), {'foo': 'bar', 'baz': 42}) +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/reference_existing_object.qbk b/libs/python/doc/reference/reference_existing_object.qbk new file mode 100644 index 0000000000..e95c8fac5f --- /dev/null +++ b/libs/python/doc/reference/reference_existing_object.qbk @@ -0,0 +1,75 @@ +[section boost/python/reference_existing_object.hpp] +[section Class `reference_existing_object`] +`reference_existing_object` is a model of [link concepts.resultconverter.resultconvertergenerator_concept ResultConverterGenerator] which can be used to wrap C++ functions which return a reference or pointer to a C++ object. When the wrapped function is called, the value referenced by its return value is not copied. A new Python object is created which contains a pointer to the referent, and no attempt is made to ensure that the lifetime of the referent is at least as long as that of the corresponding Python object. Thus, it can be *highly dangerous* to use `reference_existing_object` without additional lifetime management from such models of [link concepts.callpolicies CallPolicies] as [link function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward `with_custodian_and_ward`]. This class is used in the implementation of [link function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r `return_internal_reference`]. +`` +namespace boost { namespace python +{ + struct reference_existing_object + { + template <class T> struct apply; + }; +}} +`` +[endsect] +[section Class `reference_existing_object` metafunctions] +``template <class T> struct apply`` +[variablelist +[[Requires][`T` is `U&` or `U*` for some `U`.]] +[[Returns][`typedef to_python_indirect<T, V> type;`, where V is a class whose static execute function constructs an instance holder containing an unowned `U*` pointing to the referent of the wrapped function's return value.]] +] +[endsect] +[section Example] +In C++: +`` +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/reference_existing_object.hpp> +#include <boost/python/return_value_policy.hpp> +#include <utility> + +// classes to wrap +struct Singleton +{ + Singleton() : x(0) {} + + int exchange(int n) // set x and return the old value + { + std::swap(n, x); + return n; + } + + int x; +}; + +Singleton& get_it() +{ + static Singleton just_one; + return just_one; +} + +// Wrapper code +using namespace boost::python; +BOOST_PYTHON_MODULE(singleton) +{ + def("get_it", get_it, + return_value_policy<reference_existing_object>()); + + class_<Singleton>("Singleton") + .def("exchange", &Singleton::exchange) + ; +} +`` +Python code: +`` +>>> import singleton +>>> s1 = singleton.get_it() +>>> s2 = singleton.get_it() +>>> id(s1) == id(s2) # s1 and s2 are not the same object +0 +>>> s1.exchange(42) # but they reference the same C++ Singleton +0 +>>> s2.exchange(99) +42 +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/register_ptr_to_python.qbk b/libs/python/doc/reference/register_ptr_to_python.qbk new file mode 100644 index 0000000000..0c9f72e836 --- /dev/null +++ b/libs/python/doc/reference/register_ptr_to_python.qbk @@ -0,0 +1,86 @@ +[section boost/python/register_ptr_to_python.hpp] +[section Introduction] +<boost/python/register_ptr_to_python.hpp> supplies `register_ptr_to_python`, a function template which registers a conversion for smart pointers to Python. The resulting Python object holds a copy of the converted smart pointer, but behaves as though it were a wrapped copy of the pointee. If the pointee type has virtual functions and the class representing its dynamic (most-derived) type has been wrapped, the Python object will be an instance of the wrapper for the most-derived type. More than one smart pointer type for a pointee's class can be registered. + +Note that in order to convert a Python `X` object to a `smart_ptr<X>&` (non-const reference), the embedded C++ object must be held by `smart_ptr<X>`, and that when wrapped objects are created by calling the constructor from Python, how they are held is determined by the HeldType parameter to `class_<...>` instances. +[endsect] +[section Function `register_ptr_to_python`] +`` +template <class P> +void register_ptr_to_python() +`` +[variablelist +[[Requires][`P` is [link concepts.dereferenceable Dereferenceable].]] +[[Effects][Allows conversions to-python of P instances. ]] +] +[endsect] +[section Example] +Here is an example of a module that contains a class A with virtual functions and some functions that work with boost::shared_ptr<A>. + +In C++: +`` +struct A +{ + virtual int f() { return 0; } +}; + +shared_ptr<A> New() { return shared_ptr<A>( new A() ); } + +int Ok( const shared_ptr<A>& a ) { return a->f(); } + +int Fail( shared_ptr<A>& a ) { return a->f(); } + +struct A_Wrapper: A +{ + A_Wrapper(PyObject* self_): self(self_) {} + int f() { return call_method<int>(self, "f"); } + int default_f() { return A::f(); } + PyObject* self; +}; + +BOOST_PYTHON_MODULE(register_ptr) +{ + class_<A, A_Wrapper>("A") + .def("f", &A::f, &A_Wrapper::default_f) + ; + + def("New", &New); + def("Ok", &Call); + def("Fail", &Fail); + + register_ptr_to_python< shared_ptr<A> >(); +} +`` +In Python: +`` +>>> from register_ptr import * +>>> a = A() +>>> Ok(a) # ok, passed as shared_ptr<A> +0 +>>> Fail(a) # passed as shared_ptr<A>&, and was created in Python! +Traceback (most recent call last): + File "<stdin>", line 1, in ? +TypeError: bad argument type for built-in operation +>>> +>>> na = New() # now "na" is actually a shared_ptr<A> +>>> Ok(a) +0 +>>> Fail(a) +0 +>>> +`` +If shared_ptr<A> is registered as follows: +`` +class_<A, A_Wrapper, shared_ptr<A> >("A") + .def("f", &A::f, &A_Wrapper::default_f) +; +`` +There will be an error when trying to convert shared_ptr<A> to shared_ptr<A_Wrapper>: +`` +>>> a = New() +Traceback (most recent call last): +File "<stdin>", line 1, in ? +TypeError: No to_python (by-value) converter found for C++ type: class boost::shared_ptr<struct A> +>>> +`` +[endsect] diff --git a/libs/python/doc/reference/return_arg.qbk b/libs/python/doc/reference/return_arg.qbk new file mode 100644 index 0000000000..08e6f299cb --- /dev/null +++ b/libs/python/doc/reference/return_arg.qbk @@ -0,0 +1,91 @@ +[section boost/python/return_arg.hpp] +[section Introduction] +`return_arg` and `return_self` instantiations are models of [link concepts.callpolicies `CallPolicies`] which return the specified argument parameter (usually `*this`) of a wrapped (member) function. +[endsect] +[section Class `return_arg`] +[table +[[Parameter][Requirements][Description][Default]] + [[arg_pos][A positive compile-time constant of type `std::size_t`.][the position of the argument to be returned.][1]] +[[Base][A model of [link concepts.callpolicies `CallPolicies`]][Used for policy composition. Any `result_converter` it supplies will be overridden by `return_arg`, but its `precall` and `postcall` policies are composed as described here [link concepts.callpolicies `CallPolicies`].][default_call_policies]] + ] +`` +namespace boost { namespace python +{ + template <size_t arg_pos=1, class Base = default_call_policies> + struct return_arg : Base + { + static PyObject* postcall(PyObject*, PyObject* result); + struct result_converter{ template <class T> struct apply; }; + template <class Sig> struct extract_return_type : mpl::at_c<Sig, arg_pos>{}; + + }; +}} +`` +[endsect] +[section Class `return_arg` static functions] +``PyObject* postcall(PyObject* args, PyObject* result);`` +[variablelist +[[Requires][`PyTuple_Check(args) != 0` and `PyTuple_Size(args) != 0`]] +[[Returns][PyTuple_GetItem(args,arg_pos-1)]] +] +[endsect] +[section Class template `return_self`] +`` +namespace boost { namespace python +{ + template <class Base = default_call_policies> + struct return_self + : return_arg<1,Base> + {}; +}} +`` +[endsect] +[section Example] +C++ module definition: +`` +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/return_arg.hpp> + +struct Widget +{ + Widget() :sensitive_(true){} + bool get_sensitive() const { return sensitive_; } + void set_sensitive(bool s) { this->sensitive_ = s; } + private: + bool sensitive_; +}; + +struct Label : Widget +{ + Label() {} + + std::string get_label() const { return label_; } + void set_label(const std::string &l){ label_ = l; } + + private: + std::string label_; +}; + +using namespace boost::python; +BOOST_PYTHON_MODULE(return_self_ext) +{ + class_<widget>("Widget") + .def("sensitive", &Widget::get_sensitive) + .def("sensitive", &Widget::set_sensitive, return_self<>()) + ; + + class_<Label, bases<Widget> >("Label") + .def("label", &Label::get_label) + .def("label", &Label::set_label, return_self<>()) + ; +} +`` +Python code: +`` +>>> from return_self_ext import * +>>> l1 = Label().label("foo").sensitive(false) +>>> l2 = Label().sensitive(false).label("foo") +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/return_by_value.qbk b/libs/python/doc/reference/return_by_value.qbk new file mode 100644 index 0000000000..2b8b7887ca --- /dev/null +++ b/libs/python/doc/reference/return_by_value.qbk @@ -0,0 +1,62 @@ +[section boost/python/return_by_value.hpp] +[section Class `return_by_value`] +`return_by_value` is a model of [link concepts.resultconverter.resultconvertergenerator_concept ResultConverterGenerator] which can be used to wrap C++ functions returning any reference or value type such that the return value is copied into a new Python object. +`` +namespace boost { namespace python +{ + struct return_by_value + { + template <class T> struct apply; + }; +}} +`` +[endsect] +[section Class `return_by_value` metafunctions] +``template <class T> struct apply`` +[variablelist +[[Returns][`typedef to_python_value<T> type;`]] +] +[endsect] +[section Example] +In C++: +`` +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/return_by_value.hpp> +#include <boost/python/return_value_policy.hpp> + +// classes to wrap +struct Bar { }; + +Bar global_bar; + +// functions to wrap: +Bar b1(); +Bar& b2(); +Bar const& b3(); + +// Wrapper code +using namespace boost::python; +template <class R> +void def_void_function(char const* name, R (*f)()) +{ + def(name, f, return_value_policy<return_by_value>()); +} + +BOOST_PYTHON_MODULE(my_module) +{ + class_<Bar>("Bar"); + def_void_function("b1", b1); + def_void_function("b2", b2); + def_void_function("b3", b3); +} +`` +Python code: +`` +>>> from my_module import * +>>> b = b1() # each of these calls +>>> b = b2() # creates a brand +>>> b = b3() # new Bar object +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/return_internal_reference.qbk b/libs/python/doc/reference/return_internal_reference.qbk new file mode 100644 index 0000000000..240ed0ab01 --- /dev/null +++ b/libs/python/doc/reference/return_internal_reference.qbk @@ -0,0 +1,88 @@ +[section boost/python/return_internal_reference.hpp] +[section Introduction] +`return_internal_reference` instantiations are models of [link concepts.callpolicies `CallPolicies`] which allow pointers and references to objects held internally by a free or member function argument or from the target of a member function to be returned safely without making a copy of the referent. The default for its first template argument handles the common case where the containing object is the target (`*this`) of a wrapped member function. +[endsect] +[section Class template `return_internal_reference`] +[table + [[Parameter][Requirements][Description][Default]] + [[owner_arg][A positive compile-time constant of type `std::size_t`.][The index of the parameter which contains the object to which the reference or pointer is being returned. If used to wrap a member function, parameter 1 is the target object (`*this`). Note that if the target Python object type doesn't support weak references, a Python TypeError exception will be raised when the function being wrapped is called.][]] + [[Base][A model of [link concepts.callpolicies `CallPolicies`]][Used for policy composition. Any `result_converter` it supplies will be overridden by `return_internal_reference`, but its `precall` and `postcall` policies are composed as described here [link concepts.callpolicies `CallPolicies`].][default_call_policies]] +] +`` +namespace boost { namespace python +{ + template <std::size_t owner_arg = 1, class Base = default_call_policies> + struct return_internal_reference : Base + { + static PyObject* postcall(PyObject*, PyObject* result); + typedef reference_existing_object result_converter; + }; +}} +`` +[endsect] +[section Class `return_internal_reference` static functions] +``PyObject* postcall(PyObject* args, PyObject* result);`` +[variablelist +[[Requires][`PyTuple_Check(args) != 0`]] +[[Returns][[link function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_st `with_custodian_and_ward_postcall::postcall(args, result)`]]] +] +[endsect] +[section Example] +C++ module definition: +`` +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/return_internal_reference.hpp> + +class Bar +{ + public: + Bar(int x) : x(x) {} + int get_x() const { return x; } + void set_x(int x) { this->x = x; } + private: + int x; +}; + +class Foo +{ + public: + Foo(int x) : b(x) {} + + // Returns an internal reference + Bar const& get_bar() const { return b; } + + private: + Bar b; +}; + +using namespace boost::python; +BOOST_PYTHON_MODULE(internal_refs) +{ + class_<Bar>("Bar", init<int>()) + .def("get_x", &Bar::get_x) + .def("set_x", &Bar::set_x) + ; + + class_<Foo>("Foo", init<int>()) + .def("get_bar", &Foo::get_bar + , return_internal_reference<>()) + ; +} +`` +Python code: +`` +>>> from internal_refs import * +>>> f = Foo(3) +>>> b1 = f.get_bar() +>>> b2 = f.get_bar() +>>> b1.get_x() +3 +>>> b2.get_x() +3 +>>> b1.set_x(42) +>>> b2.get_x() +42 +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/return_opaque_pointer.qbk b/libs/python/doc/reference/return_opaque_pointer.qbk new file mode 100644 index 0000000000..e87d82b9b7 --- /dev/null +++ b/libs/python/doc/reference/return_opaque_pointer.qbk @@ -0,0 +1,95 @@ +[section boost/python/return_opaque_pointer.hpp] +[section Class `return_opaqe_pointer`] +return_opaque_pointer is a model of [link concepts.resultconverter.resultconvertergenerator_concept ResultConverterGenerator] which can be used to wrap C++ functions returning pointers to undefined types such that the return value is copied into a new Python object. + +In addition to specifying the `return_opaque_pointer` policy the [link to_from_python_type_conversion.boost_python_opaque_pointer_conv.macro_boost_python_opaque_specia `BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID`] macro must be used to define specializations for the [link utility_and_infrastructure.boost_python_type_id_hpp.functions `type_id`] function on the type pointed to by returned pointer. +`` +namespace boost { namespace python +{ + struct return_opaque_pointer + { + template <class R> struct apply; + }; +}} +`` +[endsect] +[section Class `return_opaque_pointer` metafunctions] +``template <class T> struct apply`` +[variablelist +[[Returns][`detail::opaque_conversion_holder<R> type;`]] +] +[endsect] +[section Example] +In C++: +`` +# include <boost/python/return_opaque_pointer.hpp> +# include <boost/python/def.hpp> +# include <boost/python/module.hpp> +# include <boost/python/return_value_policy.hpp> + +typedef struct opaque_ *opaque; + +opaque the_op = ((opaque) 0x47110815); + +opaque get () { return the_op; } +void use (opaque op) { + if (op != the_op) + throw std::runtime_error (std::string ("failed")); +} + +void failuse (opaque op) { + if (op == the_op) + throw std::runtime_error (std::string ("success")); +} + +BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID(opaque_) + +namespace bpl = boost::python; + +BOOST_PYTHON_MODULE(opaque_ext) +{ + bpl::def ( + "get", &::get, bpl::return_value_policy<bpl::return_opaque_pointer>()); + bpl::def ("use", &::use); + bpl::def ("failuse", &::failuse); +} +`` +Python code: +`` +""" +>>> from opaque_ext import * +>>> # +>>> # Check for correct conversion +>>> use(get()) +>>> failuse(get()) +Traceback (most recent call last): + ... +RuntimeError: success +>>> # +>>> # Check that there is no conversion from integers ... +>>> use(0) +Traceback (most recent call last): + ... +TypeError: bad argument type for built-in operation +>>> # +>>> # ... and from strings to opaque objects +>>> use("") +Traceback (most recent call last): + ... +TypeError: bad argument type for built-in operation +""" +def run(args = None): + import sys + import doctest + + if args is not None: + sys.argv = args + return doctest.testmod(sys.modules.get(__name__)) + +if __name__ == '__main__': + print "running..." + import sys + sys.exit(run()[0]) +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/return_value_policy.qbk b/libs/python/doc/reference/return_value_policy.qbk new file mode 100644 index 0000000000..6c2e394cc3 --- /dev/null +++ b/libs/python/doc/reference/return_value_policy.qbk @@ -0,0 +1,59 @@ +[section boost/python/return_value_policy.hpp] +[section Introduction] +return_value_policy instantiations are simply models of [link concepts.callpolicies `CallPolicies`] which are composed of a [link concepts.resultconverter.resultconvertergenerator_concept `ResultConverterGenerator`] and optional `Base` [link concepts.callpolicies `CallPolicies`]. +[endsect] +[section Class template `return_value_policy`] +[table +[[Parameter][Requirements][Default]] + [[ResultConverterGenerator][A model of [link concepts.resultconverter.resultconvertergenerator_concept `ResultConverterGenerator`]][]] +[[Base][A model of [link concepts.callpolicies `CallPolicies`]][default_call_policies]] + ] +`` +namespace boost { namespace python +{ + template <class ResultConverterGenerator, class Base = default_call_policies> + struct return_value_policy : Base + { + typedef ResultConverterGenerator result_converter; + }; +}} +`` +[endsect] +[section Example] +C++ module definition: +`` +#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(my_module) +{ + class_<Bar>("Bar"); + + class_<Foo>("Foo", init<int>()) + .def("get_bar", &Foo::get_bar + , return_value_policy<copy_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 +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/scope.qbk b/libs/python/doc/reference/scope.qbk new file mode 100644 index 0000000000..d17ae69b72 --- /dev/null +++ b/libs/python/doc/reference/scope.qbk @@ -0,0 +1,83 @@ +[section boost/python/scope.hpp] +[section Introduction] +Defines facilities for querying and controlling the Python scope (namespace) which will contain new wrapped classes and functions. +[endsect] +[section 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 it to the associated global Python object. Constructing a scope object with an argument changes the associated global Python object to the one held by the argument, until the lifetime of the scope object ends, at which time the associated global Python object reverts to what it was before the scope object was constructed. +`` +namespace boost { namespace python +{ + class scope : public object + { + public: + scope(scope const&); + scope(object const&); + scope(); + ~scope() + private: + void operator=(scope const&); + }; +}} +`` +[endsect] +[section Class scope constructors and destructor] +`` +explicit scope(scope const& x); +explicit 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. +[endsect] +[section Example] +The following example shows how scope setting can be used to define nested classes. + +C++ Module definition: +`` +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/scope.hpp> +using namespace boost::python; + +struct X +{ + void f() {} + + struct Y { int g() { return 42; } }; +}; + +BOOST_PYTHON_MODULE(nested) +{ + // add some constants to the current (module) scope + scope().attr("yes") = 1; + scope().attr("no") = 0; + + // Change the current scope + scope outer + = class_<X>("X") + .def("f", &X::f) + ; + + // Define a class Y in the current scope, X + class_<X::Y>("Y") + .def("g", &X::Y::g) + ; +} +`` +Interactive Python: +`` +>>> import nested +>>> nested.yes +1 +>>> y = nested.X.Y() +>>> y.g() +42 +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/slice.qbk b/libs/python/doc/reference/slice.qbk new file mode 100644 index 0000000000..32e3363f44 --- /dev/null +++ b/libs/python/doc/reference/slice.qbk @@ -0,0 +1,136 @@ +[section boost/python/slice.hpp] +[section Introduction] +Exposes a [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] for the Python [@http://www.python.org/doc/2.3.3/api/slice-objects.html `slice`] type. +[endsect] +[section Class `slice`] +Exposes the extended slicing protocol by wrapping the built-in slice type. The semantics of the constructors and member functions defined below can be fully understood by reading the [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] concept definition. Since `slice` is publicly derived from [link object_wrappers.boost_python_object_hpp.class_object `object`], the public `object` interface applies to `slice` instances as well. +`` +namespace boost { namespace python +{ + class slice : public object + { + public: + slice(); // create an empty slice, equivalent to [::] + + template <typename Int1, typename Int2> + slice(Int1 start, Int2 stop); + + template <typename Int1, typename Int2, typename Int3> + slice(Int1 start, Int2 stop, Int3 step); + + // Access the parameters this slice was created with. + object start(); + object stop(); + object step(); + + // The return type of slice::get_indices() + template <typename RandomAccessIterator> + struct range + { + RandomAccessIterator start; + RandomAccessIterator stop; + int step; + }; + + template <typename RandomAccessIterator> + range<RandomAccessIterator> + get_indices( + RandomAccessIterator const& begin, + RandomAccessIterator const& end); + }; +}} +`` +[endsect] +[section Class `slice` constructors] +``slice();`` +[variablelist +[[Effects][constructs a slice with default stop, start, and step values. Equivalent to the slice object created as part of the Python expression `base[::]`.]] +[[Throws][nothing]] +] +`` +template <typename Int1, typename Int2> +slice(Int1 start, Int2 stop); +`` +[variablelist +[[Requires][`start`, `stop`, and `step` are of type `slice_nil` or convertible to type `object`.]] +[[Effects][constructs a new slice with default step value and the provided start and stop values. Equivalent to the slice object created by the built-in Python function `slice(start,stop)`, or as part of the Python expression `base[start:stop]`.]] +[[Throws][`error_already_set` and sets a Python TypeError exception if no conversion is possible from the arguments to type object.]] +] +`` +template <typename Int1, typename Int2, typename Int3> +slice(Int1 start, Int2 stop, Int3 step); +`` +[variablelist +[[Requires][`start`, `stop`, and `step` are `slice_nil` or convertible to type `object`.]] +[[Effects][constructs a new slice with start stop and step values. Equivalent to the slice object created by the built-in Python function `slice(start,stop,step)`, or as part of the Python expression `base[start:stop:step]`.]] +[[Throws][`error_already_set` and sets a Python TypeError exception if no conversion is possible from the arguments to type object.]] +] +[endsect] +[section Class `slice` observer functions] +`` +object slice::start() const; +object slice::stop() const; +object slice::step() const; +`` +[variablelist +[[Effects][None]] +[[Throws][nothing]] +[[Returns][the parameter that the slice was created with. If the parameter was omitted or `slice_nil` was used when the slice was created, than that parameter will be a reference to `PyNone` and compare equal to a default-constructed object. In principal, any object may be used when creating a slice object, but in practice they are usually integers.]] +] +`` +template <typename RandomAccessIterator> +slice::range<RandomAccessIterator> +slice::get_indices( + RandomAccessIterator const& begin, + RandomAccessIterator const& end) const; +`` +[variablelist +[[Arguments][A pair of STL-conforming Random Access Iterators that form a half-open range.]] +[[Effects][Create a RandomAccessIterator pair that defines a fully-closed range within the `[begin,end)` range of its arguments. This function translates this slice's indices while accounting for the effects of any PyNone or negative indices, and non-singular step sizes.]] +[[Returns][a `slice::range` that has been initialized with a non-zero value of step and a pair of RandomAccessIterators that point within the range of this functions arguments and define a closed interval.]] +[[Throws][Raises a Python TypeError exception if any of this slice's arguments are neither references to PyNone nor convertible to int. Throws `std::invalid_argument` if the resulting range would be empty. You should always wrap calls to `slice::get_indices()` within `try { ...; } catch (std::invalid_argument) {}` to handle this case and take appropriate action.]] +[[Rationale][closed-interval: If an open interval were used, then for step size other than 1, the required state for the end iterator would point beyond the one-past-the-end position or before the beginning of the specified range. +exceptions on empty slice: It is impossible to define a closed interval over an empty range, so some other form of error checking would have to be used to prevent undefined behavior. In the case where the exception is not caught, it will simply be translated to Python by the default exception handling mechanisms. ]] +] +[endsect] +[section Example] +`` +using namespace boost::python; + +// Perform an extended slice of a Python list. +// Warning: extended slicing was not supported for built-in types prior +// to Python 2.3 +list odd_elements(list l) +{ + return l[slice(_,_,2)]; +} + +// Perform a multidimensional extended slice of a Numeric.array +numeric::array even_columns(numeric::array arr) +{ + // select every other column, starting with the second, of a 2-D array. + // Equivalent to "return arr[:, 1::2]" in Python. + return arr[make_tuple( slice(), slice(1,_,2))]; +} + +// Perform a summation over a slice of a std::vector. +double partial_sum(std::vector<double> const& Foo, const slice index) +{ + slice::range<std::vector<double>::const_iterator> bounds; + try { + bounds = index.get_indices<>(Foo.begin(), Foo.end()); + } + catch (std::invalid_argument) { + return 0.0; + } + double sum = 0.0; + while (bounds.start != bounds.stop) { + sum += *bounds.start; + std::advance( bounds.start, bounds.step); + } + sum += *bounds.start; + return sum; +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/ssize_t.qbk b/libs/python/doc/reference/ssize_t.qbk new file mode 100644 index 0000000000..1cddfd1bd6 --- /dev/null +++ b/libs/python/doc/reference/ssize_t.qbk @@ -0,0 +1,27 @@ +[section boost/python/ssize_t.hpp] +[section Introduction] +Python 2.5 introduces a new `Py_ssize_t` typedef and two related macros ([@http://www.python.org/dev/peps/pep-0353/ PEP 353]). The <boost/python/ssize_t.hpp> header imports these definitions into the `boost::python` namespace as `ssize_t`, `ssize_t_max`, and `ssize_t_min`. Appropriate definitions are provided for backward compatibility with previous Python versions. +[endsect] +[section Typedefs] +Imports `Py_ssize_t` into the `boost::python` namespace if available, or provides an appropriate typedef for backward compatibility: +`` +#if PY_VERSION_HEX >= 0x02050000 +typedef Py_ssize_t ssize_t; +#else +typedef int ssize_t; +#endif +`` +[endsect] +[section Constants] +Imports `PY_SSIZE_T_MAX` and `PY_SSIZE_T_MIN` as constants into the `boost::python` namespace if available, or provides appropriate constants for backward compatibility: +`` +#if PY_VERSION_HEX >= 0x02050000 +ssize_t const ssize_t_max = PY_SSIZE_T_MAX; +ssize_t const ssize_t_min = PY_SSIZE_T_MIN; +#else +ssize_t const ssize_t_max = INT_MAX; +ssize_t const ssize_t_min = INT_MIN; +#endif +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/stl_iterator.qbk b/libs/python/doc/reference/stl_iterator.qbk new file mode 100644 index 0000000000..d0b26563e9 --- /dev/null +++ b/libs/python/doc/reference/stl_iterator.qbk @@ -0,0 +1,108 @@ +[section boost/python/stl_iterator.hpp] +[section Introduction] +<boost/python/stl_iterator.hpp> provides types for creating C++ Iterators from [@http://www.python.org/doc/current/lib/typeiter.html Python iterables]. +[endsect] +[section Class template `stl_input_iterator`] +Instances of `stl_input_iterator<T>` hold a Python iterator and adapt it for use with STL algorithms. `stl_input_iterator<T>` satisfies the requirements for an Input Iterator. +[table +[[Template Parameter][Requirements][Semantics][Default]] +[[ValueType][ValueType must be CopyConstructible.][Dereferencing an instance of `stl_input_iterator<ValueType>` will return an rvalue of type ValueType.][None]] +] +`` +namespace boost { namespace python +{ + template <class ValueType> + struct stl_input_iterator + { + typedef std::ptrdiff_t difference_type; + typedef ValueType value_type; + typedef ValueType* pointer; + typedef ValueType reference; + typedef std::input_iterator_tag iterator_category; + + stl_input_iterator(); + stl_input_iterator(object const& ob); + + stl_input_iterator& operator++(); + stl_input_iterator operator++(int); + + ValueType operator*() const; + + friend bool operator==(stl_input_iterator const& lhs, stl_input_iterator const& rhs); + friend bool operator!=(stl_input_iterator const& lhs, stl_input_iterator const& rhs); + private: + object it; // For exposition only + object ob; // For exposition only + }; +}} +`` +[endsect] +[section Class template `stl_input_iterator` constructors] +`` +stl_input_iterator() +`` +[variablelist +[[Effects][Creates a past-the-end input iterator, useful for signifying the end of a sequence. ]] +[[Postconditions][`this` is past-the-end]] +[[Throws][Nothing.]] +] +``stl_input_iterator(object const& ob)`` +[variablelist +[[Effects][Calls ob.attr("__iter__")() and stores the resulting Python iterator object in this->it. Then, calls this->it.attr("next")() and stores the result in this->ob. If the sequence is exhausted, sets this->ob to object(). ]] +[[Postconditions][this is a dereferenceable or past-the-end.]] +] +[endsect] +[section Class template `stl_input_iterator` modifiers] +`` +stl_input_iterator &operator++() +`` +[variablelist +[[Effects][Calls this->it.attr("next")() and stores the result in this->ob. If the sequence is exhausted, sets this->ob to object(). ]] +[[Postconditions][this is a dereferenceable or past-the-end.]] +[[Returns][`*this`]] +] +``stl_input_iterator &operator++(int)`` +[variablelist +[[Effects][`stl_input_iterator tmp = *this; ++*this; return tmp;`]] +[[Postconditions][this is a dereferenceable or past-the-end.]] +] +[endsect] +[section Class template `stl_input_iterator` observers] +`` +ValueType operator*() const +`` +[variablelist +[[Effects][Returns the current element in the sequence. ]] +[[Returns][`extract<ValueType>(this->ob);`]] +] +`` +friend bool operator==(stl_input_iterator const& lhs, stl_input_iterator const& rhs) +`` +[variablelist +[[Effects][Returns true if both iterators are dereferenceable or if both iterators are past-the-end, false otherwise. ]] +[[Returns][`(lhs.ob == object()) == (rhs.ob == object())`]] +] +`` +friend bool operator!=(stl_input_iterator const& lhs, stl_input_iterator const& rhs) +`` +[variablelist +[[Effects][Returns false if both iterators are dereferenceable or if both iterators are past-the-end, true otherwise. ]] +[[Returns][`!(lhs == rhs)`]] +] +[endsect] +[section Example] +`` +#include <boost/python/object.hpp> +#include <boost/python/stl_iterator.hpp> + +#include <list> + +using namespace boost::python; +std::list<int> sequence_to_int_list(object const& ob) +{ + stl_input_iterator<int> begin(ob), end; + return std::list<int>(begin, end); +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/str.qbk b/libs/python/doc/reference/str.qbk new file mode 100644 index 0000000000..12fe589629 --- /dev/null +++ b/libs/python/doc/reference/str.qbk @@ -0,0 +1,153 @@ +[section boost/python/str.hpp] +[section Introduction] +Exposes a [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] for the Python [@http://www.python.org/dev/doc/devel/lib/string-methods.html `str`] type. +[endsect] +[section Class `str`] +Exposes the [@http://www.python.org/dev/doc/devel/lib/string-methods.html string methods] of Python's built-in `str` type. The semantics of the constructors and member functions defined below, except for the two-argument constructors which construct str objects from a range of characters, can be fully understood by reading the [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] concept definition. Since str is publicly derived from [link object_wrappers.boost_python_object_hpp.class_object `object`], the public `object` interface applies to `str` instances as well. +`` +namespace boost { namespace python +{ + class str : public object + { + public: + str(); // new str + + str(char const* s); // new str + + str(char const* start, char const* finish); // new str + str(char const* start, std::size_t length); // 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; + }; +}} +`` +[endsect] +[section Example] +`` +using namespace boost::python; +str remove_angle_brackets(str x) +{ + return x.strip('<').strip('>'); +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/to_python_converter.qbk b/libs/python/doc/reference/to_python_converter.qbk new file mode 100644 index 0000000000..45d4121c2c --- /dev/null +++ b/libs/python/doc/reference/to_python_converter.qbk @@ -0,0 +1,91 @@ +[section boost/python/to_python_converter.hpp] +[section Introduction] +`to_python_converter` registers a conversion from objects of a given C++ type into a Python object. +[endsect] +[section Class template `to_python_converter`] +`to_python_converter` adds a wrapper around a static member function of its second template parameter, handling low-level details such as insertion into the converter registry. + +In the table below, x denotes an object of type T +[table +[[Parameter][Requirements][Description]] +[[T][][The C++ type of the source object in the conversion]] +[[Conversion][`PyObject* p = Conversion::convert(x)`, +`if p == 0`, `PyErr_Occurred() != 0`.][A class type whose static member function convert does the real work of the conversion.]] +[[bool has_get_pytype=false][`PyTypeObject const * p = Conversion::get_pytype()`] +[Optional member - if Conversion has `get_pytype` member supply `true` for this parameters. If present `get_pytype` is used to document the return type of functions using this conversion. The `get_pytype` may be implemented using the classes and functions from pytype_function.hpp NOTE : For backward compatibility this parameter may be passed after checking if BOOST_PYTHON_SUPPORTS_PY_SIGNATURES is defined (see [link function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.example here]).] +]] + +`` +namespace boost { namespace python +{ + template <class T, class Conversion, bool convertion_has_get_pytype_member=false> + struct to_python_converter + { + to_python_converter(); + }; +}} +`` +[section Class template `to_python_converter` constructor] +``to_python_converter();`` +[variablelist +[[Effects][Registers a `to_python` converter which uses `Conversion::convert()` to do its work.]] +] +[endsect] +[endsect] +[section Example] +This example presumes that someone has implemented the standard noddy example module from the Python documentation, and placed the corresponding declarations in "noddy.h". Because noddy_NoddyObject is the ultimate trivial extension type, the example is a bit contrived: it wraps a function for which all information is contained in the type of its return value. + +In C++: +`` +#include <boost/python/reference.hpp> +#include <boost/python/module.hpp> +#include "noddy.h" + +struct tag {}; +tag make_tag() { return tag(); } + +using namespace boost::python; + +struct tag_to_noddy +{ + static PyObject* convert(tag const& x) + { + return PyObject_New(noddy_NoddyObject, &noddy_NoddyType); + } + static PyTypeObject const* get_pytype() + { + return &noddy_NoddyType; + } +}; + +BOOST_PYTHON_MODULE(to_python_converter) +{ + def("make_tag", make_tag); + to_python_converter<tag, tag_to_noddy, true>(); //"true" because tag_to_noddy has member get_pytype +} +`` +In Python: +`` +>>> import to_python_converter +>>> def always_none(): +... return None +... +>>> def choose_function(x): +... if (x % 2 != 0): +... return to_python_converter.make_tag +... else: +... return always_none +... +>>> a = [ choose_function(x) for x in range(5) ] +>>> b = [ f() for f in a ] +>>> type(b[0]) +<type 'NoneType'> +>>> type(b[1]) +<type 'Noddy'> +>>> type(b[2]) +<type 'NoneType'> +>>> type(b[3]) +<type 'Noddy'> +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/to_python_indirect.qbk b/libs/python/doc/reference/to_python_indirect.qbk new file mode 100644 index 0000000000..9b03ba5365 --- /dev/null +++ b/libs/python/doc/reference/to_python_indirect.qbk @@ -0,0 +1,65 @@ +[section boost/python/to_python_indirect.hpp] +[section Introduction] + <boost/python/to_python_indirect.hpp> supplies a way to construct new Python objects that hold wrapped C++ class instances via a pointer or smart pointer. + [endsect] +[section Class `to_python_indirect`] +Class template `to_python_indirect` converts objects of its first argument type to python as extension class instances, using the ownership policy provided by its 2nd argument. +[table +[[Parameter][Requirements][Description]] + [[T][Either `U cv&` (where cv is any optional cv-qualification) or a [link concepts.dereferenceable Dereferenceable] type such that `*x` is convertible to `U const&`, where `U` is a class type. ][`A` type deferencing a C++ class exposed to Python using class template [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel `class_`]. ]] +[[MakeHolder][`h = MakeHolder::execute(p);` ][A class whose static `execute()` creates an `instance_holder`. ]] + ] +Instantiations of to_python_indirect are models of [link concepts.resultconverter `ResultConverter`]. +`` +namespace boost { namespace python +{ + template <class T, class MakeHolder> + struct to_python_indirect + { + static bool convertible(); + PyObject* operator()(T ptr_or_reference) const; + private: + static PyTypeObject* type(); + }; +}} +`` +[endsect] +[section Class `to_python_indirect` observers] +``PyObject* operator()(T x) const;`` +[variablelist +[[Requires][`x` refers to an object (if it is a pointer type, it is non-null). `convertible() == true`.]] +[[Effects][Creates an appropriately-typed Boost.Python extension class instance, uses MakeHolder to create an instance_holder from x, installs the instance_holder in the new extension class instance, and returns a pointer to it.]] +] +[endsect] +[section Class `to_python_indirect` statics] +``bool convertible()`` +[variablelist +[[Effects][Returns true iff any module has registered a Python type corresponding to U. ]] +] +[endsect] +[endsect] +[section Example] +This example replicates the functionality of [link function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object `reference_existing_object`], but without some of the compile-time error checking. +`` +struct make_reference_holder +{ + typedef boost::python::objects::instance_holder* result_type; + template <class T> + static result_type execute(T* p) + { + return new boost::python::objects::pointer_holder<T*, T>(p); + } +}; + +struct reference_existing_object +{ + // metafunction returning the ResultConverter + template <class T> + struct apply + { + typedef boost::python::to_python_indirect<T,make_reference_holder> type; + }; +}; +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/to_python_value.qbk b/libs/python/doc/reference/to_python_value.qbk new file mode 100644 index 0000000000..4b31d73f27 --- /dev/null +++ b/libs/python/doc/reference/to_python_value.qbk @@ -0,0 +1,34 @@ +[section boost/python/to_python_value.hpp] +[section Introduction] +`to_python_value` is a model of [link concepts.resultconverter ResultConverter] which copies its argument into a new Python object. +[endsect] +[section Class template `to_python_value`] +`` +namespace boost { namespace python +{ + template <class T> + struct to_python_value + { + typedef typename add_reference< + typename add_const<T>::type + >::type argument_type; + + static bool convertible(); + PyObject* operator()(argument_type) const; + }; +}} +`` +[endsect] +[section Class `to_python_value` observers] +``static bool convertible();`` +[variablelist +[[Returns][`true` iff a converter has been registered which can convert `T` to python by-value. ]] +] +``PyObject* operator()(argument_type x) const;`` +[variablelist +[[Requires][`convertible() == true`]] +[[Effects][converts `x` to python]] +[[Returns][the resulting Python object iff a converter for `T` has been registered, `0` otherwise. ]] +] +[endsect] +[endsect] diff --git a/libs/python/doc/reference/topics.qbk b/libs/python/doc/reference/topics.qbk new file mode 100644 index 0000000000..644f20d437 --- /dev/null +++ b/libs/python/doc/reference/topics.qbk @@ -0,0 +1,7 @@ +[chapter Topics + [quickbook 1.7] +] + +[include calling.qbk] +[include pickle.qbk] +[include indexing.qbk] diff --git a/libs/python/doc/reference/tuple.qbk b/libs/python/doc/reference/tuple.qbk new file mode 100644 index 0000000000..0c54161c68 --- /dev/null +++ b/libs/python/doc/reference/tuple.qbk @@ -0,0 +1,52 @@ +[section boost/python/tuple.hpp] +[section Introduction] +Exposes a [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] for the Python [@http://www.python.org/doc/current/tut/node7.html#SECTION007300000000000000000`tuple`] type. +[endsect] +[section 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 [link concepts.objectwrapper.typewrapper_concept_requirements TypeWrapper] concept definition. Since tuple is publicly derived from [link object_wrappers.boost_python_object_hpp.class_object `object`], the public `object` interface applies to `tuple` instances as well. +`` +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) + }; +}} +`` +[endsect] +[section Function `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); +}} +`` +[variablelist +[[Effect][Constructs a new tuple object composed of `object(a0), + object(a0),...object(an)`. ]] +] +[endsect] +[section Example] +`` +using namespace boost::python; +tuple head_and_tail(object sequence) +{ + return make_tuple(sequence[0],sequence[-1]); +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/type_id.qbk b/libs/python/doc/reference/type_id.qbk new file mode 100644 index 0000000000..bb013119bb --- /dev/null +++ b/libs/python/doc/reference/type_id.qbk @@ -0,0 +1,83 @@ +[section boost/python/type_id.hpp] +[section Introduction] +<boost/python/type_id.hpp> provides types and functions for runtime type identification like those of of `<typeinfo>`. It exists mostly to work around certain compiler bugs and platform-dependent interactions with shared libraries. +[endsect] +[section Class template `type_info`] +`type_info` instances identify a type. As `std::type_info` is specified to (but unlike its implementation in some compilers), `boost::python::type_info` never represents top-level references or cv-qualification (see section 5.2.8 in the C++ standard). Unlike `std::type_info`, `boost::python::type_info` instances are copyable, and comparisons always work reliably across shared library boundaries. +`` +namespace boost { namespace python +{ + class type_info : totally_ordered<type_info> + { + public: + // constructor + type_info(std::type_info const& = typeid(void)); + + // comparisons + bool operator<(type_info const& rhs) const; + bool operator==(type_info const& rhs) const; + + // observers + char const* name() const; + }; +}} +`` +[section Class template `type_info` constructor] +``type_info(std::type_info const& = typeid(void));`` +[variablelist +[[Effects][constructs a `type_info` object which identifies the same type as its argument.]] +[[Rationale][Since it is occasionally necessary to make an array of `type_info` objects a benign default argument is supplied. Note: this constructor does not correct for non-conformance of compiler `typeid()` implementations. See `type_id`, below.]] +] +[endsect] +[section Class template `type_info` comparison] +``bool operator<(type_info const &rhs) const;`` +[variablelist +[[Effects][yields a total order over `type_info` objects.]] +] +``bool operator==(type_info const &rhs) const;`` +[variablelist +[[Returns][`true` iff the two values describe the same type.]] +[[Note][The use of `totally_ordered<type_info>` as a private base class supplies operators `<=`, `>=`, `>`, and `!=`]] +] +[endsect] +[section Class template `type_info` observers] +`` +char const* name() const; +`` +[variablelist +[[Returns][The result of calling `name()` on the argument used to construct the object.]] +] +[endsect] +[endsect] +[section Functions] +`` +std::ostream& operator<<(std::ostream&s, type_info const&x); +`` +[variablelist +[[Effects][Writes a description of the type described by to `x` into s.]] +[[Rationale][Not every C++ implementation provides a truly human-readable `type_info::name()` string, but for some we may be able to decode the string and produce a reasonable representation.]] +[[Note][On some non-conforming C++ implementations, the code is not actually as simple as described above; the semantics are adjusted to work as-if the C++ implementation were conforming.]] +] +`` +template <class T> type_info type_id() +`` +[variablelist +[[Returns][`type_info(typeid(T))`]] +[[Note][On some non-conforming C++ implementations, the code is not actually as simple as described above; the semantics are adjusted to work as-if the C++ implementation were conforming.]] +] +[endsect] +[section Example] +The following example, though silly, illustrates how the type_id facility might be used +`` +#include <boost/python/type_id.hpp> + +// Returns true iff the user passes an int argument +template <class T> +bool is_int(T x) +{ + using boost::python::type_id; + return type_id<T>() == type_id<int>(); +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/utility.qbk b/libs/python/doc/reference/utility.qbk new file mode 100644 index 0000000000..3123cd8dc5 --- /dev/null +++ b/libs/python/doc/reference/utility.qbk @@ -0,0 +1,10 @@ +[chapter Utility and Infrastructure + [quickbook 1.7] +] + +[include has_back_reference.qbk] +[include instance_holder.qbk] +[include pointee.qbk] +[include handle.qbk] +[include type_id.qbk] +[include ssize_t.qbk] diff --git a/libs/python/doc/reference/with_custodian_and_ward.qbk b/libs/python/doc/reference/with_custodian_and_ward.qbk new file mode 100644 index 0000000000..76a03632dd --- /dev/null +++ b/libs/python/doc/reference/with_custodian_and_ward.qbk @@ -0,0 +1,72 @@ +[section boost/python/with_custodian_and_ward.hpp] +[section Introduction] +This header provides facilities for establishing a lifetime dependency between two of a function's Python argument or result objects. The ward object will not be destroyed until after the custodian as long as the custodian object supports [@http://www.python.org/doc/current/lib/module-weakref.html weak references] (Boost.Python extension classes all support weak references). If the custodian object does not support weak references and is not `None`, an appropriate exception will be thrown. The two class templates `with_custodian_and_ward` and `with_custodian_and_ward_postcall` differ in the point at which they take effect. + +In order to reduce the chance of inadvertently creating dangling pointers, the default is to do lifetime binding before the underlying C++ object is invoked. However, before invocation the result object is not available, so `with_custodian_and_ward_postcall` is provided to bind lifetimes after invocation. Also, if a C++ exception is thrown after `with_custodian_and_ward<>::precall` but before the underlying C++ object actually stores a pointer, the lifetime of the custodian and ward objects will be artificially bound together, so one might choose `with_custodian_and_ward_postcall` instead, depending on the semantics of the function being wrapped. + +Please note that this is not the appropriate tool to use when wrapping functions which transfer ownership of a raw pointer across the function-call boundary. Please see the FAQ if you want to do that. +[endsect] +[section Class `with_custodian_and_ward`] +[table +[[Parameter][Requirements][Description][Default]] + [[custodian][ A positive compile-time constant of `type std::size_t`. ][ The 1-based index of the parameter which is the dependency in the lifetime relationship to be established. If used to wrap a member function, parameter 1 is the target object (`*this`). Note that if the target Python object type doesn't support weak references, a Python TypeError exception will be raised when the C++ object being wrapped is called. ][]] +[[ward][ A positive compile-time constant of type `std::size_t`. ][ The 1-based index of the parameter which is the dependent in the lifetime relationship to be established. If used to wrap a member function, parameter 1 is the target object (`*this`). ][]] +[[Base][ A model of [link concepts.callpolicies `CallPolicies`]][ Used for policy [link concepts.callpolicies.callpolicies_composition composition]. ][default_call_policies]] + ] +`` +namespace boost { namespace python +{ + template <std::size_t custodian, std::size_t ward, class Base = default_call_policies> + struct with_custodian_and_ward : Base + { + static bool precall(PyObject* args); + }; +}}`` +[endsect] +[section Class `with_custodian_and_ward` static functions] +``bool precall(PyObject* args);`` +[variablelist +[[Requires][`PyTuple_Check(args) != 0`]] +[[Effects][Makes the lifetime of the argument indicated by ward dependent on the lifetime of the argument indicated by custodian. ]] +[[Returns][false and PyErr_Occurred() != 0 upon failure, true otherwise.]] +] +[endsect] + +[section Class `with_custodian_and_ward_postcall`] +[table +[[Parameter][Requirements][Description][Default]] + [[custodian][ A positive compile-time constant of type `std::size_t`. ][ The index of the parameter which is the dependency in the lifetime relationship to be established. Zero indicates the result object; 1 indicates the first argument. If used to wrap a member function, parameter 1 is the target object (`*this`). Note that if the target Python object type doesn't support weak references, a Python TypeError exception will be raised when the C++ object being wrapped is called. ][]] +[[ward][ A positive compile-time constant of type `std::size_t`. ][ The index of the parameter which is the dependent in the lifetime relationship to be established. Zero indicates the result object; 1 indicates the first argument. If used to wrap a member function, parameter 1 is the target object (`*this`). ][]] +[[Base][ A model of [link concepts.callpolicies `CallPolicies`]][ Used for policy [link concepts.callpolicies.callpolicies_composition composition]. ][default_call_policies]] + ] +`` +namespace boost { namespace python +{ + template <std::size_t custodian, std::size_t ward, class Base = default_call_policies> + struct with_custodian_and_ward_postcall : Base + { + static PyObject* postcall(PyObject* args, PyObject* result); + }; +}} +`` +[endsect] +[section Class `with_custodian_and_ward_postcall` static functions] +``PyObject *postcall(PyObject* args, PyObject* result);`` +[variablelist +[[Requires][`PyTuple_Check(args) != 0`, `result != 0`]] +[[Effects][Makes the lifetime of the object indicated by ward dependent on the lifetime of the object indicated by custodian. ]] +[[Returns][`0` and `PyErr_Occurred() != 0` upon failure, `true` otherwise. ]] +] +[endsect] +[section Example] +The following example shows how `with_custodian_and_ward_postcall` is used by the library to implement `return_internal_reference` +`` +template <std::size_t owner_arg = 1, class Base = default_call_policies> +struct return_internal_reference + : with_custodian_and_ward_postcall<0, owner_arg, Base> +{ + typedef reference_existing_object result_converter; +}; +`` +[endsect] +[endsect] diff --git a/libs/python/doc/reference/wrapper.qbk b/libs/python/doc/reference/wrapper.qbk new file mode 100644 index 0000000000..5c5bfc4847 --- /dev/null +++ b/libs/python/doc/reference/wrapper.qbk @@ -0,0 +1,117 @@ +[section boost/python/wrapper.hpp] +[section Introduction] +To wrap a class T such that its virtual functions can be "overridden in Python"—so that the corresponding method of a Python derived class will be called when the virtual function is invoked from C++—you must create a C++ wrapper class derived from `T` that overrides those virtual functions so that they call into Python. This header contains classes that can be used to make that job easier. +[endsect] +[section Class `override`] +Encapsulates a Python override of a C++ virtual function. An override object either holds a callable Python object or `None`. +`` +namespace boost +{ + class override : object + { + public: + unspecified operator() const; + template <class A0> + unspecified operator(A0) const; + template <class A0, class A1> + unspecified operator(A0, A1) const; + ... + template <class A0, class A1, ...class An> + unspecified operator(A0, A1, ...An) const; + }; +}; +`` +[endsect] +[section Class `override` observer functions] +`` +unspecified operator() const; +template <class A0> +unspecified operator(A0) const; +template <class A0, class A1> +unspecified operator(A0, A1) const; +... +template <class A0, class A1, ...class An> +unspecified operator(A0, A1, ...An) const; +`` +[variablelist +[[Effects][If *this holds a callable Python object, it is invoked with the specified arguments in the manner specified here. Otherwise, throws [link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set].]] +[[Returns][An object of unspecified type that holds the Python result of the invocation and, when converted to a C++ type R, attempts to convert that result object to R. If that conversion fails, throws [link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set].]] +] +[endsect] +[section Class template `wrapper`] +Deriving your wrapper class from both `T` and `wrapper<T>` makes writing that derived class easier. +`` +namespace boost +{ + class wrapper + { + protected: + override get_override(char const* name) const; + }; +}; +`` +[endsect] +[section Class template `wrapper` observer functions] +``override get_override(char const* name) const;`` +[variablelist +[[Requires][name is a [link ntbs].]] +[[Returns][If `*this` is the C++ base class subobject of a Python derived class instance that overrides the named function, returns an override object that delegates to the Python override. Otherwise, returns an override object that holds `None`.]] +] +[endsect] +[section Example] +`` +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/wrapper.hpp> +#include <boost/python/call.hpp> + +using namespace boost::python; + +// Class with one pure virtual function +struct P +{ + virtual ~P(){} + virtual char const* f() = 0; + char const* g() { return "P::g()"; } +}; + +struct PCallback : P, wrapper<P> +{ + char const* f() + { + return this->get_override("f")(); + } +}; + +// Class with one non-pure virtual function +struct A +{ + virtual ~A(){} + virtual char const* f() { return "A::f()"; } +}; + +struct ACallback : A, wrapper<A> +{ + char const* f() + { + if (override f = this->get_override("f")) + return f(); + return A::f(); + } + + char const* default_f() { return this->A::f(); } +}; + +BOOST_PYTHON_MODULE_INIT(polymorphism) +{ + class_<PCallback,boost::noncopyable>("P") + .def("f", pure_virtual(&P::f)) + ; + + class_<ACallback,boost::noncopyable>("A") + .def("f", &A::f, &ACallback::default_f) + ; +} +`` +[endsect] +[endsect] diff --git a/libs/python/doc/support.html b/libs/python/doc/support.html deleted file mode 100644 index 3198563417..0000000000 --- a/libs/python/doc/support.html +++ /dev/null @@ -1,74 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="boost.css"> - - <title>Boost.Python - Support Resources</title> - </head> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="index.html">Boost.Python</a></h1> - - <h2 align="center">Support Resources</h2> - </td> - </tr> - </table> - <hr> - - <h2>Synopsis</h2> - - <p>This is a list of available resources for support with Boost.Python - problems and feature requests. <b>Please try to resist emailing the - Boost.Python developers directly for support.</b> Use the following - resources instead; the developers are listening!</p> - <hr> - - <dl class="page-index"> - <dt><b><a href="http://www.boost-consulting.com">Boost - Consulting</a></b> - Commercial support, development, training, and - distribution for all the Boost libraries, from the people who brought - you Boost.Python.<br> - </dt> - - <dt><b><a href= - "http://www.boost.org/more/mailing_lists.htm#cplussig">The Python - C++-sig</a></b> mailing list is a forum for discussing Python/C++ - interoperability, and Boost.Python in particular. Post your - Boost.Python questions here.<br> - </dt> - - <dt>The <b>Boost.Python <a href= - "http://www.python.org/cgi-bin/moinmoin/boost_2epython">Wiki - Pages</a></b> established by Mike Rovner as part of the <a href= - "http://www.python.org/cgi-bin/moinmoin">PythonInfo Wiki</a> serves as - a forum to gather peoples' experience and as a cookbook.<br> - </dt> - </dl> - <hr> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 12 Sept, 2003 <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2003.</i></p> - </body> -</html> - diff --git a/libs/python/doc/support.qbk b/libs/python/doc/support.qbk new file mode 100644 index 0000000000..f075e3e98e --- /dev/null +++ b/libs/python/doc/support.qbk @@ -0,0 +1,17 @@ +[chapter Support Resources + [quickbook 1.7] + [id support] +] + + +[h2 Synopsis] +This is a list of available resources for support with Boost.Python problems and feature requests. Please try to resist emailing the Boost.Python developers directly for support. Use the following resources instead; the developers are listening! + +[h2 Support] +* The _bp_list_ is a forum for discussing Python/C++ interoperability, and Boost.Python in particular. Post your Boost.Python questions here. +* The _bb_list_ is a forum for discussing Boost's Build System. +* The Boost.Python [@https://github.com/boostorg/python/issues Issue tracker] + [note In the past we used Trac, which still hosts a considerable number of [@https://svn.boost.org/trac/boost/query?status=!closed&component=python+USE+GITHUB open issues]. We hope to be able to either close them or migrate them to the new issue tracker.] +* The Boost.Python [@https://github.com/boostorg/python/wiki Wiki] +* Boost.Python [@https://github.com/boostorg/python Source repository] + diff --git a/libs/python/doc/tutorial/doc/tutorial.qbk b/libs/python/doc/tutorial.qbk index 10a452200c..b75cba97ea 100644 --- a/libs/python/doc/tutorial/doc/tutorial.qbk +++ b/libs/python/doc/tutorial.qbk @@ -1,27 +1,26 @@ -[library python - [version 2.0] +[article Boost.Python Tutorial + [quickbook 1.7] [authors [de Guzman, Joel], [Abrahams, David]] [copyright 2002 2003 2004 2005 Joel de Guzman, David Abrahams] [category inter-language support] + [id tutorial] [purpose Reflects C++ classes and functions into Python ] [license Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at - <ulink url="http://www.boost.org/LICENSE_1_0.txt"> - http://www.boost.org/LICENSE_1_0.txt - </ulink>) + [@http://www.boost.org/LICENSE_1_0.txt] ] ] [/ QuickBook Document version 0.9 ] -[def __note__ [$images/note.png]] -[def __alert__ [$images/alert.png]] -[def __tip__ [$images/tip.png]] -[def :-) [$images/smiley.png]] -[def __jam__ [$images/jam.png]] +[def __note__ [$../images/note.png]] +[def __alert__ [$../images/alert.png]] +[def __tip__ [$../images/tip.png]] +[def :-) [$../images/smiley.png]] +[def __jam__ [$../images/jam.png]] [section QuickStart] @@ -120,7 +119,7 @@ __jam__ [@../../../../example/tutorial/Jamroot Here] is our minimalist Jamroot file. Simply copy the file and tweak [^use-project boost] to where your -boost root directory is and your OK. +boost root directory is and you're OK. The comments contained in the Jamrules file above should be sufficient to get you going. @@ -1076,7 +1075,7 @@ bidirectional mapping between C++ and Python while maintaining the Python feel. Boost.Python C++ [^object]s are as close as possible to Python. This should minimize the learning curve significantly. -[$images/python.png] +[$../images/python.png] [section Basic Interface] @@ -1982,4 +1981,3 @@ a large source file, as explained in the [@../../../v2/faq.html#c1204 FAQ].] [endsect] [endsect] [/ General Techniques] - diff --git a/libs/python/doc/tutorial/doc/Jamfile.v2 b/libs/python/doc/tutorial/doc/Jamfile.v2 deleted file mode 100644 index ba8882636d..0000000000 --- a/libs/python/doc/tutorial/doc/Jamfile.v2 +++ /dev/null @@ -1,18 +0,0 @@ -# Copyright Joel de Guzman 2006. Distributed under the Boost -# Software License, Version 1.0. (See accompanying -# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -project boost/libs/python/doc/tutorial/doc ; - -import boostbook : boostbook ; -using quickbook ; - -path-constant images : html ; - -boostbook tutorial - : - tutorial.qbk - : - <xsl:param>boost.root=../../../../../.. - <format>pdf:<xsl:param>img.src.path=$(images)/ - <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/python/doc/tutorial/doc/html - ; diff --git a/libs/python/doc/tutorial/doc/html/images/note.png b/libs/python/doc/tutorial/doc/html/images/note.png Binary files differdeleted file mode 100755 index 3ed047cacb..0000000000 --- a/libs/python/doc/tutorial/doc/html/images/note.png +++ /dev/null diff --git a/libs/python/doc/tutorial/doc/html/images/tip.png b/libs/python/doc/tutorial/doc/html/images/tip.png Binary files differdeleted file mode 100755 index 9f596b0b88..0000000000 --- a/libs/python/doc/tutorial/doc/html/images/tip.png +++ /dev/null diff --git a/libs/python/doc/tutorial/doc/html/index.html b/libs/python/doc/tutorial/doc/html/index.html deleted file mode 100644 index c324f065ce..0000000000 --- a/libs/python/doc/tutorial/doc/html/index.html +++ /dev/null @@ -1,142 +0,0 @@ -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> -<title>Chapter 1. python 2.0</title> -<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> -<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> -<link rel="home" href="index.html" title="Chapter 1. python 2.0"> -<link rel="next" href="python/hello.html" title="Building Hello World"> -</head> -<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table cellpadding="2" width="100%"><tr> -<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td> -<td align="center"><a href="../../../../../../index.html">Home</a></td> -<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td> -<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> -<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> -<td align="center"><a href="../../../../../../more/index.htm">More</a></td> -</tr></table> -<hr> -<div class="spirit-nav"><a accesskey="n" href="python/hello.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a></div> -<div class="chapter"> -<div class="titlepage"><div> -<div><h2 class="title"> -<a name="python"></a>Chapter 1. python 2.0</h2></div> -<div><div class="author"><h3 class="author"> -<span class="firstname">Joel</span> <span class="surname">de Guzman</span> -</h3></div></div> -<div><div class="author"><h3 class="author"> -<span class="firstname">David</span> <span class="surname">Abrahams</span> -</h3></div></div> -<div><p class="copyright">Copyright © 2002-2005 Joel - de Guzman, David Abrahams</p></div> -<div><div class="legalnotice"> -<a name="python.legal"></a><p> - Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top"> - http://www.boost.org/LICENSE_1_0.txt </a>) - </p> -</div></div> -</div></div> -<div class="toc"> -<p><b>Table of Contents</b></p> -<dl> -<dt><span class="section"><a href="index.html#python.quickstart">QuickStart</a></span></dt> -<dt><span class="section"><a href="python/hello.html">Building Hello World</a></span></dt> -<dt><span class="section"><a href="python/exposing.html">Exposing Classes</a></span></dt> -<dd><dl> -<dt><span class="section"><a href="python/exposing.html#python.constructors">Constructors</a></span></dt> -<dt><span class="section"><a href="python/exposing.html#python.class_data_members">Class Data Members</a></span></dt> -<dt><span class="section"><a href="python/exposing.html#python.class_properties">Class Properties</a></span></dt> -<dt><span class="section"><a href="python/exposing.html#python.inheritance">Inheritance</a></span></dt> -<dt><span class="section"><a href="python/exposing.html#python.class_virtual_functions">Class Virtual Functions</a></span></dt> -<dt><span class="section"><a href="python/exposing.html#python.virtual_functions_with_default_implementations">Virtual Functions with Default Implementations</a></span></dt> -<dt><span class="section"><a href="python/exposing.html#python.class_operators_special_functions">Class Operators/Special Functions</a></span></dt> -</dl></dd> -<dt><span class="section"><a href="python/functions.html">Functions</a></span></dt> -<dd><dl> -<dt><span class="section"><a href="python/functions.html#python.call_policies">Call Policies</a></span></dt> -<dt><span class="section"><a href="python/functions.html#python.overloading">Overloading</a></span></dt> -<dt><span class="section"><a href="python/functions.html#python.default_arguments">Default Arguments</a></span></dt> -<dt><span class="section"><a href="python/functions.html#python.auto_overloading">Auto-Overloading</a></span></dt> -</dl></dd> -<dt><span class="section"><a href="python/object.html">Object Interface</a></span></dt> -<dd><dl> -<dt><span class="section"><a href="python/object.html#python.basic_interface">Basic Interface</a></span></dt> -<dt><span class="section"><a href="python/object.html#python.derived_object_types">Derived Object types</a></span></dt> -<dt><span class="section"><a href="python/object.html#python.extracting_c___objects">Extracting C++ objects</a></span></dt> -<dt><span class="section"><a href="python/object.html#python.enums">Enums</a></span></dt> -<dt><span class="section"><a href="python/object.html#python.creating_python_object">Creating <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span></code> from <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code></a></span></dt> -</dl></dd> -<dt><span class="section"><a href="python/embedding.html">Embedding</a></span></dt> -<dd><dl><dt><span class="section"><a href="python/embedding.html#python.using_the_interpreter">Using the interpreter</a></span></dt></dl></dd> -<dt><span class="section"><a href="python/iterators.html">Iterators</a></span></dt> -<dt><span class="section"><a href="python/exception.html">Exception Translation</a></span></dt> -<dt><span class="section"><a href="python/techniques.html">General Techniques</a></span></dt> -<dd><dl> -<dt><span class="section"><a href="python/techniques.html#python.creating_packages">Creating Packages</a></span></dt> -<dt><span class="section"><a href="python/techniques.html#python.extending_wrapped_objects_in_python">Extending Wrapped Objects in Python</a></span></dt> -<dt><span class="section"><a href="python/techniques.html#python.reducing_compiling_time">Reducing Compiling Time</a></span></dt> -</dl></dd> -</dl> -</div> -<div class="section"> -<div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="python.quickstart"></a>QuickStart</h2></div></div></div> -<p> - The Boost Python Library is a framework for interfacing Python and C++. It - allows you to quickly and seamlessly expose C++ classes functions and objects - to Python, and vice-versa, using no special tools -- just your C++ compiler. - It is designed to wrap C++ interfaces non-intrusively, so that you should not - have to change the C++ code at all in order to wrap it, making Boost.Python - ideal for exposing 3rd-party libraries to Python. The library's use of advanced - metaprogramming techniques simplifies its syntax for users, so that wrapping - code takes on the look of a kind of declarative interface definition language - (IDL). - </p> -<h3> -<a name="quickstart.hello_world"></a> - Hello World - </h3> -<p> - Following C/C++ tradition, let's start with the "hello, world". A - C++ Function: - </p> -<pre class="programlisting"><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">greet</span><span class="special">()</span> -<span class="special">{</span> - <span class="keyword">return</span> <span class="string">"hello, world"</span><span class="special">;</span> -<span class="special">}</span> -</pre> -<p> - can be exposed to Python by writing a Boost.Python wrapper: - </p> -<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> - -<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">hello_ext</span><span class="special">)</span> -<span class="special">{</span> - <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> - <span class="identifier">def</span><span class="special">(</span><span class="string">"greet"</span><span class="special">,</span> <span class="identifier">greet</span><span class="special">);</span> -<span class="special">}</span> -</pre> -<p> - That's it. We're done. We can now build this as a shared library. The resulting - DLL is now visible to Python. Here's a sample Python session: - </p> -<pre class="programlisting"><span class="special">>>></span> <span class="keyword">import</span> <span class="identifier">hello_ext</span> -<span class="special">>>></span> <span class="keyword">print</span> <span class="identifier">hello_ext</span><span class="special">.</span><span class="identifier">greet</span><span class="special">()</span> -<span class="identifier">hello</span><span class="special">,</span> <span class="identifier">world</span> -</pre> -<div class="blockquote"><blockquote class="blockquote"><p> - <span class="emphasis"><em><span class="bold"><strong>Next stop... Building your Hello World module - from start to finish...</strong></span></em></span> - </p></blockquote></div> -</div> -</div> -<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> -<td align="left"><p><small>Last revised: December 26, 2011 at 21:58:39 GMT</small></p></td> -<td align="right"><div class="copyright-footer"></div></td> -</tr></table> -<hr> -<div class="spirit-nav"><a accesskey="n" href="python/hello.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a></div> -</body> -</html> diff --git a/libs/python/doc/tutorial/index.html b/libs/python/doc/tutorial/index.html deleted file mode 100644 index 7924277724..0000000000 --- a/libs/python/doc/tutorial/index.html +++ /dev/null @@ -1,18 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta http-equiv="refresh" content="0; URL=doc/html/index.html"> - </head> - <body> - Automatic redirection failed, click this - <a href="doc/html/index.html">link</a> <hr> - <p>© Copyright Beman Dawes, 2001</p> - <p>Distributed under the Boost Software License, Version 1.0. (See - accompanying file <a href="../../../../LICENSE_1_0.txt"> - LICENSE_1_0.txt</a> or copy at - <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p> - </body> -</html> diff --git a/libs/python/doc/v2/Apr2002.html b/libs/python/doc/v2/Apr2002.html deleted file mode 100644 index 62350defa4..0000000000 --- a/libs/python/doc/v2/Apr2002.html +++ /dev/null @@ -1,166 +0,0 @@ -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<link rel="stylesheet" type="text/css" href="../boost.css"> -<title>Boost.Python - April 2002 Progress Report</title> -</head> -<body link="#0000ff" vlink="#800080"> -<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - <h2 align="center">April 2002 Progress Report</h2> - </td> - </tr> -</table> -<hr> -<h2>Contents</h2> -<dl class="index"> - <dt><a href="#accomplishments">Accomplishments</a></dt> - <dl class="index"> - <dt><a href="#arity">Arbitrary Arity Support</a></dt> - <dt><a href="#callbacks">New Callback Interface</a></dt> - <dt><a href="#policies">Call Policies for Construtors</a></dt> - <dt><a href="#bugs">Real Users, Real Bugs</a></dt> - <dt><a href="#insights">New Insights</a></dt> - <dt><a href="#v1">Boost.Python V1 Maintenance</a></dt> - </dl> - - <dt><a href="#missing">What's Missing</a></dt> - -</dl> - -<h2><a name="accomplishments">Accomplishments</a></h2> - -April was a short month as far as Boost.Python was concerned, since -the spring ISO C++ Committee Meeting (and associated vacation) -occupied me for the 2nd half of the month. However, a suprising amount -of work got done... - -<h3><a name="arity">Arbitrary Arity Support</a></h3> - -I began using the <a -href="../../../preprocessor/doc/index.html">Boost.Preprocessor</a> -metaprogramming library to generate support for functions and member -functions of arbitrary arity, which was, to say the least, quite an -adventure. The feedback cycle resulting from my foray into -Boost.Preprocessor resulted in several improvements to the library, -most notably in its documentation. - -<p> - -Boost.Python now supports calls of up to 17 arguments on most -compilers. Because most EDG-based compilers have dismal preprocessor -performance, I had to "manually" expand the metaprograms for -arities from zero to fifteen arguments, and EDG-based compilers with -<code>__EDG_VERSION__ <= 245</code> only support 15 -arguments by default. If some crazy program finds a need for more than -the default arity support, users can increase the base support by -setting the <code>BOOST_PYTHON_MAX_ARITY</code> preprocessor symbol. - -<h3><a name="callbacks">New Callback Interface</a></h3> - -I mentioned in <a href="Mar2002.html">last month's report</a> that I -wasn't pleased with the interface for the interface for calling into -Python, so now it has been redesigned. The new interface is outlined -in <a -href="http://mail.python.org/pipermail/c++-sig/2002-April/000953.html">this -message</a> (though the GCC 2.95.3 bugs have been fixed). - -<h3><a name="policies">Call Policies for Constructors</a></h3> - -On April 2nd, I <a -href="http://mail.python.org/pipermail/c++-sig/2002-April/000916.html">announced</a> -support for the use of call policies with constructors. - -<h3><a name="bugs">Real Users, Real Bugs</a></h3> - -At least two people outside of Kull began actually using Boost.Python -v2 in earnest this month. Peter Bienstman and Pearu Pearson both -provided valuable real-world bug reports that helped me to improve the -library's robustness. - -<h3><a name="insights">New Insights</a></h3> - -<a -href="http://mail.python.org/pipermail/c++-sig/2002-May/001010.html" ->Answering some of Pearu's questions</a> about explicitly converting -objects between Python and C++ actually led me to a new understanding -of the role of the current conversion facilities. In Boost.Python v1, -all conversions between Python and C++ were handled by a single family -of functions, called <code>to_python()</code> and -<code>from_python()</code>. Since the primary role of Boost.Python is -to wrap C++ functions in Python, I used these names for the first kind -of converters I needed: those that extract C++ objects to be used as -function arguments and which C++ function return values to -Python. The better-considered approach in Boost.Python v2 uses a -completely different mechanism for conversions used when calling -Python from C++, as in wrapped virtual function implementations. I -usually think of this as a "callback", as in "calling -back into Python", and I named the converters used in callbacks -accordingly: <code>to_python_callback</code> and -<code>from_python_callback</code>. However, as it turns out, the -behavior of the "callback" converters is the appropriate one -for users who want to explicitly extract a C++ value from a Python -object, or create a Python object from a C++ value. The upshot is that -it probably makes sense to change the name of the existing <code>to_python</code> and -<code>from_python</code> so those names are available for the -user-friendly explicit converters. - -<p> -<a -href="http://mail.python.org/pipermail/c++-sig/2002-May/001013.html">Another -of Pearu's questions</a> pushes momentum further in the direction of a -more-sophisticated overloading mechanism than the current -simple-minded "first match" approach, as I suggested <a -href="Mar2002.html#implicit_conversions">last month</a>. - -<h3><a name="v1">Boost.Python V1 Maintenance</a></h3> - -As much as I'm looking forward to retiring Boost.Python v1, a -significant amount of effort has been being spent dealing with support -problems; the saying that code rots when left alone is true, and -Boost.Python is no exception. Eventually it became obvious to me that -we were going to have to invest some effort in keeping V1 healthy -while working on V2. Ralf and I have expanded support for various -compilers and stabilized the V1 codebase considerably. We discarded -the obsolete Visual Studio projects which were causing so much -confusion. Still to do before the next Boost release: -<ol> -<li>Update the build/test documentation with detailed instructions for -configuring various toolsets. -<li>Provide some links to Boost.Python v2 to let people know what's -coming. -</ol> - - -<h2><a name="missing">What's Missing</a></h2> - -Last month I announced that I would implement the following which are -not yet complete: -<ol> -<li>Document all implemented features -<li>Implement conversions for <code>char</code> types. This is -implemented but not tested, so we have to assume it doesn't work. -</ol> - -These are my first priority for this month (especially the -documentation). - -<p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> -</p> -<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> - 2002. </i></p> -</body> -</html> diff --git a/libs/python/doc/v2/CallPolicies.html b/libs/python/doc/v2/CallPolicies.html deleted file mode 100644 index 06384a23d9..0000000000 --- a/libs/python/doc/v2/CallPolicies.html +++ /dev/null @@ -1,165 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../../../../boost.css"> - - <title>Boost.Python - CallPolicies Concept</title> - </head> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">CallPolicies Concept</h2> - </td> - </tr> - </table> - <hr> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#composition">CallPolicies Composition</a></dt> - - <dt><a href="#concept-requirements">Concept Requirements</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#CallPolicies-concept">CallPolicies Concept</a></dt> - </dl> - </dd> - </dl> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>Models of the CallPolicies concept are used to specialize the behavior - of Python callable objects generated by Boost.Python to wrapped C++ - objects like function and member function pointers, providing three - behaviors:</p> - - <ol> - <li><code>precall</code> - Python argument tuple management before the - wrapped object is invoked</li> - - <li><code>result_converter</code> - C++ return value handling</li> - - <li><code>postcall</code> - Python argument tuple and result management - after the wrapped object is invoked</li> - <li><code>extract_return_type</code> - metafunction for extracting the return type from a given signature type sequence</li> - </ol> - - <h2><a name="composition"></a>CallPolicies Composition</h2> - In order to allow the use of multiple models of CallPolicies in the same - callable object, Boost.Python's CallPolicies class templates provide a - chaining interface which allows them to be recursively composed. This - interface takes the form of an optional template parameter, - <code>Base</code> which defaults to <a href= - "default_call_policies.html#default_call_policies-spec"><code>default_call_policies</code></a>. - By convention, the <code>precall</code> function of the <code>Base</code> - is invoked <i>after</i> the <code>precall</code> function supplied by the - outer template, and the <code>postcall</code> function of the - <code>Base</code> is invoked <i>before</i> the <code>postcall</code> - function of the outer template. If a <code>result_converter</code> is - supplied by the outer template, it <i>replaces</i> any - <code>result_converter</code> supplied by the <code>Base</code>. For an - example, see <a href= - "return_internal_reference.html#return_internal_reference-spec"><code>return_internal_reference</code></a>. - - - <h2><a name="concept-requirements"></a>Concept Requirements</h2> - - <h3><a name="CallPolicies-concept"></a>CallPolicies Concept</h3> - - <p>In the table below, <code><b>x</b></code> denotes an object whose type - <code><b>P</b></code> is a model of CallPolicies, <code><b>a</b></code> - denotes a <code>PyObject*</code> pointing to a Python argument tuple - object, and <code><b>r</b></code> denotes a <code>PyObject*</code> - referring to a "preliminary" result object.</p> - - <table summary="CallPolicies expressions" border="1" cellpadding="5"> - <tr> - <td><b>Expression</b></td> - - <td><b>Type</b></td> - - <td><b>Result/Semantics</b></td> - </tr> - - <tr> - <td valign="top"><code>x.precall(a)</code></td> - - <td>convertible to <code>bool</code></td> - - <td>returns <code>false</code> and <code><a href= - "http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>() != 0</code> - upon failure, <code>true</code> otherwise.</td> - </tr> - - <tr> - <td valign="top"><code>P::result_converter</code></td> - - <td>A model of <a href= - "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a>.</td> - - <td>An MPL unary <a href= - "../../../mpl/doc/refmanual/metafunction-class.html">Metafunction - Class</a> used produce the "preliminary" result object.</td> - </tr> - - <tr> - <td valign="top"><code>x.postcall(a, r)</code></td> - - <td>convertible to <code>PyObject*</code></td> - - <td>0 <code>0</code> and <code><a href= - "http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>() != 0</code> - upon failure. Must "conserve references" even in the event of an - exception. In other words, if <code>r</code> is not returned, its - reference count must be decremented; if another existing object is - returned, its reference count must be incremented.</td> - </tr> - <tr> - <td valign="top"><code>P::extract_return_type</code></td> - - <td>A model of <a href= - "../../../mpl/doc/refmanual/metafunction.html">Metafunction</a>.</td> - - <td>An MPL unary <a href= - "../../../mpl/doc/refmanual/metafunction.html">Metafunction</a> used extract the return type from a given signature. By default it is derived from mpl::front.</td> - </tr> - </table> - Models of CallPolicies are required to be <a href= - "../../../utility/CopyConstructible.html">CopyConstructible</a>. - <hr> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - - <p>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.</p> - </body> -</html> - diff --git a/libs/python/doc/v2/Dereferenceable.html b/libs/python/doc/v2/Dereferenceable.html deleted file mode 100644 index f7c53fd237..0000000000 --- a/libs/python/doc/v2/Dereferenceable.html +++ /dev/null @@ -1,74 +0,0 @@ -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<link rel="stylesheet" type="text/css" href="../../../../boost.css"> -<title>Boost.Python - Dereferenceable Concept</title> -</head> -<body link="#0000ff" vlink="#800080"> -<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - <h2 align="center">Dereferenceable Concept</h2> - </td> - </tr> -</table> -<hr> -<dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - <dt><a href="#concept-requirements">Concept Requirements</a></dt> - <dl class="page-index"> - <dt><a href="#Dereferenceable-concept">Dereferenceable Concept</a></dt> - </dl> -</dl> - -<h2><a name="introduction"></a>Introduction</h2> - -<p>Instances of a Dereferenceable type can be used like a pointer to access an lvalue. - -<h2><a name="concept-requirements"></a>Concept Requirements</h2> -<h3><a name="Dereferenceable-concept"></a>Dereferenceable Concept</h3> - -<p>In the table below, <code><b>T</b></code> is a model of -Dereferenceable, and <code><b>x</b></code> denotes an object of -type <code>T</code>. In addition, all pointers are Dereferenceable. - -<table summary="Dereferenceable expressions" border="1" cellpadding="5"> - - <tr> - <td><b>Expression</b></td> - <td><b>Result</b></td> - <td><b>Operational Semantics</b></td> - </tr> - - <tr> - <td><code>get_pointer(x)</code></td> - <td>convertible to <code><a href="pointee.html#pointee-spec">pointee</a><T>::type*</code> - <td><code>&*x</code>, or a null pointer - </tr> -<tr> - -</table> - -<hr> -<p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 18 December, 2003 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> -</p> - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002-2003. </i> - -<p>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. -</body> -</html> diff --git a/libs/python/doc/v2/Extractor.html b/libs/python/doc/v2/Extractor.html deleted file mode 100644 index 441ca38b39..0000000000 --- a/libs/python/doc/v2/Extractor.html +++ /dev/null @@ -1,96 +0,0 @@ -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<link rel="stylesheet" type="text/css" href="../../../../boost.css"> -<title>Boost.Python - Extractor Concept</title> -</head> -<body link="#0000ff" vlink="#800080"> -<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - <h2 align="center">Extractor Concept</h2> - </td> - </tr> -</table> -<hr> -<dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - <dt><a href="#concept-requirements">Concept Requirements</a></dt> - <dl class="page-index"> - <dt><a href="#Extractor-concept">Extractor Concept</a></dt> - </dl> - <dt><a href="#notes">Notes</a></dt> -</dl> - -<h2><a name="introduction"></a>Introduction</h2> - -<p>An Extractor is a class which Boost.Python can use to extract C++ -objects from Python objects, and is typically used by facilities that -define <code>from_python</code> conversions for -"traditional" Python extension types. - -<h2><a name="concept-requirements"></a>Concept Requirements</h2> -<h3><a name="Extractor-concept"></a>Extractor Concept</h3> - -<p>In the table below, <code><b>X</b></code> denotes a model of -Extractor and <code><b>a</b></code> denotes an instance of a Python -object type. - -<table summary="Extractor expressions" border="1" cellpadding="5"> - - <tr> - <td><b>Expression</b></td> - <td><b>Type</b></td> - <td><b>Semantics</b></td> - </tr> - - <tr> - <td valign="top"><code>X::execute(a)</code></td> - <td>non-void - <td>Returns the C++ object being extracted. The - <code>execute</code> function must not be overloaded. - </tr> - - <tr> - <td valign="top"><code>&a.ob_type</code> - <td><code><a - href="http://www.python.org/doc/2.2/ext/dnt-type-methods.html">PyTypeObject</a>**</code> - <td>Points to the <code>ob_type</code> field of an object which is - layout-compatible with <code>PyObject</code> - </tr> - - </tr> - -</table> - -<h2><a name="notes"></a>Notes</h2> - -Informally, an Extractor's <code>execute</code> member must be a -non-overloaded static function whose single argument is a Python -object type. Acceptable Python object types include those publicly (and -unambiguously) derived from <code>PyObject</code>, and POD types which -are layout-compatible with PyObject. - -<hr> -<p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> -</p> - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002. </i> - -<p>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. -</body> -</html> diff --git a/libs/python/doc/v2/HolderGenerator.html b/libs/python/doc/v2/HolderGenerator.html deleted file mode 100644 index 58b4265af8..0000000000 --- a/libs/python/doc/v2/HolderGenerator.html +++ /dev/null @@ -1,74 +0,0 @@ -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<link rel="stylesheet" type="text/css" href="../../../../boost.css"> -<title>Boost.Python - Holder Concept</title> -</head> -<body link="#0000ff" vlink="#800080"> -<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - <h2 align="center">HolderGenerator Concept</h2> - </td> - </tr> -</table> -<hr> -<dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - <dt><a href="#concept-requirements">Concept Requirements</a></dt> - <dl class="page-index"> - <dt><a href="#HolderGenerator-concept">HolderGenerator Concept</a></dt> - </dl> -</dl> - -<h2><a name="introduction"></a>Introduction</h2> - -<p>A HolderGenerator is a unary metafunction class which returns types -suitable for holding instances of its argument in a wrapped C++ class -instance. - -<h2><a name="concept-requirements"></a>Concept Requirements</h2> -<h3><a name="HolderGenerator-concept"></a>HolderGenerator Concept</h3> - -<p>In the table below, <code><b>G</b></code> denotes an type which -models HolderGenerator, and <code><b>X</b></code> denotes a class -type. - -<table summary="Holder expressions" border="1" cellpadding="5"> - - <tr> - <td><b>Expression</b></td> - <td><b>Requirements</b></td> - </tr> - - <tr> - <td valign="top"><code>G::apply<X>::type</code></td> - <td>A concrete subclass of <a - href="instance_holder.html#instance_holder-spec">instance_holder</a> - which can hold objects of type <code>X</code>. - </tr> -</table> - -<hr> -<p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> -</p> - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002. </i> - -<p>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. -</body> -</html> diff --git a/libs/python/doc/v2/Jun2002.html b/libs/python/doc/v2/Jun2002.html deleted file mode 100644 index db1fc25c62..0000000000 --- a/libs/python/doc/v2/Jun2002.html +++ /dev/null @@ -1,229 +0,0 @@ -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<link rel="stylesheet" type="text/css" href="../boost.css"> -<title>Boost.Python - June 2002 Progress Report</title> -</head> -<body link="#0000ff" vlink="#800080"> -<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - <h2 align="center">June 2002 Progress Report</h2> - </td> - </tr> -</table> -<hr> -<h2>Contents</h2> -<dl class="index"> - <dt><a href="#intro">Introduction</a></dt> - <dt><a href="#handle"><code>handle<T></code></a></dt> - <dt><a href="#object"><code>object</code></a></dt> - <dl class="index"> - <dt><a href="#operators"><code>object</code> operators</a></dt> - <dt><a href="#conversions"><code>object</code> conversions</a></dt> - </dl> - <dt><a href="#list"><code>list</code></a></dt> - <dt><a href="#numerics"><code>Numerics</code></a></dt> - <dt><a href="#community">Community</a></dt> - <dt><a href="#next">What's Next</a></dt> -</dl> - -<h2><a name="intro">Introduction</a></h2> - -July was mostly focused on allowing expressive manipulation of -individual Python objects, or what Ralf Grosse-Kunstleve calls -"Writing Python in C++". The work began with this <a -href="http://mail.python.org/pipermail/c++-sig/2002-June/001311.html">posting</a>, -which outlines the issues and intention. - -<h2><a name="handle"><code>handle<T></code></a></h2> - -The most basic element needed was a replacement for the -<code>reference<></code> class template and the -<code>ref</code> typedef from Boost.Python v1, a simple smart -pointer to a Python object. The old v1 typedef -"<code>ref</code>" (for -<code>reference<PyObject></code>) had to be retired because I -thought it would be too confusing given the importance of <code><a -href="../../../bind/ref.html">boost::ref</a>()</code> to this -library. I began a <a -href="http://mail.python.org/pipermail/c++-sig/2002-June/001311.html">discussion</a>of -possible names, and it was eventually <a -href="http://mail.python.org/pipermail/c++-sig/2002-June/001337.html">decided</a> -to rename <code>reference</code> to <code>handle</code> and supply a -default argument so that <code>ref</code> could be spelled -<code>handle<></code> without an additional typedef. There -were also some interface changes to make it safer and more-efficient -to interface with the raw -<code>PyObject*</code>s forced on us by Python's 'C' API. A -discussion of those protocols can be found <a -href="http://mail.python.org/pipermail/c++-sig/2002-June/001401.html">here</a>. - -<h2><a name="handle"><code>object</code></a></h2> - -It is intended that users will seldom need or want to work with -<code>handle<></code>; its major distinguishing features are -that it gives direct access to the underlying object representation -through <code>operator*</code> and <code>operator-></code>, and -that can be <code>NULL</code>, both sources of danger. Instead the -library provides a class called <code>object</code>, which -encapsulates a valid Python object and provides a similar interface to -Python's. - -<h3><a name="operators"><code>object</code> operators</a></h3> - -The first challenge was to provide support for object manipulations -using a Python-like syntax, mostly in the form of operator overloads: - -<table border="1"> -<tr><th>Python <th>C++ - -<tr> - <td><code>y = x.foo</code> <td><code>y = x.attr("foo"); -<tr> - <td><code>x.foo = 1</code> <td><code>x.attr("foo") = 1; - -<tr> - <td><code>y = x[z]</code> <td><code>y = x[z]; -<tr> - <td><code>x[z] = 1</code> <td><code>x[z] = 1; - -<tr> - <td><code>y = x[3:-1]</code> <td><code>y = x.slice(3,-1); - -<tr> - <td><code>y = x[3:]</code> <td><code>y = x.slice(3,_); - -<tr> - <td><code>y = x[:-2]</code> <td><code>y = x.slice(_,-2); - -<tr> - <td><code>z = x(1, y)</code> <td><code>z = x(1, y); -<tr> - <td><code>z = x.f(1, y)</code> <td><code>z = x.attr("f")(1, y); - -<tr> - <td><code>not x</code> <td><code>!x - -<tr> - <td><code>x and y</code> <td><code>x and y -</table> - -I'm still a unsatisfied with the interface for attribute access. There -original proposal used a syntax like this one: -<pre> -y = x._("foo"); -x._("foo") = 1; -</pre> - -which was only marginally better than what we've got. Niki Spahiev -then <a -href="http://mail.python.org/pipermail/c++-sig/2002-June/001447.html">pointed -out</a> a potential conflict with the macro which GNU Gettext <a -href="http://www.gnu.org/manual/gettext/html_mono/gettext.html#SEC6">suggests</a> -people define. This unfortunate state of affairs forced us into using -<code>attr</code> instead. I'd still like to find a better interface, -but the lack of overloadable C++ operators which aren't already used -in Python is an obstacle. The comma operator is still a possibility, -but it has the wrong precedence: -<pre> -y = x,"foo" // error -x,"foo" = 1; // error - -y = (x,"foo"); // ok -(x,"foo") = 1; // ok -</pre> - -Well, I guess we could consider adding that to the interface without -removing <code>attr()</code>, to see how it plays out... - -<h3><a name="operators"><code>object</code> conversions</a></h3> - -The <code>object</code> class also provided an opportunity to replace -Boost.Python v1's <code>to_python()</code> as a user-level -interface. Instead, <code>object</code> has a templated constructor -which can be used to convert any C++ object to Python using the same -underlying mechanisms used for the arguments to <code><a -href="call.html">call</a><></code>. - -<p>Incidentally, the implementation of operator and conversion support -for object uncovered an inordinate number of compiler bugs in our -targeted platforms. It was a lot more "interesting" than it -should have been. - -<h2><a name="list"><code>list</code></a></h2> - -With <code>object</code> implemented, it was time to begin replacing -the ad-hoc implementations of <code>list</code>, <code>string</code>, -and <code>dictionary</code> supplied by Boost.Python v1 with something -more robust. I started with <code>list</code> as an example. Because -<code>object</code> already provides all of the requisite operators, -publicly deriving <code>list</code> from object seemed like a good -choice. The remaining issues were what do do about the one-argument -list constructor (which in Python attempts to convert its argument to -a list), and how to deal converting with <code>list</code> arguments -to wrapped functions. Some of the issues are laid out in <a -href="http://mail.python.org/pipermail/c++-sig/2002-June/001551.html">this -thread</a>. Ultimately, it was decided that <code>list(x)</code> -should do the same thing in C++ as in Python (conversion), while -<code>list</code> arguments should only match Python -<code>list</code>s (and <code>list</code> subclasses). The -implementation worked well, and provided a <a -href="http://mail.python.org/pipermail/c++-sig/2002-June/001586.html">roadmap</a> -for the protocol to be used for implementation of the other built-in -types. - -<h2><a name="numerics">Numerics</a></h2> - -Support for C++ <code>long long</code> and <code>unsigned long -long</code> -(and <code>__int64</code> on MSVC) to/from python conversions was -added this month. We also improved handling of numeric overflows when -converting, e.g., a Python int to a type with a more limited range of -representation. - -<h2><a name="community">Community</a></h2> - -<ul> -<li>Ralf W. Grosse-Kunstleve and Nick Sauter have implemented -<a href="http://cci.lbl.gov/boost/">multiplatform nightly -build-and-test</a> runs for Boost.Python V2 at LBL. - -<li>Dave Hawkes has made significant progress on generating the -Python <a -href="http://mail.python.org/pipermail/c++-sig/2002-June/001503.html">built-in -function and API wrappers</a> - -<li>Achim Domma has agreed to take up the job of implementing the -<code>str</code>, <code>dict</code>, and <code>tuple</code> classes. -</ul> - -Deep thanks to all the Boost.Python contributors! This project -wouldn't be possible without your participation. - - <h2><a name="next">What's Next</a></h2> - -As I write this we are already well into the month of July, so I -suggest you consult the <a -href="http://mail.python.org/pipermail/c++-sig/2002-July/">Mailing -List Archive</a> if you want to know what's been happening. Otherwise -you'll just have to wait till next month (hopefully the beginning). - -<p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> -</p> -<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> - 2002. </i></p> -</body> -</html> diff --git a/libs/python/doc/v2/Mar2002.html b/libs/python/doc/v2/Mar2002.html deleted file mode 100644 index 97444d2290..0000000000 --- a/libs/python/doc/v2/Mar2002.html +++ /dev/null @@ -1,237 +0,0 @@ -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<link rel="stylesheet" type="text/css" href="../boost.css"> -<title>Boost.Python - March 2002 Progress Report</title> -</head> -<body link="#0000ff" vlink="#800080"> -<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - <h2 align="center">March 2002 Progress Report</h2> - </td> - </tr> -</table> -<hr> -<h2>Contents</h2> -<dl class="index"> - <dt><a href="#accomplishments">Accomplishments</a></dt> - <dl class="index"> - <dt><a href="#calling_python">Calling Python from C++</a></dt> - <dt><a href="#virtual_functions">Virtual Functions</a></dt> - <dt><a href="#abstract_classes">Abstract Classes</a></dt> - <dt><a href="#implicit_conversions">C++ Implicit Conversions</a></dt> - <dt><a href="#data_members">C++ Data Members</a></dt> - <dt><a href="#miscellaneous">Miscellaneous</a></dt> - </dl> - - <dt><a href="#future">The Near future</a></dt> - - <dt><a href="#notes">Notes</a></dt> - -</dl> - -<h2><a name="accomplishments">Accomplishments</a></h2> - -March was mostly devoted to the reimplementation of features from -Boost.Python v1, and some new features. Re-examination of the features -from Boost.Python v1 allowed me to make significant improvements. - -<h3><a name="calling_python">Calling Python from C++</a></h3> - -The ability to call Python from C++ is crucial for virtual function -support. Implementing this feature well for V2 proved to be more -interesting than I expected. You can review most of the relevant -design decisions -<a href="callbacks.txt">here</a>. - -<p> -One point which <i>isn't</i> emphasized in that document is that there -are subtle differences in the way <code>from_python</code> conversions -work when used for C++ function arguments and Python function return -values. In particular, while <code>T const&</code> arguments may -invoke rvalue converters, a reference-to-const return value requires -an lvalue converter, since a temporary conversion result would leave -the returned reference dangling. - -<p>I'm not particularly pleased with the current callback interface, -since it usually results in constructs like: -<pre> -<u>return returning</u><X&>::call(f, obj); -</pre> -However, I think the following may be possible and I plan to investigate: -<pre> -return apply<X&>(f, obj); -</pre> -I'm open to suggestion for better names (and syntaxes)! - -<h3><a name="virtual_functions">Virtual Functions</a></h3> - -Once Python callbacks were implemented, it was just a short step to -implementing virtual functions. Python extension class exposing a C++ -class whose virtual functions are overridable in Python must actually -hold a C++ instance of a class <i>derived</i> from the one exposed to -Python. Needing some way for users to specify that class, I added an -optional template argument to <code>value_holder_generator</code> and -<code>pointer_holder_generator<></code> to specify the class -actually held. This move began to put pressure on the -<code>class_<></code> interface, since the need for the user to -produce complicated instantations of -<code>class_<></code> was increased: - -<pre> -class<Foo, bases<>, value_holder_generator<Foo_callback> >("Foo") -.def("hello", &Foo::hello) -... -</pre> - -<h3><a name="abstract_classes">Abstract Classes</a></h3> - -Normally when a C++ class is exposed to Python, the library registers -a conversion function which allows users to wrap functions returning -values of that type. Naturally, these return values are temporaries, -so the conversion function must make a copy in some -dynamically-allocated storage (a "holder") which is managed -by the corresponding Python object. - -<p>Unfortunately, in the case of abstract classes (and other types -without a publicly-accessible copy constructor), instantiating this -conversion function causes a compilation error. In order to support -non-copyable classes, there had to be some way to prevent the library -from trying to instantiate the conversion function. The only practical -approach I could think of was to add an additional template parameter -to the <code>class_<></code> interface. When the number of -template parameters with useful defaults begins to grow, it is often -hard to choose an order which allows users to take advantage of the -defaults. - -<p> - -This was the straw that broke the -<code>class_<></code> interface's back and caused the redesign -whose outcome is detailed <a -href="http://mail.python.org/pipermail/c++-sig/2002-March/000892.html">here</a>. -The approach allows the user to supply the optional parameters in an -arbitrary order. It was inspired by the use of <a -href="../../../utility/iterator_adaptors.htm#named_tempalte_parameters">named -template parameters</a> in the <a -href="../../../utility/iterator_adaptors.htm">Boost Iterator Adaptor -Library</a>, though in this case it is possible to deduce the meaning -of the template parameters entirely from their type properties, -resulting in a simpler interface. Although the move from a -policy-based design to what resembles a configuration DSL usually -implies a loss of flexibility, in this case I think any costs are far -outweighed by the advantages. - -<p>Note: working around the limitations of the various compilers I'm -supporting was non-trivial, and resulted in a few messy implementation -details. It might be a good idea to switch to a more-straightforward -approach once Metrowerks CodeWarrior Pro8 is released. - -<h3><a name="implicit_conversions">C++ Implicit Conversions</a></h3> - -Support for C++ implicit conversion involves creating -<code>from_python</code> converters for a type <code>U</code> which in -turn use <code>from_python</code> converters registered for a type -<code>T</code> where there exists a implicit conversion from -<code>T</code> to <code>U</code>. The current implementation is -subject to two inefficiencies: -<ol> - -<li>Because an rvalue <code>from_python</code> converter produces two -pieces of data (a function and a <code>void*</code>) from its -<code>convertible()</code> function, we end up calling the function -for <code>T</code> twice: once when the converter is looked up in the -registry, and again when the conversion is actually performed. - -<li>A vector is used to mark the "visited" converters, preventing -infinite recursion as <code>T</code> to -<code>U</code> and <code>U</code> to <code>T</code> converters -continually search through one-another. - -</ol> - -I consider the former to be a minor issue. The second may or may not -prove to be computationally significant, but I believe that -architecturally, it points toward a need for more sophisticated -overload resolution. It may be that we want CLOS-style multimethod -dispatching along with C++ style rules that prevent more than one -implicit conversion per argument. - -<h3><a name="data_members">C++ Data Members</a></h3> - -To supply the ability to directly access data members, I was able to -hijack the new Python <a -href="http://www.python.org/2.2/descrintro.html#property">property</a> -type. I had hoped that I would also be able to re-use the work of <a -href="make_function.html">make_function</a> to create callable python -objects from C++ functions which access a data member of a given -class. C++ facilities for specifying data member pointer non-type -template arguments require the user to explicitly specify the type of -the data member and this under-utilized feature is also not -well-implemented on all compilers, so passing the member pointer as a -runtime value is the only practical approach. The upshot is that any -such entity would actually have to be a function <i>object</i>, and I -haven't implemented automatic wrapping of C++ callable function -objects yet, so there is less re-use in the implementation than I'd -like. I hope to implement callable object wrapping and refactor this -code one day. I also hope to implement static data member support, -for which Python's property will not be an appropriate descriptor. - -<h3><a name="miscellaneous">Miscellaneous</a></h3> -<ul> -<li>Moved <code>args<></code> and <code>bases<></code> from unnamed namespace to <code>boost::python</code> in their own header files. -<li>Convert <code>NULL</code> pointers returned from wrapped C++ functions to <code>None</code>. -<li>Improved some compile-time error checks. -<li>Eliminated <code>boost/python/detail/eval.hpp</code> in favor of -more-general <code>boost/mpl/apply.hpp</code>. -<li>General code cleanup and refactoring. -<li>Works with Microsoft Visual C++ 7.0 -<li>Warning suppression for many compilers -<li>Elegant interface design for exporting <code>enum</code> types. -</ul> -<hr> - -<h2><a name="future">The Near Future</a></h2> - -Before April 15th I plan to -<ol> -<li>Document all implemented features -<li>Implement a <code>CallPolicy</code> interface for constructors of wrapped -classes -<li>Implement conversions for <code>char</code> types. -<li>Implement automated code generation for all headers containing -families of overloaded functions to handle arbitrary arity. -</ol> - -I also hope to implement a mechanism for generating conversions -between arbitrary Python sequences and C++ containers, if time permits -(and others haven't already done it)! - -<h2><a name="notes">Notes</a></h2> - -The older version of KCC used by Kull is generating lots of warnings -about a construct I use to instantiate static members of various class -templates. I'm thinking of moving to an idiom which uses a function -template to suppress it, but worry about bloating the size of debug -builds. Since KCC users may be moving to GCC, I'm not sure that it's -worth doing anything about it. - -<p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> -</p> -<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> - 2002. </i></p> -</body> -</html> diff --git a/libs/python/doc/v2/May2002.html b/libs/python/doc/v2/May2002.html deleted file mode 100644 index 5e5b6aaa4b..0000000000 --- a/libs/python/doc/v2/May2002.html +++ /dev/null @@ -1,311 +0,0 @@ -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<link rel="stylesheet" type="text/css" href="../boost.css"> -<title>Boost.Python - May 2002 Progress Report</title> -</head> -<body link="#0000ff" vlink="#800080"> -<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - <h2 align="center">May 2002 Progress Report</h2> - </td> - </tr> -</table> -<hr> -<h2>Contents</h2> -<dl class="index"> - <dt><a href="#intro">Introduction</a></dt> - <dt><a href="#features">New Features</a></dt> - <dl> - <dt><a href="#aix_shared">Shared Library Support for AIX</a><dd> - <dt><a href="#class_enhancements">Class Enhancements</a><dd> - <dl> - <dt><a href="#operators">Operators</a><dd> - <dt><a href="#iterators">Iterators</a><dd> - <dt><a href="#properties">Properties</a><dd> - <dt><a href="#setattr">setattr</a><dd> - <dt><a href="#module">__module__ Attribute</a><dd> - </dl> - <dt><a href="#back_reference">back_reference</a><dd> - </dl> - - <dt><a href="#documentation">Documentation</a></dt> - <dt><a href="#misc">Miscellaneous</a></dt> - <dl class="index"> - <dt><a href="#converters">Converters</a></dt> - <dt><a href="#checkins">Checkins Mailing List</a></dt> - <dt><a href="#shared">Shared Libraries</a></dt> - </dl> - - <dt><a href="#next">What's Next</a></dt> -</dl> - -<h2><a name="intro">Introduction</a></h2> - -Aside from library development, work on Boost.Python in May was -focused on reducing the support burden. In recent weeks, responding to -requests for support, espcially surrounding building the library, had -begun to impede progress on development. There was a major push to -release a stable 1.28.0 of Boost, including documentation of <a -href="../../../../tools/build/v1/build_system.htm">Boost.Build</a> and specific -<a href="../building.html">instructions</a> for building Boost.Python -v1. The documentation for Boost.Python v2 was also updated as -described <a href="#documentation">here</a>. - -<h2><a name="features">New Features</a></h2> - - <h3><a name="aix_shared">Shared Library Support for AIX</a></h3> - - The Kull group required the ability to build and test Boost.Python - extensions on AIX, a platform with "creatively designed" - shared library semantics. Making this work was a multi-pronged - effort, involving changes to Boost.Build and some great research by - Martin Casado which uncovered the key mechanism required to allow - shared libraries to use functions from the Python executable. The - current solution used in Boost.Build relies on a <a - href="../../../../tools/build/v1/gen_aix_import_file.py">Python - Script</a> as part of the build process. This is not a problem for - Boost.Python, as Python will be available. However, the commands - issued by the script are so simple that a 100%-pure-Boost.Jam - solution is surely possible. Linking on AIX is sufficiently - interesting to have skewed the Boost.Python development schedule a - bit. - - <h3><a name="class_enhancements">Class Enhancements</a></h3> - - <h4><a name="operators">Operators</a></h4> - -Support for exposing C++ operators and functions as the corresponding -Python special methods was added. Thinking that the Boost.Python -v1 interface was a little too esoteric (especially the use of -<code>left_operand<...>/right_operand<...></code> for -asymmetric operands), I introduced a simple form of <a -href="http://osl.iu.edu/~tveldhui/papers/Expression-Templates/exprtmpl.html">expression -templates</a> which allow users to simply write the expressions that -should be wrapped, as in this <a href="operators.html#examples">example</a>. - - <h4><a name="iterators">Iterators</a></h4> - -Python iterator support as required by the Kull project resulted in a -highly flexible interface allowing: - -<dl> - -<dt>Direct exposure of a class' <code>begin()</code> and -<code>end()</code> functions: - -<pre> - ... - .def("__iter__", iterator<list_int>()) -</pre> -<dd> - -<dt>Creation of iterators from member functions... -<pre> - ... - .def("__iter__" - , range(&my_class::x_begin, &my_class::x_end)) - ) -</pre> -<dd> - -<dt>...and member data: -<pre> - ... - .def("__iter__" - , range(&std::pair<char*,char*>::first, &std::pair<char*,char*>::second)) - ) -</pre> -<dd> - -<dt>The ability to specify <a -href="CallPolicies.html">CallPolicies</a>, e.g. to prevent copying of -heavyweight values: - -<pre> - ... - .def("__iter__", - , range<return_value_policy<copy_non_const_reference> >( - &my_sequence<heavy>::begin - , &my_sequence<heavy>::end)) -</pre> -<dd> - -</dl> - - <h4><a name="properties">Properties</a></h4> - -The Kull iteration interfaces also required the ability to iterate -over a sequence specified by an instance's attribute: -<pre> ->>> f = field() ->>> for e in f.elements: -... print e, -</pre> - -This forced the exposure of the <a - href="http://www.python.org/2.2/descrintro.html#property"><code>property</code></a> - interface used internally to implement the data member exposure - facility described in <a - href="Mar2002.html#data_members">March</a>. Properties are an - incredibly useful idiom, so it's good to be able to provide them - at little new development cost. - - <h4><a name="setattr">setattr</a></h4> - -<code>class_<></code> acquired a <code>setattr</code> member -function which allows users to easily add new Python objects as class -attributes. - - <h4><a name="module">__module__ Attribute</a></h4> - -Ralf Grosse-Kunstleve has been working on pickling support for v2. To -make it work correctly, he had to make sure that a class' -<code>__module__</code> attribute was set correctly. - -<h3><a name="back_reference"><code>back_reference</code></a></h3> - -The new <code>back_reference<T></code> template can be used as a -function parameter when the user needs access to both a <code>T</code> -argument and to the Python object which manages it. The function will -only match in the overload resolution process if it would match the -same function signature with <code>T</code> substituted for -<code>back_reference<T></code>. This feature is not yet -documented. - -<h2><a name="documentation">Documentation</a></h2> - -In a major effort to prepare Boost.Python v2 to replace v1, many pages -of new reference documentation were added: - -<blockquote> - -<dl> - <dt><a href="CallPolicies.html">CallPolicies.html</a><dd> - <dt><a href="Dereferenceable.html">Dereferenceable.html</a><dd> - <dt><a href="Extractor.html">Extractor.html</a><dd> - <dt><a href="HolderGenerator.html">HolderGenerator.html</a><dd> - <dt><a href="ResultConverter.html">ResultConverter.html</a><dd> - <dt><a href="call_method.html">call_method.html</a><dd> - <dt><a href="callbacks.html">callbacks.html</a><dd> - <dt><a href="data_members.html">data_members.html</a><dd> - <dt><a href="has_back_reference.html">has_back_reference.html</a><dd> - <dt><a href="implicit.html">implicit.html</a><dd> - <dt><a href="instance_holder.html">instance_holder.html</a><dd> - <dt><a href="operators.html">operators.html</a><dd> - <dt><a href="ptr.html">ptr.html</a><dd> - <dt><a href="type_id.html">type_id.html</a><dd> - <dt><a href="with_custodian_and_ward.html">with_custodian_and_ward.html</a><dd> -</dl> - -</blockquote> -Major updates were made to the following pages: - - -<blockquote> -<dl> - <dt><a href="call.html">call.html</a><dd> <dt>updated<dd> - <dt><a href="class.html">class.html</a><dd> - <dt><a href="reference.html">reference.html</a><dd> -</dl> -</blockquote> - - As usual, careful documentation forces one to consider the - interface again, and there were many interface changes - associated with this effort, including the elevation of the - following components from implementation detail to - first-class library citizen: - -<blockquote> -<dl> - <dt>type_id.hpp<dd> - <dt>pointee.hpp<dd> - <dt>lvalue_from_pytype.hpp<dd></dl> -</dl> -</blockquote> - -<h2><a name="misc">Miscellaneous</a></h2> - - <h3><a name="converters">Converters</a></h3> - -It appears that the world of C++ <==> Python conversion rules is -an endlessly-rich area of exploration. Completing the conversions for -<code>char</code> and <code>char const*</code> types, as described at -the end of <a href="Apr2002.html#missing">April's report</a>, -uncovered some interesting new shades to the problem. It turns out to -be worth distinguishing mutable and immutable lvalue conversions, -because despite the fact that Python doesn't understand -<code>const</code>, it does understand immutability (c.f. Python -strings, which expose an immutable <code>char</code> pointer). It is -also worth recognizing types which represent lvalue <i>sequences</i>, -to prevent Python <code>"foobar"</code> from being silently -truncated to C++ <code>'f'</code>. More details on this insight can be -found in the mailing list <a -href="http://mail.python.org/pipermail/c++-sig/2002-May/001023.html"> -archive</a>. I don't plan to do anything about this immediately, but I -do think it's the right direction to go in the long run. - - <h3><a name="checkins">Checkins Mailing List</a></h3> - -In order to better coordinate changes made by multiple developers, I -enabled <a -href="http://sourceforge.net/docman/display_doc.php?docid=772&group_id=1">syncmail</a> -for the Boost.Python CVS trees, and established an associated <a -href="http://lists.sourceforge.net/lists/listinfo/boost-python-cvs">mailing -list</a>. Subscribe to this list to receive notices of each new -checkin. - - <h3><a name="shared">Shared Libraries</a></h3> - -Beyond the vagaries of dynamic linking on AIX, I have been -participating in a more-general discussion of dynamic linking for -C++. Needless to say, C++ dynamic linking is of critical importance to -Boost.Python: all extension modules are normally built as shared -libraries, and Boost.Python extension modules share a common library -as well. - -In fact, there are at least two separate conversations. One -in the C++ standard extensions mailing list concerns what can be -standardized for C++ and shared libraries; the other, mostly on the <a -href="http://gcc.gnu.org/ml/gcc/">gcc</a> mailing list, concerns the -behavior of GCC on Posix/ELF platforms. - -Some of the GCC threads are here: - -<blockquote> -<a -href="http://gcc.gnu.org/ml/gcc/2002-05/msg02002.html">http://gcc.gnu.org/ml/gcc/2002-05/msg02002.html</a><br> -<a -href="http://gcc.gnu.org/ml/gcc/2002-05/msg02945.html">http://gcc.gnu.org/ml/gcc/2002-05/msg02945.html</a><br> -<a href="http://gcc.gnu.org/ml/gcc/2002-05/msg01758.html">http://gcc.gnu.org/ml/gcc/2002-05/msg01758.html</a> -</blockquote> - - <h2><a name="next">What's Next</a></h2> - -Development is focused on what's needed to be able to retire -Boost.Python v1. At the moment, that means deciding the user-friendly -interfaces for to_/from_python conversion, and formally exposing the -Python object smart pointers and object wrapper classes. Quite a few -questions have also been showing up recently about how to embed Python -with Boost.Python, and how to link with it statically; the solutions -to these issues will probably have to be formalized before long. - -<p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> -</p> -<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> - 2002. </i></p> -</body> -</html> diff --git a/libs/python/doc/v2/ObjectWrapper.html b/libs/python/doc/v2/ObjectWrapper.html deleted file mode 100644 index 7962e69fa5..0000000000 --- a/libs/python/doc/v2/ObjectWrapper.html +++ /dev/null @@ -1,153 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - ObjectWrapper Concept</title> - </head> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">ObjectWrapper and TypeWrapper Concepts</h2> - </td> - </tr> - </table> - <hr> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#concept-requirements">Concept Requirements</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#ObjectWrapper-concept">ObjectWrapper Concept</a></dt> - - <dt><a href="#TypeWrapper-concept">TypeWrapper Concept</a></dt> - </dl> - </dd> - - <dt><a href="#caveat">Caveat</a></dt> - </dl> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>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.</p> - - <h2><a name="concept-requirements"></a>Concept Requirements</h2> - - <h3><a name="ObjectWrapper-concept"></a>ObjectWrapper Concept</h3> - Models of the ObjectWrapper concept have <a href= - "object.html#object-spec">object</a> 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 <code>R</code> is itself an <a href= - "#TypeWrapper-concept">TypeWrapper</a>, a member function invocation of - the form -<pre> -x.<i>some_function</i>(<i>a<small>1</small>, a<small>2</small>,...a<small>n</small></i>) -</pre> - always has semantics equivalent to: -<pre> -<a href= -"extract.html#extract-spec">extract</a><R>(x.attr("<i>some_function</i>")(<a - href= -"object.html#object-spec-ctors">object</a>(<i>a<small>1</small></i>), <a -href= -"object.html#object-spec-ctors">object</a>(<i>a<small>2</small></i>),...<a -href="object.html#object-spec-ctors">object</a>(<i>a<small>n</small></i>)))() -</pre> - When the <code>R</code> is an <a href= - "#TypeWrapper-concept">TypeWrapper</a>, the result type may be - constructed by taking direct posession of: -<pre> -x.attr("<i>some_function</i>")(<a href= -"object.html#object-spec-ctors">object</a>(<i>a<small>1</small></i>), <a - href= -"object.html#object-spec-ctors">object</a>(<i>a<small>2</small></i>),...<a - href= -"object.html#object-spec-ctors">object</a>(<i>a<small>n</small></i>)).ptr() -</pre> - [see <a href="#caveat">caveat</a> below] - - <h3><a name="TypeWrapper-concept"></a>TypeWrapper Concept</h3> - TypeWrapper is a refinement of ObjectWrapper which is associated with a - particular Python type <code>X</code>. For a given TypeWrapper - <code>T</code>, a valid constructor expression -<pre> -T(<i>a<small>1</small>, a<small>2</small>,...a<small>n</small></i>) -</pre> - builds a new <code>T</code> object managing the result of invoking - <code>X</code> with arguments corresponding to -<pre> -<a href= -"object.html#object-spec-ctors">object</a>(<i>a<small>1</small></i>), <a - href= -"object.html#object-spec-ctors">object</a>(<i>a<small>2</small></i>),...<a - href= -"object.html#object-spec-ctors">object</a>(<i>a<small>n</small></i>) -</pre> - -When used as arguments to wrapped C++ functions, or as the template -parameter to <code><a -href="extract.html#extract-spec">extract</a><></code>, only -instances of the associated Python type will be considered a match. - - <h3><a name="caveat">Caveat</a></h3> - 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 <code><a href= - "dict.html#dict-spec">dict</a></code> member function <code>items</code> - returns an object of type <code><a href= - "list.html#list-spec">list</a></code>. Now suppose the user defines this - <code>dict</code> subclass in Python: -<pre> ->>> class mydict(dict): -... def items(self): -... return tuple(dict.items(self)) # return a tuple -</pre> - Since an instance of <code>mydict</code> is also an instance of - <code>dict</code>, when used as an argument to a wrapped C++ function, - <code><a href="dict.html#dict-spec">boost::python::dict</a></code> can - accept objects of Python type <code>mydict</code>. Invoking - <code>items()</code> on this object can result in an instance of <code><a - href="list.html#list-spec">boost::python::list</a></code> which actually - holds a Python tuple. Subsequent attempts to use list methods (e.g. - <code>append</code>, or any other mutating operation) on this object will - raise the same exception that would occur if you tried to do it from - Python. - <hr> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/ResultConverter.html b/libs/python/doc/v2/ResultConverter.html deleted file mode 100644 index be53a9b974..0000000000 --- a/libs/python/doc/v2/ResultConverter.html +++ /dev/null @@ -1,124 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<link rel="stylesheet" type="text/css" href="../../../../boost.css"> -<title>Boost.Python - ResultConverter Concept</title> -</head> -<body link="#0000ff" vlink="#800080"> -<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - <h2 align="center">ResultConverter Concept</h2> - </td> - </tr> -</table> -<hr> -<dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - <dt><a href="#concept-requirements">Concept Requirements</a></dt> - <dd> - <dl class="page-index"> - <dt><a href="#ResultConverter-concept">ResultConverter Concept</a></dt> - <dt><a href="#ResultConverterGenerator-concept">ResultConverterGenerator Concept</a></dt> - </dl> - </dd> -</dl> - -<h2><a name="introduction"></a>Introduction</h2> - -<p>A ResultConverter for a type <code>T</code> is a type whose -instances can be used to convert C++ return values of type -<code>T</code> <code>to_python</code>. A ResultConverterGenerator is -an MPL unary metafunction class which, given the return type of a C++ -function, returns a ResultConverter for that type. ResultConverters in -Boost.Python generally inspect library's registry of converters to -find a suitable converter, but converters which don't use the registry -are also possible. - -<h2><a name="concept-requirements"></a>Concept Requirements</h2> -<h3><a name="ResultConverter-concept"></a>ResultConverter Concept</h3> - -<p>In the table below, <code><b>C</b></code> denotes a ResultConverter -type for a type <b><code>R</code></b> , <code><b>c</b></code> denotes -an object of type <code><b>C</b></code> , and <code><b>r</b></code> -denotes an object of type <code><b>R</b></code>. - -<table summary="ResultConverter expressions" border="1" cellpadding="5"> - - <tr> - <td><b>Expression</b></td> - <td><b>Type</b></td> - <td><b>Semantics</b></td> - </tr> - - <tr> - <td valign="top"><code>C c;</code></td> - <td> - <td>Constructs a <code>C</code> object. - </tr> - - <tr> - <td valign="top"><code>c.convertible()</code></td> - <td>convertible to <code>bool</code></td> - <td><code>false</code> iff no conversion from any <code>R</code> value - to a Python object is possible.</td> - </tr> - - <tr> - <td valign="top"><code>c(r)</code></td> - <td>convertible to <code>PyObject*</code></td> - <td>A pointer to a Python object corresponding to <code>r</code>, - or <code>0</code> iff <code>r</code> could not be converted - <code>to_python</code>, in which case <a - href="http://www.python.org/doc/current/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a> - should return non-zero.</td> - </tr> - <tr> - <td valign="top"><code>c.get_pytype()</code></td> - <td><code>PyTypeObject const*</code></td> - <td>A pointer to a Python Type object corresponding to result of the conversion, - or <code>0</code>. Used for documentation generation. If <code>0</code> is returned - the generated type in the documentation will be <b>object</b> .</td> - </tr> -</table> - -<h3><a name="ResultConverterGenerator-concept"></a>ResultConverterGenerator Concept</h3> -<p>In the table below, <code><b>G</b></code> denotes a -ResultConverterGenerator type and <code><b>R</b></code> denotes a possible -C++ function return type. - -<table summary="ResultConverterGenerator expressions" border="1" cellpadding="5"> - <tr> - <td><b>Expression</b></td> - <td><b>Requirements</b></td> - </tr> - <tr> - <td valign="top"><code>G::apply<R>::type</code></td> - <td>A ResultConverter type for <code>R</code>.</td> -</table> - -<hr> -<p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 09 May, 2002 <!--Luann's birthday! --> - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> -</p> - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002. </i> - -<p>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. -</body> -</html> diff --git a/libs/python/doc/v2/acknowledgments.html b/libs/python/doc/v2/acknowledgments.html deleted file mode 100644 index 28f1b1dbde..0000000000 --- a/libs/python/doc/v2/acknowledgments.html +++ /dev/null @@ -1,135 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - Acknowledgments</title> - </head> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Acknowledgments</h2> - </td> - </tr> - </table> - <hr> - - <p><a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> is - the architect, designer, and implementor of <b>Boost.Python</b>.</p> - - <p><a href="mailto:brett.calcott@paradise.net.nz">Brett Calcott</a> - contributed and maintains the Visual Studio project files and - documentation.</p> - - <p><a href="mailto:Gottfried.Ganssauge-at-haufe.de">Gottfried - Ganßauge</a> supplied support for opaque pointer conversions, - complete with documentation and a regression test (and I didn't - even have to ask him for those)! - - <p>Joel de Guzman implemented the <a href="overloads.html">default - argument support</a> and wrote the excellent <a href= - "../tutorial/index.html">tutorial documentation</a>.</p> - - <p><a href="http://www.boost.org/people/ralf_w_grosse_kunstleve.htm">Ralf W. - Grosse-Kunstleve</a> implemented the <a href="pickle.html">pickle - support</a>, and has enthusiastically supported the library since its - birth, contributing to design decisions and providing invaluable - real-world insight into user requirements. Ralf has written some <a href= - "faq.html#question2">extensions</a> for converting C++ containers that I - hope will be incorporated into the library soon. He also implemented the - cross-module support in the first version of Boost.Python. More - importantly, Ralf makes sure nobody forgets the near-perfect synergy of - C++ and Python for solving the problems of large-scale software - construction.</p> - - <p><a href="http://www.boost.org/people/aleksey_gurtovoy.htm">Aleksey Gurtovoy</a> - wrote an incredible C++ <a href="http://www.mywikinet.com/mpl">Template - Metaprogramming Library</a> which allows Boost.Python to perform much of - its compile-time magic. In addition, Aleksey very generously contributed - his time and deep knowledge of the quirks of various buggy compilers to - help us get around problems at crucial moments.</p> - - <p><a href="http://www.boost.org/people/paul_mensonides.htm">Paul Mensonides</a>, - building on the work <a href="http://www.boost.org/people/vesa_karvonen.htm">Vesa - Karvonen</a>, wrote a similarly amazing <a href= - "../../../preprocessor/doc/index.html">Preprocessor Metaprogramming - Library</a>, and generously contributed the time and expertise to get it - working in the Boost.Python library, rewriting much of Boost.Python to - use the new preproccessor metaprogramming constructs and helping us to - work around buggy and slow C++ preprocessors.</p> - - <p><a href="mailto:nicodemus-at-globalite.com.br">Bruno da Silva de - Oliveira</a> contributed the ingenious <a - href="../../pyste/index.html">Pyste</a> ("Pie-Steh") - code generator. - - <p><a href="mailto:nickm@sitius.com">Nikolay Mladenov</a> contributed - <code>staticmethod</code> support.</p> - - <p>Martin Casado solved some sticky problems which allow us to build the - Boost.Python shared library for AIX's crazy dynamic linking model.</p> - - <p><a href="mailto:achim@procoders.net">Achim Domma</a> contributed some - of the <a href="reference.html#object_wrappers">Object Wrappers</a> and - HTML templates for this documentation. Dave Hawkes contributed - inspiration for the use of the <code><a href= - "scope.html#scope-spec">scope</a></code> class to simplify module - definition syntax. Pearu Pearson wrote some of the test cases that are in - the current test suite.</p> - - <p>The development of this version of Boost.Python was funded in part by - the <a href="http://www.llnl.gov/">Lawrence Livermore National - Laboratories</a> and by the <a href="http://cci.lbl.gov/">Computational - Crystallography Initiative</a> at Lawrence Berkeley National - Laboratories.</p> - - <p><a href="http://kogs-www.informatik.uni-hamburg.de/~koethe/">Ullrich - Koethe</a> had independently developed a similar system. When he - discovered Boost.Python v1, he generously contributed countless hours of - coding and much insight into improving it. He is responsible for an early - version of the support for function overloading and wrote the support for - reflecting C++ inheritance relationships. He has helped to improve - error-reporting from both Python and C++ (we hope to do as well in v2 - again soon), and has designed the original support for exposing numeric - operators, including a way to avoid explicit coercion by means of - overloading.</p> - - <p>The members of the boost mailing list and the Python community - supplied invaluable early feedback. In particular, Ron Clarke, Mark - Evans, Anton Gluck, Chuck Ingold, Prabhu Ramachandran, and Barry Scott - took the brave step of trying to use Boost.Python while it was still in - early stages of development.</p> - - <p>The first version of Boost.Python would not have been possible without - the support of Dragon Systems, which supported its development and - release as a Boost library.</p> - <hr> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 26 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/args.html b/libs/python/doc/v2/args.html deleted file mode 100644 index e04720b7e5..0000000000 --- a/libs/python/doc/v2/args.html +++ /dev/null @@ -1,199 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/args.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/args.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#keyword-expression"><i>keyword-expressions</i></a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#arg-spec">class <code>arg</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#arg-synopsis">class <code>arg</code> - synopsis</a></dt> - - <dt><a href="#arg-ctor">class <code>arg</code> - constructor</a></dt> - - <dt><a href="#arg-operator">class <code>arg</code> template - <code>operator =</code></a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#keyword-expression-operators"><i>Keyword-expression</i> - operator <code>,</code></a></dt> - - <dt><a href="#functions">Functions (deprecated)</a></dt> - - <dd> - <dl class="page-index"> - <dt><code><a href= - "#args-spec">args</a>(</code>...<code>)</code></dt> - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>Supplies a family of overloaded functions for specifying argument - keywords for wrapped C++ functions.</p> - - <h2><a name="keyword-expression"></a><i>keyword-expressions</i></h2> - - <p>A <b>keyword-expression</b> results in an object which holds a - sequence of <a href="definitions.html#ntbs">ntbs</a>es, and whose type - encodes the number of keywords specified. The <b>keyword-expression</b> - may contain default values for some or all of the keywords it holds</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="arg-spec"></a><code>class arg;</code></h3> - - <p>The objects of class arg are keyword-expressions holding one keyword ( - size one )</p> - - <h4><a name="arg-synopsis"></a>Class <code>arg</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - struct arg - { - template <class T> - arg &operator = (T const &value); - explicit arg (char const *name){elements[0].name = name;} - }; - -}} -</pre> - - <h4><a name="arg-ctor"></a>Class <code>arg</code> constructor</h4> -<pre> -arg(char const* name); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> The argument must be a <a href= - "definitions.html#ntbs">ntbs</a>.</dt> - - <dt><b>Effects:</b> Constructs an <code>arg</code> object holding a - keyword with name <code>name</code>.</dt> - </dl> - - <h4><a name="arg-operator"></a>Class <code>arg</code> operator =</h4> -<pre> -template <class T> arg &operator = (T const &value); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> The argument must convertible to python.</dt> - - <dt><b>Effects:</b> Assigns default value for the keyword.</dt> - - <dt><b>Returns:</b> Reference to <code>this</code>.</dt> - </dl> - - <h2><a name="keyword-expression-operators"><i>Keyword-expression</i> - operator <code>,</code></a></h2> -<pre> - <i>keyword-expression</i> operator , (<i>keyword-expression</i>, const arg &kw) const - <i>keyword-expression</i> operator , (<i>keyword-expression</i>, const char *name) const; -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> The argument <code>name</code> must be a <a href= - "definitions.html#ntbs">ntbs</a>.</dt> - - <dt><b>Effects:</b> Extends the <i>keyword-expression</i> argument with - one more keyword.</dt> - - <dt><b>Returns:</b> The extended <i>keyword-expression</i>.</dt> - </dl> - - <h2><font color="#7F7F7F"><a name="functions"></a>Functions - (deprecated)</font></h2> - - <h3><a name="args-spec"></a><code><font color= - "#7F7F7F">args</font>(</code>...<code>)</code></h3> -<pre> -<font color="#7F7F7F"> <i>unspecified1</i> args(char const*); - <i>unspecified2</i> args(char const*, char const*); - . - . - . - <i>unspecifiedN</i> args(char const*, char const*, ... char const*); -</font> -</pre> - - <dl class="function-semantics"> - <dt><font color="#7F7F7F"><b>Requires:</b> Every argument must be a <a - href="definitions.html#ntbs">ntbs</a>.</font></dt> - - <dt><font color="#7F7F7F"><b>Returns:</b> an object representing a <a - href="#keyword-expression"><i>keyword-expression</i></a> encapsulating - the arguments passed.</font></dt> - </dl> - - <h2><a name="examples"></a>Example</h2> -<pre> -#include <boost/python/def.hpp> -using namespace boost::python; - -int f(double x, double y, double z=0.0, double w=1.0); - -BOOST_PYTHON_MODULE(xxx) -{ - def("f", f - , ( arg("x"), "y", arg("z")=0.0, arg("w")=1.0 ) - ); -} -</pre> - - <p>Revised 01 August, 2003</p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002-2003.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/call.html b/libs/python/doc/v2/call.html deleted file mode 100644 index adba2b5fe8..0000000000 --- a/libs/python/doc/v2/call.html +++ /dev/null @@ -1,85 +0,0 @@ -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<link rel="stylesheet" type="text/css" href="../boost.css"> -<title>Boost.Python - <call.hpp></title> -</head> -<body link="#0000ff" vlink="#800080"> -<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - <h2 align="center">Header <call.hpp></h2> - </td> - </tr> -</table> -<hr> -<h2>Contents</h2> -<dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - <dt><a href="#functions">Functions</a></dt> - <dl class="page-index"> - <dt><a href="#call-spec">call</a></dt> - </dl> - - <dt><a href="#examples">Example(s)</a></dt> - -</dl> -<hr> -<h2><a name="introduction"></a>Introduction</h2> -<p> - <code><boost/python/call.hpp></code> defines the <a - href="#call-spec"><code>call</code></a> family of overloaded function - templates, used to invoke Python callable objects from C++. - -<h2><a name="functions"></a>Functions</h2> -<pre> -<a name="call-spec">template <class R, class A1, class A2, ... class A<i>n</i>></a> -R call(PyObject* callable, A1 const&, A2 const&, ... A<i>n</i> const&) -</pre> -<dl class="function-semantics"> - <dt><b>Requires:</b> <code>R</code> is a pointer type, reference - type, or a complete type with an accessible copy constructor</dt> - - <dt><b>Effects:</b> Invokes <code>callable(a1, a2, ...a<i>n</i>)</code> in - Python, where <code>a1</code>...<code>a<i>n</i></code> are the arguments to - <code>call()</code>, converted to Python objects. - <dt><b>Returns:</b> The result of the Python call, converted to the C++ type <code>R</code>.</dt> - -</dt> - <dt><b>Rationale:</b> For a complete semantic description and - rationale, see <a href="callbacks.html">this page</a>. -</dt> -</dl> - -<h2><a name="examples"></a>Example(s)</h2> - -The following C++ function applies a Python callable object to its two -arguments and returns the result. If a Python exception is raised or -the result can't be converted to a <code>double</code>, an exception -is thrown. - -<pre> -double apply2(PyObject* func, double x, double y) -{ - return boost::python::call<double>(func, x, y); -} -</pre> - -<p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 9 May, 2002 <!-- Luann's birthday! --> - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> -</p> -<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> - 2002. </i></p> -</body> -</html> diff --git a/libs/python/doc/v2/call_method.html b/libs/python/doc/v2/call_method.html deleted file mode 100644 index e54ffb26aa..0000000000 --- a/libs/python/doc/v2/call_method.html +++ /dev/null @@ -1,161 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <call_method.hpp></title> - </head> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <call_method.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#call_method-spec">call_method</a></dt> - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><boost/python/call_method.hpp></code> defines the <a href= - "#call_method-spec"><code>call_method</code></a> family of overloaded - function templates, used to invoke callable attributes of Python objects - from C++.</p> - - <h2><a name="functions"></a>Functions</h2> -<pre> -<a name= -"call_method-spec">template <class R, class A1, class A2, ... class A<i>n</i>></a> -R call_method(PyObject* self, char const* method, A1 const&, A2 const&, ... A<i>n</i> const&) -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>R</code> is a pointer type, reference type, - or a complete type with an accessible copy constructor</dt> - - <dt><b>Effects:</b> Invokes - <code>self.<i>method</i>(a1, a2, ...a<i>n</i>)</code> in - Python, where <code>a1</code>...<code>a<i>n</i></code> are the - arguments to <code>call_method()</code>, converted to Python objects. - For a complete semantic description, see <a href="callbacks.html">this - page</a>.</dt> - - <dt><b>Returns:</b> The result of the Python call, converted to the C++ - type <code>R</code>.</dt> - - <dt><b>Rationale:</b> <code>call_method</code> is critical to - implementing C++ virtual functions which are overridable in Python, as - shown by the example below.</dt> - </dl> - - <h2><a name="examples"></a>Example(s)</h2> - The following C++ illustrates the use of <code>call_method</code> in - wrapping a class with a virtual function that can be overridden in - Python: - - <h3>C++ Module Definition</h3> -<pre> -#include <boost/python/module.hpp> -#include <boost/python/class.hpp> -#include <boost/utility.hpp> -#include <cstring> - -// class to be wrapped -class Base -{ - public: - virtual char const* class_name() const { return "Base"; } - virtual ~Base(); -}; - -bool is_base(Base* b) -{ - return !std::strcmp(b->class_name(), "Base"); -} - -// Wrapper code begins here -using namespace boost::python; - -// Callback class -class Base_callback : public Base -{ - public: - Base_callback(PyObject* self) : m_self(self) {} - - char const* class_name() const { return <b>call_method</b><char const*>(m_self, "class_name"); } - char const* Base_name() const { return Base::class_name(); } - private: - PyObject* const m_self; -}; - -using namespace boost::python; -BOOST_PYTHON_MODULE(my_module) -{ - def("is_base", is_base); - - class_<Base,Base_callback, noncopyable>("Base") - .def("class_name", &Base_callback::Base_name) - ; - -} -</pre> - - <h3>Python Code</h3> -<pre> ->>> from my_module import * ->>> class Derived(Base): -... def __init__(self): -... Base.__init__(self) -... def class_name(self): -... return self.__class__.__name__ -... ->>> is_base(Base()) # calls the class_name() method from C++ -1 ->>> is_base(Derived()) -0 -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/callbacks.html b/libs/python/doc/v2/callbacks.html deleted file mode 100644 index 4e91befadb..0000000000 --- a/libs/python/doc/v2/callbacks.html +++ /dev/null @@ -1,254 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - Calling Python Functions and Methods</title> - </head> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Calling Python Functions and Methods</h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#argument_handling">Argument Handling</a></dt> - - <dt><a href="#result_handling">Result Handling</a></dt> - - <dt><a href="#result_handling">Rationale</a></dt> - </dl> - <hr> - - <h2><a name="introduction">Introduction</a></h2> - The simplest way to call a Python function from C++, given an <code><a - href="object.html#object-spec">object</a></code> instance <code>f</code> - holding the function, is simply to invoke its function call operator. -<pre> -f("tea", 4, 2) // In Python: f('tea', 4, 2) -</pre> - And of course, a method of an <code><a href= - "object.html#object-spec">object</a></code> instance <code>x</code> can - be invoked by using the function-call operator of the corresponding - attribute: -<pre> -x.attr("tea")(4, 2); // In Python: x.tea(4, 2) -</pre> - - <p>If you don't have an <code>object</code> instance, Boost.Python - provides two families of function templates, <code><a href= - "call.html#call-spec">call</a></code> and <code><a href= - "call_method.html#call_method-spec">call_method</a></code>, for invoking - Python functions and methods respectively on <code>PyObject*</code>s. The - interface for calling a Python function object (or any Python callable - object) looks like:</p> -<pre> -call<ResultType>(callable_object, a1, a2... a<i>N</i>); -</pre> - Calling a method of a Python object is similarly easy: -<pre> -call_method<ResultType>(self_object, "<i>method-name</i>", a1, a2... a<i>N</i>); -</pre> - This comparitively low-level interface is the one you'll use when - implementing C++ virtual functions that can be overridden in Python. - - <h2><a name="argument_handling">Argument Handling</a></h2> - - <p>Arguments are converted to Python according to their type. By default, - the arguments <code>a1</code>...<code>a<i>N</i></code> are copied into - new Python objects, but this behavior can be overridden by the use of - <code><a href="ptr.html#ptr-spec">ptr()</a></code> and <a href= - "../../../bind/ref.html">ref()</a>:</p> -<pre> -class X : boost::noncopyable -{ - ... -}; - -void apply(PyObject* callable, X& x) -{ - // Invoke callable, passing a Python object which holds a reference to x - boost::python::call<void>(callable, boost::ref(x)); -} -</pre> - In the table below, <code><b>x</b></code> denotes the actual argument - object and <code><b>cv</b></code> denotes an optional - <i>cv-qualification</i>: "<code>const</code>", "<code>volatile</code>", - or "<code>const volatile</code>". - - <table border="1" summary="class_ template parameters"> - <tr> - <th>Argument Type</th> - - <th>Behavior</th> - </tr> - - <tr> - <td><code>T cv&</code><br> - <code>T cv</code></td> - - <td>The Python argument is created by the same means used for the - return value of a wrapped C++ function returning <code>T</code>. When - <code>T</code> is a class type, that normally means <code>*x</code> - is copy-constructed into the new Python object.</td> - </tr> - - <tr> - <td><code>T*</code></td> - - <td>If <code>x == 0</code>, the Python argument will be - <code><a href= - "http://www.python.org/doc/current/lib/bltin-null-object.html">None</a></code>. - Otherwise, the Python argument is created by the same means used for - the return value of a wrapped C++ function returning <code>T</code>. - When <code>T</code> is a class type, that normally means - <code>*x</code> is copy-constructed into the new Python object.</td> - </tr> - - <tr> - <td><code><a href= - "../../../bind/ref.html">boost::reference_wrapper</a><T></code></td> - - <td>The Python argument contains a pointer to, rather than a copy of, - <code>x.get()</code>. Note: failure to ensure that no Python code - holds a reference to the resulting object beyond the lifetime of - <code>*x.get()</code> <b>may result in a crash!</b></td> - </tr> - - <tr> - <td><code><a href= - "ptr.html#pointer_wrapper-spec">pointer_wrapper</a><T></code></td> - - <td>If <code>x.get() == 0</code>, the Python argument will - be <code><a href= - "http://www.python.org/doc/current/lib/bltin-null-object.html">None</a></code>. - Otherwise, the Python argument contains a pointer to, rather than a - copy of, <code>*x.get()</code>. Note: failure to ensure that no - Python code holds a reference to the resulting object beyond the - lifetime of <code>*x.get()</code> <b>may result in a crash!</b></td> - </tr> - </table> - - <h2><a name="result_handling">Result Handling</a></h2> - In general, <code>call<ResultType>()</code> and - <code>call_method<ResultType>()</code> return - <code>ResultType</code> by exploiting all lvalue and rvalue - <code>from_python</code> converters registered for ResultType and - returning a copy of the result. However, when <code>ResultType</code> is - a pointer or reference type, Boost.Python searches only for lvalue - converters. To prevent dangling pointers and references, an exception - will be thrown if the Python result object has only a single reference - count. - - <h2><a name="rationale">Rationale</a></h2> - In general, to get Python arguments corresponding to - <code>a1</code>...<code>a<i>N</i></code>, a new Python object must be - created for each one; should the C++ object be copied into that Python - object, or should the Python object simply hold a reference/pointer to - the C++ object? In general, the latter approach is unsafe, since the - called function may store a reference to the Python object somewhere. If - the Python object is used after the C++ object is destroyed, we'll crash - Python. - - <p>In keeping with the philosophy that users on the Python side shouldn't - have to worry about crashing the interpreter, the default behavior is to - copy the C++ object, and to allow a non-copying behavior only if the user - writes <code><a href="../../../bind/ref.html">boost::ref</a>(a1)</code> - instead of a1 directly. At least this way, the user doesn't get dangerous - behavior "by accident". It's also worth noting that the non-copying - ("by-reference") behavior is in general only available for class types, - and will fail at runtime with a Python exception if used otherwise[<a - href="#1">1</a>].</p> - - <p>However, pointer types present a problem: one approach is to refuse to - compile if any aN has pointer type: after all, a user can always pass - <code>*aN</code> to pass "by-value" or <code>ref(*aN)</code> to indicate - a pass-by-reference behavior. However, this creates a problem for the - expected null pointer to <code>None</code> conversion: it's illegal to - dereference a null pointer value.</p> - - <p>The compromise I've settled on is this:</p> - - <ol> - <li>The default behavior is pass-by-value. If you pass a non-null - pointer, the pointee is copied into a new Python object; otherwise the - corresponding Python argument will be None.</li> - - <li>if you want by-reference behavior, use <code>ptr(aN)</code> if - <code>aN</code> is a pointer and <code>ref(aN)</code> otherwise. If a - null pointer is passed to <code>ptr(aN)</code>, the corresponding - Python argument will be <code>None</code>.</li> - </ol> - - <p>As for results, we have a similar problem: if <code>ResultType</code> - is allowed to be a pointer or reference type, the lifetime of the object - it refers to is probably being managed by a Python object. When that - Python object is destroyed, our pointer dangles. The problem is - particularly bad when the <code>ResultType</code> is char const* - the - corresponding Python String object is typically uniquely-referenced, - meaning that the pointer dangles as soon as <code>call<char - const*>(...)</code> returns.</p> - - <p>The old Boost.Python v1 deals with this issue by refusing to compile - any uses of <code>call<char const*>()</code>, but this goes both - too far and not far enough. It goes too far because there are cases where - the owning Python string object survives beyond the call (just for - instance, when it's the name of a Python class), and it goes not far - enough because we might just as well have the same problem with a - returned pointer or reference of any other type.</p> - - <p>In Boost.Python v2 this is dealt with by:</p> - - <ol> - <li>lifting the compile-time restriction on const char* callback - returns</li> - - <li>detecting the case when the reference count on the result Python - object is 1 and throwing an exception inside of - <code>call<U>(...)</code> when <code>U</code> is a pointer or - reference type.</li> - </ol> - This should be acceptably safe because users have to explicitly specify a - pointer/reference for <code>U</code> in <code>call<U></code>, and - they will be protected against dangles at runtime, at least long enough - to get out of the <code>call<U>(...)</code> invocation. - <hr> - <a name="1">[1]</a> It would be possible to make it fail at compile-time - for non-class types such as int and char, but I'm not sure it's a good - idea to impose this restriction yet. - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/callbacks.txt b/libs/python/doc/v2/callbacks.txt deleted file mode 100644 index 2795680fd7..0000000000 --- a/libs/python/doc/v2/callbacks.txt +++ /dev/null @@ -1,92 +0,0 @@ -.. Copyright David Abrahams 2006. Distributed under the Boost -.. Software License, Version 1.0. (See accompanying -.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - -Here's the plan: - -I aim to provide an interface similar to that of Boost.Python v1's -callback<>::call(...) for dealing with callbacks. The interface will -look like: - - returning<ResultType>::call("method_name", self_object, a1, a2...); - -or - - returning<ResultType>::call(callable_object, a1, a2...); - -ARGUMENT HANDLING - -There is an issue concerning how to make Python objects from the -arguments a1...aN. A new Python object must be created; should the C++ -object be copied into that Python object, or should the Python object -simply hold a reference/pointer to the C++ object? In general, the -latter approach is unsafe, since the called function may store a -reference to the Python object somewhere. If the Python object is used -after the C++ object is destroyed, we'll crash Python. - -I plan to make the copying behavior the default, and to allow a -non-copying behavior if the user writes boost::ref(a1) instead of a1 -directly. At least this way, the user doesn't get dangerous behavior "by -accident". It's also worth noting that the non-copying ("by-reference") -behavior is in general only available for class types, and will fail at -runtime with a Python exception if used otherwise** - -However, pointer types present a problem: My first thought is to refuse -to compile if any aN has pointer type: after all, a user can always pass -*aN to pass "by-value" or ref(*aN) to indicate a pass-by-reference -behavior. However, this creates a problem for the expected NULL pointer -=> None conversion: it's illegal to dereference a null pointer value. - -We could use another construct, say "ptr(aN)", to deal with null -pointers, but then what does it mean? We know what it does when aN is -NULL, but it might either have by-value or by-reference behavior when aN -is non-null. - -The compromise I've settled on is this: - -1. The default behavior is pass-by-value. If you pass a non-null - pointer, the pointee is copied into a new Python object; otherwise - the corresponding Python argument will be None. - -2. if you want by-reference behavior, use ptr(aN) if aN is a pointer - and ref(aN) otherwise. If a null pointer is passed to ptr(aN), the - corresponding Python argument will be None. - -RESULT HANDLING - -As for results, we have a similar problem: if ResultType is allowed to -be a pointer or reference type, the lifetime of the object it refers to -is probably being managed by a Python object. When that Python object is -destroyed, our pointer dangles. The problem is particularly bad when the -ResultType is char const* - the corresponding Python String object is -typically uniquely-referenced, meaning that the pointer dangles as soon -as returning<char const*>::call() returns. - -Boost.Python v1 deals with this issue by refusing to compile any uses of -callback<char const*>::call(), but IMO this goes both too far and not -far enough. It goes too far because there are cases where the owning -String object survives beyond the call (just for instance when it's the -name of a Python class), and it goes not far enough because we might -just as well have the same problem with any returned pointer or -reference. - -I propose to address this in Boost.Python v2 by - - 1. lifting the compile-time restriction on const - char* callback returns - - 2. detecting the case when the reference count on the - result Python object is 1 and throwing an exception - inside of returning<U>::call() when U is a pointer or - reference type. - -I think this is acceptably safe because users have to explicitly specify -a pointer/reference for U in returning<U>, and they will be protected -against dangles at runtime, at least long enough to get out of the -returning<U>::call() invocation. - --Dave - -**It would be possible to make it fail at compile-time for non-class -types such as int and char, but I'm not sure it's a good idea to impose -this restriction yet. diff --git a/libs/python/doc/v2/class.html b/libs/python/doc/v2/class.html deleted file mode 100644 index edfc609704..0000000000 --- a/libs/python/doc/v2/class.html +++ /dev/null @@ -1,790 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> - <meta name="generator" content= - "HTML Tidy for Cygwin (vers 1st September 2004), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-latin-1-dos"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/class.hpp>, - <boost/python/class_fwd.hpp></title> -</head> - -<body link="#0000FF" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Headers <boost/python/class.hpp>, - <boost/python/class_fwd.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#class_-spec">Class template - <code>class_</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#class_-spec-synopsis">Class <code>class_</code> - synopsis</a></dt> - - <dt><a href="#class_-spec-ctors">Class <code>class_</code> - constructors</a></dt> - - <dt><a href="#class_-spec-modifiers">Class <code>class_</code> - modifier functions</a></dt> - </dl> - </dd> - - <dt><a href="#bases-spec">Class template <code>bases</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#bases-spec-synopsis">Class template - <code>bases</code> synopsis</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - <hr> - - <h2><a name="introduction" id="introduction"></a>Introduction</h2> - - <p><code><boost/python/class.hpp></code> defines the interface - through which users expose their C++ classes to Python. It declares the - <code>class_</code> class template, which is parameterized on the class - type being exposed. It also exposes the <code>init</code>, - <code>optional</code> and <code>bases</code> utility class templates, which - are used in conjunction with <code>class_</code>.</p> - - <p><code><boost/python/class_fwd.hpp></code> contains a forward - declaration of the <code>class_</code> class template.</p> - - <h2><a name="classes" id="classes"></a>Classes</h2> - - <h3><a name="class_-spec" id="class_-spec"></a>Class template - <code>class_<T, <font color="#007F00">Bases, HeldType, - NonCopyable</font>></code></h3> - - <p>Creates a Python class associated with the C++ type passed as its first - parameter. Although it has four template parameters, only the first one is - required. The three optional arguments can actually be supplied - <font color="#007F00"><b>in any order</b></font>; Boost.Python determines - the role of the argument from its type.<br> - <br></p> - - <table border="1" summary="class_ template parameters"> - <tr> - <th>Template Parameter</th> - - <th>Requirements</th> - - <th>Semantics</th> - - <th>Default</th> - </tr> - - <tr> - <td><code>T</code></td> - - <td>A class type.</td> - - <td>The class being wrapped</td> - </tr> - - <tr> - <td><code><font color="#007F00">Bases</font></code></td> - - <td>A specialization of <a href= - "#bases-spec"><code>bases<</code>...<code>></code></a> which - specifies previously-exposed C++ base classes of <code>T</code><a href= - "#footnote_1">[1]</a>.</td> - - <td>Registers <code>from_python</code> conversions from wrapped - <code>T</code> instances to each of its exposed direct and indirect - bases. For each polymorphic base <code>B</code>, registers conversions - from indirectly-held wrapped <code>B</code> instances to - <code>T</code>.</td> - - <td><code><a href="#bases-spec">bases<></a></code></td> - </tr> - - <tr> - <td><code><font color="#007F00">HeldType</font></code></td> - - <td>Must be <code>T</code>, a class derived from <code>T</code>, or a - <a href="Dereferenceable.html">Dereferenceable</a> type for which - <code><a href= - "pointee.html#pointee-spec">pointee</a><HeldType>::type</code> is - <code>T</code> or a class derived from <code>T</code>.</td> - - <td>Specifies the type that is actually embedded in a Python object - wrapping a <code>T</code> instance when <code>T</code>'s constructor is - called or when a <code>T</code> or <code>T*</code> is converted to - Python without the use of <a href= - "http://www.boost.org/libs/python/doc/v2/callbacks.html#argument_handling"> - <code>ptr</code></a>, <a href= - "http://www.boost.org/libs/python/doc/v2/callbacks.html#argument_handling"> - <code>ref</code></a>, or <a href="CallPolicies.html">Call Policies</a> - such as <code><a href= - "return_internal_reference.html">return_internal_reference</a></code>. - More details <a href="#HeldType">below</a>.</td> - - <td><code>T</code></td> - </tr> - - <tr> - <td><code><font color="#007F00">NonCopyable</font></code></td> - - <td>If supplied, must be <a href= - "../../../utility/utility.htm#Class_noncopyable">boost::noncopyable</a>.</td> - - <td>Suppresses automatic registration of <code>to_python</code> - conversions which copy <code>T</code> instances. Required when - <code>T</code> has no publicly-accessible copy constructor.</td> - - <td>An unspecified type other than - <code>boost::noncopyable</code>.</td> - </tr> - </table> - - <h4><a name="HeldType" id="HeldType">HeldType Semantics</a></h4> - - <ol> - <li>If <code>HeldType</code> is derived from T, its exposed - constructor(s) must accept an initial <code>PyObject*</code> argument - which refers back to the Python object that contains the - <code>HeldType</code> instance, as shown in <a href= - "call_method.html#examples">this example</a>. This argument is not - included in the <em><a href= - "init.html#init-expressions">init-expression</a></em> passed to <a href= - "#class_-spec-modifiers"><code>def(init_expr)</code></a>, below, nor is - it passed explicitly by users when Python instances of <code>T</code> are - created. This idiom allows C++ virtual functions which will be overridden - in Python to access the Python object so the Python method can be - invoked. Boost.Python automatically registers additional converters which - allow wrapped instances of <code>T</code> to be passed to wrapped C++ - functions expecting <code>HeldType</code> arguments.</li> - - <li>Because Boost.Python will always allow wrapped instances of - <code>T</code> to be passed in place of <code>HeldType</code> arguments, - specifying a smart pointer for <code>HeldType</code> allows users to pass - Python <code>T</code> instances where a smart pointer-to-<code>T</code> - is expected. Smart pointers such as <code>std::auto_ptr<></code> or - <code><a href= - "../../../smart_ptr/shared_ptr.htm">boost::shared_ptr<></a></code> - which contain a nested type <code>element_type</code> designating the - referent type are automatically supported; additional smart pointer types - can be supported by specializing <a href= - "pointee.html#pointee-spec">pointee<HeldType></a>.</li> - - <li>As in case 1 above, when <code>HeldType</code> is a smart pointer to - a class derived from <code>T</code>, the initial <code>PyObject*</code> - argument must be supplied by all of <code>HeldType</code>'s exposed - constructors.</li> - - <li>Except in cases 1 and 3, users may optionally specify that T itself - gets initialized with a similar initial <code>PyObject*</code> argument - by specializing <a href= - "has_back_reference.html#has_back_reference-spec">has_back_reference<T></a>.</li> - </ol> - - <h4><a name="class_-spec-synopsis" id="class_-spec-synopsis"></a>Class - template <code>class_</code> synopsis</h4> - <pre> -namespace boost { namespace python -{ - template <class T - <font color="#007F00"> , class Bases = bases<> - , class HeldType = T - , class NonCopyable = <i>unspecified</i> - > -</font> class class_ : public <a href="object.html#object-spec">object</a> - { - // Constructors with default __init__ - class_(char const* name); - class_(char const* name, char const* docstring); - - // Constructors, specifying non-default __init__ - template <class Init> - class_(char const* name, Init); - template <class Init> - class_(char const* name, char const* docstring, Init); - - // Exposing additional __init__ functions - template <class Init> - class_& def(Init); - - // defining methods - template <class F> - class_& def(char const* name, F f); - template <class Fn, class A1> - class_& def(char const* name, Fn fn, A1 const&); - template <class Fn, class A1, class A2> - class_& def(char const* name, Fn fn, A1 const&, A2 const&); - template <class Fn, class A1, class A2, class A3> - class_& def(char const* name, Fn fn, A1 const&, A2 const&, A3 const&); - - // declaring method as static - class_& staticmethod(char const* name); - - // exposing operators - template <<i>unspecified</i>> - class_& def(<a href= -"operators.html#operator_-spec">detail::operator_</a><unspecified>); - - // Raw attribute modification - template <class U> - class_& setattr(char const* name, U const&); - - // exposing data members - template <class D> - class_& def_readonly(char const* name, D T::*pm); - - template <class D> - class_& def_readwrite(char const* name, D T::*pm); - - // exposing static data members - template <class D> - class_& def_readonly(char const* name, D const& d); - template <class D> - class_& def_readwrite(char const* name, D& d); - - // property creation - template <class Get> - void add_property(char const* name, Get const& fget, char const* doc=0); - template <class Get, class Set> - void add_property( - char const* name, Get const& fget, Set const& fset, char const* doc=0); - - template <class Get> - void add_static_property(char const* name, Get const& fget); - template <class Get, class Set> - void add_static_property(char const* name, Get const& fget, Set const& fset); - - // pickle support - template <typename PickleSuite> - self& def_pickle(PickleSuite const&); - self& enable_pickling(); - }; -}} -</pre> - - <h4><a name="class_-spec-ctors" id="class_-spec-ctors"></a>Class template - <code>class_</code> constructors</h4> - <pre> -class_(char const* name); -class_(char const* name, char const* docstring); -template <class Init> -class_(char const* name, Init init_spec); -template <class Init> -class_(char const* name, char const* docstring, Init init_spec); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>name</code> is an <a href= - "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= - "http://www.python.org/doc/current/ref/identifiers.html">identifier - naming rules</a>. If <code>docstring</code> is supplied, it must be an - <a href="definitions.html#ntbs">ntbs</a>. If <code>init_spec</code> is - supplied, it must be either the special enumeration constant - <code>no_init</code> or an <a href= - "init.html#init-expressions">init-expression</a> compatible with - <code>T</code>.</dt> - - <dt><b>Effects:</b> Constructs a <code>class_</code> object holding a - Boost.Python extension class named <code>name</code>. The - <code>name</code>d attribute of the <a href= - "scope.html#introduction">current scope</a> is bound to the new extension - class.</dt> - - <dd> - <ul> - <li>If supplied, the value of <code>docstring</code> is bound to the - <code>__doc__</code> attribute of the extension class.</li> - - <li>If <code>init_spec</code> is <code>no_init</code>, a special - <code>__init__</code> function is generated which always raises a - Python exception. Otherwise, <code>this->def(init_spec)</code> is - called.</li> - - <li>If <code>init_spec</code> is not supplied, - <code>this->def(init<>())</code> is called.</li> - </ul> - </dd> - - <dt><b>Rationale:</b>Allowing the user to specify constructor arguments - in the <code>class_<></code> constructor helps her to avoid the - common run-time errors which result from invoking wrapped member - functions without having exposed an <code>__init__</code> function which - creates the requisite <code>T</code> instance. Types which are not - default-constructible will cause a compile-time error unless - <code>Init</code> is supplied. The user must always supply - <code>name</code> as there is currently no portable method to derive the - text of the class name from its type.</dt> - </dl> - - <h4><a name="class_-spec-modifiers" id="class_-spec-modifiers"></a>Class - template <code>class_</code> modifier functions</h4> - <pre> -template <class Init> -class_& def(Init init_expr); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>init_expr</code> is the result of an <a href= - "init.html#init-expressions">init-expression</a> compatible with - <code>T</code>.</dt> - - <dt><b>Effects:</b> For each <a href="init.html#init-expressions">valid - prefix</a> <em>P</em> of <code>Init</code>, adds an - <code>__init__(</code>...<code>)</code> function overload to the - extension class accepting <em>P</em> as arguments. Each overload - generated constructs an object of <code>HeldType</code> according to the - semantics described <a href="#HeldType">above</a>, using a copy of - <code>init_expr</code>'s <a href="CallPolicies.html">call policies</a>. - If the longest <a href="init.html#init-expressions">valid prefix</a> of - <code>Init</code> contains <em>N</em> types and <code>init_expr</code> - holds <em>M</em> keywords, an initial sequence of the keywords are used - for all but the first <em>N</em> - <em>M</em> arguments of each - overload.</dt> - - <dt><b>Returns:</b> <code>*this</code></dt> - - <dt><b>Rationale:</b> Allows users to easily expose a class' constructor - to Python.</dt> - </dl><br> - <pre> -template <class F> -class_& def(char const* name, Fn fn); -template <class Fn, class A1> -class_& def(char const* name, Fn fn, A1 const& a1); -template <class Fn, class A1, class A2> -class_& def(char const* name, Fn fn, A1 const& a1, A2 const& a2); -template <class Fn, class A1, class A2, class A3> -class_& def(char const* name, Fn fn, A1 const& a1, A2 const& a2, A3 const& a3); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>name</code> is an <a href= - "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= - "http://www.python.org/doc/current/ref/identifiers.html">identifier - naming rules</a>.</dt> - - <dd> - <ul> - <li>If <code>a1</code> is the result of an <a href= - "overloads.html#overload-dispatch-expression"><em>overload-dispatch-expression</em></a>, - only the second form is allowed and fn must be a pointer to function - or pointer to member function whose <a href="definitions.html#arity"> - arity</a> is the same as A1's <a href= - "overloads.html#overload-dispatch-expression"><em>maximum - arity</em></a>. - - <dl> - <dt><b>Effects:</b> For each prefix <em>P</em> of - <code>Fn</code>'s sequence of argument types, beginning with the - one whose length is <code>A1</code>'s <a href= - "overloads.html#overload-dispatch-expression"><em>minimum - arity</em></a>, adds a - <code><em>name</em>(</code>...<code>)</code> method overload to - the extension class. Each overload generated invokes - <code>a1</code>'s call-expression with <em>P</em>, using a copy - of <code>a1</code>'s <a href="CallPolicies.html">call - policies</a>. If the longest valid prefix of <code>A1</code> - contains <em>N</em> types and <code>a1</code> holds <em>M</em> - keywords, an initial sequence of the keywords are used for all - but the first <em>N</em> - <em>M</em> arguments of each - overload.<br></dt> - </dl> - </li> - - <li>Otherwise, a single method overload is built around fn, which - must not be null: - - <ul> - <li>If fn is a function pointer, its first argument must be of - the form <code>U</code>, <code>U <em>cv</em>&</code>, <code>U - <em>cv</em>*</code>, or <code>U <em>cv</em>* const&</code>, - where <code>T*</code> is convertible to <code>U*</code>, and - <code>a1</code>-<code>a3</code>, if supplied, may be selected in - any order from the table below.</li> - - <li>Otherwise, if fn is a member function pointer, its target - must be <code>T</code> or one of its public base classes, and - <code>a1</code>-<code>a3</code>, if supplied, may be selected in - any order from the table below.</li> - - <li>Otherwise, <code>Fn</code> must be [derived from] - <code><a href="object.html#object-spec">object</a></code>, and - <code>a1-a2</code>, if supplied, may be selcted in any order from - the first two rows of the table below. To be useful, - <code>fn</code> should be <a href= - "http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-6"> - callable</a>.</li> - </ul> - - <table border="1" summary="def() optional arguments"> - <tr> - <th>Memnonic Name</th> - - <th>Requirements/Type properties</th> - - <th>Effects</th> - </tr> - - <tr> - <td>docstring</td> - - <td>Any <a href="definitions.html#ntbs">ntbs</a>.</td> - - <td>Value will be bound to the <code>__doc__</code> attribute - of the resulting method overload. If an earlier overload - supplied a docstring, two newline characters and the new - docstring are appended to it.</td> - </tr> - - <tr> - <td>policies</td> - - <td>A model of <a href= - "CallPolicies.html">CallPolicies</a></td> - - <td>A copy will be used as the call policies of the resulting - method overload.</td> - </tr> - - <tr> - <td>keywords</td> - - <td>The result of a <a href= - "args.html#keyword-expression"><em>keyword-expression</em></a> - specifying no more arguments than the <a href= - "definitions.html#arity">arity</a> of <code>fn</code>.</td> - - <td>A copy will be used as the call policies of the resulting - method overload.</td> - </tr> - </table> - </li> - </ul> - </dd> - - <dt><b>Returns:</b> <code>*this</code></dt> - </dl> - <pre> -class_& staticmethod(char const* name); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>name</code> is an <a href= - "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= - "http://www.python.org/doc/current/ref/identifiers.html">identifier - naming rules</a>, and corresponds to a method whose overloads have all - been defined.</dt> - - <dt><b>Effects:</b> Replaces the existing named attribute <i>x</i> with - the result of invoking <code>staticmethod(</code><i>x</i><code>)</code> - in Python. Specifies that the corresponding method is static and - therefore no object instance will be passed to it. This is equivalent to - the Python statement:</dt> - - <dd> - <pre> -setattr(self, name, staticmethod(getattr(self, name))) -</pre> - </dd> - - <dt><b>Note:</b> Attempting to invoke <code>def(name,...)</code> after - invoking <code>staticmethod(name)</code> will <a href= - "definitions.html#raise">raise</a> a RuntimeError.</dt> - - <dt><b>Returns:</b> <code>*this</code></dt> - </dl><br> - <pre> -template <<i>unspecified</i>> -class_& def(<a href= -"operators.html#operator_-spec">detail::operator_</a><unspecified>); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> Adds a Python <a href= - "http://www.python.org/doc/ref/specialnames.html">special method</a> as - described <a href="operators.html">here</a>.</dt> - - <dt><b>Returns:</b> <code>*this</code></dt> - </dl> - <pre> -template <class U> -class_& setattr(char const* name, U const& u); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>name</code> is an <a href= - "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= - "http://www.python.org/doc/current/ref/identifiers.html">identifier - naming rules</a>.</dt> - - <dt><b>Effects:</b> Converts u to Python and adds it to the attribute - dictionary of the extension class:</dt> - - <dd> - <blockquote> - <code><a href= - "http://www.python.org/doc/current/api/object.html#l2h-166">PyObject_SetAttrString</a>(this->ptr(), - name, <a href= - "object.html#object-spec-ctors">object</a>(u).ptr());</code> - </blockquote> - </dd> - - <dt><b>Returns:</b> <code>*this</code></dt> - </dl><br> - <pre> -template <class Get> -void add_property(char const* name, Get const& fget, char const* doc=0); -template <class Get, class Set> -void add_property( - char const* name, Get const& fget, Set const& fset, char const* doc=0); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>name</code> is an <a href= - "definitions.html#ntbs">ntbs</a> which conform to Python's <a href= - "http://www.python.org/doc/current/ref/identifiers.html">identifier - naming rules</a>.</dt> - - <dt><b>Effects:</b> Creates a new Python <a href= - "http://www.python.org/2.2.2/descrintro.html#property"><code>property</code></a> - class instance, passing <code><a href= - "object.html#object-spec-ctors">object</a>(fget)</code> (and - <code><a href="object.html#object-spec-ctors">object</a>(fset)</code> in - the second form) with an (optional) docstring <code>doc</code> to its - constructor, then adds that property to the Python class object under - construction with the given attribute <code>name</code>.</dt> - - <dt><b>Returns:</b> <code>*this</code></dt> - - <dt><b>Rationale:</b> Allows users to easily expose functions that can be - invoked from Python with attribute access syntax.</dt> - </dl><br> - <pre> -template <class Get> -void add_static_property(char const* name, Get const& fget); -template <class Get, class Set> -void add_static_property(char const* name, Get const& fget, Set const& fset); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>name</code> is an <a href= - "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= - "http://www.python.org/doc/current/ref/identifiers.html">identifier - naming rules</a>.</dt> - - <dt><b>Effects:</b> Creates a Boost.Python.StaticProperty object, passing - <code><a href="object.html#object-spec-ctors">object</a>(fget)</code> - (and <code><a href= - "object.html#object-spec-ctors">object</a>(fset)</code> in the second - form) to its constructor, then adds that property to the Python class - under construction with the given attribute <code>name</code>. - StaticProperty is a special subclass of Python's <a href= - "http://www.python.org/2.2.2/descrintro.html#property"><code>property</code></a> - class which can be called without an initial <code>self</code> - argument.</dt> - - <dt><b>Returns:</b> <code>*this</code></dt> - - <dt><b>Rationale:</b> Allows users to easily expose functions that can be - invoked from Python with static attribute access syntax.</dt> - </dl><br> - <pre> -template <class D> -class_& def_readonly(char const* name, D T::*pm, char const* doc=0); -template <class D> -class_& def_readonly(char const* name, D const& d); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>name</code> is an <a href= - "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= - "http://www.python.org/doc/current/ref/identifiers.html">identifier - naming rules</a>. <code>doc</code> is also an ntbs.</dt> - - <dt><b>Effects:</b></dt> - - <dd> - <pre> -this->add_property(name, <a href= -"data_members.html#make_getter-spec">make_getter</a>(pm), doc); -</pre>and - <pre> -this->add_static_property(name, <a href= -"data_members.html#make_getter-spec">make_getter</a>(d)); -</pre>respectively.<br> - <br> - </dd> - - <dt><b>Returns:</b> <code>*this</code></dt> - - <dt><b>Rationale:</b> Allows users to easily expose a class' data member - or free variable such that it can be inspected from Python with a natural - syntax.</dt> - </dl> - <pre> -template <class D> -class_& def_readwrite(char const* name, D T::*pm, char const* doc=0); -template <class D> -class_& def_readwrite(char const* name, D& d); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b></dt> - - <dd> - <pre> -this->add_property(name, <a href= -"data_members.html#make_getter-spec">make_getter</a>(pm), <a href= -"data_members.html#make_setter-spec">make_setter</a>(pm), doc); -</pre>and - <pre> -this->add_static_property(name, <a href= -"data_members.html#make_getter-spec">make_getter</a>(d), <a href= -"data_members.html#make_setter-spec">make_setter</a>(d)); -</pre>respectively.<br> - <br> - </dd> - - <dt><b>Returns:</b> <code>*this</code></dt> - - <dt><b>Rationale:</b> Allows users to easily expose a class' data or free - variable member such that it can be inspected and set from Python with a - natural syntax.</dt> - </dl> - <pre> -template <typename PickleSuite> -class_& def_pickle(PickleSuite const&); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> PickleSuite must be publically derived from <a href= - "pickle.html"><code>pickle_suite</code></a>.</dt> - - <dt><b>Effects:</b> Defines a legal combination of the special attributes - and methods: <code>__getinitargs__</code>, <code>__getstate__</code>, - <code>__setstate__</code>, <code>__getstate_manages_dict__</code>, - <code>__safe_for_unpickling__</code>, <code>__reduce__</code></dt> - - <dt><b>Returns:</b> <code>*this</code></dt> - - <dt><b>Rationale:</b> Provides an <a href="pickle.html">easy to use - high-level interface</a> for establishing complete pickle support for the - wrapped class. The user is protected by compile-time consistency - checks.</dt> - </dl><br> - <pre> -class_& enable_pickling(); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> Defines the <code>__reduce__</code> method and the - <code>__safe_for_unpickling__</code> attribute.</dt> - - <dt><b>Returns:</b> <code>*this</code></dt> - - <dt><b>Rationale:</b> Light-weight alternative to - <code>def_pickle()</code>. Enables implementation of <a href= - "pickle.html">pickle support</a> from Python.</dt> - </dl><br> - - <h3><a name="bases-spec" id="bases-spec"></a>Class template - <code>bases<T1, T2,</code>...<code>TN></code></h3> - - <p>An <a href="../../../mpl/doc/refmanual/forward-sequence.html">MPL - sequence</a> which can be used in - <code>class_<</code>...<code>></code> instantiations indicate a list - of base classes.</p> - - <h4><a name="bases-spec-synopsis" id="bases-spec-synopsis"></a>Class - template <code>bases</code> synopsis</h4> - <pre> -namespace boost { namespace python -{ - template <T1 = <i>unspecified</i>,...T<i>n</i> = <i>unspecified</i>> - struct bases - {}; -}} -</pre> - - <h2><a name="examples" id="examples"></a>Example(s)</h2> - - <p>Given a C++ class declaration:</p> - <pre> -class Foo : public Bar, public Baz -{ - public: - Foo(int x, char const* y); - Foo(double); - - std::string const& name() { return m_name; } - void name(char const*); - - double value; // public data - private: - ... -}; -</pre>A corresponding Boost.Python extension class can be created with: - <pre> -using namespace boost::python; - -class_<Foo,bases<Bar,Baz> >("Foo", - "This is Foo's docstring." - "It describes our Foo extension class", - - init<int,char const*>(args("x","y"), "__init__ docstring") - ) - .def(init<double>()) - .def("get_name", &Foo::get_name, return_internal_reference<>()) - .def("set_name", &Foo::set_name) - .def_readwrite("value", &Foo::value) - ; -</pre> - <hr> - <a name="footnote_1" id="footnote_1">[1]</a> By "previously-exposed" we - mean that the for each <code>B</code> in <code>bases</code>, an instance of - <code>class_<B<font color="#007F00">, ...</font>></code> must have - already been constructed. - <pre> -class_<Base>("Base"); -class_<Derived, bases<Base> >("Derived"); -</pre>Revised -<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 1 November, 2005 <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002.</i></p> -</body> -</html> diff --git a/libs/python/doc/v2/configuration.html b/libs/python/doc/v2/configuration.html deleted file mode 100644 index 1be862ed62..0000000000 --- a/libs/python/doc/v2/configuration.html +++ /dev/null @@ -1,217 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - Configuration</title> - </head> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Configuration</h2> - </td> - </tr> - </table> - <hr> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#app-defined">Application Defined Macros</a></dt> - - <dt><a href="#lib-defined-impl">Library Defined Implementation - Macros</a></dt> - </dl> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><b>Boost.Python</b> uses several configuration macros in <a href= - "http://www.boost.org/libs/config/config.htm"><boost/config.hpp></a>, - as well as configuration macros meant to be supplied by the application. - These macros are documented here.</p> - - <h2><a name="app-defined"></a>Application Defined Macros</h2> - - <p>These are the macros that may be defined by an application using - <b>Boost.Python</b>. Note that if you extend a strict interpretation of - the C++ standard to cover dynamic libraries, using different values of - these macros when compiling different libraries (including extension - modules and the <b>Boost.Python</b> library itself) is a violation of the - <a href="definitions.html#ODR">ODR</a>. However, we know of no C++ - implementations on which this particular violation is detectable or - causes any problems.</p> - - <table summary="application defined macros" width="100%" cellpadding= - "10"> - <tr> - <th align="left"><b>Macro</b></th> - - <th><b>Default</b></th> - - <th align="left"><b>Meaning</b></th> - </tr> - - <tr> - <td valign="top"><code>BOOST_PYTHON_MAX_ARITY</code></td> - - <td valign="top" align="center">15</td> - - <td valign="top">The maximum <a href= - "definitions.html#arity">arity</a> of any function, member function, - or constructor to be wrapped, invocation of a <b>Boost.Python</b> - function wich is specified as taking arguments - <code>x1, x2,</code>...<code>X</code><i>n</i>. This includes, in - particular, callback mechanisms such as <code><a href= - "object.html#object-spec">object</a>::operator()(</code>...<code>)</code> - or <code><a href= - "call_method.html#call_method-spec">call_method</a><R>(</code>... - <code>)</code>.</td> - </tr> - - <tr> - <td valign="top"><code>BOOST_PYTHON_MAX_BASES</code></td> - - <td valign="top" align="center">10</td> - - <td valign="top">The maximum number of template arguments to the - <code><a href= - "class.html#bases-spec">bases</a><</code>...<code>></code> - class template, which is used to specify the bases of a wrapped C++ - class..</td> - </tr> - - <tr> - <td valign="top"><code>BOOST_PYTHON_STATIC_MODULE</code></td> - - <td valign="top" align="center"><i>not defined</i></td> - - <td valign="top">If defined, prevents your module initialization - function from being treated as an exported symbol on platforms which - support that distinction in-code</td> - </tr> - - <tr> - <td valign="top"><code>BOOST_PYTHON_ENABLE_CDECL</code></td> - - <td valign="top" align="center"><i>not defined</i></td> - - <td valign="top">If defined, allows functions using the <code>__cdecl - </code> calling convention to be wrapped.</td> - </tr> - - <tr> - <td valign="top"><code>BOOST_PYTHON_ENABLE_STDCALL</code></td> - - <td valign="top" align="center"><i>not defined</i></td> - - <td valign="top">If defined, allows functions using the <code>__stdcall - </code> calling convention to be wrapped.</td> - </tr> - - <tr> - <td valign="top"><code>BOOST_PYTHON_ENABLE_FASTCALL</code></td> - - <td valign="top" align="center"><i>not defined</i></td> - - <td valign="top">If defined, allows functions using the <code>__fastcall - </code> calling convention to be wrapped.</td> - </tr> - </table> - - <h2><a name="lib-defined-impl"></a>Library Defined Implementation - Macros</h2> - - <p>These macros are defined by <b>Boost.Python</b> and are implementation - details of interest only to implementors and those porting to new - platforms.</p> - - <table summary="library defined implementation macros" width="100%" - cellpadding="10"> - <tr> - <th align="left"><b>Macro</b></th> - - <th><b>Default</b></th> - - <th align="left"><b>Meaning</b></th> - </tr> - - <tr> - <td valign="top"><code>BOOST_PYTHON_TYPE_ID_NAME</code></td> - - <td valign="top" align="center"><i>not defined</i></td> - - <td valign="top">If defined, this indicates that the type_info - comparison across shared library boundaries does not work on this - platform. In other words, if shared-lib-1 passes - <code>typeid(T)</code> to a function in shared-lib-2 which compares - it to <code>typeid(T)</code>, that comparison may return - <code>false</code>. If this macro is #defined, Boost.Python uses and - compares <code>typeid(T).name()</code> instead of using and comparing - the <code>std::type_info</code> objects directly.</td> - </tr> - <tr> - <td valign="top"><code>BOOST_PYTHON_NO_PY_SIGNATURES</code></td> - - <td valign="top" align="center"><i>not defined</i></td> - - <td valign="top">If defined for a module no pythonic signatures are generated - for the docstrings of the module functions, and no python type is associated with any - of the converters registered by the module. This also reduces the binary size of the - module by about 14% (gcc compiled).<br> - If defined for the boost_python runtime library, the default for the - <code>docstring_options.enable_py_signatures()</code> is set to <code>false</code>. - </td> - - </tr> - <tr> - <td valign="top"><code>BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</code></td> - - <td valign="top" align="center"><i>defined if <code>BOOST_PYTHON_NO_PY_SIGNATURES</code> is undefined</i></td> - - <td valign="top">This macro is defined to enable a smooth transition from older Boost.Python versions - which do not support pythonic signatures. For example usage see - <a href="pytype_function.html#examples">here</a>. - </td> - - </tr> - <tr> - <td valign="top"><code>BOOST_PYTHON_PY_SIGNATURES_PROPER_INIT_SELF_TYPE</code></td> - - <td valign="top" align="center"><i>not defined</i></td> - - <td valign="top">If defined the python type of <code>__init__</code> method "self" parameters - is properly generated, otherwise <code><b>object</b></code> is used. It is undefined - by default because it increases the binary size of the module by about 14% (gcc compiled).</td> - - </tr> - </table> - <hr> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 7 January, 2003 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/copy_const_reference.html b/libs/python/doc/v2/copy_const_reference.html deleted file mode 100644 index 97c2a282ce..0000000000 --- a/libs/python/doc/v2/copy_const_reference.html +++ /dev/null @@ -1,149 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - - <boost/python/copy_const_reference.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/copy_const_reference.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#copy_const_reference-spec">Class - <code>copy_const_reference</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#copy_const_reference-spec-synopsis">Class - <code>copy_const_reference</code> synopsis</a></dt> - - <dt><a href="#copy_const_reference-spec-metafunctions">Class - <code>copy_const_reference</code> metafunctions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="copy_const_reference-spec"></a>Class - <code>copy_const_reference</code></h3> - - <p><code>copy_const_reference</code> is a model of <a href= - "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> - 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.</p> - - <h4><a name="copy_const_reference-spec-synopsis"></a>Class - <code>copy_const_reference</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - struct copy_const_reference - { - template <class T> struct apply; - }; -}} -</pre> - - <h4><a name="copy_const_reference-spec-metafunctions"></a>Class - <code>copy_const_reference</code> metafunctions</h4> -<pre> -template <class T> struct apply -</pre> - - <dl class="metafunction-semantics"> - <dt><b>Requires:</b> <code>T</code> is <code>U const&</code> for - some <code>U</code>.</dt> - - <dt><b>Returns:</b> <code>typedef <a href= - "to_python_value.html#to_python_value-spec">to_python_value</a><T> - type;</code></dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - - <h3>C++ Module Definition</h3> -<pre> -#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(my_module) -{ - class_<Bar>("Bar"); - - class_<Foo>("Foo", init<int>()) - .def("get_bar", &Foo::get_bar - , return_value_policy<copy_const_reference>()) - ; -} -</pre> - - <h3>Python Code</h3> -<pre> ->>> from my_module import * ->>> f = Foo(3) # create a Foo object ->>> b = f.get_bar() # make a copy of the internal Bar object -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/copy_non_const_reference.html b/libs/python/doc/v2/copy_non_const_reference.html deleted file mode 100644 index 987efad83d..0000000000 --- a/libs/python/doc/v2/copy_non_const_reference.html +++ /dev/null @@ -1,149 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - - <boost/python/copy_non_const_reference.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/copy_non_const_reference.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#copy_non_const_reference-spec">Class - <code>copy_non_const_reference</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#copy_non_const_reference-spec-synopsis">Class - <code>copy_non_const_reference</code> synopsis</a></dt> - - <dt><a href= - "#copy_non_const_reference-spec-metafunctions">Class - <code>copy_non_const_reference</code> metafunctions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="copy_non_const_reference-spec"></a>Class - <code>copy_non_const_reference</code></h3> - - <p><code>copy_non_const_reference</code> is a model of <a href= - "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> - 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.</p> - - <h4><a name="copy_non_const_reference-spec-synopsis"></a>Class - <code>copy_non_const_reference</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - struct copy_non_const_reference - { - template <class T> struct apply; - }; -}} -</pre> - - <h4><a name="copy_non_const_reference-spec-metafunctions"></a>Class - <code>copy_non_const_reference</code> metafunctions</h4> -<pre> -template <class T> struct apply -</pre> - - <dl class="metafunction-semantics"> - <dt><b>Requires:</b> <code>T</code> is <code>U&</code> for some - non-const <code>U</code>.</dt> - - <dt><b>Returns:</b> <code>typedef <a href= - "to_python_value.html#to_python_value-spec">to_python_value</a><T> - type;</code></dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - - <p>C++ code:</p> -<pre> -#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(my_module) -{ - class_<Bar>("Bar"); - - class_<Foo>("Foo", init<int>()) - .def("get_bar", &Foo::get_bar - , return_value_policy<copy_non_const_reference>()) - ; -} -</pre> - Python Code: -<pre> ->>> from my_module import * ->>> f = Foo(3) # create a Foo object ->>> b = f.get_bar() # make a copy of the internal Bar object -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/data_members.html b/libs/python/doc/v2/data_members.html deleted file mode 100644 index 36f818d3d9..0000000000 --- a/libs/python/doc/v2/data_members.html +++ /dev/null @@ -1,229 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/data_members.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/data_members.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#make_getter-spec">make_getter</a></dt> - - <dt><a href="#make_setter-spec">make_setter</a></dt> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><a href="#make_getter-spec">make_getter</a>()</code> and - <code><a href="#make_setter-spec">make_setter</a>()</code> are the - functions used internally by <code>class_<>::<a href= - "class.html#class_-spec-modifiers">def_readonly</a></code> and - <code>class_<>::<a href= - "class.html#class_-spec-modifiers">def_readwrite</a></code> to produce - Python callable objects which wrap C++ data members.</p> - - <h2><a name="functions"></a>Functions</h2> -<pre> -<a name="make_getter-spec">template <class C, class D></a> -<a href="object.html#object-spec">object</a> make_getter(D C::*pm); - -template <class C, class D, class Policies> -<a href= -"object.html#object-spec">object</a> make_getter(D C::*pm, Policies const& policies); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>Policies</code> is a model of <a href= - "CallPolicies.html">CallPolicies</a>.</dt> - - <dt><b>Effects:</b> Creates a Python callable object which accepts a - single argument that can be converted <code>from_python</code> to - <code>C*</code>, and returns the corresponding member <code>D</code> - member of the <code>C</code> object, converted <code>to_python</code>. - If <code>policies</code> is supplied, it will be applied to the - function as described <a href="CallPolicies.html">here</a>. Otherwise, - the library attempts to determine whether <code>D</code> is a - user-defined class type, and if so uses <code><a href= - "return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a><></code></dt> - - <dt>for <code>Policies</code>. Note that this test may inappropriately - choose <code>return_internal_reference<></code> in some cases - when <code>D</code> is a smart pointer type. This is a known - defect.</dt> - - <dt><b>Returns:</b> An instance of <a href= - "object.html#object-spec">object</a> which holds the new Python - callable object.</dt> - </dl> -<pre> -template <class D> -<a href="object.html#object-spec">object</a> make_getter(D const& d); -template <class D, class Policies> -<a href= -"object.html#object-spec">object</a> make_getter(D const& d, Policies const& policies); - -template <class D> -<a href="object.html#object-spec">object</a> make_getter(D const* p); -template <class D, class Policies> -<a href= -"object.html#object-spec">object</a> make_getter(D const* p, Policies const& policies); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>Policies</code> is a model of <a href= - "CallPolicies.html">CallPolicies</a>.</dt> - - <dt><b>Effects:</b> Creates a Python callable object which accepts no - arguments and returns <code>d</code> or <code>*p</code>, converted - <code>to_python</code> on demand. If <code>policies</code> is supplied, - it will be applied to the function as described <a href= - "CallPolicies.html">here</a>. Otherwise, the library attempts to - determine whether <code>D</code> is a user-defined class type, and if - so uses <code><a href= - "reference_existing_object.html#reference_existing_object-spec">reference_existing_object</a></code></dt> - - <dt>for <code>Policies</code>.</dt> - - <dt><b>Returns:</b> An instance of <a href= - "object.html#object-spec">object</a> which holds the new Python - callable object.</dt> - </dl> -<pre> -<a name="make_setter-spec">template <class C, class D></a> -<a href="object.html#object-spec">object</a> make_setter(D C::*pm); - -template <class C, class D, class Policies> -<a href= -"object.html#object-spec">object</a> make_setter(D C::*pm, Policies const& policies); -</pre> - - <dl class="function*-semantics"> - <dt><b>Requires:</b> <code>Policies</code> is a model of <a href= - "CallPolicies.html">CallPolicies</a>.</dt> - - <dt><b>Effects:</b> Creates a Python callable object which, when called - from Python, expects two arguments which can be converted - <code>from_python</code> to <code>C*</code> and - <code>D const&</code>, respectively, and sets the - corresponding <code>D</code> member of the <code>C</code> object. If - <code>policies</code> is supplied, it will be applied to the function - as described <a href="CallPolicies.html">here</a>.</dt> - - <dt><b>Returns:</b> An instance of <a href= - "object.html#object-spec">object</a> which holds the new Python - callable object.</dt> - </dl> -<pre> -template <class D> -<a href="object.html#object-spec">object</a> make_setter(D& d); -template <class D, class Policies> -<a href= -"object.html#object-spec">object</a> make_setter(D& d, Policies const& policies); - -template <class D> -<a href="object.html#object-spec">object</a> make_setter(D* p); -template <class D, class Policies> -<a href= -"object.html#object-spec">object</a> make_setter(D* p, Policies const& policies); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>Policies</code> is a model of <a href= - "CallPolicies.html">CallPolicies</a>.</dt> - - <dt><b>Effects:</b> Creates a Python callable object which accepts one - argument, which is converted from Python to <code>D const&</code> - and written into <code>d</code> or <code>*p</code>, respectively. If - <code>policies</code> is supplied, it will be applied to the function - as described <a href="CallPolicies.html">here</a>.</dt> - - <dt><b>Returns:</b> An instance of <a href= - "object.html#object-spec">object</a> which holds the new Python - callable object.</dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - - <p>The code below uses make_getter and make_setter to expose a data - member as functions:</p> -<pre> -#include <boost/python/data_members.hpp> -#include <boost/python/module.hpp> -#include <boost/python/class.hpp> - -struct X -{ - X(int x) : y(x) {} - int y; -}; - -using namespace boost::python; - -BOOST_PYTHON_MODULE_INIT(data_members_example) -{ - class_<X>("X", init<int>()) - .def("get", make_getter(&X::y)) - .def("set", make_setter(&X::y)) - ; -} -</pre> - It can be used this way in Python: -<pre> ->>> from data_members_example import * ->>> x = X(1) ->>> x.get() -1 ->>> x.set(2) ->>> x.get() -2 -</pre> - - <p> - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 5 August, 2003 <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/def.html b/libs/python/doc/v2/def.html deleted file mode 100644 index 3c71fd363b..0000000000 --- a/libs/python/doc/v2/def.html +++ /dev/null @@ -1,191 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/def.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/def.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#def-spec">def</a></dt> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><a href="#def-spec">def</a>()</code> is the function which can - be used to expose C++ functions and callable objects as Python functions - in the current <code><a href="scope.html">scope</a></code>.</p> - - <h2><a name="functions"></a>Functions</h2> - <a name="def-spec"></a>def -<pre> -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&); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>name</code> is an <a href= - "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= - "http://www.python.org/doc/current/ref/identifiers.html">identifier - naming rules</a>.</dt> - - <dd> - <ul> - <li>If <code>Fn</code> is [derived from] <code><a href= - "object.html#object-spec">object</a></code>, it will be added to - the current scope as a single overload. To be useful, - <code>fn</code> should be <a href= - "http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-6">callable</a>.</li> - - <li> - If <code>a1</code> is the result of an <a href= - "overloads.html#overload-dispatch-expression"><em>overload-dispatch-expression</em></a>, - only the second form is allowed and fn must be a pointer to - function or pointer to member function whose <a href= - "definitions.html#arity">arity</a> is the same as A1's <a href= - "overloads.html#overload-dispatch-expression"><em>maximum - arity</em></a>. - - <dl> - <dt><b>Effects:</b> For each prefix <em>P</em> of - <code>Fn</code>'s sequence of argument types, beginning with - the one whose length is <code>A1</code>'s <a href= - "overloads.html#overload-dispatch-expression"><em>minimum - arity</em></a>, adds a - <code><em>name</em>(</code>...<code>)</code> function overload - to the <a href="scope.html">current scope</a>. Each overload - generated invokes <code>a1</code>'s call-expression with - <em>P</em>, using a copy of <code>a1</code>'s <a href= - "CallPolicies.html">call policies</a>. If the longest valid - prefix of <code>A1</code> contains <em>N</em> types and - <code>a1</code> holds <em>M</em> keywords, an initial sequence - of the keywords are used for all but the first - <em>N</em> - <em>M</em> arguments of each - overload.<br> - </dt> - </dl> - </li> - - <li>Otherwise, fn must be a non-null function or member function - pointer, and a single function overload built around fn is added to - the <a href="scope.html">current scope</a>. If any of - <code>a1</code>-<code>a3</code> are supplied, they may be selected - in any order from the table below.</li> - </ul> - - <table border="1" summary="def() optional arguments"> - <tr> - <th>Memnonic Name</th> - - <th>Requirements/Type properties</th> - - <th>Effects</th> - </tr> - - <tr> - <td>docstring</td> - - <td>Any <a href="definitions.html#ntbs">ntbs</a>.</td> - - <td>Value will be bound to the <code>__doc__</code> attribute of - the resulting method overload.</td> - </tr> - - <tr> - <td>policies</td> - - <td>A model of <a href="CallPolicies.html">CallPolicies</a></td> - - <td>A copy will be used as the call policies of the resulting - method overload.</td> - </tr> - - <tr> - <td>keywords</td> - - <td>The result of a <a href= - "args.html#keyword-expression"><em>keyword-expression</em></a> - specifying no more arguments than the <a href= - "definitions.html#arity">arity</a> of <code>fn</code>.</td> - - <td>A copy will be used as the call policies of the resulting - method overload.</td> - </tr> - </table> - </dd> - </dl> - - <h2><a name="examples"></a>Example</h2> -<pre> -#include <boost/python/def.hpp> -#include <boost/python/module.hpp> -#include <boost/python/args.hpp> - -using namespace boost::python; - -char const* foo(int x, int y) { return "foo"; } - -BOOST_PYTHON_MODULE(def_test) -{ - def("foo", foo, args("x", "y"), "foo's docstring"); -} -</pre> - - <p> - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 7 March, 2003 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/def_visitor.html b/libs/python/doc/v2/def_visitor.html deleted file mode 100644 index 08fa0c5145..0000000000 --- a/libs/python/doc/v2/def_visitor.html +++ /dev/null @@ -1,137 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - <meta name="generator" content="Microsoft FrontPage 5.0"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/def_visitor.hpp></title> - - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - - <td valign="top"> - <h1 align="center"><a href="../index.html"><font size="7">Boost.Python</font></a></h1> - - <h2 align="center">Header <boost/python/def_visitor.hpp></h2> - </table> - <hr> - - <h2>Contents</h2> - - -<dl class="page-index"> - <dt><a href="#introduction">Introduction</a> - <dt><a href="#classes">Classes</a> - <dd> - <dl class="page-index"> - <dt><a href="#def_visitor-spec">Class <code>def_visitor</code></a> - <dd> <a href="#def_visitor-synopsis">Class <code>def_visitor</code> - synopsis</a></dd> - <dd> <a href="#def_visitor-requirements">Class <code>def_visitor</code> - requirements</a></dd> - </dl> - <dt><a href="#examples">Example</a> -</dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - -<p><code><boost/python/def_visitor.hpp></code> provides a generic visitation - interface through which the <a href="class.html">class_</a> <b>def</b> member - functionality can be extended non-intrusively to avoid cluttering the <a href="class.html">class_</a> - interface. It declares the <code>def_visitor<T> </code>class template, - which is parameterized on the derived type <tt>DerivedVisitor</tt>, which provides - the actual <b>def</b> functionality through its <b>visit</b> member functions. -<h2><a name="classes"></a>Classes</h2> - - <h3><a name="def_visitor-spec"></a>Class template <code>def_visitor<DerivedVisitor></code></h3> - - -<p>The class def_visitor is a base class paramaterized by its derived class. The - def_visitor class is a protocol class. Its derived class, DerivedVisitor, is - expected to have a member function visit. The def_visitor class is never instantiated - directly. Instead, an instance of its subclass, DerivedVisitor, is passed - on as an argument to the <a href="class.html">class_</a> def member function. -<h4> -<a name="def_visitor-synopsis" id="def_visitor-synopsis"></a>Class <code>def_visitor </code>synopsis</h4> -<pre>namespace boost { namespace python { - - template <class DerivedVisitor> - class def_visitor {}; -}</pre> -<h3><a name="def_visitor-requirements"></a><code>def_visitor </code>requirements</h3> - - -<p>The <span class="pre">client supplied class </span><span class="pre"></span><tt class="literal"><span class="pre">DerivedVisitor</span></tt> - template parameter is expected to: -<ul> - <li>be privately derived from def_visitor</li> - <li>grant friend access to class def_visitor_access</li> - <li>define either or both visit member functions listed in the table below:</li> -</ul> - - -<table border class="table"> - <tr> - <td width="181" nowrap><b>Expression</b></td> - <td width="85"><b>Return Type</b></td> - <td width="330"><b>Requirements</b></td> - <td width="259"><b>Effects</b></td> - </tr> - <tr> - <td nowrap>visitor.visit(cls)</td> - <td>void</td> - <td>cls is an instance of a <a href="class.html">class_</a> being wrapped - to Python. visitor is a def_visitor derived class.</td> - <td>A call to cls.def(visitor) forwards to this member function.</td> - </tr> - <tr> - <td nowrap>visitor.visit(cls, name, options)</td> - <td>void</td> - <td>cls is a class_ instance, name is a C string. visitor is a def_visitor - derived class. options is a context specific optional argument.</td> - <td>A call to cls.def(name, visitor) or cls.def(name, visitor, options) forwards - to this member function. </td> - </tr> -</table> - - <h2><a name="examples"></a>Example</h2> - - -<pre>class X {/*...*/};<br> -class my_def_visitor : boost::python::def_visitor<my_def_visitor> -{ - friend class def_visitor_access; - - template <class classT> - void visit(classT& c) const - { - c - .def("foo", &my_def_visitor::foo) - .def("bar", &my_def_visitor::bar) - ; - } - - static void foo(X& self); - static void bar(X& self); -}; - -BOOST_PYTHON_MODULE(my_ext) -{ - class_<X>("X") - .def(my_def_visitor()) - ; -} -</pre> - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->27 August, 2003<!--webbot bot="Timestamp" endspan i-checksum="34484" --> - </p> - - - <p><i>© Copyright Joel de Guzman 2003. </i> Distributed under the Boost - Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) diff --git a/libs/python/doc/v2/default_call_policies.html b/libs/python/doc/v2/default_call_policies.html deleted file mode 100644 index 30d0a50de7..0000000000 --- a/libs/python/doc/v2/default_call_policies.html +++ /dev/null @@ -1,173 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - <meta name="generator" content="HTML Tidy, see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - - <boost/python/default_call_policies.hpp></title> - - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/default_call_policies.hpp></h2> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#classes">Classes</a> - - <dd> - <dl class="page-index"> - <dt><a href="#default_call_policies-spec">Class - <code>default_call_policies</code></a> - - <dd> - <dl class="page-index"> - <dt><a href="#default_call_policies-spec-synopsis">Class - <code>default_call_policies</code> synopsis</a> - - <dt><a href="#default_call_policies-spec-statics">Class - <code>default_call_policies</code> static functions</a> - </dl> - - <dt><a href="#default_result_converter-spec">Class - <code>default_result_converter</code></a> - - <dd> - <dl class="page-index"> - <dt><a href="#default_result_converter-spec-synopsis">Class - <code>default_result_converter</code> synopsis</a> - - <dt><a href="#default_result_converter-spec-metafunctions">Class - <code>default_result_converter</code> metafunctions</a> - </dl> - </dl> - - <dt><a href="#examples">Example</a> - </dl> - <hr> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="default_call_policies-spec"></a>Class - <code>default_call_policies</code></h3> - - <p><code>default_call_policies</code> is a model of <a href= - "CallPolicies.html">CallPolicies</a> with no <code>precall</code> or - <code>postcall</code> behavior and a <code>result_converter</code> which - handles by-value returns. Wrapped C++ functions and member functions use - <code>default_call_policies</code> unless otherwise specified. You may find - it convenient to derive new models of <a href= - "CallPolicies.html">CallPolicies</a> from - <code>default_call_policies</code>. - - <h4><a name="default_call_policies-spec-synopsis"></a>Class - <code>default_call_policies</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - struct default_call_policies - { - static bool precall(PyObject*); - static PyObject* postcall(PyObject*, PyObject* result); - typedef <a href= -"#default_result_converter-spec">default_result_converter</a> result_converter; - template <class Sig> struct extract_return_type : mpl::front<Sig>{}; - }; -}} -</pre> - - <h4><a name="default_call_policies-spec-statics"></a>Class - <code>default_call_policies</code> static functions</h4> -<pre> -bool precall(PyObject*); -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> <code>true</code> - - <dt><b>Throws:</b> nothing - </dl> -<pre> -PyObject* postcall(PyObject*, PyObject* result); -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> <code>result</code> - - <dt><b>Throws:</b> nothing - </dl> - - <h3><a name="default_result_converter-spec"></a>Class - <code>default_result_converter</code></h3> - - <p><code>default_result_converter</code> is a model of <a href= - "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> which can be - used to wrap C++ functions returning non-pointer types, <code>char - const*</code>, and <code>PyObject*</code>, by-value. - - <h4><a name="default_result_converter-spec-synopsis"></a>Class - <code>default_result_converter</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - struct default_result_converter - { - template <class T> struct apply; - }; -}} -</pre> - - <h4><a name="default_result_converter-spec-metafunctions"></a>Class - <code>default_result_converter</code> metafunctions</h4> -<pre> -template <class T> struct apply -</pre> - - <dl class="metafunction-semantics"> - <dt><b>Requires:</b> <code>T</code> is not a reference type. If - <code>T</code> is a pointer type, <code>T</code> is <code>const - char*</code> or <code>PyObject*</code>. - - <dt><b>Returns:</b> <code>typedef <a href= - "to_python_value.html#to_python_value-spec">to_python_value</a><T - const&> type;</code> - </dl> - - <h2><a name="examples"></a>Example</h2> - - <p>This example comes from the Boost.Python implementation itself. Because - the <a href= - "return_value_policy.html#return_value_policy-spec">return_value_policy</a> - class template does not implement <code>precall</code> or - <code>postcall</code> behavior, its default base class is - <code>default_call_policies</code>: -<pre> -template <class Handler, class Base = default_call_policies> -struct return_value_policy : Base -{ - typedef Handler result_converter; -}; -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 11 June, 2007 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - - - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002.</i> Distributed under the Boost Software License, - Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at - http://www.boost.org/LICENSE_1_0.txt)</p> - diff --git a/libs/python/doc/v2/definitions.html b/libs/python/doc/v2/definitions.html deleted file mode 100644 index cfec181c7f..0000000000 --- a/libs/python/doc/v2/definitions.html +++ /dev/null @@ -1,102 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - Definitions</title> - </head> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Definitions</h2> - </td> - </tr> - </table> - <hr> - - <dl class="definitions"> - <dt><b><a name="arity">arity</a>:</b> The number of arguments accepted - by a function or member function. Unless otherwise specified, the - hidden "<code>this</code>" argument to member functions is not counted - when specifying arity</dt> - - <dd><br> - </dd> - - <dt><b><a name="ntbs">ntbs</a>:</b> Null-Terminated Byte String, or - `C'-string. C++ string literals are <strong>ntbs</strong>es. An - <strong>ntbs</strong> must never be null.</dt> - - <dd><br> - </dd> - - <dt><b><a name="raise">raise</a>:</b> Exceptions in Python are - "raised", not "thrown", as they are in C++. When this documentation - says that some Python exception is "raised" in the context of C++ code, - it means that the corresponding Python exception is set via the <a - href= - "http://www.python.org/doc/current/api/exceptionHandling.html">Python/'C' - API</a>, and <code><a href= - "errors.html#throw_error_already_set-spec">throw_error_already_set</a>()</code> - is called.</dt> - - <dd><br> - </dd> - - <dt><b><a name="POD">POD</a>:</b> A technical term from the C++ - standard. Short for "Plain Ol'Data": A POD-struct is an aggregate class - that has no non-static data members of type pointer to member, - non-POD-struct, non-POD-union (or array of such types) or reference, - and has no user-defined copy assign- ment operator and no user-defined - destructor. Similarly, a POD-union is an aggregate union that has no - non-static data members of type pointer to member, non-POD-struct, - non-POD-union (or array of such types) or reference, and has no - user-defined copy assignment operator and no user-defined destructor. A - POD class is a class that is either a POD-struct or a POD-union. An - aggregate is an array or a class (clause 9) with no user-declared - constructors (12.1), no private or protected non-static data members - (clause 11), no base classes (clause 10), and no virtual functions - (10.3).</dt> - - <dd><br> - </dd> - - <dt><b><a name="ODR">ODR</a>:</b> The "One Definition - Rule", which says that any entity in a C++ program must have the same definition in all translation units (object files) which make up a program. - </dt> - - <dd><br> - </dd> - - - </dl> - <hr> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/dict.html b/libs/python/doc/v2/dict.html deleted file mode 100644 index 82ea136536..0000000000 --- a/libs/python/doc/v2/dict.html +++ /dev/null @@ -1,152 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/dict.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/dict.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#dict-spec">Class <code>dict</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#dict-spec-synopsis">Class <code>dict</code> - synopsis</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>Exposes a <a href= - "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> for the Python - <a href= - "http://www.python.org/dev/doc/devel/lib/typesmapping.html">dict</a> - type.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="dict-spec"></a>Class <code>dict</code></h3> - - <p>Exposes the <a href= - "http://www.python.org/dev/doc/devel/lib/typesmapping.html">mapping - protocol</a> of Python's built-in <code>dict</code> type. The semantics - of the constructors and member functions defined below can be fully - understood by reading the <a href= - "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept - definition. Since <code>dict</code> is publicly derived from <code><a - href="object.html#object-spec">object</a></code>, the public object - interface applies to <code>dict</code> instances as well.</p> - - <h4><a name="dict-spec-synopsis"></a>Class <code>dict</code> - synopsis</h4> -<pre> -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; - }; -}} -</pre> - - <h2><a name="examples"></a>Example</h2> -<pre> -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; -} -</pre> - - <p>Revised 30 September, 2002</p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/docstring_options.html b/libs/python/doc/v2/docstring_options.html deleted file mode 100644 index a2a0cc6459..0000000000 --- a/libs/python/doc/v2/docstring_options.html +++ /dev/null @@ -1,386 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> - <meta name="generator" content= - "HTML Tidy for Linux/x86 (vers 1st September 2004), see www.w3.org"> - <meta http-equiv="Content-Type" content= - "text/html; charset=us-ascii"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - - <boost/python/docstring_options.hpp></title> -</head> - -<body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" - summary="header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width= - "277" alt="C++ Boost" src="../../../../boost.png" border= - "0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href= - "../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/docstring_options.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#docstring_options-spec">Class - <code>docstring_options</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#docstring_options-spec-synopsis">Class - <code>docstring_options</code> synopsis</a></dt> - - <dt><a href="#docstring_options-spec-ctors">Class - <code>docstring_options</code> constructors</a></dt> - - <dt><a href="#docstring_options-spec-dtors">Class - <code>docstring_options</code> destructors</a></dt> - - <dt><a href="#docstring_options-spec-modifiers">Class - <code>docstring_options</code> modifiers</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Examples</a></dt> - </dl> - <hr> - - <h2><a name="introduction" id= - "introduction"></a>Introduction</h2> - - <p>Boost.Python supports user-defined docstrings with automatic - appending of C++ signatures. These features are enabled by - default. The <code>class docstring_options</code> is available to - selectively suppress the user-defined docstrings, signatures, or - both.</p> - - <h2><a name="classes" id="classes"></a>Classes</h2> - - <h3><a name="docstring_options-spec" id= - "docstring_options-spec"></a>Class - <code>docstring_options</code></h3> - - <p>Controls the appearance of docstrings of wrapped functions and - member functions for the life-time of the instance. The instances - are noncopyable to eliminate the possibility of surprising side - effects.</p> - - <h4><a name="docstring_options-spec-synopsis" id= - "docstring_options-spec-synopsis"></a>Class - <code>docstring_options</code> synopsis</h4> - <pre> -namespace boost { namespace python { - - class docstring_options : boost::noncopyable - { - public: - docstring_options(bool show_all=true); - - docstring_options(bool show_user_defined, bool show_signatures); - - docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures); - - ~docstring_options(); - - void - disable_user_defined(); - - void - enable_user_defined(); - - void - disable_signatures(); - - void - enable_signatures(); - - void - disable_py_signatures(); - - void - enable_py_signatures(); - - void - disable_cpp_signatures(); - - void - enable_cpp_signatures(); - - void - disable_all(); - - void - enable_all(); - }; - -}} -</pre> - - <h4><a name="docstring_options-spec-ctors" id= - "docstring_options-spec-ctors"></a>Class - <code>docstring_options</code> constructors</h4> - <pre> -docstring_options(bool show_all=true); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> Constructs a <code>docstring_options</code> - object which controls the appearance of function and - member-function docstrings defined in the code that follows. If - <code>show_all</code> is <code>true</code>, both the - user-defined docstrings and the automatically generated Python and C++ - signatures are shown. If <code>show_all</code> is - <code>false</code> the <code>__doc__</code> attributes are - <code>None</code>.</dt> - </dl> - <pre> -docstring_options(bool show_user_defined, bool show_signatures); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> Constructs a <code>docstring_options</code> - object which controls the appearance of function and - member-function docstrings defined in the code that follows. - Iff <code>show_user_defined</code> is <code>true</code>, the - user-defined docstrings are shown. Iff - <code>show_signatures</code> is <code>true</code>, Python and C++ - signatures are automatically added. If both - <code>show_user_defined</code> and <code>show_signatures</code> - are <code>false</code>, the <code>__doc__</code> attributes are - <code>None</code>.</dt> - </dl> - <pre> -docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> Constructs a <code>docstring_options</code> - object which controls the appearance of function and - member-function docstrings defined in the code that follows. - Iff <code>show_user_defined</code> is <code>true</code>, the - user-defined docstrings are shown. Iff - <code>show_py_signatures</code> is <code>true</code>, Python - signatures are automatically added. Iff - <code>show_cpp_signatures</code> is <code>true</code>, C++ - signatures are automatically added. If all parameters are - <code>false</code>, the <code>__doc__</code> attributes are - <code>None</code>.</dt> - </dl> - - <h4><a name="docstring_options-spec-dtors" id= - "docstring_options-spec-dtors"></a>Class - <code>docstring_options</code> destructors</h4> - <pre> -~docstring_options(); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> Restores the previous state of the - docstring options. In particular, if - <code>docstring_options</code> instances are in nested C++ - scopes the settings effective in the enclosing scope are - restored. If the last <code>docstring_options</code> instance - goes out of scope the default "all on" settings are - restored.</dt> - </dl> - - <h4><a name="docstring_options-spec-modifiers" id= - "docstring_options-spec-modifiers"></a>Class - <code>docstring_options</code> modifier functions</h4> - <pre> -void disable_user_defined(); -void enable_user_defined(); -void disable_signatures(); -void enable_signatures(); -void disable_py_signatures(); -void enable_py_signatures(); -void disable_cpp_signatures(); -void enable_cpp_signatures(); -void disable_all(); -void enable_all(); -</pre> - - <dl class="function-semantics"> - <dt>These member functions dynamically change the appearance of - docstrings in the code that follows. The - <code>*_user_defined()</code> and <code>*_signatures()</code> - member functions are provided for fine-grained control. The - <code>*_all()</code> member functions are convenient shortcuts - to manipulate all settings simultaneously.</dt> - </dl> - - <h2><a name="examples" id="examples"></a>Examples</h2> - - <h4>Docstring options defined at compile time</h4> - <pre> -#include <boost/python/module.hpp> -#include <boost/python/def.hpp> -#include <boost/python/docstring_options.hpp> - -void foo() {} - -BOOST_PYTHON_MODULE(demo) -{ - using namespace boost::python; - docstring_options doc_options(DEMO_DOCSTRING_SHOW_ALL); - def("foo", foo, "foo doc"); -} -</pre>If compiled with <code>-DDEMO_DOCSTRING_SHOW_ALL=true</code>: - <pre> ->>> import demo ->>> print demo.foo.__doc__ -foo() -> None : foo doc -C++ signature: - foo(void) -> void -</pre>If compiled with -<code>-DDEMO_DOCSTRING_SHOW_ALL=false</code>: - <pre> ->>> import demo ->>> print demo.foo.__doc__ -None -</pre> - - <h4>Selective suppressions</h4> - <pre> -#include <boost/python/module.hpp> -#include <boost/python/def.hpp> -#include <boost/python/args.hpp> -#include <boost/python/docstring_options.hpp> - -int foo1(int i) { return i; } -int foo2(long l) { return static_cast<int>(l); } -int foo3(float f) { return static_cast<int>(f); } -int foo4(double d) { return static_cast<int>(d); } - -BOOST_PYTHON_MODULE(demo) -{ - using namespace boost::python; - docstring_options doc_options; - def("foo1", foo1, arg("i"), "foo1 doc"); - doc_options.disable_user_defined(); - def("foo2", foo2, arg("l"), "foo2 doc"); - doc_options.disable_signatures(); - def("foo3", foo3, arg("f"), "foo3 doc"); - doc_options.enable_user_defined(); - def("foo4", foo4, arg("d"), "foo4 doc"); - doc_options.enable_py_signatures(); - def("foo5", foo4, arg("d"), "foo5 doc"); - doc_options.disable_py_signatures(); - doc_options.enable_cpp_signatures(); - def("foo6", foo4, arg("d"), "foo6 doc"); -} -</pre>Python code: - <pre> ->>> import demo ->>> print demo.foo1.__doc__ -foo1( (int)i) -> int : foo1 doc -C++ signature: - foo1(int i) -> int ->>> print demo.foo2.__doc__ -foo2( (int)l) -> int : -C++ signature: - foo2(long l) -> int ->>> print demo.foo3.__doc__ -None ->>> print demo.foo4.__doc__ -foo4 doc ->>> print demo.foo5.__doc__ -foo5( (float)d) -> int : foo5 doc ->>> print demo.foo6.__doc__ -foo6 doc -C++ signature: - foo6(double d) -> int -</pre> - - <h4>Wrapping from multiple C++ scopes</h4> - <pre> -#include <boost/python/module.hpp> -#include <boost/python/def.hpp> -#include <boost/python/args.hpp> -#include <boost/python/docstring_options.hpp> - -int foo1(int i) { return i; } -int foo2(long l) { return static_cast<int>(l); } - -int bar1(int i) { return i; } -int bar2(long l) { return static_cast<int>(l); } - -namespace { - - void wrap_foos() - { - using namespace boost::python; - // no docstring_options here - // -> settings from outer C++ scope are in effect - def("foo1", foo1, arg("i"), "foo1 doc"); - def("foo2", foo2, arg("l"), "foo2 doc"); - } - - void wrap_bars() - { - using namespace boost::python; - bool show_user_defined = true; - bool show_signatures = false; - docstring_options doc_options(show_user_defined, show_signatures); - def("bar1", bar1, arg("i"), "bar1 doc"); - def("bar2", bar2, arg("l"), "bar2 doc"); - } -} - -BOOST_PYTHON_MODULE(demo) -{ - boost::python::docstring_options doc_options(false); - wrap_foos(); - wrap_bars(); -} -</pre>Python code: - <pre> ->>> import demo ->>> print demo.foo1.__doc__ -None ->>> print demo.foo2.__doc__ -None ->>> print demo.bar1.__doc__ -bar1 doc ->>> print demo.bar2.__doc__ -bar2 doc -</pre> - - <h4>See also: <code>boost/libs/python/test/docstring.cpp</code> - and <code>docstring.py</code></h4> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 16 January, 2006 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/ralf_w_grosse_kunstleve.htm">Ralf W. - Grosse-Kunstleve</a> 2006.</i></p> -</body> -</html> diff --git a/libs/python/doc/v2/enum.html b/libs/python/doc/v2/enum.html deleted file mode 100644 index c5ec2b9217..0000000000 --- a/libs/python/doc/v2/enum.html +++ /dev/null @@ -1,234 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/enum.hpp></title> - </head> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/enum.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#enum_-spec">Class template - <code>enum_</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#enum_-spec-synopsis">Class template <code>enum_</code> - synopsis</a></dt> - - <dt><a href="#enum_-spec-ctors">Class template <code>enum_</code> - constructors</a></dt> - - <dt><a href="#enum_-spec-modifiers">Class template <code>enum_</code> - modifier functions</a></dt> - </dl> - </dd> - - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><boost/python/enum.hpp></code> defines the - interface through which users expose their C++ enumeration types - to Python. It declares the - <code>enum_</code> class template, which is parameterized on the - enumeration type being exposed. </p> - - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="enum_-spec"></a>Class template - <code>enum_<T></code></h3> - - <p>Creates a Python class derived from Python's <code>int</code> - type which is associated with the C++ type passed as its first - parameter. - - <h4><a name="enum_-spec-synopsis"></a>Class template <code>enum_</code> - synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <class T> - class enum_ : public <a href="object.html#object-spec">object</a> - { - enum_(char const* name, char const* doc = 0); - enum_<T>& value(char const* name, T); - enum_<T>& export_values(); - }; -}} -</pre> - - <h4><a name="enum_-spec-ctors"></a>Class template <code>enum_</code> - constructors</h4> -<pre> -enum_(char const* name, char const* doc=0); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>name</code> is an <a href= - "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= - "http://www.python.org/doc/current/ref/identifiers.html">identifier - naming rules</a>. - - <dt><b>Effects:</b> Constructs an <code>enum_</code> object - holding a Python extension type derived from <code>int</code> - which is named <code>name</code>. The - <code>name</code>d attribute of the <a href= - "scope.html#introduction">current scope</a> is bound to the new - extension type.</dt> - </dl> - - <h4><a name="enum_-spec-modifiers"></a>Class template - <code>enum_</code> modifier functions</h4> -<pre> -inline enum_<T>& value(char const* name, T x); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>name</code> is an <a href= - "definitions.html#ntbs">ntbs</a> which conforms to Python's <a - href= - "http://www.python.org/doc/current/ref/identifiers.html">identifier - naming rules</a>. - - <dt><b>Effects:</b> adds an instance of the wrapped enumeration - type with value <code>x</code> to the type's dictionary as the - <code>name</code>d attribute.</dt> - - <dt><b>Returns:</b> <code>*this</code></dt> - - </dl> - -<pre> -inline enum_<T>& export_values(); -</pre> - - <dl class="function-semantics"> - - <dt><b>Effects:</b> sets attributes in the current <a - href="scope.html#scope-spec"><code>scope</code></a> with the - same names and values as all enumeration values exposed so far - by calling <code>value()</code>.</dt> - - <dt><b>Returns:</b> <code>*this</code></dt> - - </dl> - - <h2><a name="examples"></a>Example(s)</h2> - - <p>C++ module definition -<pre> -#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) - .export_values() - .value("blue", blue) - ; - - def("identity", identity_); -} -</pre> - <p>Interactive Python: -<pre> ->>> from enums import * - ->>> identity(red) -enums.color.red - ->>> identity(color.red) -enums.color.red - ->>> identity(green) -enums.color.green - ->>> identity(color.green) -enums.color.green - ->>> identity(blue) -Traceback (most recent call last): - File "<stdin>", line 1, in ? -NameError: name blue' is not defined - ->>> 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 -</pre> - <hr> - - Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 December, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/errors.html b/libs/python/doc/v2/errors.html deleted file mode 100644 index 69a3cf5700..0000000000 --- a/libs/python/doc/v2/errors.html +++ /dev/null @@ -1,289 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/errors.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/errors.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#error_already_set-spec">Class - <code>error_already_set</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#error_already_set-spec-synopsis">Class - <code>error_already_set</code> synopsis</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#handle_exception-spec">handle_exception</a></dt> - - <dt><a href="#expect_non_null-spec">expect_non_null</a></dt> - - <dt><a href= - "#throw_error_already_set-spec">throw_error_already_set</a></dt> - </dl> - </dd> - - <dt><a href="#examples">Examples</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><boost/python/errors.hpp></code> 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.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="error_already_set-spec"></a>Class - <code>error_already_set</code></h3> - - <p><code>error_already_set</code> is an exception type which can be - thrown to indicate that a Python error has occurred. If thrown, the - precondition is that <a href= - "http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred()</a> - returns a value convertible to <code>true</code>. Portable code shouldn't - throw this exception type directly, but should instead use <code><a href= - "#throw_error_already_set-spec">throw_error_already_set</a>()</code>, - below.</p> - - <h4><a name="error_already_set-spec-synopsis"></a>Class error_already_set - synopsis</h4> -<pre> -namespace boost { namespace python -{ - class error_already_set {}; -}} -</pre> - - <h2><a name="functions"></a>Functions</h2> -<pre> -<a name= -"handle_exception-spec">template <class T> bool handle_exception</a>(T f) throw(); - -void handle_exception() throw(); -</pre> - - <dl class="handle_exception-semantics"> - <dt><b>Requires:</b> The first form requires that the expression - <code><a href= - "../../../../doc/html/functionN.html">function0</a><void>(f)</code> - is valid. The second form requires that a C++ exception is currently - being handled (see section 15.1 in the C++ standard).</dt> - - <dt><b>Effects:</b> The first form calls <code>f()</code> inside a - <code>try</code> block which first attempts to use all registered <a - href="exception_translator.html">exception translators</a>. If none of - those translates the exception, the <code>catch</code> clauses then set - an appropriate Python exception for the C++ exception caught, returning - <code>true</code> if an exception was thrown, <code>false</code> - otherwise. The second form passes a function which rethrows the - exception currently being handled to the first form.</dt> - - <dt><b>Postconditions:</b> No exception is being handled</dt> - - <dt><b>Throws:</b> nothing</dt> - - <dt><b>Rationale:</b> At inter-language boundaries it is important to - ensure that no C++ exceptions escape, since the calling language - usually doesn't have the equipment necessary to properly unwind the - stack. Use <code>handle_exception</code> 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: <code><a href= - "make_function.html#make_function-spec">make_function</a>()</code>, - <code><a href= - "make_function.html#make_constructor-spec">make_constructor</a>()</code>, - <code><a href="def.html#class_-spec-modifiers">def</a>()</code> and <code><a href= - "class.html#def-spec">class_::def</a>()</code>. The second form can be - more convenient to use (see the <a href="#examples">example</a> below), - but various compilers have problems when exceptions are rethrown from - within an enclosing <code>try</code> block.</dt> - </dl> -<pre> -<a name= -"expect_non_null-spec">template <class T> T* expect_non_null(T* x);</a> -</pre> - - <dl class="expect_non_null-semantics"> - <dt><b>Returns:</b> <code>x</code></dt> - - <dt><b>Throws:</b> <code><a href= - "#error_already_set-spec">error_already_set</a>()</code> iff <code>x == - 0</code>.</dt> - - <dt><b>Rationale:</b> Simplifies error-handling when calling functions - in the <a href="http://www.python.org/doc/2.2/api/api.html">Python/C - API</a> which return 0 on error.</dt> - </dl> -<pre> -<a name="throw_error_already_set-spec">void throw_error_already_set();</a> -</pre> - - <dl class="throw_error_already_set-semantics"> - <dt><b>Effects:</b> <code>throw <a href= - "#error_already_set-spec">error_already_set</a>();</code></dt> - </dl> - - <dl> - <dt><b>Rationale:</b> Many platforms and compilers are not able to - consistently catch exceptions thrown across shared library boundaries. - Using this function from the Boost.Python library ensures that the - appropriate <code>catch</code> block in <code><a href= - "#handle_exception-spec">handle_exception</a>()</code> can catch the - exception.</dt> - </dl> - - <h2><a name="examples"></a>Examples</h2> -<pre> -#include <string> -#include <boost/python/errors.hpp> -#include <boost/python/object.hpp> -#include <boost/python/handle.hpp> - -// Returns a std::string which has the same value as obj's "__name__" -// attribute. -std::string get_name(boost::python::object obj) -{ - // throws if there's no __name__ attribute - PyObject* p = boost::python::expect_non_null( - PyObject_GetAttrString(obj.ptr(), "__name__")); - - char const* s = PyString_AsString(p); - if (s != 0) - Py_DECREF(p); - - // throws if it's not a Python string - std::string result( - boost::python::expect_non_null( - PyString_AsString(p))); - - Py_DECREF(p); // Done with p - - return result; -} - -// -// Demonstrate form 1 of handle_exception -// - -// Place into result a Python Int object whose value is 1 if a and b have -// identical "__name__" attributes, 0 otherwise. -void same_name_impl(PyObject*& result, boost::python::object a, boost::python::object b) -{ - result = PyInt_FromLong( - get_name(a) == get_name(a2)); -} - -object borrowed_object(PyObject* p) -{ - return boost::python::object( - boost::python::handle<>( - boost::python::borrowed(a1))); -} - -// 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), borrowed_object(a1), borrowed_object(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(borrowed_object(a1)) == get_name(borrowed_object(a2))); - } - catch(...) - { - // If an exception was thrown, translate it to Python - boost::python::handle_exception(); - return 0; - } -} -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/exception_translator.html b/libs/python/doc/v2/exception_translator.html deleted file mode 100644 index 4cc7bb91b4..0000000000 --- a/libs/python/doc/v2/exception_translator.html +++ /dev/null @@ -1,150 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - - <boost/python/exception_translator.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/exception_translator.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href= - "#register_exception_translator-spec">register_exception_translator</a></dt> - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>As described <a href="errors.html#handle_exception-spec">here</a>, 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 <a href= - "http://www.python.org/doc/current/lib/module-exceptions.html">RuntimeError</a> - exception whose representation is - <code>'Unidentifiable C++ Exception'</code>. To produce better - error messages, users can register additional exception translators as - described below.</p> - - <h2><a name="functions"></a>Functions</h2> - -<h3><code><a name="register_exception_translator-spec">register_exception_translator</a></code></h3> - -<pre> -<a name="register_exception_translator-spec">template<class ExceptionType, class Translate></a> -void register_exception_translator(Translate translate); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b></dt> - - <dd> - <code>Translate</code> is <a href= - "../../../utility/CopyConstructible.html">Copyconstructible</a>, and - the following code must be well-formed: -<pre> -void f(ExceptionType x) { translate(x); } -</pre> - The expression <code>translate(x)</code> must either throw a C++ - exception, or a subsequent call to <code><a href= - "http://www.python.org/doc/current/api/exceptionHandling.html">PyErr_Occurred</a>()</code> - must return 1. - </dd> - - <p> - - <dt><b>Effects:</b> Adds a copy of <code>translate</code> 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).</dt> - </dl> - - <h2><a name="examples"></a>Example</h2> -<pre> -#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); -} -</pre> - <br> - <br> - - <hr> - - <p>Revised 03 October, 2002</p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/exec.html b/libs/python/doc/v2/exec.html deleted file mode 100644 index 83d2c9b896..0000000000 --- a/libs/python/doc/v2/exec.html +++ /dev/null @@ -1,163 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/exec.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/exec.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#eval-spec"><code>eval</code></a></dt> - <dt><a href="#exec-spec"><code>exec</code></a></dt> - <dt><a href="#exec_file-spec"><code>exec_file</code></a></dt> - </dl> - </dd> - <dt><a href="#examples">Examples</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>Exposes a mechanism for embedding the python interpreter into C++ code.</p> - - <h2><a name="functions"></a>Functions</h2> - - <h3><a name="eval-spec"></a><code>eval</code></h3> - <pre> -object eval(str expression, - object globals = object(), - object locals = object()); - </pre> - <dl class="function-semantics"> - <dt><b>Effects:</b> - Evaluate Python expression from <code>expression</code> in the context - specified by the dictionaries <code>globals</code> and <code>locals</code>. - </dt> - <dt><b>Returns:</b> - An instance of <a href="object.html#object-spec">object</a> - which holds the value of the expression. - </dt> - </dl> - - <h3><a name="exec-spec"></a><code>exec</code></h3> - <pre> -object exec(str code, - object globals = object(), - object locals = object()); - </pre> - <dl class="function-semantics"> - <dt><b>Effects:</b> - Execute Python source code from <code>code</code> in the context - specified by the dictionaries <code>globals</code> and <code>locals</code>. - </dt> - <dt><b>Returns:</b> - An instance of <a href="object.html#object-spec">object</a> - which holds the result of executing the code. - </dt> - </dl> - - <h3><a name="exec_file-spec"></a><code>exec_file</code></h3> - <pre> -object exec_file(str filename, - object globals = object(), - object locals = object()); - </pre> - <dl class="function-semantics"> - <dt><b>Effects:</b> - Execute Python source code from the file named by <code>filename</code> - in the context specified by the dictionaries <code>globals</code> and - <code>locals</code>. - </dt> - <dt><b>Returns:</b> - An instance of <a href="object.html#object-spec">object</a> - which holds the result of executing the code. - </dt> - </dl> - - <h2><a name="examples"></a>Examples</h2> - - <para>The following example demonstrates the use of <function>import</function> - and <function>exec</function> to define a function in python, and later call - it from within C++.</para> - -<pre> -#include <iostream> -#include <string> - -using namespace boost::python; - -void greet() -{ - // Retrieve the main module. - object main = import("__main__"); - - // Retrieve the main module's namespace - object global(main.attr("__dict__")); - - // Define greet function in Python. - object result = exec( - "def greet(): \n" - " return 'Hello from Python!' \n", - global, global); - - // Create a reference to it. - object greet = global["greet"]; - - // Call it. - std::string message = extract<std::string>(greet()); - std::cout << message << std::endl; -} -</pre> - - <para>Instead of embedding the python script into a string, - we could also store it in an a file...</para> - -<pre> -def greet(): - return 'Hello from Python!' -</pre> - <para>... and execute that instead.</para> -<pre> - // ... - // Load the greet function from a file. - object result = exec_file(script, global, global); - // ... -} -</pre> - <p>Revised 01 November, 2005</p> - - <p><i>© Copyright Stefan Seefeld 2005.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/extract.html b/libs/python/doc/v2/extract.html deleted file mode 100644 index 3c6b77f2f0..0000000000 --- a/libs/python/doc/v2/extract.html +++ /dev/null @@ -1,232 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/extract.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/extract.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#extract-spec">Class <code>extract</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#extract-spec-synopsis">Class <code>extract</code> - synopsis</a></dt> - - <dt><a href="#extract-spec-ctors">Class <code>extract</code> - constructors and destructor</a></dt> - - <dt><a href="#extract-spec-observers">Class - <code>extract</code> observer functions</a></dt> - </dl> - </dd> - </dl> - </dd> - - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>Exposes a mechanism for extracting C++ object values from - generalized Python objects. Note that - <code>extract<</code>...<code>></code> can also be used to - "downcast" an <a - href="object.html#object-spec">object</a> to some specific <a - href="ObjectWrapper.html#ObjectWrapper-concept">ObjectWrapper</a>. Because - invoking a mutable python type with an argument of the same type - (e.g. <code>list([1,2])</code> typically makes a <em>copy</em> of - the argument object, this may be the only way to access the <a - href="ObjectWrapper.html#ObjectWrapper-concept">ObjectWrapper</a>'s - interface on the original object. - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="extract-spec"></a>Class template <code>extract</code></h3> - - <p><code>extract<T></code> can be used to extract a value of - an arbitrary C++ type from an instance of <code><a - href="object.html#object-spec">object</a></code>. Two usages are supported: -<ol> -<li><b><code>extract<T>(o)</code></b> is a temporary object -which is implicitly convertible to <code>T</code> (explicit conversion -is also available through the object's function-call -operator). However, if no conversion is available which can convert -<code>o</code> to an object of type <code>T</code>, a Python -<code>TypeError</code> exception will be <a -href="definitions.html#raise">raised</a>. - -<li><b><code>extract<T> x(o);</code></b> constructs an extractor -whose <code>check()</code> member function can be used to ask whether -a conversion is available without causing an exception to be thrown. -</ol> - - <h4><a name="extract-spec-synopsis"></a>Class template <code>extract</code> - synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <class T> - struct extract - { - typedef <i>unspecified</i> result_type; - - extract(PyObject*); - extract(object const&); - - result_type operator()() const; - operator result_type() const; - - bool check() const; - }; -}} -</pre> - - <h4><a name="extract-spec-ctors"></a>Class <code>extract</code> - constructors and destructor</h4> -<pre> -extract(PyObject* p); -extract(object const&); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> The first form requires that <code>p</code> is non-null.</dt> - - <dt><b>Effects:</b>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.</dt> - </dl> - - <h4><a name="extract-spec-observers"></a>Class <code>extract</code> - observer functions</h4> -<pre> -result_type operator()() const; -operator result_type() const; -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> Converts the stored pointer to - <code>result_type</code>, which is either <code>T</code> or - <code>T const&</code>. - </dt> - - <dt><b>Returns:</b> An object of <code>result_type</code> - corresponding to the one referenced by the stored pointer.</dt> - - <dt><b>Throws:</b> <code><a - href="errors.html#error_already_set-spec">error_already_set</a></code> - and sets a <code>TypeError</code> if no such conversion is - available. May also emit other unspecified exceptions thrown by - the converter which is actually used.</dt> - </dl> - -<pre> -bool check() const; -</pre> - - <dl class="function-semantics"> - - <dt><b>Postconditions:</b> None. In particular, note that a - return value of <code>true</code> does not preclude an exception - being thrown from <code>operator result_type()</code> or - <code>operator()()</code>.</dt> - - <dt><b>Returns:</b> <code>false</code> <i>only</i> if no conversion from the - stored pointer to <code>T</code> is available.</dt> - - </dl> - - - <h2><a name="examples"></a>Examples</h2> - -<pre> -#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__")()) -} -</pre> - -The following example shows how extract can be used along with -<code><a -href="class.html#class_-spec">class_</a><</code>...<code>></code> -to create and access an instance of a wrapped C++ class. - -<pre> -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& x = extract<X&>(x_obj); - assert(x.value() == 3); -} -</pre> - <p>Revised 15 November, 2002</p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/faq.html b/libs/python/doc/v2/faq.html deleted file mode 100644 index 75283d77ce..0000000000 --- a/libs/python/doc/v2/faq.html +++ /dev/null @@ -1,861 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - FAQ</title> - </head> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Frequently Asked Questions (FAQs)</h2> - </td> - </tr> - </table> - <hr> - - <dl class="page-index"> - - <dt><a href="#funcptr">How can I wrap a function which takes a - function pointer as an argument?</a><dd> - - <dt><a href="#dangling">I'm getting the "attempt to return dangling - reference" error. What am I doing wrong?</a></dt> - - <dt><a href="#question1">Is return_internal_reference - efficient?</a></dt> - - <dt><a href="#question2">How can I wrap functions which take C++ - containers as arguments?</a></dt> - - <dt><a href="#c1204">fatal error C1204:Compiler limit:internal - structure overflow</a></dt> - - <dt><a href="#debugging">How do I debug my Python extensions?</a></dt> - - <dt><a href="#imul">Why doesn't my <code>*=</code> operator - work?</a></dt> - - <dt><a href="#macosx">Does Boost.Python work with Mac OS X?</a></dt> - - <dt><a href="#xref">How can I find the existing PyObject that holds a - C++ object?</a></dt> - - <dt><a href="#ownership">How can I wrap a function which needs to take - ownership of a raw pointer?</a></dt> - - <dt><a href="#slow_compilation">Compilation takes too much time and eats too much memory! - What can I do to make it faster?</a></dt> - - <dt><a href="#packages">How do I create sub-packages using Boost.Python?</a></dt> - - <dt><a href="#msvcthrowbug" - >error C2064: term does not evaluate to a function taking 2 arguments</a> - </dt> - - <dt><a href="#custom_string" - >How can I automatically convert my custom string type to - and from a Python string?</a></dt> - - <dt><a href="#topythonconversionfailed">Why is my automatic to-python conversion not being - found?</a></dt> - - <dt><a href="#threadsupport">Is Boost.Python thread-aware/compatible with multiple interpreters?</a></dt> - </dl> - <hr> - - <h2><a name="funcptr">How can I wrap a function which takes a - function pointer as an argument?</a></h2> - - If what you're trying to do is something like this: -<pre> -typedef boost::function<void (string s) > funcptr; - -void foo(funcptr fp) -{ - fp("hello,world!"); -} - -BOOST_PYTHON_MODULE(test) -{ - def("foo",foo) ; -} -</pre> - -And then: - -<pre> ->>> def hello(s): -... print s -... ->>> foo(hello) -hello, world! -</pre> - - The short answer is: "you can't". This is not a - Boost.Python limitation so much as a limitation of C++. The - problem is that a Python function is actually data, and the only - way of associating data with a C++ function pointer is to store it - in a static variable of the function. The problem with that is - that you can only associate one piece of data with every C++ - function, and we have no way of compiling a new C++ function - on-the-fly for every Python function you decide to pass - to <code>foo</code>. In other words, this could work if the C++ - function is always going to invoke the <em>same</em> Python - function, but you probably don't want that. - - <p>If you have the luxury of changing the C++ code you're - wrapping, pass it an <code>object</code> instead and call that; - the overloaded function call operator will invoke the Python - function you pass it behind the <code>object</code>. - - <p>For more perspective on the issue, see <a - href="http://aspn.activestate.com/ASPN/Mail/Message/1554837">this - posting</a>. - - <hr> - - <h2><a name="dangling">I'm getting the "attempt to return dangling - reference" error. What am I doing wrong?</a></h2> - That exception is protecting you from causing a nasty crash. It usually - happens in response to some code like this: -<pre> -period const& get_floating_frequency() const -{ - return boost::python::call_method<period const&>( - m_self,"get_floating_frequency"); -} -</pre> - And you get: -<pre> -ReferenceError: Attempt to return dangling reference to object of type: -class period -</pre> - - <p>In this case, the Python method invoked by <code>call_method</code> - constructs a new Python object. You're trying to return a reference to a - C++ object (an instance of <code>class period</code>) contained within - and owned by that Python object. Because the called method handed back a - brand new object, the only reference to it is held for the duration of - <code>get_floating_frequency()</code> above. When the function returns, - the Python object will be destroyed, destroying the instance of - <code>class period</code>, and leaving the returned reference dangling. - That's already undefined behavior, and if you try to do anything with - that reference you're likely to cause a crash. Boost.Python detects this - situation at runtime and helpfully throws an exception instead of letting - you do that.<br> - </p> - <hr> - - <h2><a name="question1"></a>Is return_internal_reference efficient?</h2> - - <blockquote> - <b>Q:</b> <i>I have an object composed of 12 doubles. A const& to - this object is returned by a member function of another class. From the - viewpoint of using the returned object in Python I do not care if I get - a copy or a reference to the returned object. In Boost.Python Version 2 - I have the choice of using copy_const_reference or - return_internal_reference. Are there considerations that would lead me - to prefer one over the other, such as size of generated code or memory - overhead?</i> - - <p><b>A:</b> copy_const_reference will make an instance with storage - for one of your objects, size = base_size + 12 * sizeof(double). - return_internal_reference will make an instance with storage for a - pointer to one of your objects, size = base_size + sizeof(void*). - However, it will also create a weak reference object which goes in the - source object's weakreflist and a special callback object to manage the - lifetime of the internally-referenced object. My guess? - copy_const_reference is your friend here, resulting in less overall - memory use and less fragmentation, also probably fewer total - cycles.</p> - </blockquote> - <hr> - - <h2><a name="question2"></a>How can I wrap functions which take C++ - containers as arguments?</h2> - - <p>Ralf W. Grosse-Kunstleve provides these notes:</p> - - <ol> - <li> - Using the regular <code>class_<></code> wrapper: -<pre> -class_<std::vector<double> >("std_vector_double") - .def(...) - ... - ; -</pre> - This can be moved to a template so that several types (double, int, - long, etc.) can be wrapped with the same code. This technique is used - in the file - - <blockquote> - scitbx/include/scitbx/array_family/boost_python/flex_wrapper.h - </blockquote> - in the "scitbx" package. The file could easily be modified for - wrapping std::vector<> instantiations. - - <p>This type of C++/Python binding is most suitable for containers - that may contain a large number of elements (>10000).</p> - </li> - - <li> - Using custom rvalue converters. Boost.Python "rvalue converters" - match function signatures such as: -<pre> -void foo(std::vector<double> const& array); // pass by const-reference -void foo(std::vector<double> array); // pass by value -</pre> - Some custom rvalue converters are implemented in the file - - <blockquote> - scitbx/include/scitbx/boost_python/container_conversions.h - </blockquote> - This code can be used to convert from C++ container types such as - std::vector<> or std::list<> to Python tuples and vice - versa. A few simple examples can be found in the file - - <blockquote> - scitbx/array_family/boost_python/regression_test_module.cpp - </blockquote> - Automatic C++ container <-> Python tuple conversions are most - suitable for containers of moderate size. These converters generate - significantly less object code compared to alternative 1 above. - </li> - </ol> - A disadvantage of using alternative 2 is that operators such as - arithmetic +,-,*,/,% are not available. It would be useful to have custom - rvalue converters that convert to a "math_array" type instead of tuples. - This is currently not implemented but is possible within the framework of - Boost.Python V2 as it will be released in the next couple of weeks. [ed.: - this was posted on 2002/03/10] - - <p>It would also be useful to also have "custom lvalue converters" such - as std::vector<> <-> Python list. These converters would - support the modification of the Python list from C++. For example:</p> - - <p>C++:</p> -<pre> -void foo(std::vector<double>& array) -{ - for(std::size_t i=0;i<array.size();i++) { - array[i] *= 2; - } -} -</pre> - Python: -<pre> ->>> l = [1, 2, 3] ->>> foo(l) ->>> print l -[2, 4, 6] -</pre> - Custom lvalue converters require changes to the Boost.Python core library - and are currently not available. - - <p>P.S.:</p> - - <p>The "scitbx" files referenced above are available via anonymous - CVS:</p> -<pre> -cvs -d:pserver:anonymous@cvs.cctbx.sourceforge.net:/cvsroot/cctbx login -cvs -d:pserver:anonymous@cvs.cctbx.sourceforge.net:/cvsroot/cctbx co scitbx -</pre> - <hr> - - <h2><a name="c1204"></a>fatal error C1204:Compiler limit:internal - structure overflow</h2> - - <blockquote> - <b>Q:</b> <i>I get this error message when compiling a large source - file. What can I do?</i> - - <p><b>A:</b> You have two choices:</p> - - <ol> - <li>Upgrade your compiler (preferred)</li> - - <li> - Break your source file up into multiple translation units. - - <p><code><b>my_module.cpp</b></code>:</p> -<pre> -... -void more_of_my_module(); -BOOST_PYTHON_MODULE(my_module) -{ - def("foo", foo); - def("bar", bar); - ... - more_of_my_module(); -} -</pre> - <code><b>more_of_my_module.cpp</b></code>: -<pre> -void more_of_my_module() -{ - def("baz", baz); - ... -} -</pre> - If you find that a <code><a href= - "class.html#class_-spec">class_</a><...></code> declaration - can't fit in a single source file without triggering the error, you - can always pass a reference to the <code>class_</code> object to a - function in another source file, and call some of its member - functions (e.g. <code>.def(...)</code>) in the auxilliary source - file: - - <p><code><b>more_of_my_class.cpp</b></code>:</p> -<pre> -void more_of_my_class(class<my_class>& x) -{ - x - .def("baz", baz) - .add_property("xx", &my_class::get_xx, &my_class::set_xx) - ; - - ... -} -</pre> - </li> - </ol> - </blockquote> - <hr> - - <h2><a name="debugging"></a>How do I debug my Python extensions?</h2> - - <p>Greg Burley gives the following answer for Unix GCC users:</p> - - <blockquote> - Once you have created a boost python extension for your c++ library or - class, you may need to debug the code. Afterall this is one of the - reasons for wrapping the library in python. An expected side-effect or - benefit of using BPL is that debugging should be isolated to the c++ - library that is under test, given that python code is minimal and - boost::python either works or it doesn't. (ie. While errors can occur - when the wrapping method is invalid, most errors are caught by the - compiler ;-). - - <p>The basic steps required to initiate a gdb session to debug a c++ - library via python are shown here. Note, however that you should start - the gdb session in the directory that contains your BPL my_ext.so - module.</p> -<pre> -(gdb) target exec python -(gdb) run - >>> from my_ext import * - >>> [C-c] -(gdb) break MyClass::MyBuggyFunction -(gdb) cont - >>> pyobj = MyClass() - >>> pyobj.MyBuggyFunction() -Breakpoint 1, MyClass::MyBuggyFunction ... -Current language: auto; currently c++ -(gdb) do debugging stuff -</pre> - </blockquote> - - <p>Greg's approach works even better using Emacs' "<code>gdb</code>" - command, since it will show you each line of source as you step through - it.</p> - - <p>On <b>Windows</b>, my favorite debugging solution is the debugger that - comes with Microsoft Visual C++ 7. This debugger seems to work with code - generated by all versions of Microsoft and Metrowerks toolsets; it's rock - solid and "just works" without requiring any special tricks from the - user.</p> - - <p>Raoul Gough has provided the following for gdb on Windows:</p> - - <blockquote> - - <p>gdb support for Windows DLLs has improved lately, so it is - now possible to debug Python extensions using a few - tricks. Firstly, you will need an up-to-date gdb with support - for minimal symbol extraction from a DLL. Any gdb from version 6 - onwards, or Cygwin gdb-20030214-1 and onwards should do. A - suitable release will have a section in the gdb.info file under - Configuration – Native – Cygwin Native – - Non-debug DLL symbols. Refer to that info section for more - details of the procedures outlined here.</p> - - <p>Secondly, it seems necessary to set a breakpoint in the - Python interpreter, rather than using ^C to break execution. A - good place to set this breakpoint is PyOS_Readline, which will - stop execution immediately before reading each interactive - Python command. You have to let Python start once under the - debugger, so that it loads its own DLL, before you can set the - breakpoint:</p> - -<p> -<pre> -$ gdb python -GNU gdb 2003-09-02-cvs (cygwin-special) -[...] - -(gdb) run -Starting program: /cygdrive/c/Python22/python.exe -Python 2.2.2 (#37, Oct 14 2002, 17:02:34) [MSC 32 bit (Intel)] on win32 -Type "help", "copyright", "credits" or "license" for more information. ->>> ^Z - - -Program exited normally. -(gdb) break *&PyOS_Readline -Breakpoint 1 at 0x1e04eff0 -(gdb) run -Starting program: /cygdrive/c/Python22/python.exe -Python 2.2.2 (#37, Oct 14 2002, 17:02:34) [MSC 32 bit (Intel)] on win32 -Type "help", "copyright", "credits" or "license" for more information. - -Breakpoint 1, 0x1e04eff0 in python22!PyOS_Readline () - from /cygdrive/c/WINNT/system32/python22.dll -(gdb) cont -Continuing. ->>> from my_ext import * - -Breakpoint 1, 0x1e04eff0 in python22!PyOS_Readline () - from /cygdrive/c/WINNT/system32/python22.dll -(gdb) # my_ext now loaded (with any debugging symbols it contains) -</pre> - </blockquote> - - <h3>Debugging extensions through Boost.Build</h3> - If you are launching your extension module tests with <a href= - "../../../../tools/build/v1/build_system.htm">Boost.Build</a> using the - <code>boost-python-runtest</code> rule, you can ask it to launch your - debugger for you by adding "--debugger=<i>debugger</i>" to your bjam - command-line: -<pre> -bjam -sTOOLS=vc7.1 "--debugger=devenv /debugexe" test -bjam -sTOOLS=gcc -sPYTHON_LAUNCH=gdb test -</pre> - It can also be extremely useful to add the <code>-d+2</code> option when - you run your test, because Boost.Build will then show you the exact - commands it uses to invoke it. This will invariably involve setting up - PYTHONPATH and other important environment variables such as - LD_LIBRARY_PATH which may be needed by your debugger in order to get - things to work right. - <hr> - - <h2><a name="imul"></a>Why doesn't my <code>*=</code> operator work?</h2> - - <blockquote> - <b>Q:</b> <i>I have exported my class to python, with many overloaded - operators. it works fine for me except the</i> <code>*=</code> - <i>operator. It always tells me "can't multiply sequence with non int - type". If I use</i> <code>p1.__imul__(p2)</code> <i>instead of</i> - <code>p1 *= p2</code><i>, it successfully executes my code. What's - wrong with me?</i> - - <p><b>A:</b> There's nothing wrong with you. This is a bug in Python - 2.2. You can see the same effect in Pure Python (you can learn a lot - about what's happening in Boost.Python by playing with new-style - classes in Pure Python).</p> -<pre> ->>> class X(object): -... def __imul__(self, x): -... print 'imul' -... ->>> x = X() ->>> x *= 1 -</pre> - To cure this problem, all you need to do is upgrade your Python to - version 2.2.1 or later. - </blockquote> - <hr> - - <h2><a name="macosx"></a>Does Boost.Python work with Mac OS X?</h2> - - It is known to work under 10.2.8 and 10.3 using - Apple's gcc 3.3 compiler: - <pre>gcc (GCC) 3.3 20030304 (Apple Computer, Inc. build 1493)</pre> - Under 10.2.8 get the August 2003 gcc update (free at - <a href="http://connect.apple.com/">http://connect.apple.com/</a>). - Under 10.3 get the Xcode Tools v1.0 (also free). - <p> - Python 2.3 is required. The Python that ships with 10.3 is - fine. Under 10.2.8 use these commands to install Python - as a framework: - <pre>./configure --enable-framework -make -make frameworkinstall</pre> - The last command requires root privileges because the target - directory is - <tt>/Library/Frameworks/Python.framework/Versions/2.3</tt>. - However, the installation does not interfere with the Python - version that ships with 10.2.8. - <p> - It is also crucial to increase the <tt>stacksize</tt> before - starting compilations, e.g.: - <pre>limit stacksize 8192k</pre> - If the <tt>stacksize</tt> is too small the build might crash with - internal compiler errors. - <p> - Sometimes Apple's compiler exhibits a bug by printing an error - like the following while compiling a - <tt>boost::python::class_<your_type></tt> - template instantiation: - <pre>.../inheritance.hpp:44: error: cannot - dynamic_cast `p' (of type `struct cctbx::boost_python::<unnamed>::add_pair* - ') to type `void*' (source type is not polymorphic)</pre> - - We do not know a general workaround, but if the definition of - <tt>your_type</tt> can be modified the following was found - to work in all cases encountered so far:<pre>struct your_type -{ - // before defining any member data -#if defined(__MACH__) && defined(__APPLE_CC__) && __APPLE_CC__ == 1493 - bool dummy_; -#endif - // now your member data, e.g. - double x; - int j; - // etc. -};</pre> - - <hr> - <h2><a name="xref">How can I find the existing PyObject that holds a C++ - object?</a></h2> - - <blockquote> - "I am wrapping a function that always returns a pointer to an - already-held C++ object." - </blockquote> - One way to do that is to hijack the mechanisms used for wrapping a class - with virtual functions. If you make a wrapper class with an initial - PyObject* constructor argument and store that PyObject* as "self", you - can get back to it by casting down to that wrapper type in a thin wrapper - function. For example: -<pre> -class X { X(int); virtual ~X(); ... }; -X* f(); // known to return Xs that are managed by Python objects - - -// wrapping code - -struct X_wrap : X -{ - X_wrap(PyObject* self, int v) : self(self), X(v) {} - PyObject* self; -}; - -handle<> f_wrap() -{ - X_wrap* xw = dynamic_cast<X_wrap*>(f()); - assert(xw != 0); - return handle<>(borrowed(xw->self)); -} - -... - -def("f", f_wrap()); -class_<X,X_wrap,boost::noncopyable>("X", init<int>()) - ... - ; -</pre> - Of course, if X has no virtual functions you'll have to use - <code>static_cast</code> instead of <code>dynamic_cast</code> with no - runtime check that it's valid. This approach also only works if the - <code>X</code> object was constructed from Python, because - <code>X</code>s constructed from C++ are of course never - <code>X_wrap</code> objects. - - <p>Another approach to this requires you to change your C++ code a bit; - if that's an option for you it might be a better way to go. work we've - been meaning to get to anyway. When a <code>shared_ptr<X></code> is - converted from Python, the shared_ptr actually manages a reference to the - containing Python object. When a shared_ptr<X> is converted back to - Python, the library checks to see if it's one of those "Python object - managers" and if so just returns the original Python object. So you could - just write <code>object(p)</code> to get the Python object back. To - exploit this you'd have to be able to change the C++ code you're wrapping - so that it deals with shared_ptr instead of raw pointers.</p> - - <p>There are other approaches too. The functions that receive the Python - object that you eventually want to return could be wrapped with a thin - wrapper that records the correspondence between the object address and - its containing Python object, and you could have your f_wrap function - look in that mapping to get the Python object out.</p> - - <hr> - - <h2><a name="ownership">How can I wrap a function which needs to take - ownership of a raw pointer?</a></h2> - - <blockquote> - <i>Part of an API that I'm wrapping goes something like this:</i> -<pre> -struct A {}; struct B { void add( A* ); } -where B::add() takes ownership of the pointer passed to it. -</pre> - - <p><i>However:</i></p> -<pre> -a = mod.A() -b = mod.B() -b.add( a ) -del a -del b -# python interpreter crashes -# later due to memory corruption. -</pre> - - <p><i>Even binding the lifetime of a</i> to b via - with_custodian_and_ward doesn't prevent the python object a from - ultimately trying to delete the object it's pointing to. Is there a way - to accomplish a 'transfer-of-ownership' of a wrapped C++ object?</p> - - <p><i>--Bruce Lowery</i></p> - </blockquote> - Yes: Make sure the C++ object is held by auto_ptr: -<pre> -class_<A, std::auto_ptr<A> >("A") - ... - ; -</pre> - Then make a thin wrapper function which takes an auto_ptr parameter: -<pre> -void b_insert(B& b, std::auto_ptr<A> a) -{ - b.insert(a.get()); - a.release(); -} -</pre> - Wrap that as B.add. Note that pointers returned via <code><a href= - "manage_new_object.html#manage_new_object-spec">manage_new_object</a></code> - will also be held by <code>auto_ptr</code>, so this transfer-of-ownership - will also work correctly. - - <hr> - <h2><a name="slow_compilation">Compilation takes too much time and eats too - much memory! What can I do to make it faster?</a></h2> - <p> - Please refer to the <a href="../tutorial/doc/html/python/techniques.html#python.reducing_compiling_time" - >Reducing Compiling Time</a> section in the tutorial. - </p> - - <hr> - <h2><a name="packages">How do I create sub-packages using Boost.Python?</a></h2> - <p> - Please refer to the <a href="../tutorial/doc/html/python/techniques.html#python.creating_packages" - >Creating Packages</a> section in the tutorial. - </p> - - <hr> - <h2><a name="msvcthrowbug"></a>error C2064: term does - not evaluate to a function taking 2 arguments</h2> - <font size="-1"><i>Niall Douglas provides these notes:</i></font><p> - If you see Microsoft Visual C++ 7.1 (MS Visual Studio .NET 2003) issue - an error message like the following it is most likely due to a bug - in the compiler: - <pre>boost\boost\python\detail\invoke.hpp(76): -error C2064: term does not evaluate to a function taking 2 arguments"</pre> - This message is triggered by code like the following: -<pre>#include <boost/python.hpp> - -using namespace boost::python; - -class FXThread -{ -public: - bool setAutoDelete(bool doso) throw(); -}; - -void Export_FXThread() -{ - class_< FXThread >("FXThread") - .def("setAutoDelete", &FXThread::setAutoDelete) - ; -} - </pre> - The bug is related to the <code>throw()</code> modifier. - As a workaround cast off the modifier. E.g.: -<pre> - .def("setAutoDelete", (bool (FXThread::*)(bool)) &FXThread::setAutoDelete)</pre> - <p>(The bug has been reported to Microsoft.)</p> - - <hr> - <h2><a name="custom_string"></a>How can I automatically - convert my custom string type to and from a Python string?</h2> - <font size="-1"><i>Ralf W. Grosse-Kunstleve provides these - notes:</i></font><p> - Below is a small, self-contained demo extension module that shows - how to do this. Here is the corresponding trivial test: - <pre>import custom_string -assert custom_string.hello() == "Hello world." -assert custom_string.size("california") == 10</pre> - - If you look at the code you will find: - - <ul> - <li>A custom <tt>to_python</tt> converter (easy): - <tt>custom_string_to_python_str</tt> - - <li>A custom lvalue converter (needs more code): - <tt>custom_string_from_python_str</tt> - </ul> - - The custom converters are registered in the global Boost.Python - registry near the top of the module initialization function. Once - flow control has passed through the registration code the automatic - conversions from and to Python strings will work in any module - imported in the same process. - -<pre>#include <boost/python/module.hpp> -#include <boost/python/def.hpp> -#include <boost/python/to_python_converter.hpp> - -namespace sandbox { namespace { - - class custom_string - { - public: - custom_string() {} - custom_string(std::string const& value) : value_(value) {} - std::string const& value() const { return value_; } - private: - std::string value_; - }; - - struct custom_string_to_python_str - { - static PyObject* convert(custom_string const& s) - { - return boost::python::incref(boost::python::object(s.value()).ptr()); - } - }; - - struct custom_string_from_python_str - { - custom_string_from_python_str() - { - boost::python::converter::registry::push_back( - &convertible, - &construct, - boost::python::type_id<custom_string>()); - } - - static void* convertible(PyObject* obj_ptr) - { - if (!PyString_Check(obj_ptr)) return 0; - return obj_ptr; - } - - static void construct( - PyObject* obj_ptr, - boost::python::converter::rvalue_from_python_stage1_data* data) - { - const char* value = PyString_AsString(obj_ptr); - if (value == 0) boost::python::throw_error_already_set(); - void* storage = ( - (boost::python::converter::rvalue_from_python_storage<custom_string>*) - data)->storage.bytes; - new (storage) custom_string(value); - data->convertible = storage; - } - }; - - custom_string hello() { return custom_string("Hello world."); } - - std::size_t size(custom_string const& s) { return s.value().size(); } - - void init_module() - { - using namespace boost::python; - - boost::python::to_python_converter< - custom_string, - custom_string_to_python_str>(); - - custom_string_from_python_str(); - - def("hello", hello); - def("size", size); - } - -}} // namespace sandbox::<anonymous> - -BOOST_PYTHON_MODULE(custom_string) -{ - sandbox::init_module(); -}</pre> - - <hr> - <h2><a name="topythonconversionfailed"></a - >Why is my automatic to-python conversion not being found?</h2> - <font size="-1"><i>Niall Douglas provides these notes:</i></font><p> - If you define custom converters similar to the ones - shown above the <tt>def_readonly()</tt> and <tt>def_readwrite()</tt> - member functions provided by <tt>boost::python::class_</tt> for - direct access to your member data will not work as expected. - This is because <tt>def_readonly("bar", &foo::bar)</tt> is - equivalent to: - -<pre>.add_property("bar", make_getter(&foo::bar, return_internal_reference()))</pre> - - Similarly, <tt>def_readwrite("bar", &foo::bar)</tt> is - equivalent to: - -<pre>.add_property("bar", make_getter(&foo::bar, return_internal_reference()), - make_setter(&foo::bar, return_internal_reference())</pre> - - In order to define return value policies compatible with the - custom conversions replace <tt>def_readonly()</tt> and - <tt>def_readwrite()</tt> by <tt>add_property()</tt>. E.g.: - -<pre>.add_property("bar", make_getter(&foo::bar, return_value_policy<return_by_value>()), - make_setter(&foo::bar, return_value_policy<return_by_value>()))</pre> - - <hr> - <h2><a name="threadsupport"></a - >Is Boost.Python thread-aware/compatible with multiple interpreters?</h2> - <font size="-1"><i>Niall Douglas provides these notes:</i></font><p> - The quick answer to this is: no.</p> - <p> - The longer answer is that it can be patched to be so, but it's - complex. You will need to add custom lock/unlock wrapping of every - time your code enters Boost.Python (particularly every virtual - function override) plus heavily modify - <tt>boost/python/detail/invoke.hpp</tt> with custom unlock/lock - wrapping of every time Boost.Python enters your code. You must - furthermore take care to <i>not</i> unlock/lock when Boost.Python - is invoking iterator changes via <tt>invoke.hpp</tt>.</p> - <p> - There is a patched <tt>invoke.hpp</tt> posted on the C++-SIG - mailing list archives and you can find a real implementation of all - the machinery necessary to fully implement this in the TnFOX - project at <a href="http://sourceforge.net/projects/tnfox/"> this - SourceForge project location</a>.</p> - - <hr> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 12 March, 2006 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002-2006.</i></p> - </body> -</html> diff --git a/libs/python/doc/v2/feb2002.html b/libs/python/doc/v2/feb2002.html deleted file mode 100644 index 5f15aeace2..0000000000 --- a/libs/python/doc/v2/feb2002.html +++ /dev/null @@ -1,367 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - <meta http-equiv="Content-Type" content= - "text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - February 2002 Progress Report</title> -<style type="text/css"> - :link { color: #0000ff } - :visited { color: #800080 } - p.c3 {font-style: italic} - h2.c2 {text-align: center} - h1.c1 {text-align: center} -</style> - - <table border="0" cellpadding="7" cellspacing="0" width= - "100%" summary="header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - - <td valign="top"> - <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> - - <h2 class="c2">February 2002 Progress Report</h2> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="index"> - <dt><a href="#Python10">Python10 Conference Report</a> - - <dt><a href="#progress">Boost.Python v2 Progress</a> - - <dd> - <dl class="index"> - <dt><a href="#documentation">Documentation</a> - - <dt><a href="#conversion">Overhaul of - <code>to_python</code>/<code>from_python</code> - conversion mechanism</a> - - <dt><a href="#miscellaneous">Miscellaneous</a> - </dl> - </dl> - - <h2><a name="Python10">Python10 Conference Report</a></h2> - I spent the first week of February at the Python10 conference - in Alexandria, VA. I'm including this experience report - for two reasons: firstly, it documents where my time was - used. Secondly, a public presence for Boost.Python and - interaction between the Python and C++ communities is - important to the future of Boost.Python, which in turn is - important to the Kull Project. - - <p>Andy Koenig, of all people, was the keynote speaker of - this year's opening plenary session. He presented his - "impressions of a polyglot outsider", which - studiously avoided any mention of C++ until the end of his - talk, when he was asked about standardization. I was - surprised to learn that the C++ community at large wanted a - few more years before beginning but when ANSI accepted - HP's request for a standard, the process was forced to - start: it was a matter of participating or having - standardization proceed without one's input. Andy managed - to highlight very effectively the balance of strengths in - Python, one of the most important being its support for - extension via libraries. In many ways that makes Python a - good analogue for C++ in the interpreted world - - <p>There were several kind mentions of the Boost.Python - library from people who found it indispensable. I was - particularly happy that Karl MacMillan, Michael Droettboom, - and Ichiro Fujinaga from Johns Hopkins is using it to do OCR - on a vast library of music notation, since in a previous life - I was an author of music notation software. These guys are - also drawing on Ullrich Koethe's VIGRA library for image - manipulation (Ullrich has been a major contributor to - Boost.Python). They also have a system for writing the - Boost.Python wrapper code in C++ comments, which allows them - to keep all of the code in one place. I've asked them to - send me some information on that. - - <p>The development of Swig has been gaining momentum again - (the basic description at - www.boost.org/libs/python/doc/comparisons.html still - applies). The talk given about it by David Beazly was very - well-attended, and they appear to have quite a few users. - Swig's strengths (coverage of many langauages) and - weaknesses (incomplete C++ language support) haven't - changed, although the C++ support seems to have improved - considerably - they now claim to have a complete model of the - C++ type system. It seems to be mostly geared at wrapping - what Walter Landry calls "C-Tran": C++ code which - traffics in built-in types with little use of abstraction. - I'm not knocking that, either: I'm sure a lot of that - code exists, so it's a valuable service. One feature Swig - has which I'd like to steal is the ability to unwrap a - single Python argument into multiple C++ arguments, for - example, by converting a Python string into a pointer and - length. When his talk was over, David approached me about a - possible joint workshop on language binding, which sounds - like a fun idea to me. - - <p>I spent some considerable time talking with Steven Knight, - the leader of the Scons build tool effort. We had a lot to - share with one another, and I gained a much better - appreciation for many of the Scons design decisions. Scons - seems to be concentrating on being the ultimate build system - substrate, and Steve seemed to think that we were on the - right track with our high-level design. We both hope that the - Boost.Build V2 high-level architecture can eventually be - ported to run on top of Scons. - - <p>They also have a highly-refined and successful development - procedure which I'd like to emulate for Boost.Build V2. - Among many other things they do, their source-control system - automatically ensures that when you check in a new test, it - is automatically run on the currently checked-in state of the - code, and is expected to fail -- a relatively obvious good - idea which I've never heard before. - - <p>Guido Van Rossum's "State of the Python - Union" address was full of questions for the community - about what should be done next, but the one idea Guido seemed - to stress was that core language stability and continuing - library development would be a good idea (sound familiar?) I - mentioned the Boost model as a counterpoint to the idea of - something like CPAN (the massive Perl library archives), and - it seemed to generate some significant interest. I've - offered to work with anyone from the Python community who - wants to set up something like Boost. - - <p>There was some discussion of "string - interpolation" (variable substitution in strings), and - Guido mentioned that he had some thoughts about the - strengths/weaknesses of Python's formatting interface. It - might be useful for those working on formatting for boost to - contact him and find out what he has to say. - - <p>Ka-Ping Yee demoed a Mailman discussion thread weaver. - This tool weaves the various messages in a discussion thread - into a single document so you can follow the entire - conversation. Since we're looking very seriously at - moving Boost to Mailman, this could be a really useful thing - for us to have. If we do this, we'll move the yahoogroups - discussions into the mailman archive so old discussions can - be easily accessed in the same fashion. - - <p>And, just because it's cool, though perhaps not - relevant: http://homepages.ulb.ac.be/~arigo/psyco/ is a - promising effort to accelerate the execution of Python code - to speeds approaching those of compiled languages. It - reminded me a lot of Todd Veldhuizen's research into - moving parts of C++ template compilation to runtime, only - coming from the opposite end of things. - - <h2><a name="progress">Boost.Python v2 Progress</a></h2> - Here's what actually got accomplished. - - <h3><a name="documentation">Documentation</a></h3> - - <p>My first priority upon returning from Python10 was to get - some documentation in place. After wasting an unfortunate - amount of time looking at automatic documentation tools which - don't quite work, I settled down to use Bill Kempf's - HTML templates designed to be a boost standard. While they - are working well, it is highly labor-intensive. - - <p>I decided to begin with the high-level reference material, - as opposed to tutorial, narrative, or nitty-gritty details of - the framework. It seemed more important to have a precise - description of the way the commonly-used components work than - to have examples in HTML (since we already have some test - modules), and since the low-level details are much - less-frequently needed by users it made sense for me to - simply respond to support requests for the time being. - - <p>After completing approximately 60% of the high-level docs - (currently checked in to libs/python/doc/v2), I found myself - ready to start documenting the mechanisms for creating - to-/from-python converters. This caused a dilemma: I had - realized during the previous week that a much simpler, - more-efficient, and easier-to-use implementation was - possible, but I hadn't planned on implementing it right - away, since what was already in place worked adequately. I - had also received my first query on the C++-sig about how to - write such a converter - - <p>Given the labor-intensive nature of documentation writing, - I decided it would be a bad idea to document the conversion - mechanism if I was just going to rewrite it. Often the best - impetus for simplifying a design is the realization that - understandably documenting its current state would be too - difficult, and this was no exception. - - <h3><a name="conversion">Overhaul of - <code>to_python</code>/<code>from_python</code> conversion - mechanism</a></h3> - - <p>There were two basic realizations involved here: - - <ol> - <li><code>to_python</code> conversion could be a one-step - process, once an appropriate conversion function is found. - This allows elimination of the separate indirect - convertibility check - - <li>There are basically two categories of from_python - conversions: those which lvalues stored within or held by - the Python object (essentially extractions), like what - happens when an instance of a C++ class exposed with class_ - is used as the target of a wrapped member function), and - those in which a new rvalue gets created, as when a Python - Float is converted to a C++ - <code>complex<double></code> or a Python tuple is - converted to a C++ <code>std::vector<></code>. From - the client side, there are two corresponding categories of - conversion: those which demand an lvalue conversion and - those which can accept an lvalue or an rvalue conversion. - </ol> - The latter realization allowed the following collapse, which - considerably simplified things: - - <blockquote> - <table border="1" summary="Conversion protocol"> - <tr> - <th>Target Type - - <th>Eligible Converters - - <tr> - <td><code>T</code> - - <td rowspan="5"><code>T</code> rvalue or lvalue - - <tr> - <td><code>T const</code> - - <tr> - <td><code>T volatile</code> - - <tr> - <td><code>T const volatile</code> - - <tr> - <td><code>T const&</code> - - <tr> - <td><code>T const*</code> - - <td rowspan="9"><code>T</code> lvalue - - <tr> - <td><code>T volatile*</code> - - <tr> - <td><code>T const volatile*</code> - - <tr> - <td><code>T&</code> - - <tr> - <td><code>T volatile&</code> - - <tr> - <td><code>T const volatile&</code> - - <tr> - <td><code>T* const&</code> - - <tr> - <td><code>T const* const&</code> - - <tr> - <td><code>T volatile*const&</code> - - <tr> - <td><code>T const volatile*const&</code> - </table> - </blockquote> - This job included the following additional enhancements: - - <ul> - <li>Elimination of virtual functions, which cause object - code bloat - - <li>Registration of a single converter function for all - lvalue conversions, two for all rvalue conversions - - <li>Killed lots of unneeded code - - <li>Increased opacity of registry interface - - <li>Eliminated all need for decorated runtime type - identifiers - - <li>Updated test modules to reflect new interface - - <li>Eliminated the need for users to worry about converter - lifetime issues Additional Builtin Conversion Enhancements - - <li>Support for complex<float>, - complex<double>, and complex<long double> - conversions - - <li>Support for bool conversions - - <li>NULL pointers representable by None in Python - - <li>Support for conversion of Python classic classes to - numeric types - </ul> - - <h3><a name="miscellaneous">Miscellaneous</a></h3> - These don't fit easily under a large heading: - - <ul> - <li>Support CallPolicies for class member functions - - <li>from_python_data.hpp: revamped type alignment - metaprogram so that it's fast enough for KCC - - <li>classfwd.hpp header forward-declares class_<T> - - <li>indirect_traits.hpp: - - <li>added is_pointer_to_reference - - <li>fixed bugs - - <li>Reduced recompilation dependencies - - <li>msvc_typeinfo works around broken MS/Intel typeid() - implementation - - <li>Many fixes and improvements to the type_traits library - in order to work around compiler bugs and suppress warnings - - <li>Eliminated the need for explicit acquisition of - converter registrations - - <li>Expanded constructor support to 6 arguments - - <li>Implemented generalized pointer lifetime support - - <li>Updated code generation for returning.hpp - - <li>Tracked down and fixed cycle GC bugs - - <li>Added comprehensive unit tests for destroy_reference, - pointer_type_id, select_from_python, complex<T>, - bool, and classic class instance conversions - </ul> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - - - <p class="c3">© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002. Distributed - under the Boost Software License, Version 1.0. (See accompanying file - LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</p> - diff --git a/libs/python/doc/v2/function_doc_signature.html b/libs/python/doc/v2/function_doc_signature.html deleted file mode 100644 index e439a77acb..0000000000 --- a/libs/python/doc/v2/function_doc_signature.html +++ /dev/null @@ -1,216 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright Nikolay Mladenov 2007. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> - <meta http-equiv="Content-Type" content= - "text/html; charset=us-ascii"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - - <boost/python/doobject/function_doc_signature.hpp></title> -</head> - -<body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" - summary="header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width= - "277" alt="C++ Boost" src="../../../../boost.png" border= - "0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href= - "../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/object/function_doc_signature.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#function_doc_signature_generator-spec">Class - <code>function_doc_signature_generator</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#function_doc_signature_generator-spec-synopsis">Class - <code>function_doc_signature_generator</code> synopsis</a></dt> - - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Examples</a></dt> - </dl> - <hr> - - <h2><a name="introduction" id= - "introduction"></a>Introduction</h2> - - <p>Boost.Python supports docstrings with automatic - appending of Pythonic and C++ signatures. This feature is implemented - by <code>class function_doc_signature_generator</code> - The class uses all of the overloads, supplied arg names and default values, as well as - the user-defined docstrings, to generate documentation for a given function.</p> - - <h2><a name="classes" id="classes"></a>Classes</h2> - - <h3><a name="function_doc_signature_generator-spec" id= - "function_doc_signature_generator-spec"></a>Class - <code>function_doc_signature_generator</code></h3> - - <p> - The class has only one public function which returns a list of strings documenting the - overloads of a function. - </p> - - <h4><a name="function_doc_signature_generator-spec-synopsis" id= - "function_doc_signature_generator-spec-synopsis"></a>Class - <code>function_doc_signature_generator</code> synopsis</h4> - <pre> -namespace boost { namespace python { namespace objects { - - class function_doc_signature_generator - { - public: - static list function_doc_signatures(function const *f); - }; - -}}} -</pre> - - - <h2><a name="examples" id="examples"></a>Examples</h2> - - <h4>Docstrings generated with <code>function_doc_signature_generator</code></h4> - <pre> -#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/raw_function.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) - - -struct X -{ - tuple f(int x = 1, double y = 4.25, char const* z = "wow") - { - return make_tuple(x, y, z); - } -}; - -BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(X_f_overloads, X::f, 0, 3) - -tuple raw_func(tuple args, dict kw) -{ - return make_tuple(args, kw); -} - -BOOST_PYTHON_MODULE(args_ext) -{ - def("f", f, (arg("x")=1, arg("y")=4.25, arg("z")="wow") - , "This is f's docstring" - ); - - def("raw", raw_function(raw_func)); - - def("f1", f, f_overloads("f1's docstring", args("x", "y", "z"))); - - - class_<X>("X", "This is X's docstring", init<>(args("self"))) - .def("f", &X::f - , "This is X.f's docstring" - , args("self","x", "y", "z")) - - ; - -} - -</pre> -Python code: - <pre> ->>> import args_ext ->>> help(args_ext) -Help on module args_ext: - -NAME - args_ext - -FILE - args_ext.pyd - -CLASSES - Boost.Python.instance(__builtin__.object) - X - - class X(Boost.Python.instance) - | This is X's docstring - | - | Method resolution order: - | X - | Boost.Python.instance - | __builtin__.object - | - | Methods defined here: - | - | __init__(...) - | __init__( (object)self) -> None : - | C++ signature: - | void __init__(struct _object *) - | - | f(...) - | f( (X)self, (int)x, (float)y, (str)z) -> tuple : This is X.f's docstring - | C++ signature: - | class boost::python::tuple f(struct X {lvalue},int,double,char const *) - | - | ................. - | -FUNCTIONS - f(...) - f([ (int)x=1 [, (float)y=4.25 [, (str)z='wow']]]) -> tuple : This is f's docstring - C++ signature: - class boost::python::tuple f([ int=1 [,double=4.25 [,char const *='wow']]]) - - f1(...) - f1([ (int)x [, (float)y [, (str)z]]]) -> tuple : f1's docstring - C++ signature: - class boost::python::tuple f1([ int [,double [,char const *]]]) - - raw(...) - object raw(tuple args, dict kwds) : - C++ signature: - object raw(tuple args, dict kwds) - - -</pre> - - <p><i>© Copyright <a href="mailto:nickm at sitius dot com">Nikolay Mladenov</a> 2007.</i></p> -</body> -</html> diff --git a/libs/python/doc/v2/handle.html b/libs/python/doc/v2/handle.html deleted file mode 100644 index b20d94a1ff..0000000000 --- a/libs/python/doc/v2/handle.html +++ /dev/null @@ -1,336 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/handle.hpp></title> - - <style type="text/css"> - p.c4 {font-style: italic} - span.c3 {color: #ff0000} - h2.c2 {text-align: center} - h1.c1 {text-align: center} - </style> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> - - <h2 class="c2">Header <boost/python/handle.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#handle-spec">Class template - <code>handle</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#handle-spec-synopsis">Class <code>handle</code> - synopsis</a></dt> - - <dt><a href="#handle-spec-ctors">Class <code>handle</code> - constructors and destructor</a></dt> - - <dt><a href="#handle-spec-modifiers">Class <code>handle</code> - modifier functions</a></dt> - - <dt><a href="#handle-spec-observers">Class <code>handle</code> - observer functions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#borrowed-spec"><code>borrowed</code></a></dt> - - <dt><a href="#allow_null-spec"><code>allow_null</code></a></dt> - </dl> - </dd> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><boost/python/handle.hpp></code> provides - <code>class template handle</code>, a smart pointer for - managing reference-counted Python objects.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="handle-spec"></a>Class template <code>handle</code></h3> - - <p><code>handle</code> is a smart pointer to a Python object type; it - holds a pointer of type <code>T*</code>, where T is its template - parameter. <code>T</code> must be either a type derived from - <code>PyObject</code> or a <a href="definitions.html#POD">POD</a> type - whose initial <code>sizeof(PyObject)</code> bytes are layout-compatible - with <code>PyObject</code>. Use <code>handle<></code> at the - boundary between the Python/'C' API and high-level code; prefer <code><a - href="object.html#object-spec">object</a></code> for a generalized - interface to Python objects.</p> - - <p><a name="upcast"></a>In this document, the term "upcast" refers to an - operation which converts a pointer <code>Y*</code> to a base class - pointer <code>T*</code> via <code>static_cast<T*></code> if - <code>Y</code> is derived from <code>T</code>, or via C-style cast - <code>(T*)</code> if it is not. However, in the latter case the "upcast" - is ill-formed if the initial <code>sizeof(PyObject)</code> bytes of - <code>Y</code> are not layout-compatible with <code>PyObject</code>.</p> - - <h4><a name="handle-spec-synopsis"></a>Class template handle - synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <class T> - class handle - { - typedef <i>unspecified-member-function-pointer</i> bool_type; - - public: // types - typedef T element_type; - - public: // member functions - ~handle(); - - template <class Y> - explicit handle(detail::borrowed<null_ok<Y> >* p); - - template <class Y> - explicit handle(null_ok<detail::borrowed<Y> >* p); - - template <class Y> - explicit handle(detail::borrowed<Y>* p); - - template <class Y> - explicit handle(null_ok<Y>* p); - - template <class Y> - explicit handle(Y* p); - - handle(); - - handle& operator=(handle const& r); - - template<typename Y> - handle& operator=(handle<Y> const & r); // never throws - - - template <typename Y> - handle(handle<Y> const& r); - - handle(handle const& r); - - T* operator-> () const; - T& operator* () const; - T* get() const; - void reset(); - T* release(); - - operator bool_type() const; // never throws - private: - T* m_p; - }; - - template <class T> struct null_ok; - namespace detail { template <class T> struct borrowed; } -}} -</pre> - - <h4><a name="handle-spec-ctors">Class <code>handle</code> constructors - and destructor</a></h4> -<pre> -virtual ~handle(); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - <code>Py_XDECREF(</code><i>upcast</i><code><PyObject*>(m_p))</code></dt> - </dl> -<pre> -template <class Y> -explicit handle(detail::borrowed<null_ok<Y> >* p); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - <code>Py_XINCREF(</code><i>upcast</i><code><PyObject*>(p)); - m_p = </code><i>upcast</i><code><T*>(p);</code></dt> - </dl> -<pre> -template <class Y> -explicit handle(null_ok<detail::borrowed<Y> >* p); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - <code>Py_XINCREF(</code><i>upcast</i><code><PyObject*>(p)); - m_p = </code><i>upcast</i><code><T*>(p);</code></dt> - </dl> -<pre> -template <class Y> -explicit handle(detail::borrowed<Y>* p); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - <code>Py_XINCREF(</code><i>upcast</i><code><PyObject*>(p)); - m_p = </code><i>upcast</i><code><T*>(<a href= - "errors.html#expect_non_null-spec">expect_non_null</a>(p));</code></dt> - </dl> -<pre> -template <class Y> -explicit handle(null_ok<Y>* p); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - <code>m_p = </code><i>upcast</i><code><T*>(p);</code></dt> - </dl> -<pre> -template <class Y> -explicit handle(Y* p); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - <code>m_p = </code><i>upcast</i><code><T*>(<a href= - "errors.html#expect_non_null-spec">expect_non_null</a>(p));</code></dt> - </dl> -<pre> -handle(); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> <code>m_p = 0;</code></dt> - </dl> -<pre> -template <typename Y> -handle(handle<Y> const& r); -handle(handle const& r); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - <code>m_p = r.m_p; Py_XINCREF(</code><i>upcast</i><code><PyObject*>(m_p));</code></dt> - </dl> - - <h4><a name="handle-spec-modifiers">Class <code>handle</code> - modifiers</a></h4> -<pre> -handle& operator=(handle const& r); -template<typename Y> -handle& operator=(handle<Y> const & r); // never throws -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - <code>Py_XINCREF(</code><i>upcast</i><code><PyObject*>(r.m_p)); Py_XDECREF(</code><i> - upcast</i><code><PyObject*>(m_p)); m_p = r.m_p;</code></dt> - </dl> -<pre> -T* release(); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> <code>T* x = m_p; m_p = 0;return - x;</code></dt> - </dl> -<pre> -void reset(); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - <code>*this = handle<T>();</code></dt> - </dl> - - <h4><a name="handle-spec-observers">Class <code>handle</code> - observers</a></h4> -<pre> -T* operator-> () const; -T* get() const; -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> <code>m_p;</code></dt> - </dl> -<pre> -T& operator* () const; -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> <code>*m_p;</code></dt> - </dl> -<pre> -operator bool_type() const; // never throws -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> 0 if <code>m_p == 0</code>, a pointer - convertible to <code>true</code> otherwise.</dt> - </dl> - - <h2><a name="functions"></a>Functions</h2> - - <h3><a name="borrowed-spec"></a><code>borrowed</code></h3> -<pre> -template <class T> -detail::borrowed<T>* borrowed(T* p) -{ - return (detail::borrowed<T>*)p; -} -</pre> - - <h3><a name="allow_null-spec"></a><code>allow_null</code></h3> -<pre> -template <class T> -null_ok<T>* allow_null(T* p) -{ - return (null_ok<T>*)p; -} -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p class="c4">© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002 -.</p> - </body> -</html> - diff --git a/libs/python/doc/v2/has_back_reference.html b/libs/python/doc/v2/has_back_reference.html deleted file mode 100644 index 29b81506cd..0000000000 --- a/libs/python/doc/v2/has_back_reference.html +++ /dev/null @@ -1,225 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/has_back_reference.hpp></title> - - <style type="text/css"> - p.c3 {font-style: italic} - h2.c2 {text-align: center} - h1.c1 {text-align: center} - </style> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> - - <h2 class="c2">Header - <boost/python/has_back_reference.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#has_back_reference-spec">Class template - <code>has_back_reference</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#has_back_reference-spec-synopsis">Class template - <code>has_back_reference</code> synopsis</a></dt> - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - </dd> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><boost/python/has_back_reference.hpp></code> defines the - predicate metafunction <code>has_back_reference<></code>, which can - be specialized by the user to indicate that a wrapped class instance - holds a <code>PyObject*</code> corresponding to a Python object.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="has_back_reference-spec"></a>Class template - <code>has_back_reference</code></h3> - - <p>A unary metafunction whose <code>value</code> is true iff its argument - is a <code>pointer_wrapper<></code>.</p> - - <h4><a name="has_back_reference-spec-synopsis"></a>Class template - <code>has_back_reference</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template<class WrappedClass> class has_back_reference - { - typedef mpl::false_ type; - }; -}} -</pre> - <p>A "<a href="../../../mpl/doc/refmanual/metafunction.html"> - metafunction</a>" that is inspected by Boost.Python to determine how - wrapped classes can be constructed.</p> - - <dl class="traits-semantics"> - <dt><code>type::value</code> is an integral constant convertible to bool - of unspecified type.</dt> - - <dt>Specializations may substitute a <code>true</code>-valued integral constant wrapper for - <code>type</code> iff for each invocation of - <code>class_<WrappedClass>::def(init<</code> - <i>type-sequence...</i><code>>())</code> and the implicitly wrapped - copy constructor (unless it is <a href="class.html#class_-spec"> - noncopyable</a>), there exists a corresponding constructor - <code>WrappedClass::WrappedClass(PyObject*, </code> - <i>type-sequence...</i><code>)</code>. If such a specialization exists, - the <code>WrappedClass</code> constructors will be called with a "back - reference" pointer to the corresponding Python object whenever they are - invoked from Python. The easiest way to provide this nested <code> -type -</code> - is to - derive the specialization from <code>mpl::true_</code>. - </dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - - <h3>C++ module definition</h3> -<pre> -#include <boost/python/class.hpp> -#include <boost/python/module.hpp> -#include <boost/python/has_back_reference.hpp> -#include <boost/python/handle.hpp> -#include <boost/shared_ptr.hpp> - -using namespace boost::python; -using boost::shared_ptr; - -struct X -{ - X(PyObject* self) : m_self(self), m_x(0) {} - X(PyObject* self, int x) : m_self(self), m_x(x) {} - X(PyObject* self, X const& other) : m_self(self), m_x(other.m_x) {} - - handle<> self() { return handle<>(borrowed(m_self)); } - int get() { return m_x; } - void set(int x) { m_x = x; } - - PyObject* m_self; - int m_x; -}; - -// specialize has_back_reference for X -namespace boost { namespace python -{ - template <> - struct has_back_reference<X> - : mpl::true_ - {}; -}} - -struct Y -{ - Y() : m_x(0) {} - Y(int x) : m_x(x) {} - int get() { return m_x; } - void set(int x) { m_x = x; } - - int m_x; -}; - -shared_ptr<Y> -Y_self(shared_ptr<Y> self) { return self; } - -BOOST_PYTHON_MODULE(back_references) -{ - class_<X>("X") - .def(init<int>()) - .def("self", &X::self) - .def("get", &X::get) - .def("set", &X::set) - ; - - class_<Y, shared_ptr<Y> >("Y") - .def(init<int>()) - .def("get", &Y::get) - .def("set", &Y::set) - .def("self", Y_self) - ; -} -</pre> - The following Python session illustrates that <code>x.self()</code> - returns the same Python object on which it is invoked, while - <code>y.self()</code> must create a new Python object which refers to the - same Y instance. - - <h3>Python code</h3> -<pre> ->>> from back_references import * ->>> x = X(1) ->>> x2 = x.self() ->>> x2 is x -<b>1</b> ->>> (x.get(), x2.get()) -(1, 1) ->>> x.set(10) ->>> (x.get(), x2.get()) -(10, 10) ->>> ->>> ->>> y = Y(2) ->>> y2 = y.self() ->>> y2 is y -<b>0</b> ->>> (y.get(), y2.get()) -(2, 2) ->>> y.set(20) ->>> (y.get(), y2.get()) -(20, 20) -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 18 July, 2004 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p class="c3">© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002 -.</p> - </body> -</html> - diff --git a/libs/python/doc/v2/implicit.html b/libs/python/doc/v2/implicit.html deleted file mode 100644 index e9d5cac583..0000000000 --- a/libs/python/doc/v2/implicit.html +++ /dev/null @@ -1,163 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/implicit.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/implicit.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#implicitly_convertible-spec">Function Template - <code>implicitly_convertible</code></a></dt> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - <code>implicitly_convertible</code> allows Boost.Python to implicitly - take advantage of a C++ implicit or explicit conversion when matching - Python objects to C++ argument types. - - <h2><a name="functions"></a>Functions</h2> - - <h3><a name="implicitly_convertible-spec"></a>Function template - <code>implicitly_convertible</code></h3> -<pre> -template <class Source, class Target> -void implicitly_convertible(); -</pre> - - <table border="1" summary="implicitly_convertible template parameters"> - <caption> - <b><code>implicitly_convertible</code> template parameters</b><br> - </caption> - - <tr> - <th>Parameter</th> - - <th>Description</th> - </tr> - - <tr> - <td><code>Source</code></td> - - <td>The source type of the implicit conversion</td> - </tr> - - <tr> - <td><code>Target</code></td> - - <td>The target type of the implicit conversion</td> - </tr> - </table> - - <dl class="function-semantics"> - <dt><b>Requires:</b> The declaration <code>Target t(s);</code>, where - <code>s</code> is of type <code>Source</code>, is valid.</dt> - - <dt><b>Effects:</b> registers an rvalue <code>from_python</code> - converter to <code>Target</code> which can succeed for any - <code>PyObject* p</code> iff there exists any registered converter - which can produce <code>Source</code> rvalues</dt> - - <dt><b>Rationale:</b> C++ users expect to be able to take advantage of - the same sort of interoperability in Python as they do in C++.</dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - - <h3>C++ module definition</h3> -<pre> -#include <boost/python/class.hpp> -#include <boost/python/implicit.hpp> -#include <boost/python/module.hpp> - -using namespace boost::python; - -struct X -{ - X(int x) : v(x) {} - operator int() const { return v; } - int v; -}; - -int x_value(X const& x) -{ - return x.v; -} - -X make_x(int n) { return X(n); } - -BOOST_PYTHON_MODULE(implicit_ext) -{ - def("x_value", x_value); - def("make_x", make_x); - - class_<X>("X", - init<int>()) - ; - - implicitly_convertible<X,int>(); - implicitly_convertible<int,X>(); -} -</pre> - - <h3>Python code</h3> -<pre> ->>> from implicit_ext import * ->>> x_value(X(42)) -42 ->>> x_value(42) -42 ->>> x = make_x(X(42)) ->>> x_value(x) -42 -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/import.html b/libs/python/doc/v2/import.html deleted file mode 100644 index 15c1c68c55..0000000000 --- a/libs/python/doc/v2/import.html +++ /dev/null @@ -1,90 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/import.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/import.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#import-spec"><code>import</code></a></dt> - </dl> - </dd> - <dt><a href="#examples">Examples</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>Exposes a mechanism for importing python modules.</p> - - <h2><a name="functions"></a>Functions</h2> - - <h3><a name="import-spec"></a><code>import</code></h3> - <pre> -object import(str name); - </pre> - <dl class="function-semantics"> - <dt><b>Effects:</b> Imports the module named by <code>name</code>.</dt> - <dt><b>Returns:</b> An instance of <a href="object.html#object-spec">object</a> - which holds a reference to the imported module.</dt> - </dl> - - <h2><a name="examples"></a>Examples</h2> - - <para>The following example demonstrates the use of <function>import</function> - to access a function in python, and later call it from within C++.</para> - -<pre> -#include <iostream> -#include <string> - -using namespace boost::python; - -void print_python_version() -{ - // Load the sys module. - object sys = import("sys"); - - // Extract the python version. - std::string version = extract<std::string>(sys.attr("version")); - std::cout << version << std::endl; -} -</pre> - <p>Revised 01 November, 2005</p> - - <p><i>© Copyright Stefan Seefeld 2005.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/index.html b/libs/python/doc/v2/index.html deleted file mode 100644 index 92593d06e7..0000000000 --- a/libs/python/doc/v2/index.html +++ /dev/null @@ -1,20 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="refresh" content="0; URL=../index.html"> - - <title></title> - </head> - - <body> - Loading index page; if nothing happens, please go to <a href= - "../index.html">../index.html</a>. - </body> -</html> - diff --git a/libs/python/doc/v2/indexing.html b/libs/python/doc/v2/indexing.html deleted file mode 100644 index 72c999c419..0000000000 --- a/libs/python/doc/v2/indexing.html +++ /dev/null @@ -1,695 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st February 2003), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - <title> - Indexing Support - </title> - </head> - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" - summary="header"> - <tr> - <td valign="top" width="300"> - <h3> - <a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border= - "0"></a> - </h3> - </td> - <td valign="top"> - <h1 align="center"> - <a href="../index.html">Boost.Python</a> - </h1> - - <h2> Headers <boost/python/indexing/indexing_suite.hpp><br> - <boost/python/indexing/vector_indexing_suite.hpp></h2> - </td> - </tr> - </table> - <hr> - <h2> - Contents - </h2> - <dl class="page-index"> - <dt> - <a href="#introduction">Introduction</a> - </dt> - <dt> - <a href="#interface">Interface</a> - </dt> - <dd> - <dl class="page-index"> - <dt> - <a href="#indexing_suite">indexing_suite</a> - </dt> - <dt> - <a href="#indexing_suite_subclasses">indexing_suite - sub-classes</a> - </dt> - <dd> - <dl class="page-index"> - <dt> - <a href="#vector_indexing_suite">vector_indexing_suite</a> - </dt> - </dl> - </dd> - </dl> - </dd> - </dl> - <dl> - <dt> - <a href="#indexing_suite_class">indexing_suite class</a> - </dt> - <dt> - <a href="#vector_indexing_suite_class">vector_indexing_suite - class<br> - </a><a href="#map_indexing_suite_class">map_indexing_suite class</a> </dt> - </dl> - <hr> - <h2> - <a name="introduction" id="introduction"></a>Introduction - </h2> - <p> - Indexing is a Boost Python facility for easy exportation of indexable - C++ containers to Python. Indexable containers are containers that - allow random access through the operator[] (e.g. std::vector). - </p> - <p> - While Boost Python has all the facilities needed to expose indexable - C++ containers such as the ubiquitous std::vector to Python, the - procedure is not as straightforward as we'd like it to be. Python - containers do not map easily to C++ containers. Emulating Python - containers in C++ (see Python Reference Manual, <a href= - "http://www.python.org/doc/current/ref/sequence-types.html">Emulating - container types</a>) using Boost Python is non trivial. There are a lot - of issues to consider before we can map a C++ container to Python. - These involve implementing wrapper functions for the methods - <strong>__len__</strong>, <strong>__getitem__</strong>, - <strong>__setitem__</strong>, <strong>__delitem__,</strong> - <strong>__iter__</strong> and <strong>__contains</strong>. - </p> - <p> - The goals: - </p> - <ul> - <li> - <div> - Make indexable C++ containers behave exactly as one would expect a - Python container to behave. - </div> - </li> - <li> - Provide default reference semantics for container element indexing - (<tt>__getitem__</tt>) such that <tt>c[i]</tt> can be mutable. - Require: - <div> - <pre> - val = c[i] - c[i].m() - val == c[i] - </pre> - </div>where <tt>m</tt> is a non-const (mutating) member function - (method). - </li> - <li> - Return safe references from <tt>__getitem__</tt> such that subsequent - adds and deletes to and from the container will not result in - dangling references (will not crash Python). - </li> - <li> - Support slice indexes. - </li> - <li> - Accept Python container arguments (e.g. lists, tuples) wherever - appropriate. - </li> - <li> - Allow for extensibility through re-definable policy classes. - </li> - <li> - Provide predefined support for the most common STL and STL like - indexable containers. - </li> - </ul> - <hr> - -<h2> <a name="interface"></a>The Boost.Python Indexing Interface</h2> -<h3> <a name="indexing_suite"></a>indexing_suite [ Header <boost/python/indexing/indexing_suite.hpp> - ]</h3> - <p> - The <tt>indexing_suite</tt> class is the base class for the - management of C++ containers intended to be integrated to Python. The - objective is make a C++ container look and feel and behave exactly as - we'd expect a Python container. The class automatically wraps these - special Python methods (taken from the Python reference: <a href= - "http://www.python.org/doc/current/ref/sequence-types.html">Emulating - container types</a>): - </p> - <dl> - <dd> - <dl> - <dt> - <b><a name="l2h-126"><tt class= - "method">__len__</tt></a></b>(<var>self</var>) - </dt> - <dd> - Called to implement the built-in function <tt class= - "function">len()</tt><a name="l2h-134"> </a> Should return - the length of the object, an integer <code>>=</code> 0. Also, - an object that doesn't define a <tt class= - "method">__nonzero__()</tt> method and whose <tt class= - "method">__len__()</tt> method returns zero is considered to be - false in a Boolean context. <a name="l2h-128"> </a> - </dd> - </dl> - <dl> - <dt> - <b><a name="l2h-129"><tt class= - "method">__getitem__</tt></a></b>(<var>self, key</var>) - </dt> - <dd> - Called to implement evaluation of - <code><var>self</var>[<var>key</var>]</code>. For sequence types, - the accepted keys should be integers and slice - objects.<a name="l2h-135"> </a> Note that the special - interpretation of negative indexes (if the class wishes to - emulate a sequence type) is up to the <tt class= - "method">__getitem__()</tt> method. If <var>key</var> is of - an inappropriate type, <tt class="exception">TypeError</tt> - may be raised; if of a value outside the set of indexes for - the sequence (after any special interpretation of negative - values), <tt class="exception">IndexError</tt> should be - raised. <span class="note"><b class="label">Note:</b> - <tt class="keyword">for</tt> loops expect that an <tt class= - "exception">IndexError</tt> will be raised for illegal - indexes to allow proper detection of the end of the - sequence.</span> - </dd> - </dl> - <dl> - <dt> - <b><a name="l2h-130"><tt class= - "method">__setitem__</tt></a></b>(<var>self, key, value</var>) - </dt> - <dd> - Called to implement assignment to - <code><var>self</var>[<var>key</var>]</code>. Same note as for - <tt class="method">__getitem__()</tt>. This should only be - implemented for mappings if the objects support changes to the - values for keys, or if new keys can be added, or for sequences if - elements can be replaced. The same exceptions should be raised - for improper <var>key</var> values as for the <tt class= - "method">__getitem__()</tt> method. - </dd> - </dl> - <dl> - <dt> - <b><a name="l2h-131"><tt class= - "method">__delitem__</tt></a></b>(<var>self, key</var>) - </dt> - <dd> - Called to implement deletion of - <code><var>self</var>[<var>key</var>]</code>. Same note as for - <tt class="method">__getitem__()</tt>. This should only be - implemented for mappings if the objects support removal of keys, - or for sequences if elements can be removed from the sequence. - The same exceptions should be raised for improper <var>key</var> - values as for the <tt class="method">__getitem__()</tt> method. - </dd> - </dl> - <dl> - <dt> - <b><a name="l2h-132"><tt class= - "method">__iter__</tt></a></b>(<var>self</var>) - </dt> - <dd> - This method is called when an iterator is required for a - container. This method should return a new iterator object that - can iterate over all the objects in the container. For mappings, - it should iterate over the keys of the container, and should also - be made available as the method <tt class= - "method">iterkeys()</tt>. - <p> - Iterator objects also need to implement this method; they are - required to return themselves. For more information on iterator - objects, see ``<a class="ulink" href= - "http://www.python.org/doc/current/lib/typeiter.html">Iterator - Types</a>'' in the <em class="citetitle"><a href= - "http://www.python.org/doc/current/lib/lib.html" title= - "Python Library Reference">Python Library Reference</a></em>. - </p> - </dd> - </dl> - <dl> - <dt> - <b><a name="l2h-133"><tt class= - "method">__contains__</tt></a></b>(<var>self, item</var>) - </dt> - <dd> - Called to implement membership test operators. Should return true - if <var>item</var> is in <var>self</var>, false otherwise. For - mapping objects, this should consider the keys of the mapping - rather than the values or the key-item pairs. - </dd> - </dl> - </dd> - </dl> - -<h3> <a name="indexing_suite_subclasses"></a>indexing_suite sub-classes</h3> - <p> - The <tt>indexing_suite</tt> is not meant to be used as is. A couple of - policy functions must be supplied by subclasses of - <tt>indexing_suite</tt>. However, a set of <tt>indexing_suite</tt> - subclasses for the standard indexable STL containers will be provided, - In most cases, we can simply use the available predefined suites. In - some cases, we can refine the predefined suites to suit our needs. - </p> - -<h3> <a name="vector_indexing_suite"></a>vector_indexing_suite [ Header <boost/python/indexing/vector_indexing_suite.hpp> - ] </h3> -<p> - The <tt>vector_indexing_suite</tt> class is a predefined - <tt>indexing_suite</tt> derived class designed to wrap - <tt>std::vector</tt> (and <tt>std::vector</tt> like [i.e. a class with - std::vector interface]) classes. It provides all the policies required by the - <tt>indexing_suite</tt>. - </p> - <p> - Example usage: - </p> - <pre> - class X {...}; - ... - - class_<std::vector<X> >("XVec") - .def(vector_indexing_suite<std::vector<X> >()) - ; -</pre> - <p> - <tt>XVec</tt> is now a full-fledged Python container (see the - <a href="../../test/vector_indexing_suite.cpp">example in full</a>, - along with its <a href="../../test/vector_indexing_suite.py">python - test</a>). -</p> - <h3><a name="map_indexing_suite" id="map_indexing_suite"></a>map_indexing_suite [ Header <boost/python/indexing/map_indexing_suite.hpp> ] </h3> - <p> The <tt>map_indexing_suite</tt> class is a predefined <tt>indexing_suite</tt> derived class designed to wrap <tt>std::map</tt> (and <tt>std::map</tt> like [i.e. a class with std::map interface]) classes. It provides all the policies required by the <tt>indexing_suite</tt>. </p> - <p> Example usage: </p> - <pre> - class X {...}; - ... - - class_<std::map<X> >("XMap") - .def(map_indexing_suite<std::map<X> >()) - ; -</pre> - <p> By default indexed elements are returned by proxy. This can be disabled by supplying <tt>true</tt> in the NoProxy template parameter. <tt>XMap</tt> is now a full-fledged Python container (see the <a href="../../test/map_indexing_suite.cpp">example in full</a>, along with its <a href="../../test/map_indexing_suite.py">python test</a>).</p> - <hr> - <h2> - <a name="indexing_suite_class"></a>indexing_suite class </h2> - <h2> <tt>indexing_suite<<br> - </tt><tt>class Container<br> - , class DerivedPolicies<font color="#007F00"><br> - </font></tt> <tt>, - bool NoProxy<br> - , - bool NoSlice<br> - </tt><tt>, class Data<br> - , class Index<br> - </tt><tt>, class Key</tt></h2> - <table width="100%" border="1"> - <tr> - <td> - <strong>Template Parameter</strong><br> - </td> - <td> - <strong>Requirements</strong> - </td> - <td> - <strong>Semantics</strong> - </td> - <td> - <strong>Default</strong> - </td> - </tr> - <tr> - <td> - <font color="#007F00"><tt>Container</tt></font> - </td> - <td> - A class type - </td> - <td> - The container type to be wrapped to Python. - </td> - <td> - - </td> - </tr> - <tr> - <td> - <font color="#007F00"><tt>DerivedPolicies</tt></font> - </td> - <td> - A subclass of indexing_suite - </td> - <td> - Derived classes provide the policy hooks. See <a href= - "#DerivedPolicies">DerivedPolicies</a> below. - </td> - <td> - - </td> - </tr> - <tr> - <td> <font color="#007F00"><tt>NoProxy</tt></font> </td> - <td> A boolean </td> - <td> By default indexed elements have Python reference semantics and are returned by proxy. This can be disabled by supplying <strong>true</strong> in the <tt>NoProxy</tt> template parameter. </td> - <td> false </td> - </tr> - <tr> - <td> - <font color="#007F00"><tt>NoSlice</tt></font> - </td> - <td> - A boolean - </td> - <td> - Do not allow slicing. </td> - <td> - false - </td> - </tr> - <tr> - <td> - <font color="#007F00"><tt>Data</tt></font> - </td> - <td> - - </td> - <td> - The container's data type. - </td> - <td> - <tt>Container::value_type</tt> - </td> - </tr> - <tr> - <td> <font color="#007F00"><tt>Index</tt></font> </td> - <td> </td> - <td> The container's index type. </td> - <td> <tt>Container::size_type</tt> </td> - </tr> - <tr> - <td> - <font color="#007F00"><tt>Key</tt></font> - </td> - <td> - - </td> - <td> - The container's key type. - </td> - <td> - <tt>Container::value_type</tt> - </td> - </tr> - </table> - <pre> - template <<br> class Container - , class DerivedPolicies - , bool NoProxy = false<br> , bool NoSlice = false - , class Data = typename Container::value_type - , class Index = typename Container::size_type - , class Key = typename Container::value_type - ><br> class indexing_suite - : unspecified - { - public: - - indexing_suite(); // default constructor - } - </pre> - <h2> - <tt><a name="DerivedPolicies"></a>DerivedPolicies</tt> - </h2> - <dl> - <dd> - Derived classes provide the hooks needed by - the <tt>indexing_suite:</tt> - </dd> - </dl> - <pre> data_type& - get_item(Container& container, index_type i); - - static object - get_slice(Container& container, index_type from, index_type to); - - static void - set_item(Container& container, index_type i, data_type const& v); - - static void - set_slice( - Container& container, index_type from, - index_type to, data_type const& v - ); - - template <class Iter> - static void<br> set_slice(Container& container, index_type from, - index_type to, Iter first, Iter last - ); - - static void - delete_item(Container& container, index_type i); - - static void - delete_slice(Container& container, index_type from, index_type to); - - static size_t - size(Container& container); - - template <class T> - static bool - contains(Container& container, T const& val); - - static index_type - convert_index(Container& container, PyObject* i); - - static index_type - adjust_index(index_type current, index_type from, - index_type to, size_type len - ); -</pre> - <blockquote> - <p> - Most of these policies are self explanatory. <tt>However, - <strong>convert_index</strong></tt> and - <tt><strong>adjust_index</strong></tt> deserve some explanation. - </p> - <p> - <strong><tt>convert_index</tt></strong> converts a Python index into - a C++ index that the container can handle. For instance, negative - indexes in Python, by convention, start counting from the right(e.g. - <tt>C[-1]</tt> indexes the rightmost element in <tt>C</tt>). - <strong><tt>convert_index</tt></strong> should handle the necessary - conversion for the C++ container (e.g. convert <tt>-1</tt> to - <tt>C.size()-1</tt>). <tt><strong>convert_index</strong></tt> should - also be able to convert the type of the index (A dynamic Python type) - to the actual type that the C++ container expects. - </p> - <p> - When a container expands or contracts, held indexes to its elements - must be adjusted to follow the movement of data. For instance, if we - erase 3 elements, starting from index 0 from a 5 element vector, what - used to be at index 4 will now be at index 1: - </p> - <pre> - [a][b][c][d][e] ---> [d][e] - ^ ^ - 4 1 -</pre> - <p> - <strong><tt>adjust_index</tt></strong> takes care of the adjustment. - Given a current index, the function should return the adjusted index - when data in the container at index <tt>from</tt>..<tt>to</tt> is - replaced by <tt>len</tt> elements. - </p> - </blockquote> - <div> - <hr> - <h2> - <a name="vector_indexing_suite_class"></a>vector_indexing_suite class - </h2> - <h3> - Class template <tt><br> - vector_indexing_suite<<br> - class <font color="#007F00">Container</font><br> - , bool <font color="#007F00">NoProxy</font><br> - , class <font color="#007F00">DerivedPolicies</font>></tt> - </h3> - <table width="100%" border="1"> - <tr> - <td> - <strong>Template Parameter</strong><br> - </td> - <td> - <strong>Requirements</strong> - </td> - <td> - <strong>Semantics</strong> - </td> - <td> - <strong>Default</strong> - </td> - </tr> - <tr> - <td> - <font color="#007F00"><tt>Container</tt></font> - </td> - <td> - A class type - </td> - <td> - The container type to be wrapped to Python. - </td> - <td> - - </td> - </tr> - <tr> - <td> - <font color="#007F00"><tt>NoProxy</tt></font> - </td> - <td> - A boolean - </td> - <td> - By default indexed elements have Python reference semantics and - are returned by proxy. This can be disabled by supplying - <strong>true</strong> in the <tt>NoProxy</tt> template parameter. - </td> - <td> - false - </td> - </tr> - <tr> - <td> - <font color="#007F00"><tt>DerivedPolicies</tt></font> - </td> - <td> - A subclass of indexing_suite - </td> - <td> - The <tt>vector_indexing_suite</tt> may still be derived to - further tweak any of the predefined policies. Static polymorphism - through CRTP (James Coplien. "Curiously Recurring Template - Pattern". C++ Report, Feb. 1995) enables the base - <tt>indexing_suite</tt> class to call policy function of the most - derived class - </td> - <td> - - </td> - </tr> - </table> - <pre> - template <<br> class Container,<br> bool NoProxy = false,<br> class DerivedPolicies = unspecified_default<br> class vector_indexing_suite : unspecified_base<br> {<br> public:<br><br> typedef typename Container::value_type data_type;<br> typedef typename Container::value_type key_type;<br> typedef typename Container::size_type index_type;<br> typedef typename Container::size_type size_type;<br> typedef typename Container::difference_type difference_type;<br> <br> data_type&<br> get_item(Container& container, index_type i); - - static object - get_slice(Container& container, index_type from, index_type to); - - static void<br> set_item(Container& container, index_type i, data_type const& v); - - static void - set_slice(Container& container, index_type from, - index_type to, data_type const& v); - - template <class Iter><br> static void<br> set_slice(Container& container, index_type from,<br> index_type to, Iter first, Iter last); - - static void - delete_item(Container& container, index_type i); - - static void - delete_slice(Container& container, index_type from, index_type to);<br> - static size_t - size(Container& container); - - static bool - contains(Container& container, key_type const& key); - - static index_type - convert_index(Container& container, PyObject* i); - - static index_type - adjust_index(index_type current, index_type from, - index_type to, size_type len); - }; - -</pre> - <h2><a name="vector_indexing_suite_class"></a>map_indexing_suite class </h2> - <h3> Class template <tt><br> - map_indexing_suite<<br> - class <font color="#007F00">Container</font><br> - , bool <font color="#007F00">NoProxy</font><br> - , class <font color="#007F00">DerivedPolicies</font>></tt> </h3> - <table width="100%" border="1"> - <tr> - <td> <strong>Template Parameter</strong><br> - </td> - <td> <strong>Requirements</strong> </td> - <td> <strong>Semantics</strong> </td> - <td> <strong>Default</strong> </td> - </tr> - <tr> - <td> <font color="#007F00"><tt>Container</tt></font> </td> - <td> A class type </td> - <td> The container type to be wrapped to Python. </td> - <td> </td> - </tr> - <tr> - <td> <font color="#007F00"><tt>NoProxy</tt></font> </td> - <td> A boolean </td> - <td> By default indexed elements have Python reference semantics and are returned by proxy. This can be disabled by supplying <strong>true</strong> in the <tt>NoProxy</tt> template parameter. </td> - <td> false </td> - </tr> - <tr> - <td> <font color="#007F00"><tt>DerivedPolicies</tt></font> </td> - <td> A subclass of indexing_suite </td> - <td> The <tt>vector_indexing_suite</tt> may still be derived to further tweak any of the predefined policies. Static polymorphism through CRTP (James Coplien. "Curiously Recurring Template Pattern". C++ Report, Feb. 1995) enables the base <tt>indexing_suite</tt> class to call policy function of the most derived class </td> - <td> </td> - </tr> - </table> - <pre> - template <<br> class Container,<br> bool NoProxy = false,<br> class DerivedPolicies = unspecified_default<br> class map_indexing_suite : unspecified_base<br> {<br> public:<br><br> typedef typename Container::value_type value_type;<br> typedef typename Container::value_type::second_type data_type;<br> typedef typename Container::key_type key_type;<br> typedef typename Container::key_type index_type;<br> typedef typename Container::size_type size_type;<br> typedef typename Container::difference_type difference_type;<br><br> static data_type&<br> get_item(Container& container, index_type i); - - static void<br> set_item(Container& container, index_type i, data_type const& v); - - static void - delete_item(Container& container, index_type i);<br> - static size_t - size(Container& container); - - static bool - contains(Container& container, key_type const& key); - - static bool<br> compare_index(Container& container, index_type a, index_type b); -<br> static index_type - convert_index(Container& container, PyObject* i); - }; - -</pre> - <hr> - © Copyright Joel de Guzman 2003. Permission to copy, use, modify, - sell and distribute this document is granted provided this copyright - notice appears in all copies. This document is provided "as is" without - express or implied warranty, and with no claim as to its suitability - for any purpose. - </div> - </body> -</html> diff --git a/libs/python/doc/v2/init.html b/libs/python/doc/v2/init.html deleted file mode 100644 index 2aacaad9f4..0000000000 --- a/libs/python/doc/v2/init.html +++ /dev/null @@ -1,251 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/init.hpp></title> - </head> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Headers <boost/python/init.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href= - "#init-expressions"><em>init-expressions</em></a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#init-spec">Class template <code>init</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#init-spec-synopsis">Class template - <code>init</code> synopsis</a></dt> - - <dt><a href="#init-spec-ctors">Class <code>init</code> - constructors</a></dt> - - </dl> - </dd> - - <dt><a href="#optional-spec">Class template - <code>optional</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#optional-spec-synopsis">Class template - <code>optional</code> synopsis</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><boost/python/init.hpp></code> defines the interface for - exposing C++ constructors to Python as extension class - <code>__init__</code> functions.</p> - - <h2><a name="init-expressions"><em>init-expressions</em></a></h2> - An <em>init-expression</em> is used to describe a family of - <code>__init__</code> methods to be generated for an extension class, and - the result has the following properties: - - <blockquote> - <dl class="properties"> - <dt><b>docstring:</b> An <a href="definitions.html#ntbs">ntbs</a> - whose value will bound to the method's <code>__doc__</code> - attribute</dt> - - <dt><b>keywords:</b> A <a href= - "args.html#keyword-expression">keyword-expression</a> which will be - used to name (a trailing subsequence of) the arguments to the - generated <code>__init__</code> function(s).</dt> - - <dt><b>call policies:</b> An instance of a model of <a href= - "CallPolicies.html">CallPolicies</a>.</dt> - - <dt><b>argument types:</b> An MPL sequence of C++ argument types - which will be used to construct the wrapped C++ object. An init - expression has one or more - <b>valid prefixes</b> which are given by a sequence of - prefixes of its argument types.</dt> - </dl> - </blockquote> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="init-spec"></a>Class template <code>init<T1 =</code> - <i>unspecified</i><code>, T2 =</code> - <i>unspecified</i><code>,</code>...<code>Tn</code> = - <i>unspecified</i><code>></code></h3> - - <p>A <a href="../../../mpl/doc/refmanual/forward-sequence.html">MPL sequence</a> which - can be used to specify a family of one or more <code>__init__</code> - functions. Only the last <code>T</code><i><small>i</small></i> supplied - may be an instantiation of <a href= - "#optional-spec"><code>optional</code></a><code><</code>...<code>></code>.</p> - - <h4><a name="init-spec-synopsis"></a>Class template <code>init</code> - synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <T1 = <i>unspecified</i>,...T<i>n</i> = <i>unspecified</i>> - 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> - <em>unspecified</em> operator[](CallPolicies const& policies) const - }; -}} -</pre> - - <h4><a name="init-spec-ctors"></a>Class template <code>init</code> - constructors</h4> -<pre> -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); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> If supplied, <code>doc</code> is an <a href= - "definitions.html#ntbs">ntbs</a>. If supplied, <code>kw</code> is the - result of a <a href="args.html#keyword-expression"></a></dt> - - <dt><b>Effects:</b> The result is an <em>init-expression</em> whose - <em>docstring</em> is <code>doc</code> and whose <em>keywords</em> are - a reference to <code>kw</code>. If the first form is used, the - resulting expression's <em>keywords</em> are empty. The expression's - <em>call policies</em> are an instance of <a href= - "default_call_policies.html#default_call_policies-spec">default_call_policies</a>. - If <code>T</code><i><small>n</small></i> is <a href= - "#optional-spec"><code>optional</code></a><code><U1, U2,</code>... - <code>U</code><small><i>m</i></small><code>></code>, the - expression's <em>valid prefixes</em> are given by:</dt> - - <dd> - <blockquote> - (<code>T1, T2,</code>...<code>T</code><i><small>n-1</small></i>), - (<code>T1, T2,</code>...<code>T</code><i><small>n-1</small></i> - <code>, U1</code>), - (<code>T1, T2,</code>...<code>T</code><i><small>n-1</small></i> - <code>, U1, U2</code>), - ...(<code>T1, T2,</code>...<code>T</code><i><small>n-1</small></i> - <code>, U1, U2,</code>...<code>U</code><i><small>m</small></i>). - </blockquote> - Otherwise, the expression has one <em>valid prefix</em> given by the - the template arguments the user specified. - </dd> - </dl> - - <h4><a name="init-spec-observers"></a>Class template <code>init</code> - observer functions</h4> -<pre> -template <class Policies> -<em>unspecified</em> operator[](Policies const& policies) const -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> Policies is a model of <a href= - "CallPolicies.html">CallPolicies</a>.</dt> - - <dt><b>Effects:</b> Returns a new <a href= - "#init-expressions"><em>init-expression</em></a> with all the same - properties as the <code>init</code> object except that its <em>call - policies</em> are replaced by a reference to - <code>policies</code>.</dt> - </dl> - - <h3><a name="optional-spec"></a>Class template <code>optional<T1 - =</code> <i>unspecified</i><code>, T2 =</code> - <i>unspecified</i><code>,</code>...<code>Tn</code> = - <i>unspecified</i><code>></code></h3> - - <p>A <a href="../../../mpl/doc/refmanual/forward-sequence.html">MPL sequence</a> which - can be used to specify the optional arguments to an <code>__init__</code> - function.</p> - - <h4><a name="optional-spec-synopsis"></a>Class template - <code>optional</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <T1 = <i>unspecified</i>,...T<i>n</i> = <i>unspecified</i>> - struct optional {}; -}} -</pre> - - <h2><a name="examples"></a>Example(s)</h2> - - <p>Given the C++ declarations:</p> -<pre> -class Y; -class X -{ - public: - X(int x, Y* y) : m_y(y) {} - X(double); - private: - Y* m_y; -}; -</pre> - A corresponding Boost.Python extension class can be created with: -<pre> -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>()) - ; -</pre> - <hr> - Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/instance_holder.html b/libs/python/doc/v2/instance_holder.html deleted file mode 100755 index 87571d1da8..0000000000 --- a/libs/python/doc/v2/instance_holder.html +++ /dev/null @@ -1,219 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content="HTML Tidy, see www.w3.org"> - <meta http-equiv="Content-Type" content= - "text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/instance_holder.hpp></title> - </head> - -<style type="text/css"> - p.c4 {font-style: italic} - span.c3 {color: #ff0000} - h2.c2 {text-align: center} - h1.c1 {text-align: center} -</style> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" - summary="header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width= - "277" alt="C++ Boost" src="../../../../boost.png" border= - "0"></a></h3> - - <td valign="top"> - <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> - - <h2 class="c2">Header <boost/python/instance_holder.hpp></h2> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a> - - <dt><a href="#classes">Classes</a> - - <dd> - <dl class="page-index"> - <dt><a href="#instance_holder-spec">Class - <code>instance_holder</code></a> - - <dd> - <dl class="page-index"> - <dt><a href="#instance_holder-spec-synopsis">Class - <code>instance_holder</code> synopsis</a> - - <dt><a href="#instance_holder-spec-ctors">Class - <code>instance_holder</code> destructor</a> - - <dt><a href="#instance_holder-spec-modifiers">Class - <code>instance_holder</code> modifier functions</a> - - <dt><a href="#instance_holder-spec-observers">Class - <code>instance_holder</code> observer functions</a> - </dl> - </dl> - - <dt><a href="#examples">Example</a> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><boost/python/instance_holder.hpp></code> provides - <code>class instance_holder</code>, the base class for types - which hold C++ instances of wrapped classes. - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="instance_holder-spec"></a>Class <code>instance_holder</code></h3> - - <p><code>instance_holder</code> is an abstract base class whose - concrete derived classes hold C++ class instances within their - Python object wrappers. To allow multiple inheritance in Python - from C++ class wrappers, each such Python object contains a chain - of <code>instance_holder</code>s. When an <code>__init__</code> - function for a wrapped C++ class is invoked, a new - <code>instance_holder</code> instance is created and installed in - the Python object using its <code><a - href="#instance_holder-spec-modifiers">install</a></code>() - function. Each concrete class derived from - <code>instance_holder</code> must provide a <code><a - href="#instance_holder-spec-observers">holds</a>()</code> - implementation which allows Boost.Python to query it for the - type(s) it is holding. In order to support the held type's wrapped - constructor(s), the class must also provide constructors that can - accept an initial <code>PyObject*</code> argument referring to the - owning Python object, and which forward the rest of their - arguments to the constructor of the held type. The initial - argument is needed to enable virtual function overriding in - Python, and may be ignored, depending on the specific - <code>instance_holder</code> subclass. - - <h4><a name="instance_holder-spec-synopsis"></a>Class instance_holder - synopsis</h4> -<pre> -namespace boost { namespace python -{ - class instance_holder : <a href="../../../utility/utility.htm#Class_noncopyable">noncopyable</a> - { - public: - // destructor - virtual ~instance_holder(); - - // instance_holder modifiers - void install(PyObject* inst) throw(); - - // instance_holder observers - virtual void* holds(type_info) = 0; - }; -}} -</pre> - - <h4><a name="instance_holder-spec-ctors">Class <code>instance_holder</code> - destructor</a></h4> -<pre> -virtual ~instance_holder(); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> destroys the object - </dl> - - <h4><a name="instance_holder-spec-modifiers">Class - <code>instance_holder</code> modifiers</a></h4> -<pre> -void install(PyObject* inst) throw(); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>inst</code> is a Python instance of a - wrapped C++ class type, or is a type derived from a wrapped C++ - class type. - <dt><b>Effects:</b> installs the new instance at the head of the - Python object's chain of held instances. - <dt><b>Throws:</b> nothing - </dl> - - <h4><a name="instance_holder-spec-observers">Class <code>instance_holder</code> - observers</a></h4> -<pre> -virtual void* holds(type_info x) = 0; -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> A pointer to an object of the type described - by <code>x</code> if <code>*this</code> contains such an object, - 0 otherwise. - </dl> - - <h2><a name="examples"></a>Example</h2> - -The following is a simplified version of the instance holder template -used by Boost.Python to wrap classes held by smart pointers: -<pre> -template <class SmartPtr, class Value> -struct pointer_holder : instance_holder -{ - // construct from the SmartPtr type - pointer_holder(SmartPtr p) - :m_p(p) - - // Forwarding constructors for the held type - pointer_holder(PyObject*) - :m_p(new Value()) - { - } - - template<class A0> - pointer_holder(PyObject*,A0 a0) - :m_p(new Value(a0)) - { - } - - template<class A0,class A1> - pointer_holder(PyObject*,A0 a0,A1 a1) - :m_p(new Value(a0,a1)) - { - } - ... - - private: // required holder implementation - void* holds(type_info dst_t) - { - // holds an instance of the SmartPtr type... - if (dst_t == python::type_id<SmartPtr>()) - return &this->m_p; - - // ...and an instance of the SmartPtr's element_type, if the - // pointer is non-null - return python::type_id<Value>() == dst_t ? &*this->m_p : 0; - } - - private: // data members - SmartPtr m_p; -}; -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - - - <p class="c4">© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002. - - </body> -</html> diff --git a/libs/python/doc/v2/iterator.html b/libs/python/doc/v2/iterator.html deleted file mode 100644 index 3557ffb9af..0000000000 --- a/libs/python/doc/v2/iterator.html +++ /dev/null @@ -1,398 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/iterator.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/iterator.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#iterator-spec">Class template - <code>iterator</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#iterator-spec-synopsis">Class - <code>iterator</code> synopsis</a></dt> - - <dt><a href="#iterator-spec-constructors">Class template - <code>iterator</code> constructor</a></dt> - </dl> - </dd> - </dl> - - <dl class="page-index"> - <dt><a href="#iterators-spec">Class template - <code>iterators</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#iterators-spec-synopsis">Class - <code>iterators</code> synopsis</a></dt> - - <dt><a href="#iterators-spec-types">Class template - <code>iterators</code> nested types</a></dt> - - <dt><a href="#iterators-spec-statics">Class template - <code>iterators</code> static functions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#range-spec">range</a></dt> - </dl> - </dd> - - <dt><a href="#examples">Examples</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><boost/python/iterator.hpp></code> provides types and - functions for creating <a href= - "http://www.python.org/doc/current/lib/typeiter.html">Python - iterators</a> from <a href= - "http://www.sgi.com/tech/stl/Container.html">C++ Containers</a> and <a - href="http://www.sgi.com/tech/stl/Iterators.html">Iterators</a>. Note - that if your <code>class_</code> supports random-access iterators, - implementing <code><a href= - "http://www.python.org/doc/current/ref/sequence-types.html#l2h-128">__getitem__</a></code> - (also known as the Sequence Protocol) may serve you better than using - this facility: Python will automatically create an iterator type for you - (see <a href= - "http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-35">iter()</a>), - and each access can be range-checked, leaving no possiblity of accessing - through an invalidated C++ iterator.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="iterator-spec"></a>Class Template <code>iterator</code></h3> - - <p>Instances of <code>iterator<C,P></code> hold a reference to a - callable Python object which, when invoked from Python, expects a single - argument <code>c</code> convertible to <code>C</code> and creates a - Python iterator that traverses [<code>c.begin()</code>, - <code>c.end()</code>). The optional <a href= - "CallPolicies.html">CallPolicies</a> <code>P</code> can be used to - control how elements are returned during iteration.</p> - - <p>In the table below, <code><b>c</b></code> is an instance of - <code>Container</code>.</p> - - <table border="1" summary="iterator template parameters"> - <tr> - <th>Template Parameter</th> - - <th>Requirements</th> - - <th>Semantics</th> - - <th>Default</th> - </tr> - - <tr> - <td><code>Container</code></td> - - <td>[c.begin(),c.end()) is a valid <a href= - "http://www.sgi.com/tech/stl/Iterators.html">Iterator range</a>.</td> - - <td>The result will convert its argument to <code>c</code> and call - <code>c.begin()</code> and <code>c.end()</code> to acquire iterators. - To invoke <code>Container</code>'s <code>const</code> - <code>begin()</code> and <code>end()</code> functions, make it - <code>const</code>.</td> - </tr> - - <tr> - <td><code>NextPolicies</code></td> - - <td>A default-constructible model of <a href= - "CallPolicies.html#CallPolicies-concept">CallPolicies</a>.</td> - - <td>Applied to the resulting iterators' <code>next()</code> - method.</td> - - <td>An unspecified model of <a href= - "CallPolicies.html#CallPolicies-concept">CallPolicies</a> which - always makes a copy of the result of deferencing the underlying C++ - iterator</td> - </tr> - </table> - - <h4><a name="iterator-spec-synopsis"></a>Class Template iterator - synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <class Container - , class NextPolicies = <i>unspecified</i>> - struct iterator : <a href="object.html#object-spec">object</a> - { - iterator(); - }; -}} -</pre> - - <h4><a name="iterator-spec-constructors"></a>Class Template iterator - constructor</h4> -<pre> -iterator() -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b></dt> - - <dd> - Initializes its base class with the result of: -<pre> -range<NextPolicies>(&iterators<Container>::begin, &iterators<Container>::end) -</pre> - </dd> - - <dt><b>Postconditions:</b> <code>this->get()</code> points to a - Python callable object which creates a Python iterator as described - above.</dt> - - <dt><b>Rationale:</b> Provides an easy way to create iterators for the - common case where a C++ class being wrapped provides - <code>begin()</code> and <code>end()</code>.</dt> - </dl> - <!-- --> - - <h3><a name="iterators-spec"></a>Class Template - <code>iterators</code></h3> - - <p>A utility class template which provides a way to reliably call its - argument's <code>begin()</code> and <code>end()</code> member functions. - Note that there is no portable way to take the address of a member - function of a C++ standard library container, so - <code>iterators<></code> can be particularly helpful when wrapping - them.</p> - - <p>In the table below, <code><b>x</b></code> is an instance of - <code>C</code>.</p> - - <table border="1" summary="iterator template parameters"> - <tr> - <th>Required Valid Expression</th> - - <th>Type</th> - </tr> - - <tr> - <td><code>x.begin()</code></td> - - <td>Convertible to <code>C::const_iterator</code> if <code>C</code> - is a <code>const</code> type; convertible to <code>C::iterator</code> - otherwise.</td> - </tr> - - <tr> - <td><code>x.end()</code></td> - - <td>Convertible to <code>C::const_iterator</code> if <code>C</code> - is a <code>const</code> type; convertible to <code>C::iterator</code> - otherwise.</td> - </tr> - </table> - - <h4><a name="iterators-spec-synopsis"></a>Class Template iterators - synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <class C> - struct iterators - { - typedef typename C::[const_]iterator iterator; - static iterator begin(C& x); - static iterator end(C& x); - }; -}} - -</pre> - - <h4><a name="iterators-spec-types"></a>Class Template iterators nested - types</h4> - If C is a <code>const</code> type, -<pre> -typedef typename C::const_iterator iterator; -</pre> - Otherwise: -<pre> -typedef typename C::iterator iterator; -</pre> - - <h4><a name="iterators-spec-statics"></a>Class Template iterators static - functions</h4> -<pre> -static iterator begin(C&); -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> <code>x.begin()</code></dt> - </dl> -<pre> -static iterator end(C&); -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> <code>x.end()</code></dt> - </dl> - <!-- --> - - <h2><a name="functions"></a>Functions</h2> -<pre> -<a name= -"range-spec">template</a> <class NextPolicies, class Target, class Accessor1, class Accessor2> -<a href= -"object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish); - -template <class NextPolicies, class Accessor1, class Accessor2> -<a href= -"object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish); - -template <class Accessor1, class Accessor2> -<a href= -"object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish); -</pre> - - <dl class="range-semantics"> - <dt><b>Requires:</b> <code>NextPolicies</code> is a - default-constructible model of <a href= - "CallPolicies.html#CallPolicies-concept">CallPolicies</a>.</dt> - - <dt><b>Effects:</b></dt> - - <dd> - <dl> - <dt>The first form creates a Python callable object which, when - invoked, converts its argument to a <code>Target</code> object - <code>x</code>, and creates a Python iterator which traverses - [<code><a href= - "../../../bind/bind.html">bind</a>(start,_1)(x)</code>, <code><a - href="../../../bind/bind.html">bind</a>(finish,_1)(x)</code>), - applying <code>NextPolicies</code> to the iterator's - <code>next()</code> function.</dt> - - <dt>The second form is identical to the first, except that - <code>Target</code> is deduced from <code>Accessor1</code> as - follows:</dt> - - <dd> - <ol> - <li>If <code>Accessor1</code> is a function type, - <code>Target</code> is the type of its first argument.</li> - - <li>If <code>Accessor1</code> is a data member pointer of the - form <code>R (T::*)</code>, <code>Target</code> is - identical to <code>T</code>.</li> - - <li>If <code>Accessor1</code> is a member function pointer of - the form - <code>R (T::*)(</code><i>arguments...</i><code>)</code> - <i>cv-opt</i>, where <i>cv-opt</i> is an optional - <code>cv-qualifier</code>, <code>Target</code> is identical to - <code>T</code>.</li> - </ol> - </dd> - - <dt>The third form is identical to the second, except that - <code>NextPolicies</code> is an unspecified model of <a href= - "CallPolicies.html#CallPolicies-concept">CallPolicies</a> which - always makes a copy of the result of deferencing the underlying C++ - iterator</dt> - </dl> - </dd> - - <dt><b>Rationale:</b> The use of <code><a href= - "../../../bind/bind.html">boost::bind</a>()</code> allows C++ iterators - to be accessed through functions, member functions or data member - pointers. Customization of <code>NextPolicies</code> (e.g. using - <code><a href= - "return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a></code>) - is useful when it is expensive to copy sequence elements of a wrapped - class type. Customization of <code>Target</code> is useful when - <code>Accessor1</code> is a function object, or when a base class of - the intended target type would otherwise be deduced.</dt> - </dl> - - <h2><a name="examples"></a>Examples</h2> -<pre> -#include <boost/python/module.hpp> -#include <boost/python/class.hpp> - -#include <vector> - -using namespace boost::python; -BOOST_PYTHON_MODULE(demo) -{ - class_<std::vector<double> >("dvec") - .def("__iter__", iterator<std::vector<double> >()) - ; -} -</pre> - A more comprehensive example can be found in: - - <dl> - <dt><code><a href= - "../../test/iterator.cpp">libs/python/test/iterator.cpp</a></code></dt> - - <dt><code><a href= - "../../test/input_iterator.cpp">libs/python/test/input_iterator.cpp</a></code></dt> - - <dt><code><a href= - "../../test/iterator.py">libs/python/test/input_iterator.py</a></code></dt> - - </dl> -<hr> - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/list.html b/libs/python/doc/v2/list.html deleted file mode 100644 index e347ae4617..0000000000 --- a/libs/python/doc/v2/list.html +++ /dev/null @@ -1,142 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/list.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/list.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#list-spec">Class <code>list</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#list-spec-synopsis">Class <code>list</code> - synopsis</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>Exposes a <a href= - "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> for the Python - <a href= - "http://www.python.org/doc/current/lib/typesseq-mutable.html">list</a> - type.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="list-spec"></a>Class <code>list</code></h3> - - <p>Exposes the <a href= - "http://www.python.org/doc/current/lib/typesseq-mutable.html">mapping - protocol</a> of Python's built-in <code>list</code> type. The semantics - of the constructors and member functions defined below can be fully - understood by reading the <a href= - "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept - definition. Since <code>list</code> is publicly derived from <code><a - href="object.html#object-spec">object</a></code>, the public object - interface applies to <code>list</code> instances as well.</p> - - <h4><a name="list-spec-synopsis"></a>Class <code>list</code> - synopsis</h4> -<pre> -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); - }; -}} -</pre> - - <h2><a name="examples"></a>Example</h2> -<pre> -using namespace boost::python; - -// Return the number of zeroes in the list -long zeroes(list l) -{ - return l.count(0); -} -</pre> - - <p>Revised 1 October, 2002</p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/long.html b/libs/python/doc/v2/long.html deleted file mode 100644 index 08ceb3bd5c..0000000000 --- a/libs/python/doc/v2/long.html +++ /dev/null @@ -1,119 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/long.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/long.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#long_-spec">Class <code>long_</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#long_-spec-synopsis">Class <code>long_</code> - synopsis</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>Exposes a <a href= - "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> for the Python - <a href= - "http://www.python.org/doc/current/lib/typesnumeric.html">long</a> - integer type.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="long_-spec"></a>Class <code>long_</code></h3> - - <p>Exposes the <a href= - "http://www.python.org/doc/current/lib/typesnumeric.html">numeric type - protocol</a> of Python's built-in <code>long</code> type. The semantics - of the constructors and member functions defined below can be fully - understood by reading the <a href= - "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept - definition. Since <code>long_</code> is publicly derived from <code><a - href="object.html#object-spec">object</a></code>, the public object - interface applies to <code>long_</code> instances as well.</p> - - <h4><a name="long_-spec-synopsis"></a>Class <code>long_</code> - synopsis</h4> -<pre> -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); - }; -}} -</pre> - - <h2><a name="examples"></a>Example</h2> -<pre> -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); -} -</pre> - - <p>Revised 1 October, 2002</p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/lvalue_from_pytype.html b/libs/python/doc/v2/lvalue_from_pytype.html deleted file mode 100755 index d27c57d0cf..0000000000 --- a/libs/python/doc/v2/lvalue_from_pytype.html +++ /dev/null @@ -1,301 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/lvalue_from_python.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/lvalue_from_pytype.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#lvalue_from_pytype-spec">Class Template - <code>lvalue_from_pytype</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#lvalue_from_pytype-spec-synopsis">Class Template - <code>lvalue_from_pytype</code> synopsis</a></dt> - - <dt><a href="#lvalue_from_pytype-spec-ctors">Class Template - <code>lvalue_from_pytype</code> constructor</a></dt> - </dl> - </dd> - </dl> - - <dl class="page-index"> - <dt><a href="#extract_identity-spec">Class Template - <code>extract_identity</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#extract_identity-spec-synopsis">Class Template - <code>extract_identity</code> synopsis</a></dt> - - <dt><a href="#extract_identity-spec-statics">Class Template - <code>extract_identity</code> static functions</a></dt> - </dl> - </dd> - - <dt><a href="#extract_member-spec">Class Template - <code>extract_member</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#extract_member-spec-synopsis">Class Template - <code>extract_member</code> synopsis</a></dt> - - <dt><a href="#extract_member-spec-statics">Class Template - <code>extract_member</code> static functions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - <code><boost/python/lvalue_from_pytype.hpp></code> supplies a - facility for extracting C++ objects from within Python instances of a - given type. This is typically useful for dealing with "traditional" - Python extension types. - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="lvalue_from_pytype-spec"></a>Class template - <code>lvalue_from_pytype</code></h3> - - <p>Class template <code>lvalue_from_pytype</code> will register - from_python converters which, given an object of the given Python type, - can extract references and pointers to a particular C++ type. Its - template arguments are:</p> - - <table border="1" summary="lvalue_from_pytype template parameters"> - <caption> - <b><code>lvalue_from_pytype</code> Requirements</b><br> - In the table below, <b><code>x</code></b> denotes an object of type - <code>PythonObject&</code> - </caption> - - <tr> - <th>Parameter</th> - - <th>Requirements</th> - - <th>Semantics</th> - </tr> - - <tr> - <td><code>Extractor</code></td> - - <td>a model of <a href= - "Extractor.html#Extractor-concept">Extractor</a> whose execute - function returns a reference type.</td> - - <td>Extracts the lvalue from the Python object once its type has been - confirmed</td> - </tr> - - <tr> - <td><code>python_type</code></td> - - <td>A compile-time constant <code><a href= - "http://www.python.org/doc/2.2/ext/dnt-type-methods.html">PyTypeObject</a>*</code></td> - - <td>The Python type of instances convertible by this converter. - Python subtypes are also convertible.</td> - </tr> - </table> - - <h4><a name="lvalue_from_pytype-spec-synopsis"></a>Class template - <code>lvalue_from_pytype</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <class Extractor, PyTypeObject const* python_type> - struct lvalue_from_pytype - { - lvalue_from_pytype(); - }; -}} -</pre> - - <h4><a name="lvalue_from_pytype-spec-ctors"></a>Class template - <code>lvalue_from_pytype</code> constructor</h4> -<pre> -lvalue_from_pytype(); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> Registers converters which can convert Python - objects of the given type to lvalues of the type returned by - <code>Extractor::execute</code>.</dt> - </dl> - - <h3><a name="extract_identity-spec"></a>Class template - <code>extract_identity</code></h3> - - <p><code>extract_identity</code> is a model of <a href= - "Extractor.html#Extractor-concept">Extractor</a> which can be used in the - common case where the C++ type to be extracted is the same as the Python - object type.</p> - - <h4><a name="extract_identity-spec-synopsis"></a>Class template - <code>extract_identity</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <class InstanceType> - struct extract_identity - { - static InstanceType& execute(InstanceType& c); - }; -}} -</pre> - - <h4><a name="extract_identity-spec-statics"></a>Class template - <code>extract_identity</code> static functions</h4> -<pre> -InstanceType& execute(InstanceType& c); -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> <code>c</code></dt> - </dl> - - <h3><a name="extract_member-spec"></a>Class template - <code>extract_member</code></h3> - - <p><code>extract_member</code> is a model of <a href= - "Extractor.html#Extractor-concept">Extractor</a> which can be used in the - common case in the common case where the C++ type to be extracted is a - member of the Python object.</p> - - <h4><a name="extract_member-spec-synopsis"></a>Class template - <code>extract_member</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <class InstanceType, class MemberType, MemberType (InstanceType::*member)> - struct extract_member - { - static MemberType& execute(InstanceType& c); - }; -}} -</pre> - - <h4><a name="extract_member-spec-statics"></a>Class template - <code>extract_member</code> static functions</h4> -<pre> -static MemberType& execute(InstanceType& c); -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> <code>c.*member</code></dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - This example presumes that someone has implemented the standard <a href= - "http://www.python.org/doc/2.2/ext/dnt-basics.html">noddy example - module</a> from the Python documentation, and we want to build a module - which manipulates <code>Noddy</code>s. Since - <code>noddy_NoddyObject</code> is so simple that it carries no - interesting information, the example is a bit contrived: it assumes you - want to keep track of one particular object for some reason. This module - would have to be dynamically linked to the module which defines - <code>noddy_NoddyType</code>. - - <h3>C++ module definition</h3> -<pre> -#include <boost/python/module.hpp> -#include <boost/python/handle.hpp> -#include <boost/python/borrowed.hpp> -#include <boost/python/lvalue_from_pytype.hpp> - -// definition lifted from the Python docs -typedef struct { - PyObject_HEAD -} noddy_NoddyObject; - -using namespace boost::python; -static handle<noddy_NoddyObject> cache; - -bool is_cached(noddy_NoddyObject* x) -{ - return x == cache.get(); -} - -void set_cache(noddy_NoddyObject* x) -{ - cache = handle<noddy_NoddyObject>(borrowed(x)); -} - -BOOST_PYTHON_MODULE(noddy_cache) -{ - def("is_cached", is_cached); - def("set_cache", set_cache); - - // register Noddy lvalue converter - lvalue_from_pytype<extract_identity<noddy_NoddyObject>,&noddy_NoddyType>(); -} -</pre> - - <h3>Python code</h3> -<pre> ->>> import noddy ->>> n = noddy.new_noddy() ->>> import noddy_cache ->>> noddy_cache.is_cached(n) -0 ->>> noddy_cache.set_cache(n) ->>> noddy_cache.is_cached(n) -1 ->>> noddy_cache.is_cached(noddy.new_noddy()) -0 -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 20 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/make_function.html b/libs/python/doc/v2/make_function.html deleted file mode 100644 index d5a6cdb06e..0000000000 --- a/libs/python/doc/v2/make_function.html +++ /dev/null @@ -1,207 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/make_function.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/make_function.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#make_function-spec">make_function</a></dt> - - <dt><a href="#make_constructor-spec">make_constructor</a></dt> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><a href="#make_function-spec">make_function</a>()</code> and - <code><a href="#make_constructor-spec">make_constructor</a>()</code> are - the functions used internally by <code><a href= - "def.html#def-spec">def</a>()</code> and <code>class_<>::<a href= - "class.html#class_-spec-modifiers">def</a>()</code> to produce Python - callable objects which wrap C++ functions and member functions.</p> - - <h2><a name="functions"></a>Functions</h2> -<pre> -<a name="make_function-spec">template <class F></a> -<a href="object.html#object-spec">object</a> make_function(F f) - -template <class F, class Policies> -<a href= -"object.html#object-spec">object</a> make_function(F f, Policies const& policies) - -template <class F, class Policies, class KeywordsOrSignature> -<a href= -"object.html#object-spec">object</a> make_function(F f, Policies const& policies, KeywordsOrSignature const& ks) - -template <class F, class Policies, class Keywords, class Signature> -<a href= -"object.html#object-spec">object</a> make_function(F f, Policies const& policies, Keywords const& kw, Signature const& sig) -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>F</code> is a function pointer or member - function pointer type. If <code>policies</code> are supplied, it must - be a model of <a href="CallPolicies.html">CallPolicies</a>. If - <code>kewords</code> are supplied, it must be the result of a <a href= - "args.html#keyword-expression"><em>keyword-expression</em></a> - specifying no more arguments than the <a href= - "definitions.html#arity">arity</a> of <code>f</code>.</dt> - - <dt><b>Effects:</b> Creates a Python callable object which, when called - from Python, converts its arguments to C++ and calls <code>f</code>. If - <code>F</code> is a pointer-to-member-function type, the target - object of the function call (<code>*this</code>) will be taken - from the first Python argument, and subsequent Python arguments - will be used as the arguments - to <code>f</code>. <ul> -<li> If <code>policies</code> are supplied, it - will be applied to the function as described <a href= - "CallPolicies.html">here</a>. -<li>If <code>keywords</code> are - supplied, the keywords will be applied in order to the final - arguments of the resulting function. -<li>If <code>Signature</code> - is supplied, it should be an instance of an <a - href="../../../mpl/doc/refmanual/front-extensible-sequence.html">MPL front-extensible - sequence</a> representing the function's return type followed by - its argument types. Pass a <code>Signature</code> when wrapping - function object types whose signatures can't be deduced, or when - you wish to override the types which will be passed to the - wrapped function. -</ul></dt> - - <dt><b>Returns:</b> An instance of <a href= - "object.html#object-spec">object</a> which holds the new Python - callable object.</dt> - - <dt><b>Caveats:</b> An argument of pointer type may - be <code>0</code> if <code>None</code> is passed from Python. - An argument type which is a constant reference may refer to a - temporary which was created from the Python object for just the - duration of the call to the wrapped function, for example - a <code>std::vector</code> conjured up by the conversion process - from a Python list. Use a non-<code>const</code> reference - argument when a persistent lvalue is required. - </dl> - -<pre> -<a name="make_constructor-spec">template <class F></a> -<a href="object.html#object-spec">object</a> make_constructor(F f) - -template <class F, class Policies> -<a href= -"object.html#object-spec">object</a> make_constructor(F f, Policies const& policies) - -template <class F, class Policies, class KeywordsOrSignature> -<a href= -"object.html#object-spec">object</a> make_constructor(F f, Policies const& policies, KeywordsOrSignature const& ks) - -template <class F, class Policies, class Keywords, class Signature> -<a href= -"object.html#object-spec">object</a> make_constructor(F f, Policies const& policies, Keywords const& kw, Signature const& sig) -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>F</code> is a - function pointer type. If <code>policies</code> are supplied, it must - be a model of <a href="CallPolicies.html">CallPolicies</a>. If - <code>kewords</code> are supplied, it must be the result of a <a href= - "args.html#keyword-expression"><em>keyword-expression</em></a> - specifying no more arguments than the <a href= - "definitions.html#arity">arity</a> of <code>f</code>.</dt> - - <dt><b>Effects:</b> Creates a Python callable object which, when called - from Python, converts its arguments to C++ and calls <code>f</code>.</dt> - - <dt><b>Returns:</b> An instance of <a href= - "object.html#object-spec">object</a> which holds the new Python - callable object.</dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - - <p>C++ function exposed below returns a callable object wrapping one of - two functions.</p> -<pre> -#include <boost/python/make_function.hpp> -#include <boost/python/module.hpp> - -char const* foo() { return "foo"; } -char const* bar() { return "bar"; } - -using namespace boost::python; -object choose_function(bool selector) -{ - if (selector) - return boost::python::make_function(foo); - else - return boost::python::make_function(bar); -} - -BOOST_PYTHON_MODULE(make_function_test) -{ - def("choose_function", choose_function); -} -</pre> - It can be used this way in Python: -<pre> ->>> from make_function_test import * ->>> f = choose_function(1) ->>> g = choose_function(0) ->>> f() -'foo' ->>> g() -'bar' -</pre> - - <p> - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/manage_new_object.html b/libs/python/doc/v2/manage_new_object.html deleted file mode 100644 index 57efb41374..0000000000 --- a/libs/python/doc/v2/manage_new_object.html +++ /dev/null @@ -1,145 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/manage_new_object.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/manage_new_object.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#manage_new_object-spec">Class - <code>manage_new_object</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#manage_new_object-spec-synopsis">Class - <code>manage_new_object</code> synopsis</a></dt> - - <dt><a href="#manage_new_object-spec-metafunctions">Class - <code>manage_new_object</code> metafunctions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="manage_new_object-spec"></a>Class - <code>manage_new_object</code></h3> - - <p><code>manage_new_object</code> is a model of <a href= - "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> - which can be used to wrap C++ functions which return a pointer to an - object allocated with a <i>new-expression</i>, and expect the caller to - take responsibility for deleting that object.</p> - - <h4><a name="manage_new_object-spec-synopsis"></a>Class - <code>manage_new_object</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - struct manage_new_object - { - template <class T> struct apply; - }; -}} -</pre> - - <h4><a name="manage_new_object-spec-metafunctions"></a>Class - <code>manage_new_object</code> metafunctions</h4> -<pre> -template <class T> struct apply -</pre> - - <dl class="metafunction-semantics"> - <dt><b>Requires:</b> <code>T</code> is <code>U*</code> for some - <code>U</code>.</dt> - - <dt><b>Returns:</b> <code>typedef <a href= - "to_python_indirect.html#to_python_indirect-spec">to_python_indirect</a><T> - type;</code></dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - - <p>In C++:</p> -<pre> -#include <boost/python/module.hpp> -#include <boost/python/class.hpp> -#include <boost/python/manage_new_object.hpp> -#include <boost/python/return_value_policy.hpp> - - -struct Foo { - Foo(int x) : x(x){} - int get_x() { return x; } - int x; -}; - -Foo* make_foo(int x) { return new Foo(x); } - -// Wrapper code -using namespace boost::python; -BOOST_PYTHON_MODULE(my_module) -{ - def("make_foo", make_foo, return_value_policy<manage_new_object>()) - class_<Foo>("Foo") - .def("get_x", &Foo::get_x) - ; -} -</pre> - In Python: -<pre> ->>> from my_module import * ->>> f = make_foo(3) # create a Foo object ->>> f.get_x() -3 -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/module.html b/libs/python/doc/v2/module.html deleted file mode 100644 index 353523cb6f..0000000000 --- a/libs/python/doc/v2/module.html +++ /dev/null @@ -1,110 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - <meta name="generator" content="HTML Tidy, see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/module.hpp></title> - - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/module.hpp></h2> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a> - - <dt><a href="#macros">Macros</a> - - <dd> - <dl class="page-index"> - <dt><a href= - "#BOOST_PYTHON_MODULE-spec">BOOST_PYTHON_MODULE</a> - </dl> - - <dt><a href="#examples">Example(s)</a> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>This header provides the basic facilities needed to create a - Boost.Python extension module. - - <h2><a name="macros"></a>Macros</h2> - - <p><a name= - "BOOST_PYTHON_MODULE-spec"><code>BOOST_PYTHON_MODULE(name)</code></a> - is used to declare Python <a href= - "http://www.python.org/doc/2.2/ext/methodTable.html#SECTION003400000000000000000"> - module initialization functions</a>. The <code>name</code> argument must - exactly match the name of the module to be initialized, and must conform to - Python's <a href= - "http://www.python.org/doc/2.2/ref/identifiers.html">identifier naming - rules</a>. Where you would normally write -<pre> -extern "C" void init<i>name</i>() -{ - ... -} -</pre> - Boost.Python modules should be initialized with -<pre> -BOOST_PYTHON_MODULE(<i>name</i>) -{ - ... -} -</pre> - -This macro generates two functions in the scope where it is used: -<code>extern "C" void init<i>name</i>()</code>, -and <code>void init_module_<i>name</i>()</code>, whose body must -follow the macro invocation. <code>init_<i>name</i></code> passes -<code>init_module_<i>name</i></code> to <code><a -href="errors.html#handle_exception-spec">handle_exception</a>()</code> so -that any C++ exceptions generated are safely processeed. During the -body of <code>init_<i>name</i></code>, the current <code><a -href="scope.html#scope-spec">scope</a></code> refers to the module -being initialized. - - <h2><a name="examples"></a>Example(s)</h2> - - <p>C++ module definition: -<pre> -#include <boost/python/module.hpp> - -BOOST_PYTHON_MODULE(xxx) -{ - throw "something bad happened" -} -</pre> - -Interactive Python: -<pre> ->>> import xxx -Traceback (most recent call last): - File "<stdin>", line 1, in ? -RuntimeError: Unidentifiable C++ Exception -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - - - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002. </i> Distributed - under the Boost Software License, Version 1.0. (See accompanying file - LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</p> - diff --git a/libs/python/doc/v2/numeric.html b/libs/python/doc/v2/numeric.html deleted file mode 100644 index eaa390af4d..0000000000 --- a/libs/python/doc/v2/numeric.html +++ /dev/null @@ -1,276 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> - -<html> -<head> - <meta name="generator" content= - "HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/numeric.hpp></title> -</head> - -<body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/numeric.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#array-spec">Class <code>array</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#array-spec-synopsis">Class <code>array</code> - synopsis</a></dt> - - <dt><a href="#array-spec-observers">Class <code>array</code> - observer functions</a></dt> - - <dt><a href="#array-spec-statics">Class <code>array</code> static - functions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - <hr> - - <h2><a name="introduction" id="introduction"></a>Introduction</h2> - - <p>Exposes a <a href= - "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> for the Python - <a href= - "http://www.python.org/dev/doc/devel/lib/typesmapping.html">array</a> - type.</p> - - <h2><a name="classes" id="classes"></a>Classes</h2> - - <h3><a name="array-spec" id="array-spec"></a>Class <code>array</code></h3> - - <p>Provides access to the array types of <a href= - "http://www.pfdubois.com/numpy/">Numerical Python</a>'s <a href= - "http://www.pfdubois.com/numpy/#Numeric">Numeric</a> and <a href= - "http://stsdas.stsci.edu/numarray/index.html">NumArray</a> modules. With - the exception of the functions documented <a href= - "#array-spec-observers">below</a>, the semantics of the constructors and - member functions defined below can be fully understood by reading the - <a href="ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept - definition. Since <code>array</code> is publicly derived from - <code><a href="object.html#object-spec">object</a></code>, the public - object interface applies to <code>array</code> instances as well.</p> - - <p><a name="default_search" id="default_search"></a>The default behavior is - to use <code>numarray.NDArray</code> as the associated Python type if the - <code>numarray</code> module is installed in the default location. - Otherwise it falls back to use <code>Numeric.ArrayType</code>. If neither - extension module is installed, overloads of wrapped C++ functions with - <code>numeric::array</code> parameters will never be matched, and other - attempted uses of <code>numeric::array</code> will <a href= - "definitions.html#raise">raise</a> an appropriate Python exception. The - associated Python type can be set manually using the <code><a href= - "#array-spec-statics">set_module_and_type</a>(...)</code> static - function.</p> - - <h4><a name="array-spec-synopsis" id="array-spec-synopsis"></a>Class - <code>array</code> synopsis</h4> - <pre> -namespace boost { namespace python { namespace numeric -{ - class array : public object - { - public: - object astype(); - template <class Type> - object astype(Type const& type_); - - template <class Type> - array 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 x<i>n</i>); - - 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 x<i>n</i>); - - 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 Sequence> - object factory(Sequence const&); - template <class Sequence, class Typecode> - object factory(Sequence const&, Typecode const&, bool copy = true, bool savespace = false); - template <class Sequence, class Typecode, class Type> - object factory(Sequence const&, Typecode const&, bool copy, bool savespace, Type const&); - template <class Sequence, class Typecode, class Type, class Shape> - object factory(Sequence const&, Typecode const&, bool copy, bool savespace, Type const&, Shape const&); - - 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 T<i>n</i>> - explicit array(T1 const& x1, T2 const& x2,...T<i>n</i> const& xn); - - static void set_module_and_type(); - static void set_module_and_type(char const* package_path = 0, char const* type_name = 0); - static void get_module_name(); - - 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; - }; -}}} -</pre> - - <h4><a name="array-spec-observers" id="array-spec-observers"></a>Class - <code>array</code> observer functions</h4> - <pre> -object factory(); -template <class Sequence> -object factory(Sequence const&); -template <class Sequence, class Typecode> -object factory(Sequence const&, Typecode const&, bool copy = true, bool savespace = false); -template <class Sequence, class Typecode, class Type> -object factory(Sequence const&, Typecode const&, bool copy, bool savespace, Type const&); -template <class Sequence, class Typecode, class Type, class Shape> -object factory(Sequence const&, Typecode const&, bool copy, bool savespace, Type const&, Shape const&); -</pre>These functions map to the underlying array type's <code>array()</code> -function family. They are not called "<code>array</code>" because of the C++ -limitation that you can't define a member function with the same name as its -enclosing class. - <pre> -template <class Type> -array new_(Type const&) const; -</pre>This function maps to the underlying array type's <code>new()</code> -function. It is not called "<code>new</code>" because that is a keyword in -C++. - - <h4><a name="array-spec-statics" id="array-spec-statics"></a>Class - <code>array</code> static functions</h4> - <pre> -static void set_module_and_type(char const* package_path, char const* type_name); -static void set_module_and_type(); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>package_path</code> and - <code>type_name</code>, if supplied, is an <a href= - "definitions.html#ntbs">ntbs</a>.</dt> - - <dt><b>Effects:</b> The first form sets the package path of the module - that supplies the type named by <code>type_name</code> to - <code>package_path</code>. The second form restores the <a href= - "#default_search">default search behavior</a>. 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 - <code>set_module_and_type</code>.</dt> - </dl> - <pre> -static std::string get_module_name() -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> Returns the name of the module containing the class - that will be held by new <code>numeric::array</code> instances.</dt> - </dl> - - <h2><a name="examples" id="examples"></a>Example</h2> - <pre> -#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; -} -</pre> - - <p>Revised 07 October, 2006</p> - - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002-2006.</i></p> -</body> -</html> diff --git a/libs/python/doc/v2/object.html b/libs/python/doc/v2/object.html deleted file mode 100644 index 8df8ef5f8f..0000000000 --- a/libs/python/doc/v2/object.html +++ /dev/null @@ -1,1121 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/object.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/object.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#types">Types</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#slice_nil-spec">slice_nil</a></dt> - </dl> - </dd> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#const_attribute_policies-spec">Class - <code>const_attribute_policies</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#const_attribute_policies-spec-synopsis">Class - <code>const_attribute_policies</code> synopsis</a></dt> - - <dt><a href="#const_attribute_policies-spec-statics">Class - <code>const_attribute_policies</code> static functions</a></dt> - </dl> - </dd> - - <dt><a href="#attribute_policies-spec">Class - <code>attribute_policies</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#attribute_policies-spec-synopsis">Class - <code>attribute_policies</code> synopsis</a></dt> - - <dt><a href="#attribute_policies-spec-statics">Class - <code>attribute_policies</code> static functions</a></dt> - </dl> - </dd> - - <dt><a href="#const_objattribute_policies-spec">Class - <code>const_objattribute_policies</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#const_objattribute_policies-spec-synopsis">Class - <code>const_objattribute_policies</code> synopsis</a></dt> - - <dt><a href="#const_objattribute_policies-spec-statics">Class - <code>const_objattribute_policies</code> static functions</a></dt> - </dl> - </dd> - - <dt><a href="#objattribute_policies-spec">Class - <code>objattribute_policies</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#objattribute_policies-spec-synopsis">Class - <code>objattribute_policies</code> synopsis</a></dt> - - <dt><a href="#objattribute_policies-spec-statics">Class - <code>objattribute_policies</code> static functions</a></dt> - </dl> - </dd> - - <dt><a href="#const_item_policies-spec">Class - <code>const_item_policies</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#const_item_policies-spec-synopsis">Class - <code>const_item_policies</code> synopsis</a></dt> - - <dt><a href="#const_item_policies-spec-statics">Class - <code>const_item_policies</code> static functions</a></dt> - </dl> - </dd> - - <dt><a href="#item_policies-spec">Class - <code>item_policies</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#item_policies-spec-synopsis">Class - <code>item_policies</code> synopsis</a></dt> - - <dt><a href="#item_policies-spec-statics">Class - <code>item_policies</code> static functions</a></dt> - </dl> - </dd> - - <dt><a href="#const_slice_policies-spec">Class - <code>const_slice_policies</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#const_slice_policies-spec-synopsis">Class - <code>const_slice_policies</code> synopsis</a></dt> - - <dt><a href="#const_slice_policies-spec-statics">Class - <code>const_slice_policies</code> static functions</a></dt> - </dl> - </dd> - - <dt><a href="#slice_policies-spec">Class - <code>slice_policies</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#slice_policies-spec-synopsis">Class - <code>slice_policies</code> synopsis</a></dt> - - <dt><a href="#slice_policies-spec-statics">Class - <code>slice_policies</code> static functions</a></dt> - </dl> - </dd> - - <dt><a href="#object_operators-spec">Class - <code>object_operators</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#object_operators-spec-synopsis">Class - <code>object_operators</code> synopsis</a></dt> - - <dt><a href="#object_operators-spec-observers">Class - <code>object_operators</code> observer functions</a></dt> - </dl> - </dd> - - <dt><a href="#object-spec">Class <code>object</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#object-spec-synopsis">Class <code>object</code> - synopsis</a></dt> - - <dt><a href="#object-spec-ctors">Class <code>object</code> - constructors and destructor</a></dt> - - <dt><a href="#object-spec-modifiers">Class template - <code>object</code> modifier functions</a></dt> - - <dt><a href="#object-spec-observers">Class template - <code>object</code> observer functions</a></dt> - </dl> - </dd> - - <dt><a href="#proxy-spec">Class template - <code>proxy</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#proxy-spec-synopsis">Class template - <code>proxy</code> synopsis</a></dt> - - <dt><a href="#proxy-spec-modifiers">Class template - <code>proxy</code> modifier functions</a></dt> - - <dt><a href="#proxy-spec-observers">Class template - <code>proxy</code> observer functions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#del-spec">del</a></dt> - - <dt><a href="#comparisons-spec">comparisons</a></dt> - - <dt><a href="#binary-spec">binary operations</a></dt> - - <dt><a href="#assignment-spec">assignment operations</a></dt> - - </dl> - - <dl class="page-index"> - <dt><a href="#object_operators-spec">operators</a></dt> - </dl> - - <dl class="page-index"> - <dt><a href="#len-spec">len()</a></dt> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>Exposes the generic Python object wrapper class <code>object</code>, - and related classes. In order to avoid some potenential problems with - argument-dependent lookup and the generalized operators defined on - <code>object</code>, all these facilities are defined in - <code>namespace boost::python::api</code>, and <code>object</code> - is imported into <code>namespace boost::python</code> with a - <i>using-declaration</i>.</p> - - <h2><a name="types"></a>Types</h2> - - <p><a name="slice_nil-spec"></a></p> -<pre> -class slice_nil; -static const _ = slice_nil(); -</pre> - A type that can be used to get the effect of leaving out an index in a - Python slice expression: -<pre> ->>> x[:-1] ->>> x[::-1] -</pre> - C++ equivalent: -<pre> -x.slice(_,-1) -x[slice(_,_,-1)] -</pre> - - <h2><a name="classes"></a>Classes</h2> - <!-- begin --> - - <h3><a name="const_attribute_policies-spec"></a>Class - <code>const_attribute_policies</code></h3> - - <p>The policies which are used for proxies representing an attribute - access to a <code>const object</code>.</p> - - <h4><a name="const_attribute_policies-spec-synopsis"></a>Class - <code>const_attribute_policies</code> synopsis</h4> -<pre> -namespace boost { namespace python { namespace api -{ - struct const_attribute_policies - { - typedef char const* key_type; - static object get(object const& target, char const* key); - }; -}}} -</pre> - - <h4><a name="const_attribute_policies-spec-statics"></a>Class - <code>const_attribute_policies</code> static functions</h4> -<pre> -static object get(object const& target, char const* key); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>key</code> is an <a href= - "definitions.html#ntbs">ntbs</a>.</dt> - - <dt><b>Effects:</b> accesses the attribute of <code>target</code> named - by <code>key</code>.</dt> - - <dt><b>Returns:</b> An <code>object</code> managing the result of the - attribute access.</dt> - - <dt><b>Throws:</b> <code><a href= - "errors.html#error_already_set-spec">error_already_set</a></code> if a - Python exception is raised.</dt> - </dl> - - <h3><a name="attribute_policies-spec"></a>Class - <code>attribute_policies</code></h3> - - <p>The policies which are used for proxies representing an attribute - access to a mutable <code>object</code>.</p> - - <h4><a name="attribute_policies-spec-synopsis"></a>Class - <code>attribute_policies</code> synopsis</h4> -<pre> -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); - }; -}}} -</pre> - - <h4><a name="attribute_policies-spec-statics"></a>Class - <code>attribute_policies</code> static functions</h4> -<pre> -static object const& set(object const& target, char const* key, object const& value); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>key</code> is an <a href= - "definitions.html#ntbs">ntbs</a>.</dt> - - <dt><b>Effects:</b> sets the attribute of <code>target</code> named by - <code>key</code> to <code>value</code>.</dt> - - <dt><b>Throws:</b> <code><a href= - "errors.html#error_already_set-spec">error_already_set</a></code> if a - Python exception is raised.</dt> - </dl> -<pre> -static void del(object const&target, char const* key); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>key</code> is an <a href= - "definitions.html#ntbs">ntbs</a>.</dt> - - <dt><b>Effects:</b> deletes the attribute of <code>target</code> named - by <code>key</code>.</dt> - - <dt><b>Throws:</b> <code><a href= - "errors.html#error_already_set-spec">error_already_set</a></code> if a - Python exception is raised.</dt> - </dl> - <!-- end --> - <!-- begin --> - - <h3><a name="const_objattribute_policies-spec"></a>Class - <code>const_objattribute_policies</code></h3> - - <p>The policies which are used for proxies representing an attribute - access to a <code>const object</code> when the attribute name is - given as a <code>const object</code>.</p> - - <h4><a name="const_objattribute_policies-spec-synopsis"></a>Class - <code>const_objattribute_policies</code> synopsis</h4> -<pre> -namespace boost { namespace python { namespace api -{ - struct const_objattribute_policies - { - typedef object const& key_type; - static object get(object const& target, object const& key); - }; -}}} -</pre> - - <h4><a name="const_objattribute_policies-spec-statics"></a>Class - <code>const_objattribute_policies</code> static functions</h4> -<pre> -static object get(object const& target, object const& key); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>key</code> is an <code>object</code> - holding a string.</dt> - - <dt><b>Effects:</b> accesses the attribute of <code>target</code> named - by <code>key</code>.</dt> - - <dt><b>Returns:</b> An <code>object</code> managing the result of the - attribute access.</dt> - - <dt><b>Throws:</b> <code><a href= - "errors.html#error_already_set-spec">error_already_set</a></code> if a - Python exception is raised.</dt> - </dl> - - <h3><a name="objattribute_policies-spec"></a>Class - <code>objattribute_policies</code></h3> - - <p>The policies which are used for proxies representing an attribute - access to a mutable <code>object</code> when the attribute name is - given as a <code>const object</code>.</p> - - <h4><a name="objattribute_policies-spec-synopsis"></a>Class - <code>objattribute_policies</code> synopsis</h4> -<pre> -namespace boost { namespace python { namespace api -{ - struct objattribute_policies : const_objattribute_policies - { - static object const& set(object const& target, object const& key, object const& value); - static void del(object const&target, object const& key); - }; -}}} -</pre> - - <h4><a name="objattribute_policies-spec-statics"></a>Class - <code>objattribute_policies</code> static functions</h4> -<pre> -static object const& set(object const& target, object const& key, object const& value); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>key</code> is an <code>object</code> - holding a string.</dt> - - <dt><b>Effects:</b> sets the attribute of <code>target</code> named by - <code>key</code> to <code>value</code>.</dt> - - <dt><b>Throws:</b> <code><a href= - "errors.html#error_already_set-spec">error_already_set</a></code> if a - Python exception is raised.</dt> - </dl> -<pre> -static void del(object const&target, object const& key); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>key</code> is an <code>object</code> - holding a string.</dt> - - <dt><b>Effects:</b> deletes the attribute of <code>target</code> named - by <code>key</code>.</dt> - - <dt><b>Throws:</b> <code><a href= - "errors.html#error_already_set-spec">error_already_set</a></code> if a - Python exception is raised.</dt> - </dl> - <!-- end --> - <!-- begin --> - - <h3><a name="const_item_policies-spec"></a>Class - <code>const_item_policies</code></h3> - - <p>The policies which are used for proxies representing an item access - (via the Python bracket operators <code>[]</code>) to a - <code>const object</code>.</p> - - <h4><a name="const_item_policies-spec-synopsis"></a>Class - <code>const_item_policies</code> synopsis</h4> -<pre> -namespace boost { namespace python { namespace api -{ - struct const_item_policies - { - typedef object key_type; - static object get(object const& target, object const& key); - }; -}}} -</pre> - - <h4><a name="const_item_policies-spec-statics"></a>Class - <code>const_item_policies</code> static functions</h4> -<pre> -static object get(object const& target, object const& key); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> accesses the item of <code>target</code> specified - by <code>key</code>.</dt> - - <dt><b>Returns:</b> An <code>object</code> managing the result of the - item access.</dt> - - <dt><b>Throws:</b> <code><a href= - "errors.html#error_already_set-spec">error_already_set</a></code> if a - Python exception is raised.</dt> - </dl> - - <h3><a name="item_policies-spec"></a>Class - <code>item_policies</code></h3> - - <p>The policies which are used for proxies representing an item access - (via the Python bracket operators <code>[]</code>) to a mutable - <code>object</code>.</p> - - <h4><a name="item_policies-spec-synopsis"></a>Class - <code>item_policies</code> synopsis</h4> -<pre> -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); - }; -}}} -</pre> - - <h4><a name="item_policies-spec-statics"></a>Class - <code>item_policies</code> static functions</h4> -<pre> -static object const& set(object const& target, object const& key, object const& value); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> sets the item of <code>target</code> specified by - <code>key</code> to <code>value</code>.</dt> - - <dt><b>Throws:</b> <code><a href= - "errors.html#error_already_set-spec">error_already_set</a></code> if a - Python exception is raised.</dt> - </dl> -<pre> -static void del(object const& target, object const& key); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> deletes the item of <code>target</code> specified - by <code>key</code>.</dt> - - <dt><b>Throws:</b> <code><a href= - "errors.html#error_already_set-spec">error_already_set</a></code> if a - Python exception is raised.</dt> - </dl> - <!-- end --> - <!-- begin --> - - <h3><a name="const_slice_policies-spec"></a>Class - <code>const_slice_policies</code></h3> - - <p>The policies which are used for proxies representing an slice access - (via the Python slice notation - <code>[</code><i>x</i><code>:</code><i>y</i><code>]</code>) to a - <code>const object</code>.</p> - - <h4><a name="const_slice_policies-spec-synopsis"></a>Class - <code>const_slice_policies</code> synopsis</h4> -<pre> -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); - }; -}}} -</pre> - - <h4><a name="const_slice_policies-spec-statics"></a>Class - <code>const_slice_policies</code> static functions</h4> -<pre> -static object get(object const& target, key_type const& key); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> accesses the slice of <code>target</code> specified - by <code>key</code>.</dt> - - <dt><b>Returns:</b> An <code>object</code> managing the result of the - slice access.</dt> - - <dt><b>Throws:</b> <code><a href= - "errors.html#error_already_set-spec">error_already_set</a></code> if a - Python exception is raised.</dt> - </dl> - - <h3><a name="slice_policies-spec"></a>Class - <code>slice_policies</code></h3> - - <p>The policies which are used for proxies representing an slice access - to a mutable <code>object</code>.</p> - - <h4><a name="slice_policies-spec-synopsis"></a>Class - <code>slice_policies</code> synopsis</h4> -<pre> -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); - }; -}}} -</pre> - - <h4><a name="slice_policies-spec-statics"></a>Class - <code>slice_policies</code> static functions</h4> -<pre> -static object const& set(object const& target, key_type const& key, object const& value); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> sets the slice of <code>target</code> specified by - <code>key</code> to <code>value</code>.</dt> - - <dt><b>Throws:</b> <code><a href= - "errors.html#error_already_set-spec">error_already_set</a></code> if a - Python exception is raised.</dt> - </dl> -<pre> -static void del(object const& target, key_type const& key); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> deletes the slice of <code>target</code> specified - by <code>key</code>.</dt> - - <dt><b>Throws:</b> <code><a href= - "errors.html#error_already_set-spec">error_already_set</a></code> if a - Python exception is raised.</dt> - </dl> - <!-- end --> - - <h3><a name="object_operators-spec"></a>Class template - <code>object_operators<U></code></h3> - - <p>This is the base class of <code>object</code> and its - <code>proxy</code> template used to supply common interface: member - functions, and operators which must be defined within the class body. Its - template parameter <code>U</code> is expected to be a class derived from - <code>object_operators<U></code>. In practice users should never - use this class directly, but it is documented here because it supplies - important interface to <code>object</code> and its proxies.</p> - - <h4><a name="object_operators-spec-synopsis"></a>Class template - <code>object_operators</code> synopsis</h4> -<pre> -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; - - detail::args_proxy operator* () const; - object operator()(detail::args_proxy const &args) const; - object operator()(detail::args_proxy const &args, - detail::kwds_proxy const &kwds) 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*); - proxy<const_object_objattribute> attr(object const&) const; - proxy<object_objattribute> attr(object 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); - }; -}}} -</pre> - - <h4><a name="object_operators-spec-observers"></a>Class template - <code>object_operators</code> observer functions</h4> -<pre> -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; -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - call<object>(object(*static_cast<U*>(this)).ptr(), a1, - a2,...aN)</dt> - </dl> - -<pre> -object operator()(detail::args_proxy const &args) const; -</pre> -<dl class="function-semantics"> - <dt><b>Effects:</b> - call object with arguments given by the tuple <varname>args</varname></dt> -</dl> -<pre> -object operator()(detail::args_proxy const &args, - detail::kwds_proxy const &kwds) const; -</pre> -<dl class="function-semantics"> - <dt><b>Effects:</b> - call object with arguments given by the tuple <varname>args</varname>, and named - arguments given by the dictionary <varname>kwds</varname></dt> -</dl> - - -<pre> -operator bool_type() const; -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> Tests truth value of <code>*this</code>.</dt> - - <dt><b>Returns:</b> - call<object>(object(*static_cast<U*>(this)).ptr(), a1, - a2,...aN)</dt> - </dl> -<pre> -proxy<const_object_attribute> attr(char const* name) const; -proxy<object_attribute> attr(char const* name); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> name is an <a href= - "definitions.html#ntbs">ntbs</a>.</dt> - - <dt><b>Effects:</b> accesses the named attribute of - <code>*this</code>.</dt> - - <dt><b>Returns:</b> a proxy object which binds - <code>object(*static_cast<U*>(this))</code> as its target, and - <code>name</code> as its key.</dt> - </dl> -<pre> -proxy<const_object_objattribute> attr(const object& name) const; -proxy<object_objattribute> attr(const object& name); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> name is a <code>object</code> holding a string.</dt> - - <dt><b>Effects:</b> accesses the named attribute of - <code>*this</code>.</dt> - - <dt><b>Returns:</b> a proxy object which binds - <code>object(*static_cast<U*>(this))</code> as its target, and - <code>name</code> as its key.</dt> - </dl> -<pre> -template <class T> -proxy<const_object_item> operator[](T const& key) const; -template <class T> -proxy<object_item> operator[](T const& key); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> accesses the item of <code>*this</code> indicated - by <code>key</code>.</dt> - - <dt><b>Returns:</b> a proxy object which binds - <code>object(*static_cast<U*>(this))</code> as its target, and - <code>object(key)</code> as its key.</dt> - </dl> -<pre> -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); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> accesses the slice of <code>*this</code> indicated - by <code>std::make_pair(object(start), object(finish))</code>.</dt> - - <dt><b>Returns:</b> a proxy object which binds - <code>object(*static_cast<U*>(this))</code> as its target, and - <code>std::make_pair(object(start), object(finish))</code> as its - key.</dt> - </dl> - <!-- --> - - <h3><a name="object-spec"></a>Class <code>object</code></h3> - - <p>The intention is that <code>object</code> 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 - <code>object</code>'s interface is provided by its base class - <code><a - href="#object_operators-spec">object_operators</a><object></code>, - and the <a href="#functions">free functions</a> defined in this - header. -</p> - - <h4><a name="object-spec-synopsis"></a>Class <code>object</code> - synopsis</h4> -<pre> -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; - - bool is_none() const; - }; -}}} -</pre> - - <h4><a name="object-spec-ctors"></a>Class <code>object</code> - constructors and destructor</h4> -<pre> -object(); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> Constructs an object managing a reference to the - Python <code>None</code> object.</dt> - - <dt><b>Throws:</b> nothing.</dt> - </dl> -<pre> -template <class T> -explicit object(T const& x); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> converts <code>x</code> to python and manages a - reference to it.</dt> - - <dt><b>Throws:</b> <code>error_already_set</code> and sets a Python - <code>TypeError</code> exception if no such conversion is - possible.</dt> - </dl> -<pre> -~object(); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> decrements the reference count of the - internally-held object.</dt> - </dl> - - <h4><a name="object-spec-modifiers"></a>Class <code>object</code> - modifiers</h4> -<pre> -object& operator=(object const& rhs); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> increments the reference count of the object held - by <code>rhs</code> and decrements the reference count of the object - held by <code>*this</code>.</dt> - </dl> - - <h4><a name="object-spec-observers"></a>Class <code>object</code> - observers</h4> -<pre> -PyObject* ptr() const; -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> a pointer to the internally-held Python - object.</dt> - </dl> - -<pre> -bool is_none() const; -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> result of (ptr() == Py_None)</dt> - </dl> - <!-- --> - - <h3><a name="proxy-spec"></a>Class template <code>proxy</code></h3> - - <p>This template is instantiated with various Policies described in this - document in order to implement attribute, item, and slice access for - <code>object</code>. It stores an object of type - <code>Policies::key_type</code>.</p> - - <h4><a name="proxy-spec-synopsis"></a>Class template <code>proxy</code> - synopsis</h4> -<pre> -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); - }; -}}} -</pre> - - <h4><a name="proxy-spec-observers"></a>Class template <code>proxy</code> - observer functions</h4> -<pre> -operator object() const; -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> applies - <code>Policies::get(</code><i>target</i><code>,</code> <i>key</i> - <code>)</code> with the proxy's target and key objects.</dt> - </dl> - - <h4><a name="proxy-spec-modifiers"></a>Class template <code>proxy</code> - modifier functions</h4> -<pre> -proxy const& operator=(proxy const& rhs) const; -template <class T> -inline proxy const& operator=(T const& rhs) const; -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - <code>Policies::set(</code><i>target</i><code>,</code> <i>key</i> - <code>, object(rhs))</code> with the proxy's target and key - objects.</dt> - </dl> -<pre> -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); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> for a given operator@=, - <code>object(*this) @= rhs;</code></dt> - <dt><b>Returns:</b> <code>*this</code></dt> - </dl> -<pre> -void del() const; -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - <code>Policies::del(</code><i>target</i><code>,</code> <i>key</i> - <code>)</code> with the proxy's target and key objects.</dt> - </dl> - <!-- --> - - <h2><a name="functions"></a>Functions</h2> -<pre> -<a name="del-spec"></a>template <class T> -void del(proxy<T> const& x); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> x.del()</dt> - </dl> -<pre> -<a name="comparisons-spec"></a> -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); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> returns the result of applying the operator to - <code>object(l)</code> and <code>object(r)</code>, respectively, in - Python.</dt> - </dl> -<pre> -<a name="binary-spec"></a> -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); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> returns the result of applying the operator to - <code>object(l)</code> and <code>object(r)</code>, respectively, in - Python.</dt> - </dl> -<pre> -<a name="assignment-spec"></a> -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); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> assigns to l the result of applying the - corresponding Python inplace operator to <code>l</code> and - <code>object(r)</code>, respectively.</dt> - - <dt><b>Returns:</b> <code>l</code>.</dt> - </dl> - -<pre> -inline long len(object const& obj); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> PyObject_Length(obj.ptr()) </dt> - <dt><b>Returns:</b> len() of object.</dt> - </dl> - -<h2><a name="examples"></a>Example</h2> - Python code: -<pre> -def sum_items(seq): - result = 0 - for x in seq: - result += x - return result -</pre> - C++ version: -<pre> -object sum_items(object seq) -{ - object result = object(0); - for (int i = 0; i < len(seq); ++i) - result += seq[i]; - return result; -} -</pre> - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 15 March, 2010 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2008.</i></p> - </body> -</html> diff --git a/libs/python/doc/v2/opaque.html b/libs/python/doc/v2/opaque.html deleted file mode 100644 index fed1d446f4..0000000000 --- a/libs/python/doc/v2/opaque.html +++ /dev/null @@ -1,138 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright 2003..2006 Haufe Mediengruppe. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> - -<html> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/opaque_pointer_converter.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/opaque_pointer_converter.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#opaque-spec">Class template - <code>opaque<Pointee></code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#opaque-spec-synopsis">Class template - <code>opaque</code> synopsis</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#macros">Macros</a></dt> - <dd> - <dl class="page-index"> - <dt><a href="#BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID-spec">Macro - <code>BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</code></a></dt> - </dl> - </dd> - - <dt><a href="#see-also">See Also</a></dt> - </dl> - <hr> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="opaque-spec"></a>Class template - <code>opaque<P></code></h3> - - <p><code>opaque<></code> registers itself as a converter from - Python objects to pointers to undefined types and vice versa.</p> - - <h4><a name="opaque-spec-synopsis"></a>Class template - <code>opaque</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template<class Pointee> - struct opaque - { - opaque(); - }; -}} -</pre> - - <h4><a name="opaque-spec-constructor"></a>Class template - <code>opaque</code> constructor</h4> -<pre> -opaque(); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - <ul> - <li>Registers the instance as a - <a href="lvalue_from_pytype.html#lvalue_from_pytype-spec"> <code>lvalue_from_pytype</code></a> - converter from Python objects into opaque pointers.</p> - <p>The Python Objects created are named after the type pointed to - by the opaque pointer being wrapped.</p></li> - <li>Registers the instance as a - <a href="to_python_converter.html#to_python_converter-spec"> <code>to_python_converter</code></a> - from opaque pointers to Python objects.</p></li> - </ul> - <p>If there is already an instance registered by another module, this - instance doesn't try to register again in order to avoid warnings - about multiple registrations.</p> - - <h4>Note</h4> - <p>Normally only a single instance of this class is created for every - Pointee.</p> - </dt> - </dl> - - <h2><a name="macros"></a>Macros</h2> - - <h3><a name="BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID-spec"></a> - Macro BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID(Pointee)</h3> - <p>This macro must be used to define specializations of the - <a href="type_id.html#type_id-spec">type_id</a> function - which can't be instantiated for incomplete types.</p> - <h4>Note</h4> - <p>The macro must be invoked in every translation unit which uses the - opaque converter.</p> - - <h2><a name="see-also"></a>See Also</h2> - <p> - <a href="return_opaque_pointer.html">return_opaque_pointer</a> - </p> - - <p>Revised - 10 September, 2006 - </p> - - <p><i>© Copyright 2003..2006 Haufe Mediengruppe. All Rights - Reserved.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/operators.html b/libs/python/doc/v2/operators.html deleted file mode 100755 index 69740243fb..0000000000 --- a/libs/python/doc/v2/operators.html +++ /dev/null @@ -1,921 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/operators.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/operators.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#self_t-spec">Class - <code>self_ns::self_t</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#self_t-spec-synopsis">Class <code>self_t</code> - synopsis</a></dt> - - <dt><a href="#self_t-spec-inplace">Class <code>self_t</code> - inplace operators</a></dt> - - <dt><a href="#self_t-spec-comparisons">Class - <code>self_t</code> comparison functions</a></dt> - - <dt><a href="#self_t-spec-ops">Class <code>self_t</code> - non-member operations</a></dt> - - <dt><a href="#self_t-spec-value-unary-ops">Class - <code>self_t</code> unary operations</a></dt> - - <dt><a href="#self_t-spec-value-ops">Class - <code>self_t</code> value operations</a></dt> - </dl> - </dd> - - <dt><a href="#other-spec">Class template - <code>other</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#other-spec-synopsis">Class <code>other</code> - synopsis</a></dt> - </dl> - </dd> - - <dt><a href="#operator_-spec">Class template - <code>operator_</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#operator_-spec-synopsis">Class - <code>operator_</code> synopsis</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#objects">Objects</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#self-spec">self</a></dt> - </dl> - </dd> - - <dt><a href="#examples">Examples</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><boost/python/operators.hpp></code> provides types and - functions for automatically generating Python <a href= - "http://www.python.org/doc/ref/specialnames.html">special methods</a> - from the corresponding C++ constructs. Most of these constructs are - operator expressions, hence the name. To use the facility, substitute the - <code><a href="#self-spec">self</a></code> object for an object of the - class type being wrapped in the expression to be exposed, and pass the - result to <a href= - "class.html#class_-spec-modifiers">class_<>::def()</a>. Much of - what is exposed in this header should be considered part of the - implementation, so is not documented in detail here.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="self_t-spec"></a>Class <code>self_ns::self_t</code></h3> - - <p><code>self_ns::self_t</code> is the actual type of the <a href= - "#self-spec"><code>self</code></a> object. The library isolates - <code>self_t</code> in its own namespace, <code>self_ns</code>, in order - to prevent the generalized operator templates which operate on it from - being found by argument-dependent lookup in other contexts. This should - be considered an implementation detail, since users should never have to - mention <code>self_t</code> directly.</p> - - <h4><a name="self_t-spec-synopsis"></a>Class <code>self_ns::self_t</code> - synopsis</h4> -<pre> -namespace boost { namespace python { namespace self_ns { -{ - <i>unspecified-type-declaration</i> self_t; - - // inplace operators - template <class T> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator+=(self_t, T); - template <class T> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator-=(self_t, T); - template <class T> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator*=(self_t, T); - template <class T> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator/=(self_t, T); - template <class T> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator%=(self_t, T); - template <class T> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator>>=(self_t, T); - template <class T> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator<<=(self_t, T); - template <class T> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator&=(self_t, T); - template <class T> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator^=(self_t, T); - template <class T> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator|=(self_t, T); - - // comparisons - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator==(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator!=(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator<(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator>(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator<=(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator>=(L const&, R const&); - - // non-member operations - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator+(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator-(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator*(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator/(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator%(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator>>(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator<<(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator&(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator^(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator|(L const&, R const&); - template <class L, class R> <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> pow(L const&, R const&); - - // unary operations - <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator-(self_t); - <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator+(self_t); - <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator~(self_t); - <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> operator!(self_t); - - // value operations - <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> int_(self_t); - <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> long_(self_t); - <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> float_(self_t); - <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> complex_(self_t); - <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> str(self_t); - - <a href= -"#operator_-spec">operator_</a><<i>unspecified</i>> repr(self_t); - -}}}; -</pre> - The tables below describe the methods generated when the results of the - expressions described are passed as arguments to <a href= - "class.html#class_-spec-modifiers">class_<>::def()</a>. - <code><b>x</b></code> is an object of the class type being wrapped. - - <h4><a name="self_t-spec-inplace"></a>Class <code>self_t</code> inplace - operators</h4> - In the table below, If <code><b>r</b></code> is an object of type - <code><a href="#other-spec">other</a><T></code>, - <code><b>y</b></code> is an object of type <code>T</code>; otherwise, - <code><b>y</b></code> is an object of the same type as - <code><b>r</b></code>. - - <table border="1" summary="self_t inplace operators"> - <tr> - <th>C++ Expression</th> - - <th>Python Method Name</th> - - <th>C++ Implementation</th> - </tr> - - <tr> - <td><code>self += r</code></td> - - <td><code>__iadd__</code></td> - - <td><code>x += y</code></td> - </tr> - - <tr> - <td><code>self -= r</code></td> - - <td><code>__isub__</code></td> - - <td><code>x -= y</code></td> - </tr> - - <tr> - <td><code>self *= r</code></td> - - <td><code>__imul__</code></td> - - <td><code>x *= y</code></td> - </tr> - - <tr> - <td><code>self /= r</code></td> - - <td><code>__idiv__</code></td> - - <td><code>x /= y</code></td> - </tr> - - <tr> - <td><code>self %= r</code></td> - - <td><code>__imod__</code></td> - - <td><code>x %= y</code></td> - </tr> - - <tr> - <td><code>self >>= r</code></td> - - <td><code>__irshift__</code></td> - - <td><code>x >>= y</code></td> - </tr> - - <tr> - <td><code>self <<= r</code></td> - - <td><code>__ilshift__</code></td> - - <td><code>x <<= y</code></td> - </tr> - - <tr> - <td><code>self &= r</code></td> - - <td><code>__iand__</code></td> - - <td><code>x &= y</code></td> - </tr> - - <tr> - <td><code>self ^= r</code></td> - - <td><code>__ixor__</code></td> - - <td><code>x ^= y</code></td> - </tr> - - <tr> - <td><code>self |= r</code></td> - - <td><code>__ior__</code></td> - - <td><code>x |= y</code></td> - </tr> - </table> - - <h4><a name="self_t-spec-comparisons"></a>Class <code>self_t</code> - comparison functions</h4> - In the tables below, if <code><b>r</b></code> is of type <code><a href= - "#self_t-spec">self_t</a></code>, <code><b>y</b></code> is an object of - the same type as <code>x</code>; <br> - if <code><b>l</b></code> or <code><b>r</b></code> is an object of type - <code><a href="#other-spec">other</a><T></code>, - <code><b>y</b></code> is an object of type <code>T</code>; <br> - otherwise, <code><b>y</b></code> is an object of the same type as - <code><b>l</b></code> or <code><b>r</b></code>.<br> - <code><b>l</b></code> is never of type <code><a href= - "#self_t-spec">self_t</a></code>. - - <p>The column of <b>Python Expressions</b> illustrates the expressions - that will be supported in Python for objects convertible to the types of - <code>x</code> and <code>y</code>. The secondary operation arises due to - Python's <a href= - "http://www.python.org/doc/ref/customization.html#l2h-89">reflection - rules</a> for rich comparison operators, and are only used when the - corresponding operation is not defined as a method of the <code>y</code> - object.</p> - - <table border="1" summary="self_t comparison functions"> - <tr> - <th>C++ Expression</th> - - <th>Python Method Name</th> - - <th>C++ Implementation</th> - - <th>Python Expressions<br> - (primary, secondary)</th> - </tr> - - <tr> - <td><code>self == r</code></td> - - <td><code>__eq__</code></td> - - <td><code>x == y</code></td> - - <td><code>x == y, y == x</code></td> - </tr> - - <tr> - <td><code>l == self</code></td> - - <td><code>__eq__</code></td> - - <td><code>y == x</code></td> - - <td><code>y == x, x == y</code></td> - </tr> - - <tr> - <td><code>self != r</code></td> - - <td><code>__ne__</code></td> - - <td><code>x != y</code></td> - - <td><code>x != y, y != x</code></td> - </tr> - - <tr> - <td><code>l != self</code></td> - - <td><code>__ne__</code></td> - - <td><code>y != x</code></td> - - <td><code>y != x, x != y</code></td> - </tr> - - <tr> - <td><code>self < r</code></td> - - <td><code>__lt__</code></td> - - <td><code>x < y</code></td> - - <td><code>x < y, y > x</code></td> - </tr> - - <tr> - <td><code>l < self</code></td> - - <td><code>__gt__</code></td> - - <td><code>y < x</code></td> - - <td><code>y > x, x < y</code></td> - </tr> - - <tr> - <td><code>self > r</code></td> - - <td><code>__gt__</code></td> - - <td><code>x > y</code></td> - - <td><code>x > y, y < x</code></td> - </tr> - - <tr> - <td><code>l > self</code></td> - - <td><code>__lt__</code></td> - - <td><code>y > x</code></td> - - <td><code>y < x, x > y</code></td> - </tr> - - <tr> - <td><code>self <= r</code></td> - - <td><code>__le__</code></td> - - <td><code>x <= y</code></td> - - <td><code>x <= y, y >= x</code></td> - </tr> - - <tr> - <td><code>l <= self</code></td> - - <td><code>__ge__</code></td> - - <td><code>y <= x</code></td> - - <td><code>y >= x, x <= y</code></td> - </tr> - - <tr> - <td><code>self >= r</code></td> - - <td><code>__ge__</code></td> - - <td><code>x >= y</code></td> - - <td><code>x >= y, y <= x</code></td> - </tr> - - <tr> - <td><code>l >= self</code></td> - - <td><code>__le__</code></td> - - <td><code>y >= x</code></td> - - <td><code>y <= x, x >= y</code></td> - </tr> - </table> - - <h4><a name="self_t-spec-ops"></a>Class <code>self_t</code> non-member - operations</h4> - The operations whose names begin with "<code>__r</code>" below will only - be called if the left-hand operand does not already support the given - operation, as described <a href= - "http://www.python.org/doc/current/ref/numeric-types.html#l2h-152">here</a>. - - - <table border="1" summary="self_t non-member operations"> - <tr> - <th>C++ Expression</th> - - <th>Python Method Name</th> - - <th>C++ Implementation</th> - </tr> - - <tr> - <td><code>self + r</code></td> - - <td><code>__add__</code></td> - - <td><code>x + y</code></td> - </tr> - - <tr> - <td><code>l + self</code></td> - - <td><code>__radd__</code></td> - - <td><code>y + x</code></td> - </tr> - - <tr> - <td><code>self - r</code></td> - - <td><code>__sub__</code></td> - - <td><code>x - y</code></td> - </tr> - - <tr> - <td><code>l - self</code></td> - - <td><code>__rsub__</code></td> - - <td><code>y - x</code></td> - </tr> - - <tr> - <td><code>self * r</code></td> - - <td><code>__mul__</code></td> - - <td><code>x * y</code></td> - </tr> - - <tr> - <td><code>l * self</code></td> - - <td><code>__rmul__</code></td> - - <td><code>y * x</code></td> - </tr> - - <tr> - <td><code>self / r</code></td> - - <td><code>__div__</code></td> - - <td><code>x / y</code></td> - </tr> - - <tr> - <td><code>l / self</code></td> - - <td><code>__rdiv__</code></td> - - <td><code>y / x</code></td> - </tr> - - <tr> - <td><code>self % r</code></td> - - <td><code>__mod__</code></td> - - <td><code>x % y</code></td> - </tr> - - <tr> - <td><code>l % self</code></td> - - <td><code>__rmod__</code></td> - - <td><code>y % x</code></td> - </tr> - - <tr> - <td><code>self >> r</code></td> - - <td><code>__rshift__</code></td> - - <td><code>x >> y</code></td> - </tr> - - <tr> - <td><code>l >> self</code></td> - - <td><code>__rrshift__</code></td> - - <td><code>y >> x</code></td> - </tr> - - <tr> - <td><code>self << r</code></td> - - <td><code>__lshift__</code></td> - - <td><code>x << y</code></td> - </tr> - - <tr> - <td><code>l << self</code></td> - - <td><code>__rlshift__</code></td> - - <td><code>y << x</code></td> - </tr> - - <tr> - <td><code>self & r</code></td> - - <td><code>__and__</code></td> - - <td><code>x & y</code></td> - </tr> - - <tr> - <td><code>l & self</code></td> - - <td><code>__rand__</code></td> - - <td><code>y & x</code></td> - </tr> - - <tr> - <td><code>self ^ r</code></td> - - <td><code>__xor__</code></td> - - <td><code>x ^ y</code></td> - </tr> - - <tr> - <td><code>l ^ self</code></td> - - <td><code>__rxor__</code></td> - - <td><code>y ^ x</code></td> - </tr> - - <tr> - <td><code>self | r</code></td> - - <td><code>__or__</code></td> - - <td><code>x | y</code></td> - </tr> - - <tr> - <td><code>l | self</code></td> - - <td><code>__ror__</code></td> - - <td><code>y | x</code></td> - </tr> - - <tr> - <td><code>pow(self, r)</code></td> - - <td><code>__pow__</code></td> - - <td><code>pow(x, y)</code></td> - </tr> - - <tr> - <td><code>pow(l, self)</code></td> - - <td><code>__rpow__</code></td> - - <td><code>pow(y, x)</code></td> - </tr> - </table> - - <h4><a name="self_t-spec-value-unary-ops"></a>Class <code>self_t</code> unary - operations</h4> - - <table border="1" summary="self_t unary operations"> - <tr> - <th>C++ Expression</th> - - <th>Python Method Name</th> - - <th>C++ Implementation</th> - </tr> - - <tr> - <td><code>-self</code></td> - - <td><code>__neg__</code></td> - - <td><code>-x</code></td> - </tr> - - <tr> - <td><code>+self</code></td> - - <td><code>__pos__</code></td> - - <td><code>+x</code></td> - </tr> - - <tr> - <td><code>~self</code></td> - - <td><code>__invert__</code></td> - - <td><code>~x</code></td> - </tr> - - <tr> - <td><code>not self</code><br><i>or</i><br><code>!self</code></td> - - <td><code>__nonzero__</code></td> - - <td><code>!!x</code></td> - </tr> - </table> - - <h4><a name="self_t-spec-value-ops"></a>Class <code>self_t</code> value - operations</h4> - - <table border="1" summary="self_t value operations"> - <tr> - <th>C++ Expression</th> - - <th>Python Method Name</th> - - <th>C++ Implementation</th> - </tr> - - <tr> - <td><code>int_(self)</code></td> - - <td><code>__int__</code></td> - - <td><code>long(x)</code></td> - </tr> - - <tr> - <td><code>long_</code></td> - - <td><code>__long__</code></td> - - <td><code>PyLong_FromLong(x)</code></td> - </tr> - - <tr> - <td><code>float_</code></td> - - <td><code>__float__</code></td> - - <td><code>double(x)</code></td> - </tr> - - <tr> - <td><code>complex_</code></td> - - <td><code>__complex__</code></td> - - <td><code>std::complex<double>(x)</code></td> - </tr> - - <tr> - <td><code>str</code></td> - - <td><code>__str__</code></td> - - <td><code><a href= - "../../../conversion/lexical_cast.htm#lexical_cast">lexical_cast</a><std::string>(x)</code></td> - </tr> - - <tr> - <td><code>repr</code></td> - - <td><code>__repr__</code></td> - - <td><code><a href= - "../../../conversion/lexical_cast.htm#lexical_cast">lexical_cast</a><std::string>(x)</code></td> - </tr> - </table> - - <h3><a name="other-spec"></a>Class Template <code>other</code></h3> - - <p>Instances of <code>other<T></code> can be used in operator - expressions with <a href="#self-spec">self</a>; the result is equivalent - to the same expression with a <code>T</code> object in place of - <code>other<T></code>. Use <code>other<T></code> to prevent - construction of a <code>T</code> object in case it is heavyweight, when - no constructor is available, or simply for clarity.</p> - - <h4><a name="other-spec-synopsis"></a>Class Template other synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <class T> - struct other - { - }; -}} -</pre> - <!-- --> - - <h3><a name="operator_-spec"></a>Class Template - <code>detail::operator_</code></h3> - - <p>Instantiations of <code>detail::operator_<></code> are used as - the return type of operator expressions involving <code><a href= - "#self-spec">self</a></code>. This should be considered an implementation - detail and is only documented here as a way of showing how the result of - <code>self</code>-expressions match calls to <a href= - "class.html#class_-spec-modifiers">class_<>::def()</a>.</p> - - <h4><a name="operator_-spec-synopsis"></a>Class Template - <code>detail::operator_</code> synopsis</h4> -<pre> -namespace boost { namespace python { namespace detail -{ - template <<i>unspecified</i>> - struct operator_ - { - }; -}}} -</pre> - - <h2><a name="objects"></a>Objects</h2> - - <p><a name="self-spec"><code>self</code></a></p> -<pre> -namespace boost { namespace python -{ - using self_ns::self; -}} -</pre> - - <h2><a name="examples"></a>Example</h2> -<pre> -#include <boost/python/module.hpp> -#include <boost/python/class.hpp> -#include <boost/python/operators.hpp> -#include <boost/operators.hpp> - -struct number - : boost::<a href= -"../../../utility/operators.htm#grpd_oprs">integer_arithmetic</a><number> -{ - explicit number(long x_) : x(x_) {} - operator long() const { return x; } - - template <class T> - number& operator+=(T const& rhs) - { x += rhs; return *this; } - - template <class T> - number& operator-=(T const& rhs) - { x -= rhs; return *this; } - - template <class T> - number& operator*=(T const& rhs) - { x *= rhs; return *this; } - - template <class T> - number& operator/=(T const& rhs) - { x /= rhs; return *this; } - - template <class T> - number& operator%=(T const& rhs) - { x %= rhs; return *this; } - - long x; -}; - -using namespace boost::python; -BOOST_PYTHON_MODULE(demo) -{ - class_<number>("number", init<long>()) - // interoperate with self - .def(self += self) - .def(self + self) - .def(self -= self) - .def(self - self) - .def(self *= self) - .def(self * self) - .def(self /= self) - .def(self / self) - .def(self %= self) - .def(self % self) - - // Convert to Python int - .def(int_(self)) - - // interoperate with long - .def(self += long()) - .def(self + long()) - .def(long() + self) - .def(self -= long()) - .def(self - long()) - .def(long() - self) - .def(self *= long()) - .def(self * long()) - .def(long() * self) - .def(self /= long()) - .def(self / long()) - .def(long() / self) - .def(self %= long()) - .def(self % long()) - .def(long() % self) - ; -} -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 5 October, 2004 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/overloads.html b/libs/python/doc/v2/overloads.html deleted file mode 100644 index 783e8e5db1..0000000000 --- a/libs/python/doc/v2/overloads.html +++ /dev/null @@ -1,229 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/overloads.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/overloads.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href= - "#overload-dispatch-expression"><i>overload-dispatch-expressions</i></a></dt> - - <dt><a href= "#OverloadDispatcher-concept">OverloadDispatcher</a> concept</dt> - - <dt><a href="#macros">Macros</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href= - "#BOOST_PYTHON_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_FUNCTION_OVERLOADS</a></dt> - - <dt><a href= - "#BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</a></dt> - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>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</p> - - <h2><a name= - "overload-dispatch-expression"></a><i>overload-dispatch-expressions</i></h2> - - <p> - An <em>overload-dispatch-expression</em> is used to describe a - family of overloaded methods to be generated for an extension - class. It has the following properties: - - <blockquote> - <dl class="properties"> - <dt><b>docstring:</b> An <a href="definitions.html#ntbs">ntbs</a> - whose value will bound to the methods' <code>__doc__</code> - attribute</dt> - - <dt><b>keywords:</b> A <a href= - "args.html#keyword-expression">keyword-expression</a> which - will be used to name (a trailing subsequence of) the arguments - to the generated methods.</dt> - - <dt><b>call policies:</b> An instance of some type which models <a href= - "CallPolicies.html">CallPolicies</a>.</dt> - - <dt><b>minimum <a href="definitions.html#arity">arity</a></b> - The minimum number of arguments to be accepted by a generated - method overload.</dt> - - <dt><b>maximum <a href="definitions.html#arity">arity</a></b> - The maximum number of arguments to be accepted by a generated - method overload.</dt> - </dl> - </blockquote> - - <h2><a name="OverloadDispatcher-concept"></a>OverloadDispatcher Concept</h2> - - An OverloadDispatcher <code>X</code> is a class which has a - <em>minimum arity</em> and a <em>maximum arity</em>, and for which - the following following are valid <a - href="#overload-dispatch-expression"><em>overload-dispatch-expression</em></a>s, - with the same minimum and maximum arity as the OverloadDispatcher. - -<pre> -X() -X(docstring) -X(docstring, keywords) -X(keywords, docstring) -X()[policies] -X(docstring)[policies] -X(docstring, keywords)[policies] -X(keywords, docstring)[policies] -</pre> - -<ul> -<li>If <code>policies</code> are supplied, it must be an instance of a -type which models <a -href="CallPolicies.html#CallPolicies-concept">CallPolicies</a>, and -will be used as the result's call policies. Otherwise the result's -call policies will be an instance of <a -href="default_call_policies.html#default_call_policies-spec">default_call_policies</a>. - -<li>If <code>docstring</code> is supplied it must be an <a -href="definitions.html#ntbs">ntbs</a>, and will be used as the result's docstring. Otherwise the result has an empty docstring. - -<li>If <code>keywords</code> is supplied it must be the result of a <a - href= "args.html#keyword-expression">keyword-expression</a> - whose length is no greater than <code>X</code>'s maximum - arity, and will be used as the result's keywords. Otherwise - the result's keywords will be empty. -</ul> - - - - - <h2><a name="macros"></a>Macros</h2> - - <h3><a name= - "BOOST_PYTHON_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_FUNCTION_OVERLOADS(name, func_id, min_args, max_args)</a></h3> - Expands to the definition of an OverloadDispatcher called - <code>name</code> in the current scope which can be used to - generate the following function invocation: -<pre> -func_id(a<small><i>1</i></small>, a<small><i>2</i></small>,...a<small><i>i</i></small>); -</pre> - - for all <code>min_args</code> <= <i>i</i> <= <code>max_args</code>. - - <h3><a name= - "BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(name, member_name, min_args, max_args)</a></h3> - - Expands to the definition of an OverloadDispatcher called - <code>name</code> in the current scope which can be used to - generate the following function invocation: -<pre> -x.member_name(a<small><i>1</i></small>, a<small><i>2</i></small>,...a<small><i>i</i></small>); -</pre> - - for all <code>min_args</code> <= <i>i</i> <= - <code>max_args</code>, where <code>x</code> is a reference to an - object of class type. - - <h2><a name="examples"></a>Example(s)</h2> - -<pre> -#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) - -struct Y {}; -struct X -{ - Y& f(int x, double y = 4.25, char const* z = "wow") - { - return inner; - } - Y inner; -}; - -BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(f_member_overloads, f, 1, 3) - -BOOST_PYTHON_MODULE(args_ext) -{ - def("f", f, - f_overloads( - args("x", "y", "z"), "This is f's docstring" - )); - - - class_<Y>("Y") - ; - - class_<X>("X", "This is X's docstring") - .def("f1", &X::f, - f_member_overloads( - args("x", "y", "z"), "f's docstring" - )[return_internal_reference<>()] - ) - ; -} -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 15 April, 2003 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/pickle.html b/libs/python/doc/v2/pickle.html deleted file mode 100644 index 22e198d63b..0000000000 --- a/libs/python/doc/v2/pickle.html +++ /dev/null @@ -1,280 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> - <title>Boost.Python Pickle Support</title> -</head> - -<body> - <div> - <img src="../../../../boost.png" alt="boost.png (6897 bytes)" align= - "center" width="277" height="86" /> - <hr /> - - <h1>Boost.Python Pickle Support</h1>Pickle is a Python module for object - serialization, also known as persistence, marshalling, or flattening. - - <p>It is often necessary to save and restore the contents of an object to - a file. One approach to this problem is to write a pair of functions that - read and write data from a file in a special format. A powerful - alternative approach is to use Python's pickle module. Exploiting - Python's ability for introspection, the pickle module recursively - converts nearly arbitrary Python objects into a stream of bytes that can - be written to a file.</p> - - <p>The Boost Python Library supports the pickle module through the - interface as described in detail in the <a href= - "http://www.python.org/doc/current/lib/module-pickle.html">Python Library - Reference for pickle.</a> This interface involves the special methods - <tt>__getinitargs__</tt>, <tt>__getstate__</tt> and <tt>__setstate__</tt> - as described in the following. Note that Boost.Python is also fully - compatible with Python's cPickle module.</p> - <hr /> - - <h2>The Boost.Python Pickle Interface</h2>At the user level, the - Boost.Python pickle interface involves three special methods: - - <dl> - <dt><strong><tt>__getinitargs__</tt></strong></dt> - - <dd> - When an instance of a Boost.Python extension class is pickled, the - pickler tests if the instance has a <tt>__getinitargs__</tt> method. - This method must return a Python tuple (it is most convenient to use - a boost::python::tuple). When the instance is restored by the - unpickler, the contents of this tuple are used as the arguments for - the class constructor. - - <p>If <tt>__getinitargs__</tt> is not defined, <tt>pickle.load</tt> - will call the constructor (<tt>__init__</tt>) without arguments; - i.e., the object must be default-constructible.</p> - </dd> - - <dt><strong><tt>__getstate__</tt></strong></dt> - - <dd>When an instance of a Boost.Python extension class is pickled, the - pickler tests if the instance has a <tt>__getstate__</tt> method. This - method should return a Python object representing the state of the - instance.</dd> - - <dt><strong><tt>__setstate__</tt></strong></dt> - - <dd>When an instance of a Boost.Python extension class is restored by - the unpickler (<tt>pickle.load</tt>), it is first constructed using the - result of <tt>__getinitargs__</tt> as arguments (see above). - Subsequently the unpickler tests if the new instance has a - <tt>__setstate__</tt> method. If so, this method is called with the - result of <tt>__getstate__</tt> (a Python object) as the argument.</dd> - </dl>The three special methods described above may be <tt>.def()</tt>'ed - individually by the user. However, Boost.Python provides an easy to use - high-level interface via the - <strong><tt>boost::python::pickle_suite</tt></strong> class that also - enforces consistency: <tt>__getstate__</tt> and <tt>__setstate__</tt> - must be defined as pairs. Use of this interface is demonstrated by the - following examples. - <hr /> - - <h2>Examples</h2>There are three files in <tt>boost/libs/python/test</tt> - that show how to provide pickle support. - <hr /> - - <h3><a href="../../test/pickle1.cpp"><tt>pickle1.cpp</tt></a></h3>The C++ - class in this example can be fully restored by passing the appropriate - argument to the constructor. Therefore it is sufficient to define the - pickle interface method <tt>__getinitargs__</tt>. This is done in the - following way: - - <ul> - <li>1. Definition of the C++ pickle function: - <pre> - struct world_pickle_suite : boost::python::pickle_suite - { - static - boost::python::tuple - getinitargs(world const& w) - { - return boost::python::make_tuple(w.get_country()); - } - }; -</pre> - </li> - - <li>2. Establishing the Python binding: - <pre> - class_<world>("world", args<const std::string&>()) - // ... - .def_pickle(world_pickle_suite()) - // ... -</pre> - </li> - </ul> - <hr /> - - <h3><a href="../../test/pickle2.cpp"><tt>pickle2.cpp</tt></a></h3>The C++ - class in this example contains member data that cannot be restored by any - of the constructors. Therefore it is necessary to provide the - <tt>__getstate__</tt>/<tt>__setstate__</tt> pair of pickle interface - methods: - - <ul> - <li>1. Definition of the C++ pickle functions: - <pre> - struct world_pickle_suite : boost::python::pickle_suite - { - static - boost::python::tuple - getinitargs(const world& w) - { - // ... - } - - static - boost::python::tuple - getstate(const world& w) - { - // ... - } - - static - void - setstate(world& w, boost::python::tuple state) - { - // ... - } - }; -</pre> - </li> - - <li>2. Establishing the Python bindings for the entire suite: - <pre> - class_<world>("world", args<const std::string&>()) - // ... - .def_pickle(world_pickle_suite()) - // ... -</pre> - </li> - </ul> - - <p>For simplicity, the <tt>__dict__</tt> is not included in the result of - <tt>__getstate__</tt>. This is not generally recommended, but a valid - approach if it is anticipated that the object's <tt>__dict__</tt> will - always be empty. Note that the safety guard described below will catch - the cases where this assumption is violated.</p> - <hr /> - - <h3><a href="../../test/pickle3.cpp"><tt>pickle3.cpp</tt></a></h3>This - example is similar to <a href= - "../../test/pickle2.cpp"><tt>pickle2.cpp</tt></a>. However, the object's - <tt>__dict__</tt> is included in the result of <tt>__getstate__</tt>. - This requires a little more code but is unavoidable if the object's - <tt>__dict__</tt> is not always empty. - <hr /> - - <h2>Pitfall and Safety Guard</h2>The pickle protocol described above has - an important pitfall that the end user of a Boost.Python extension module - might not be aware of: - - <p><strong><tt>__getstate__</tt> is defined and the instance's - <tt>__dict__</tt> is not empty.</strong></p> - - <p>The author of a Boost.Python extension class might provide a - <tt>__getstate__</tt> method without considering the possibilities - that:</p> - - <ul> - <li>his class is used in Python as a base class. Most likely the - <tt>__dict__</tt> of instances of the derived class needs to be pickled - in order to restore the instances correctly.</li> - - <li>the user adds items to the instance's <tt>__dict__</tt> directly. - Again, the <tt>__dict__</tt> of the instance then needs to be - pickled.</li> - </ul> - - <p>To alert the user to this highly unobvious problem, a safety guard is - provided. If <tt>__getstate__</tt> is defined and the instance's - <tt>__dict__</tt> is not empty, Boost.Python tests if the class has an - attribute <tt>__getstate_manages_dict__</tt>. An exception is raised if - this attribute is not defined:</p> - <pre> - RuntimeError: Incomplete pickle support (__getstate_manages_dict__ not set) -</pre>To resolve this problem, it should first be established that the <tt> - __getstate__</tt> and <tt>__setstate__</tt> methods manage the - instances's <tt>__dict__</tt> correctly. Note that this can be done - either at the C++ or the Python level. Finally, the safety guard should - intentionally be overridden. E.g. in C++ (from <a href= - "../../test/pickle3.cpp"><tt>pickle3.cpp</tt></a>): - <pre> - struct world_pickle_suite : boost::python::pickle_suite - { - // ... - - static bool getstate_manages_dict() { return true; } - }; -</pre>Alternatively in Python: - <pre> - import your_bpl_module - class your_class(your_bpl_module.your_class): - __getstate_manages_dict__ = 1 - def __getstate__(self): - # your code here - def __setstate__(self, state): - # your code here -</pre> - <hr /> - - <h2>Practical Advice</h2> - - <ul> - <li>In Boost.Python extension modules with many extension classes, - providing complete pickle support for all classes would be a - significant overhead. In general complete pickle support should only be - implemented for extension classes that will eventually be pickled.</li> - - <li>Avoid using <tt>__getstate__</tt> if the instance can also be - reconstructed by way of <tt>__getinitargs__</tt>. This automatically - avoids the pitfall described above.</li> - - <li>If <tt>__getstate__</tt> is required, include the instance's - <tt>__dict__</tt> in the Python object that is returned.</li> - </ul> - <hr /> - - <h2>Light-weight alternative: pickle support implemented in Python</h2> - - <h3><a href="../../test/pickle4.cpp"><tt>pickle4.cpp</tt></a></h3>The - <tt>pickle4.cpp</tt> example demonstrates an alternative technique for - implementing pickle support. First we direct Boost.Python via the - <tt>class_::enable_pickling()</tt> member function to define only the - basic attributes required for pickling: - <pre> - class_<world>("world", args<const std::string&>()) - // ... - .enable_pickling() - // ... -</pre>This enables the standard Python pickle interface as described in the -Python documentation. By "injecting" a <tt>__getinitargs__</tt> method into -the definition of the wrapped class we make all instances pickleable: - <pre> - # import the wrapped world class - from pickle4_ext import world - - # definition of __getinitargs__ - def world_getinitargs(self): - return (self.get_country(),) - - # now inject __getinitargs__ (Python is a dynamic language!) - world.__getinitargs__ = world_getinitargs -</pre>See also the <a href= -"../tutorial/doc/html/python/techniques.html#python.extending_wrapped_objects_in_python"> - tutorial section</a> on injecting additional methods from Python. - <hr /> - © Copyright Ralf W. Grosse-Kunstleve 2001-2004. Distributed under the - Boost Software License, Version 1.0. (See accompanying file - LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - - <p>Updated: Feb 2004.</p> - </div> -</body> -</html> diff --git a/libs/python/doc/v2/platforms.html b/libs/python/doc/v2/platforms.html deleted file mode 100644 index ac984b43fc..0000000000 --- a/libs/python/doc/v2/platforms.html +++ /dev/null @@ -1,135 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - Known Working Platforms and Compilers</title> - </head> - - <body link="#0000ff" vlink="#800080"> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Known Working Platforms and Compilers</h2> - </td> - </tr> - </table> - <hr> - Please see - our <a - href="http://boost.sourceforge.net/regression-logs">regression - logs</a> for up-to-date information. Note that logs not marked - otherwise reflect the CVS state, not the condition of the release. - - <p> - Earlier versions of <b>Boost.Python</b> have been successfully - tested on the following platforms and compilers. - - <dl class="page-index"> - <dt>Unix Platforms:</dt> - - <dd> - <dl> - <dt>with Python <a href="http://www.python.org/2.2">2.2</a> and <a - href="http://www.python.org/2.2.2">2.2.2b1</a>:</dt> - - <dd> - <dl> - <dt><a href="http://gcc.gnu.org">GCC</a> 2.95.3, 2.96, 3.0.4, - 3.1, and 3.2 on <a href="http://www.redhat.com">RedHat Linux 7.3</a> - for Intel x86</dt> - - <dt>Tru64 CXX 6.5.1 on OSF v. 5.1 for Dec/Compaq - Alpha</dt> - - <dt> - MIPSPro 7.3.1.2m on <a href= - "http://www.sgi.com/software/irix6.5/">IRIX 6.5</a> for SGI - mips</dt> - - <dt><a href="http://gcc.gnu.org">GCC 3.1</a> on SunOS 5.8</dt> - </dl> - </dd> - - <dt>with Python <a href= - "http://www.python.org/2.2.1">2.2.1</a></dt> - - <dd> - <dl> - <dt>KCC 3.4d on OSF v. 5.1 for Dec/Compaq Alpha</dt> - - <dt>KCC 3.4d</a> on AIX</dt> - </dl> - </dd> - </dl> - <br> - </dd> - - <dt>Microsoft Windows XP Professional with Python <a href= - "http://www.python.org/2.2">2.2</a>, <a href= - "http://www.python.org/2.2.1">2.2.1</a>, and <a href= - "http://www.python.org/2.2.2">2.2.2b1</a>:</dt> - - <dd> - <dl> - <dt><a href= - "http://msdn.microsoft.com/visualc/default.asp">Microsoft Visual - C++</a> 6, 7, and 7.1 beta</dt> - - <dt><a href= - "http://msdn.microsoft.com/visualc/default.asp">Microsoft Visual - C++ 6</a> with <a href="http://www.stlport.org">STLPort - 4.5.3</a></dt> - - <dt><a href= - "http://www.metrowerks.com/MW/Develop/Desktop/Windows/Professional/Default.htm"> - Metrowerks CodeWarrior</a> 7.2, 8.0, 8.2 and 8.3 beta</dt> - - <dt><a href= - "http://www.intel.com/software/products/compilers/c60/">Intel - C++</a> 5.0, 6.0, and 7.0 beta</dt> - - <dt><a href= - "http://www.intel.com/software/products/compilers/c60/">Intel C++ - 5.0</a> with <a href="http://www.stlport.org">STLPort - 4.5.3</a></dt> - - <dt><a href="http://www.cygwin.com">Cygwin</a> <a href= - "http://gcc.gnu.org">GCC</a> 3.0.4 and 3.2</dt> - - <dt><a href="http://www.mingw.org">MinGW-1.1</a> (<a href= - "http://gcc.gnu.org">GCC 2.95.3-5</a>)</dt> - - <dt><a href="http://www.mingw.org">MinGW-2.0</a> (<a href= - "http://gcc.gnu.org">GCC 3.2</a>)</dt> - </dl> - </dd> - </dl> - <hr> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/pointee.html b/libs/python/doc/v2/pointee.html deleted file mode 100644 index 2dcec8c368..0000000000 --- a/libs/python/doc/v2/pointee.html +++ /dev/null @@ -1,119 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - <meta name="generator" content="HTML Tidy, see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/pointee.hpp></title> - - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/pointee.hpp></h2> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a> - - <dt><a href="#classes">Classes</a> - - <dd> - <dl class="page-index"> - <dt><a href="#pointee-spec">Class Template<code>pointee</code></a> - - <dd> - <dl class="page-index"> - <dt><a href="#pointee-spec-synopsis">Class Template - <code>pointee</code> synopsis</a> - </dl> - </dl> - - <dt><a href="#examples">Example</a> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><boost/python/pointee.hpp></code> introduces a - traits <a - href="../../../mpl/doc/refmanual/metafunction.html">metafunction</a> - template <code>pointee<T></code> that can be used to extract the "pointed-to" type from the type of a pointer or smart pointer. - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="pointee-spec"></a>Class Template <code>pointee<class T></code></h3> - - <p><code>pointee<T></code> is used by the <code><a - href="class.html#class_-spec">class_</a><...></code> - template to deduce the type being held when a pointer or smart - pointer type is used as its <code>HeldType</code> argument. - - <h4><a name="pointee-spec-synopsis"></a>Class Template - <code>pointee</code> synopsis</h4> -<pre> -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; - }; -} -</pre> - - - <h2><a name="examples"></a>Example</h2> - -Given a 3rd-party smart pointer type -<code>smart_pointer<T></code>, one might partially specialize -<code>pointee<smart_pointer<T> ></code> so that it can be -used as the <code>HeldType</code> for a class wrapper: - -<pre> -#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(...) - ... - ; -} -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - - - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002. </i> Distributed - under the Boost Software License, Version 1.0. (See accompanying file - LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</p> - - diff --git a/libs/python/doc/v2/progress_reports.html b/libs/python/doc/v2/progress_reports.html deleted file mode 100644 index 5a8b015a20..0000000000 --- a/libs/python/doc/v2/progress_reports.html +++ /dev/null @@ -1,47 +0,0 @@ -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<link rel="stylesheet" type="text/css" href="../boost.css"> -<title>Boost.Python - Progress Reports</title> -</head> -<body link="#0000ff" vlink="#800080"> -<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - <h2 align="center">Progress Reports</h2> - </td> - </tr> -</table> -<hr> - -Monthly progress reports are required as part of Boost Consulting's -contract with LLNL for Boost.Python development. These reports contain -a useful record of the project history, including the rationale for -design decisions and links to relevant discussions. - -<dl class="page-index"> - <dt><a href="feb2002.html">February 2002</a></dt> - <dt><a href="Mar2002.html">March 2002</a></dt> - <dt><a href="Apr2002.html">April 2002</a></dt> - <dt><a href="May2002.html">May 2002</a></dt> - <dt><a href="Jun2002.html">June 2002</a></dt> -</dl> -<hr> -<p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> -</p> -<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> - 2002. </i></p> -</body> -</html> diff --git a/libs/python/doc/v2/ptr.html b/libs/python/doc/v2/ptr.html deleted file mode 100644 index 4aca539158..0000000000 --- a/libs/python/doc/v2/ptr.html +++ /dev/null @@ -1,265 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - <meta name="generator" content="HTML Tidy, see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/ptr.hpp></title> - - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/ptr.hpp></h2> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a> - - <dt><a href="#functions">Functions</a> - <dd> - <dl class="page-index"> - <dt><a href="#ptr-spec">ptr</a> - </dl> - - <dt><a href="#classes">Classes</a> - <dd> - <dl class="page-index"> - <dt><a href="#pointer_wrapper-spec">Class template <code>pointer_wrapper</code></a> - - <dd> - <dl class="page-index"> - <dt><a href="#pointer_wrapper-spec-synopsis">Class template <code>pointer_wrapper</code> synopsis</a> - - <dt><a href="#pointer_wrapper-spec-types">Class - <code>pointer_wrapper</code> types</a> - - <dt><a href="#pointer_wrapper-spec-ctors">Class - <code>pointer_wrapper</code> constructors and destructor</a> - - <dt><a href="#pointer_wrapper-spec-observers">Class - <code>pointer_wrapper</code> observer functions</a> - - </dl> - </dl> - - <dt><a href="#metafunctions">Metafunctions</a> - <dd> - <dl class="page-index"> - <dt><a href="#is_pointer_wrapper-spec">Class template <code>is_pointer_wrapper</code></a> - - <dd> - <dl class="page-index"> - <dt><a href="#is_pointer_wrapper-spec-synopsis">Class template <code>is_pointer_wrapper</code> synopsis</a> - </dl> - - - <dt><a href="#unwrap_pointer-spec">Class template <code>unwrap_pointer</code></a> - - <dd> - <dl class="page-index"> - <dt><a href="#unwrap_pointer-spec-synopsis">Class template <code>unwrap_pointer</code> synopsis</a> - </dl> - - </dl> - - - <dt><a href="#examples">Example(s)</a> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><boost/python/ptr.hpp></code> defines the - <code>ptr()</code> function template, which allows users to - specify how to convert C++ pointer values to python in the context - of implementing overridable virtual functions, invoking Python - callable objects, or explicitly converting C++ objects to - Python. Normally, when passing pointers to Python callbacks, the - pointee is copied to ensure that the Python object - never holds a dangling reference. To specify that the new Python - object should merely contain a copy of a pointer <code>p</code>, - the user can pass <code><a href="#ptr-spec">ptr</a>(p)</code> instead of passing - <code>p</code> directly. This interface is meant to mirror the use - of <a href="../../../bind/ref.html"><code>boost::ref()</code></a>, - which can be similarly used to prevent copying of referents. - - <p><code>ptr(p)</code> returns an instance of <code><a - href="#pointer_wrapper-spec">pointer_wrapper<></a></code>, which - can be detected using the <code><a - href="#is_pointer_wrapper-spec">is_pointer_wrapper<></a></code> - metafunction; <code><a - href="#unwrap_pointer-spec">unwrap_pointer<></a></code> is a - metafunction which extracts the original pointer type from a - <code>pointer_wrapper<></code>. These classes can be thought - of as implementation details. - - <h2><a name="functions"></a>Functions</h2> -<pre> - -<a name="ptr-spec">template <class T></a> -pointer_wrapper<T> ptr(T x); -</pre> - - <dl class="ptr-semantics"> - <dt><b>Requires:</b> <code>T</code> is a pointer type. - - <dt><b>Returns:</b> <code><a href="#pointer_wrapper-spec">pointer_wrapper</a><T>(x)</code> - - <dt><b>Throws:</b> nothing. - </dl> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="pointer_wrapper-spec"></a>Class template <code>pointer_wrapper</code></h3> - - <p>A "type envelope" which is returned by <a - href="#ptr-spec">ptr()</a>, used to indicate reference semantics - for pointers passed to Python callbacks. - - <h4><a name="pointer_wrapper-spec-synopsis"></a>Class - <code>pointer_wrapper</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template<class Ptr> class pointer_wrapper - { - public: - typedef Ptr type; - - explicit pointer_wrapper(Ptr x); - operator Ptr() const; - Ptr get() const; - }; -}} -</pre> - - <h4><a name="pointer_wrapper-spec-types"></a>Class template <code>pointer_wrapper</code> types</h4> -<pre> -typedef Ptr type; -</pre> -The type of the pointer being wrapped. - - <h4><a name="pointer_wrapper-spec-ctors"></a>Class template <code>pointer_wrapper</code> constructors and - destructor</h4> -<pre> -explicit pointer_wrapper(Ptr x); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>Ptr</code> is a pointer type. - - <dt><b>Effects:</b> Stores <code>x</code> in a the <code>pointer_wrapper<></code>. - <dt><b>Throws:</b> nothing. - </dl> - - <h4><a name="pointer_wrapper-spec-observers"></a>Class template <code>pointer_wrapper</code> observer - functions</h4> -<pre> -operator Ptr() const; -Ptr get() const; -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> a copy of the stored pointer. - <dt><b>Rationale:</b> <code>pointer_wrapper</code> is intended - to be a stand-in for the actual pointer type, but sometimes it's - better to have an explicit way to retrieve the pointer. - </dl> - - <h2><a name="metafunctions"></a>Metafunctions</h2> - - <h3><a name="is_pointer_wrapper-spec"></a>Class template <code>is_pointer_wrapper</code></h3> - - <p>A unary metafunction whose <code>value</code> is true iff its - argument is a <code>pointer_wrapper<></code>. - - <h4><a name="is_pointer_wrapper-spec-synopsis"></a>Class template <code>is_pointer_wrapper</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template<class T> class is_pointer_wrapper - { - static <i>unspecified</i> value = ...; - }; -}} -</pre> - - - <dl class="metafunction-semantics"> - <dt><b>Returns:</b> <code>true</code> iff <code>T</code> is a - specialization of -<code>pointer_wrapper<></code>. -<dt><code>value</code> is an integral constant convertible to bool of -unspecified type - - </dl> - -<h3><a name="unwrap_pointer-spec"></a>Class template <code>unwrap_pointer</code></h3> - -A unary metafunction which extracts the wrapped pointer type from a -specialization of <code>pointer_wrapper<></code>. - - <h4><a name="unwrap_pointer-spec-synopsis"></a>Class template <code>unwrap_pointer</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template<class T> class unwrap_pointer - { - typedef <i>unspecified</i> type; - }; -}} -</pre> - - <dl class="metafunction-semantics"> - <dt><b>Returns:</b> <code>T::type</code> if <code>T</code> is a - specialization of -<code>pointer_wrapper<></code>, <code>T</code> otherwise - </dl> - - - <h2><a name="examples"></a>Example(s)</h2> - -This example illustrates the use of <code>ptr()</code> to prevent an -object from being copied: -<pre> -#include <boost/python/call.hpp> -#include <boost/python/ptr.hpp> - -class expensive_to_copy -{ - ... -}; - -void pass_as_arg(expensive_to_copy* x, PyObject* f) -{ - // call the Python function f, passing a Python object built around - // which refers to *x by-pointer. - // - // *** Note: ensuring that *x outlives the argument to f() is *** - // *** up to the user! Failure to do so could result in a crash! *** - - boost::python::call<void>(f, ptr(x)); -} -... -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - - - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002. </i> Distributed - under the Boost Software License, Version 1.0. (See accompanying file - LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</p> - diff --git a/libs/python/doc/v2/python.html b/libs/python/doc/v2/python.html deleted file mode 100644 index 9c4e27ec63..0000000000 --- a/libs/python/doc/v2/python.html +++ /dev/null @@ -1,110 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>This is a convenience header which #includes all of the public - interface headers that are part of the Boost.Python library</p> -<pre> -# include <args.hpp> -# include <args_fwd.hpp> -# include <back_reference.hpp> -# include <bases.hpp> -# include <borrowed.hpp> -# include <call.hpp> -# include <call_method.hpp> -# include <class.hpp> -# include <copy_const_reference.hpp> -# include <copy_non_const_reference.hpp> -# include <data_members.hpp> -# include <def.hpp> -# include <default_call_policies.hpp> -# include <dict.hpp> -# include <enum.hpp> -# include <errors.hpp> -# include <exception_translator.hpp> -# include <extract.hpp> -# include <handle.hpp> -# include <has_back_reference.hpp> -# include <implicit.hpp> -# include <init.hpp> -# include <instance_holder.hpp> -# include <iterator.hpp> -# include <list.hpp> -# include <long.hpp> -# include <lvalue_from_pytype.hpp> -# include <make_function.hpp> -# include <manage_new_object.hpp> -# include <module.hpp> -# include <numeric.hpp> -# include <object.hpp> -# include <object_protocol.hpp> -# include <object_protocol_core.hpp> -# include <operators.hpp> -# include <other.hpp> -# include <overloads.hpp> -# include <pointee.hpp> -# include <ptr.hpp> -# include <reference_existing_object.hpp> -# include <return_internal_reference.hpp> -# include <return_value_policy.hpp> -# include <scope.hpp> -# include <self.hpp> -# include <slice_nil.hpp> -# include <str.hpp> -# include <to_python_converter.hpp> -# include <to_python_indirect.hpp> -# include <to_python_value.hpp> -# include <tuple.hpp> -# include <type_id.hpp> -# include <with_custodian_and_ward.hpp> -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/pytype_function.html b/libs/python/doc/v2/pytype_function.html deleted file mode 100644 index fcc2a7f928..0000000000 --- a/libs/python/doc/v2/pytype_function.html +++ /dev/null @@ -1,370 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright Nikolay Mladenov 2007. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> - <meta http-equiv="Content-Type" content= - "text/html; charset=us-ascii"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - - <boost/python/doobject/pytype_function.hpp></title> -</head> - -<body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" - summary="header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width= - "277" alt="C++ Boost" src="../../../../boost.png" border= - "0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href= - "../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/converter/pytype_function.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#wrap_pytype-spec">Class - <code>wrap_pytype</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#wrap_pytype-spec-synopsis">Class - <code>wrap_pytype</code> synopsis</a></dt> - - </dl> - </dd> - </dl> - </dd> - - <dd> - <dl class="page-index"> - <dt><a href="#registered_pytype-spec">Class - <code>registered_pytype</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#registered_pytype-spec-synopsis">Class - <code>registered_pytype</code> synopsis</a></dt> - - </dl> - </dd> - </dl> - </dd> - - <dd> - <dl class="page-index"> - <dt><a href="#expected_from_python_type-spec">Class - <code>expected_from_python_type</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#expected_from_python_type-spec-synopsis">Class - <code>expected_from_python_type</code> synopsis</a></dt> - - </dl> - </dd> - </dl> - </dd> - - <dd> - <dl class="page-index"> - <dt><a href="#to_python_target_type-spec">Class - <code>to_python_target_type</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#to_python_target_type-spec-synopsis">Class - <code>to_python_target_type</code> synopsis</a></dt> - - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Examples</a></dt> - </dl> - <hr> - - <h2><a name="introduction" id= - "introduction"></a>Introduction</h2> - - <p>To support Pythonic signatures the converters should supply a <code>get_pytype</code> function - returning a pointer to the associated <code>PyTypeObject</code>. See for example - <a href="ResultConverter.html#ResultConverter-concept">ResultConverter</a> or - <a href="to_python_converter.html#to_python_converter-spec">to_python_converter</a>. - The classes in this header file are meant to be used when implmenting <code>get_pytype</code>. - There are also <code>_direct</code> versions of the templates of <code>class T</code> which - should be used with undecorated type parameter, expected to be in the conversion registry when the module loads. - </p> - - <h2><a name="classes" id="classes"></a>Classes</h2> - - <h3><a name="wrap_pytype-spec" id= - "wrap_pytype-spec"></a>Class - <code>wrap_pytype</code></h3> - - <p> - This template generates a static <code>get_pytype</code> member returning the template parameter. - </p> - - <h4><a name="wrap_pytype-spec-synopsis" id= - "wrap_pytype-spec-synopsis"></a>Class - <code>wrap_pytype</code> synopsis</h4> - <pre> -namespace boost { namespace python { namespace converter{ - - template < PyTypeObject const *pytype > - class wrap_pytype - { - public: - static PyTypeObject const *get_pytype(){return pytype; } - }; - -}}} -</pre> - - - <h3><a name="registered_pytype-spec" id= - "registered_pytype-spec"></a>Class - <code>registered_pytype</code></h3> - - <p> - This template should be used with template parameters which are (possibly decorated) - types exported to python using <a href="class.html"><code>class_</code></a>. - The generated a static <code>get_pytype</code> member - returns the corresponding python type. - </p> - - <h4><a name="registered_pytype-spec-synopsis" id= - "registered_pytype-spec-synopsis"></a>Class - <code>registered_pytype</code> synopsis</h4> - <pre> -namespace boost { namespace python { namespace converter{ - - template < class T > - class registered_pytype - { - public: - static PyTypeObject const *get_pytype(); - }; - -}}} -</pre> - - - <h3><a name="expected_from_python_type-spec" id= - "expected_from_python_type-spec"></a>Class - <code>expected_from_python_type</code></h3> - - <p> - This template generates a static <code>get_pytype</code> member which inspects the registered - <code>from_python</code> converters for the type <code>T</code> and returns a matching python type. - </p> - - <h4><a name="expected_from_python_type-spec-synopsis" id= - "expected_from_python_type-spec-synopsis"></a>Class - <code>expected_from_python_type</code> synopsis</h4> - <pre> -namespace boost { namespace python { namespace converter{ - - template < class T > - class expected_from_python_type - { - public: - static PyTypeObject const *get_pytype(); - }; - -}}} -</pre> - - - <h3><a name="to_python_target_type-spec" id= - "to_python_target_type-spec"></a>Class - <code>to_python_target_type</code></h3> - - <p> - This template generates a static <code>get_pytype</code> member returning the - python type to which T can be converted. - </p> - - <h4><a name="to_python_target_type-spec-synopsis" id= - "to_python_target_type-spec-synopsis"></a>Class - <code>to_python_target_type</code> synopsis</h4> - <pre> -namespace boost { namespace python { namespace converter{ - - template < class T > - class to_python_target_type - { - public: - static PyTypeObject const *get_pytype(); - }; - -}}} -</pre> - - - <h2><a name="examples" id="examples"></a>Examples</h2> - - This example presumes that someone has implemented the standard <a href= - "http://www.python.org/doc/2.2/ext/dnt-basics.html">noddy example - module</a> from the Python documentation, and placed the corresponding - declarations in <code>"noddy.h"</code>. Because - <code>noddy_NoddyObject</code> is the ultimate trivial extension type, - the example is a bit contrived: it wraps a function for which all - information is contained in the <i>type</i> of its return value. - - <h3>C++ module definition</h3> -<pre> -#include <boost/python/reference.hpp> -#include <boost/python/module.hpp> -#include "noddy.h" - -struct tag {}; -tag make_tag() { return tag(); } - -using namespace boost::python; - -struct tag_to_noddy -#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //unnecessary overhead if py signatures are not supported -: wrap_pytype<&noddy_NoddyType> //inherits get_pytype from wrap_pytype -#endif -{ - static PyObject* convert(tag const& x) - { - return PyObject_New(noddy_NoddyObject, &noddy_NoddyType); - } -}; - -BOOST_PYTHON_MODULE(to_python_converter) -{ - def("make_tag", make_tag); - to_python_converter<tag, tag_to_noddy -#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //invalid if py signatures are not supported - , true -#endif - >(); //"true" because tag_to_noddy has member get_pytype -} -</pre> - - -<p>The following example registers to and from python converters using the templates -<code>expected_from_python_type</code> and <code>to_pyhton_target_type</code>. -</p> -<pre> -#include <boost/python/module.hpp> -#include <boost/python/def.hpp> -#include <boost/python/extract.hpp> -#include <boost/python/to_python_converter.hpp> -#include <boost/python/class.hpp> - -using namespace boost::python; - -struct A -{ -}; - -struct B -{ - A a; - B(const A& a_):a(a_){} -}; - -// Converter from A to python int -struct BToPython -#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //unnecessary overhead if py signatures are not supported - : converter::to_python_target_type<A> //inherits get_pytype -#endif -{ - static PyObject* convert(const B& b) - { - return incref(object(b.a).ptr()); - } -}; - -// Conversion from python int to A -struct BFromPython -{ - BFromPython() - { - boost::python::converter::registry::push_back - ( &convertible - , &construct - , type_id< B >() -#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //invalid if py signatures are not supported - , &converter::expected_from_python_type<A>::get_pytype//convertible to A can be converted to B -#endif - ); - } - - static void* convertible(PyObject* obj_ptr) - { - extract<const A&> ex(obj_ptr); - if (!ex.check()) return 0; - return obj_ptr; - } - - static void construct( - PyObject* obj_ptr, - converter::rvalue_from_python_stage1_data* data) - { - void* storage = ( - (converter::rvalue_from_python_storage< B >*)data)-> storage.bytes; - - extract<const A&> ex(obj_ptr); - new (storage) B(ex()); - data->convertible = storage; - } -}; - - -B func(const B& b) { return b ; } - -BOOST_PYTHON_MODULE(pytype_function_ext) -{ - to_python_converter< B , BToPython -#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //invalid if py signatures are not supported - ,true -#endif - >(); //has get_pytype - BFromPython(); - - class_<A>("A") ; - - def("func", &func); - -} - - - ->>> from pytype_function_ext import * ->>> print func.__doc__ -func( (A)arg1) -> A : - C++ signature: - struct B func(struct B) -</pre> - - - <p><i>© Copyright <a href="mailto:nickm at sitius dot com">Nikolay Mladenov</a> 2007.</i></p> -</body> -</html> diff --git a/libs/python/doc/v2/raw_function.html b/libs/python/doc/v2/raw_function.html deleted file mode 100755 index 0ad4c37c24..0000000000 --- a/libs/python/doc/v2/raw_function.html +++ /dev/null @@ -1,118 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/raw_function.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/raw_function.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#raw_function-spec">raw_function</a></dt> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><a href="#raw_function-spec">raw_function</a>(...)</code> - is used to convert a function taking a <a - href="tuple.html#tuple-spec">tuple</a> and a <a - href="dict.html#dict-spec">dict</a> into a Python callable object - which accepts a variable number of arguments and arbitrary keyword - arguments. - - <h2><a name="functions"></a>Functions</h2> - <a name="raw_function-spec"></a>raw_function -<pre> -template <class F> -object raw_function(F f, std::size_t min_args = 0); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>f(tuple(), dict())</code> is - well-formed.</dt> - - <dt><b>Returns:</b> a <a href= - "http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-6">callable</a> object which requires at least <code>min_args</code> arguments. When called, the actual non-keyword arguments will be passed in a <a - href="tuple.html#tuple-spec">tuple</a> as the first argument to <code>f</code>, and the keyword arguments will be passed in a <a - href="dict.html#dict-spec">dict</a> as the second argument to <code>f</code>. - - </dd> - </dl> - - <h2><a name="examples"></a>Example</h2> -C++: -<pre> -#include <boost/python/def.hpp> -#include <boost/python/tuple.hpp> -#include <boost/python/dict.hpp> -#include <boost/python/module.hpp> -#include <boost/python/raw_function.hpp> - -using namespace boost::python; - -tuple raw(tuple args, dict kw) -{ - return make_tuple(args, kw); -} - -BOOST_PYTHON_MODULE(raw_test) -{ - def("raw", raw_function(raw)); -} -</pre> - -Python: -<pre> ->>> from raw_test import * - ->>> raw(3, 4, foo = 'bar', baz = 42) -((3, 4), {'foo': 'bar', 'baz': 42}) -</pre> - <p> - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 7 March, 2003 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/reference.html b/libs/python/doc/v2/reference.html deleted file mode 100644 index 5ebdad105e..0000000000 --- a/libs/python/doc/v2/reference.html +++ /dev/null @@ -1,1192 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - Reference</title> - - <style type="text/css"> - p.c3 {font-style: italic} - h2.c2 {text-align: center} - h1.c1 {text-align: center} - </style> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "reference"> - <tr> - <td valign="top" width="300"> - <h3><a href="http://www.boost.org"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> - - <h2 class="c2">Reference</h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="Reference"> - <dt><a href="#concepts">Concepts</a></dt> - - <dt><a href="#high_level">High Level Components</a></dt> - - <dt><a href="#object_wrappers">Object Wrappers</a></dt> - - <dt><a href="#invocation">Function Invocation and Creation</a></dt> - - <dd> - <dl class="index"> - <dt><a href="#models_of_call_policies">Models of - CallPolicies</a></dt> - - <dt><a href="#models_of_result_converter">Models of - ResultConverter</a></dt> - - <dt><a href="#result_converter_generators">Models of - ResultConverterGenerator</a></dt> - </dl> - </dd> - - <dt><a href="#type_conversion">To/From Python Type Conversion</a></dt> - - <dt><a href="#embedding">Embedding</a></dt> - - <dt><a href="#utility">Utility and Infrastructure</a></dt> - - <dt><a href="#topics">Topics</a></dt> - </dl> - <hr> - <!-- xxxxx --> - - <h2><a name="concepts">Concepts</a></h2> - - <dl class="index"> - <dt><a href= - "CallPolicies.html#CallPolicies-concept">CallPolicies</a></dt> - - <dt><a href= - "Dereferenceable.html#Dereferenceable-concept">Dereferenceable</a></dt> - - <dt><a href="Extractor.html#Extractor-concept">Extractor</a></dt> - - <dt><a href= - "HolderGenerator.html#HolderGenerator-concept">HolderGenerator</a></dt> - - <dt><a href= - "ResultConverter.html#ResultConverter-concept">ResultConverter</a></dt> - - <dt><a href= - "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a></dt> - - <dt><a href= - "ObjectWrapper.html#ObjectWrapper-concept">ObjectWrapper</a></dt> - - <dt><a href= - "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a></dt> - </dl> - - <h2><a name="high_level">High Level Components</a></h2> - - <dl> - <dt><a href="class.html">class.hpp/class_fwd.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="class.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="class.html#class_-spec">class_</a></dt> - - <dt><a href="class.html#bases-spec">bases</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="def.html">def.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="def.html#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="def.html#def-spec">def</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="def_visitor.html">def_visitor.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="def_visitor.html#classes">Classes</a></dt> - </dl> - </dd> - - <dt><a href="docstring_options.html">docstring_options.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="docstring_options.html#classes">Classes</a></dt> - </dl> - </dd> - - <dt><a href="enum.html">enum.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="enum.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="enum.html#enum_-spec">enum_</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="errors.html">errors.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="errors.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "errors.html#error_already_set-spec">error_already_set</a></dt> - </dl> - </dd> - - <dt><a href="errors.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "errors.html#handle_exception-spec">handle_exception</a></dt> - - <dt><a href= - "errors.html#expect_non_null-spec">expect_non_null</a></dt> - - <dt><a href= - "errors.html#throw_error_already_set-spec">throw_error_already_set</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href= - "exception_translator.html">exception_translator.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "exception_translator.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "exception_translator.html#register_exception_translator-spec">register_exception_translator</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="init.html">init.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="init.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="init.html#init-spec">init</a></dt> - - <dt><a href="init.html#optional-spec">optional</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="iterator.html">iterator.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="iterator.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="iterator.html#iterator-spec">iterator</a></dt> - - <dt><a href="iterator.html#iterators-spec">iterators</a></dt> - </dl> - </dd> - - <dt><a href="iterator.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href="iterator.html#range-spec">range</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="module.html">module.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="module.html#macros">Macros</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "module.html#BOOST_PYTHON_MODULE-spec">BOOST_PYTHON_MODULE</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="operators.html">operators.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="operators.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="operators.html#self_t-spec">self_t</a></dt> - - <dt><a href="operators.html#other-spec">other</a></dt> - - <dt><a href="operators.html#operator_-spec">operator_</a></dt> - </dl> - </dd> - - <dt><a href="operators.html#objects">Objects</a></dt> - - <dd> - <dl class="index"> - <dt><a href="operators.html#self-spec">self</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="scope.html">scope.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="scope.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="scope.html#scope-spec">scope</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="stl_iterator.html">stl_iterator.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="stl_iterator.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="stl_iterator.html#stl_input_iterator-spec">stl_input_iterator</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="wrapper.html">wrapper.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="wrapper.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="wrapper.html#override-spec">override</a></dt> - - <dt><a href="wrapper.html#wrapper-spec">wrapper</a></dt> - </dl> - </dd> - </dl> - </dd> - </dl> - - <h2><a name="object_wrappers">Object Wrappers</a></h2> - - <dl class="index"> - <dt><a href="dict.html">dict.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="dict.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="dict.html#dict-spec">dict</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="list.html">list.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="list.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="list.html#list-spec">list</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="long.html">long.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="long.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="long.html#long_-spec">long_</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="numeric.html">numeric.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="numeric.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="numeric.html#array-spec">numeric::array</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="object.html">object.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="object.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="object.html#object-spec">object</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="str.html">str.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="str.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="str.html#str-spec">str</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="tuple.html">tuple.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="tuple.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="tuple.html#tuple-spec">tuple</a></dt> - </dl> - </dd> - - <dt><a href="tuple.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href="tuple.html#make_tuple-spec">make_tuple</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="slice.html">slice.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="slice.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="slice.html#slice-spec">slice</a></dt> - </dl> - </dd> - </dl> - </dd> - </dl> - - <h2><a name="invocation">Function Invocation and Creation</a></h2> - - <dl class="index"> - <dt><a href="args.html">args.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="args.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href="args.html#args-spec">args</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="call.html">call.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="call.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href="call.html#call-spec">call</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="call_method.html">call_method.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="call_method.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "call_method.html#call_method-spec">call_method</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="data_members.html">data_members.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="data_members.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "data_members.html#make_getter-spec">make_getter</a></dt> - - <dt><a href= - "data_members.html#make_setter-spec">make_setter</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="make_function.html">make_function.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="make_function.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "make_function.html#make_function-spec">make_function</a></dt> - - <dt><a href= - "make_function.html#make_constructor-spec">make_constructor</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="overloads.html">overloads.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="overloads.html#macros">macros</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "overloads.html#BOOST_PYTHON_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_FUNCTION_OVERLOADS</a></dt> - - <dt><a href= - "overloads.html#BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="ptr.html">ptr.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="ptr.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href="ptr.html#ptr-spec">ptr</a></dt> - </dl> - </dd> - - <dt><a href="ptr.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "ptr.html#pointer_wrapper-spec">pointer_wrapper</a></dt> - </dl> - </dd> - - <dt><a href="ptr.html#metafunctions">MetaFunctions</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "ptr.html#is_pointer_wrapper-spec">is_pointer_wrapper</a></dt> - - <dt><a href= - "ptr.html#unwrap_pointer-spec">unwrap_pointer</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="raw_function.html">raw_function.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="raw_function.html#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href= - "raw_function.html#raw_function-spec">raw_function</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dd> - <a name="function_documentation"></a> - - <h3>Function documentation</h3> - - <dl class="index"> - <dt><a href= - "function_doc_signature.html">function_doc_signature.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "function_doc_signature.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "function_doc_signature.html#function_doc_signature_generator-spec">function_doc_signature_generator</a></dt> - - </dl> - </dd> - </dl> - </dd> - </dl> - <dl class="index"> - <dt><a href= - "pytype_function.html">pytype_function.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "pytype_function.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "pytype_function.html#wrap_pytype-spec">wrap_pytype</a></dt> - - </dl> - <dl class="index"> - <dt><a href= - "pytype_function.html#expected_from_python_type-spec">expected_from_python_type</a></dt> - - </dl> - <dl class="index"> - <dt><a href= - "pytype_function.html#to_python_target_type-spec">to_python_target_type</a></dt> - - </dl> - <dl class="index"> - <dt><a href= - "pytype_function.html#registered_pytype-spec">registered_pytype</a></dt> - - </dl> - </dd> - </dl> - </dd> - </dl> - </dd> - - <dd> - <a name="models_of_call_policies"></a> - - <h3>Models of CallPolicies</h3> - - <dl class="index"> - <dt><a href= - "default_call_policies.html">default_call_policies.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "default_call_policies.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "default_call_policies.html#default_call_policies-spec">default_call_policies</a></dt> - - <dt><a href= - "default_call_policies.html#default_result_converter-spec">default_result_converter</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="return_arg.html">return_arg.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="return_arg.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "return_arg.html#return_arg-spec">return_arg</a></dt> - - <dt><a href= - "return_arg.html#return_self-spec">return_self</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href= - "return_internal_reference.html">return_internal_reference.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "return_internal_reference.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "return_internal_reference.html#return_internal_reference-spec"> - return_internal_reference</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href= - "return_value_policy.html">return_value_policy.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="return_value_policy.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "return_value_policy.html#return_value_policy-spec">return_value_policy</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href= - "with_custodian_and_ward.html">with_custodian_and_ward.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "with_custodian_and_ward.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "with_custodian_and_ward.html#with_custodian_and_ward-spec"> - with_custodian_and_ward</a></dt> - - <dt><a href= - "with_custodian_and_ward.html#with_custodian_and_ward_postcall-spec"> - with_custodian_and_ward_postcall</a></dt> - </dl> - </dd> - </dl> - </dd> - </dl> - <a name="models_of_result_converter"></a> - - <h3>Models of ResultConverter</h3> - - <dl class="index"> - <dt><a href= - "to_python_indirect.html">to_python_indirect.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="to_python_indirect.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "to_python_indirect.html#to_python_indirect-spec">to_python_indirect</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="to_python_value.html">to_python_value.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="to_python_value.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "to_python_value.html#to_python_value-spec">to_python_value</a></dt> - </dl> - </dd> - </dl> - </dd> - </dl> - <a name="result_converter_generators"></a> - - <h3>Models of ResultConverterGenerator</h3> - - <dl class="index"> - <dt><a href= - "copy_const_reference.html">copy_const_reference.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "copy_const_reference.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "copy_const_reference.html#copy_const_reference-spec">copy_const_reference</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href= - "copy_non_const_reference.html">copy_non_const_reference.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "copy_non_const_reference.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "copy_non_const_reference.html#copy_non_const_reference-spec"> - copy_non_const_reference</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="manage_new_object.html">manage_new_object.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="manage_new_object.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "manage_new_object.html#manage_new_object-spec">manage_new_object</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href= - "reference_existing_object.html">reference_existing_object.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "reference_existing_object.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "reference_existing_object.html#reference_existing_object-spec"> - reference_existing_object</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="return_by_value.html">return_by_value.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="return_by_value.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "return_by_value.html#return_by_value-spec">return_by_value</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href= - "return_opaque_pointer.html">return_opaque_pointer.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "return_opaque_pointer.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "return_opaque_pointer.html#return_opaque_pointer-spec">return_opaque_pointer</a></dt> - </dl> - </dd> - </dl> - </dd> - </dl> - </dd> - </dl> - - <h2><a name="type_conversion">To/From Python Type Conversion</a></h2> - - <dl class="index"> - <dt><a href="extract.html">extract.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="extract.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="extract.html#extract-spec">extract</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="implicit.html">implicit.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="implicit.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "implicit.html#implicitly_convertible-spec">implicitly_convertible</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="lvalue_from_pytype.html">lvalue_from_pytype.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="lvalue_from_pytype.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "lvalue_from_pytype.html#lvalue_from_pytype-spec">lvalue_from_pytype</a></dt> - - <dt><a href= - "lvalue_from_pytype.html#extract_identity-spec">extract_identity</a></dt> - - <dt><a href= - "lvalue_from_pytype.html#extract_member-spec">extract_member</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href= - "opaque.html">opaque_pointer_converter.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "opaque.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "opaque.html#opaque-spec">opaque</a></dt> - </dl> - </dd> - - <dt><a href="opaque.html#macros">Macros</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "opaque.html#BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID-spec"> - BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="to_python_converter.html">to_python_converter.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="to_python_converter.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "to_python_converter.html#to_python_converter-spec">to_python_converter</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href= - "register_ptr_to_python.html">register_ptr_to_python.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "register_ptr_to_python.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "register_ptr_to_python.html#register_ptr_to_python-spec">register_ptr_to_python</a></dt> - </dl> - </dd> - </dl> - </dd> - </dl> - - <h2><a name="embedding">Embedding</a></h2> - - <dl class="index"> - <dt><a href="exec.html">exec.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="exec.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href="exec.html#eval-spec">eval</a></dt> - <dt><a href="exec.html#exec-spec">exec</a></dt> - <dt><a href="exec.html#exec_file-spec">exec_file</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="import.html">import.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="import.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href="import.html#import-spec">import</a></dt> - </dl> - </dd> - </dl> - </dd> - </dl> - - <h2><a name="utility">Utility and Infrastructure</a></h2> - - <dl> - <dt><a href="has_back_reference.html">has_back_reference.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="has_back_reference.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "has_back_reference.html#has_back_reference-spec">has_back_reference</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="instance_holder.html">instance_holder.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="instance_holder.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href= - "instance_holder.html#instance_holder-spec">instance_holder</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="pointee.html">pointee.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="pointee.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt>class template <a href= - "pointee.html#pointee-spec">pointee</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="python.html"><boost/python.hpp></a></dt> - - <dt><a href="handle.html">handle.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="handle.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="handle.html#handle-spec">handle</a></dt> - </dl> - </dd> - - <dt><a href="handle.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href="handle.html#borrowed-spec">borrowed</a></dt> - - <dt><a href="handle.html#allow_null-spec">allow_null</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="type_id.html">type_id.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="type_id.html#functions">Functions</a></dt> - - <dd> - <dl class="index"> - <dt><a href="type_id.html#type_id-spec">type_id</a></dt> - </dl> - </dd> - - <dt><a href="type_id.html#classes">Classes</a></dt> - - <dd> - <dl class="index"> - <dt><a href="type_id.html#type_info-spec">type_info</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="ssize_t.html">ssize_t.hpp</a></dt> - - <dd> - <dl class="index"> - <dt><a href="ssize_t.html#typedefs">Typedefs</a></dt> - - <dt><a href="ssize_t.html#constants">Constants</a></dt> - </dl> - </dd> - </dl> - - <h2><a name="topics">Topics</a></h2> - - <dl> - <dt><a href="callbacks.html">Calling Python Functions and - Methods</a></dt> - - <dt><a href="pickle.html">Pickle Support</a><br> - <a href="indexing.html">Indexing Support</a></dt> - </dl> - <hr> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 31 October, 2004 -<!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p class="c3">© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002 -.</p> - </body> -</html> - diff --git a/libs/python/doc/v2/reference_existing_object.html b/libs/python/doc/v2/reference_existing_object.html deleted file mode 100644 index 12e228f50e..0000000000 --- a/libs/python/doc/v2/reference_existing_object.html +++ /dev/null @@ -1,180 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - - <boost/python/reference_existing_object.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/reference_existing_object.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#reference_existing_object-spec">Class - <code>reference_existing_object</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#reference_existing_object-spec-synopsis">Class - <code>reference_existing_object</code> synopsis</a></dt> - - <dt><a href= - "#reference_existing_object-spec-metafunctions">Class - <code>reference_existing_object</code> metafunctions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="reference_existing_object-spec"></a>Class - <code>reference_existing_object</code></h3> - - <p><code>reference_existing_object</code> is a model of <a href= - "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> - which can be used to wrap C++ functions which return a reference or - pointer to a C++ object. When the wrapped function is called, the value - referenced by its return value is not copied. A new Python object is - created which contains a pointer to the referent, and no attempt is made - to ensure that the lifetime of the referent is at least as long as that - of the corresponding Python object. Thus, it can be <font color= - "#ff0000"><b>highly dangerous</b></font> to use - <code>reference_existing_object</code> without additional lifetime - management from such models of <a href= - "CallPolicies.html">CallPolicies</a> as <a href= - "with_custodian_and_ward.html#with_custodian_and_ward-spec">with_custodian_and_ward</a>. - This class is used in the implementation of <a href= - "return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a>.</p> - - <h4><a name="reference_existing_object-spec-synopsis"></a>Class - <code>reference_existing_object</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - struct reference_existing_object - { - template <class T> struct apply; - }; -}} -</pre> - - <h4><a name="reference_existing_object-spec-metafunctions"></a>Class - <code>reference_existing_object</code> metafunctions</h4> -<pre> -template <class T> struct apply -</pre> - - <dl class="metafunction-semantics"> - <dt><b>Requires:</b> <code>T</code> is <code>U&</code> or - <code>U*</code>for some <code>U</code>.</dt> - - <dt><b>Returns:</b> <code>typedef <a href= - "to_python_indirect.html#to_python_indirect-spec">to_python_indirect</a><T,V> - type</code>, where <code>V</code> is a class whose - static <code>execute</code> function constructs an instance - holder containing an <i>unowned</i> - <code>U*</code> pointing to the referent of the wrapped function's - return value.</dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - - <p>In C++:</p> -<pre> -#include <boost/python/module.hpp> -#include <boost/python/class.hpp> -#include <boost/python/reference_existing_object.hpp> -#include <boost/python/return_value_policy.hpp> -#include <utility> - -// classes to wrap -struct Singleton -{ - Singleton() : x(0) {} - - int exchange(int n) // set x and return the old value - { - std::swap(n, x); - return n; - } - - int x; -}; - -Singleton& get_it() -{ - static Singleton just_one; - return just_one; -} - -// Wrapper code -using namespace boost::python; -BOOST_PYTHON_MODULE(singleton) -{ - def("get_it", get_it, - return_value_policy<reference_existing_object>()); - - class_<Singleton>("Singleton") - .def("exchange", &Singleton::exchange) - ; -} -</pre> - In Python: -<pre> ->>> import singleton ->>> s1 = singleton.get_it() ->>> s2 = singleton.get_it() ->>> id(s1) == id(s2) # s1 and s2 are not the same object -0 ->>> s1.exchange(42) # but they reference the same C++ Singleton -0 ->>> s2.exchange(99) -42 -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/register_ptr_to_python.html b/libs/python/doc/v2/register_ptr_to_python.html deleted file mode 100644 index 5f660e18f0..0000000000 --- a/libs/python/doc/v2/register_ptr_to_python.html +++ /dev/null @@ -1,162 +0,0 @@ -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -<link rel="stylesheet" type="text/css" href="../boost.css"> -<title>Boost.Python - <register_ptr_to_python.hpp></title> -</head> -<body link="#0000ff" vlink="#800080"> -<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - <h2 align="center">Header <register_ptr_to_python.hpp></h2> - </td> - </tr> -</table> -<hr> -<h2>Contents</h2> -<dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - <dt><a href="#functions">Functions</a></dt> - <dl class="page-index"> - <dt><a href="#register_ptr_to_python-spec">register_ptr_to_python</a></dt> - </dl> - - <dt><a href="#examples">Example(s)</a></dt> - -</dl> -<hr> -<h2><a name="introduction"></a>Introduction</h2> -<p> - <code><boost/python/register_ptr_to_python.hpp></code> - supplies <code>register_ptr_to_python</code>, a function template - which registers a conversion for smart pointers to Python. The - resulting Python object holds a copy of the converted smart pointer, - but behaves as though it were a wrapped copy of the pointee. If - the pointee type has virtual functions and the class representing - its dynamic (most-derived) type has been wrapped, the Python object - will be an instance of the wrapper for the most-derived type. More than - one smart pointer type for a pointee's class can be registered. -</p> -<p> - Note that in order to convert a Python <code>X</code> object to a - <code>smart_ptr<X>&</code> (non-const reference), the embedded C++ - object must be held by <code>smart_ptr<X></code>, and that when wrapped - objects are created by calling the constructor from Python, how they are held - is determined by the <code>HeldType</code> parameter to - <code>class_<...></code> instances. -</p> - -<h2><a name="functions"></a>Functions</h2> -<pre> -<a name="register_ptr_to_python-spec">template <class P> -void register_ptr_to_python() -</pre> -<dl class="function-semantics"> - <dt><b>Requires:</b> <code>P</code> is <a href="Dereferenceable.html#Dereferenceable-concept">Dereferenceable</a>. - </dt> - <dt><b>Effects:</b> Allows conversions to-python of <code>P</code> - instances. - </dt> -</dl> - -<h2><a name="examples"></a>Example(s)</h2> - -<h3>C++ Wrapper Code</h3> - -Here is an example of a module that contains a class <code>A</code> with -virtual functions and some functions that work with -<code>boost::shared_ptr<A></code>. - -<pre> -struct A -{ - virtual int f() { return 0; } -}; - -shared_ptr<A> New() { return shared_ptr<A>( new A() ); } - -int Ok( const shared_ptr<A>& a ) { return a->f(); } - -int Fail( shared_ptr<A>& a ) { return a->f(); } - -struct A_Wrapper: A -{ - A_Wrapper(PyObject* self_): self(self_) {} - int f() { return call_method<int>(self, "f"); } - int default_f() { return A::f(); } - PyObject* self; -}; - -BOOST_PYTHON_MODULE(register_ptr) -{ - class_<A, A_Wrapper>("A") - .def("f", &A::f, &A_Wrapper::default_f) - ; - - def("New", &New); - def("Ok", &Call); - def("Fail", &Fail); - - register_ptr_to_python< shared_ptr<A> >(); -} -</pre> - -<h3>Python Code</h3> - -<pre> ->>> from register_ptr import * ->>> a = A() ->>> Ok(a) # ok, passed as shared_ptr<A> -0 ->>> Fail(a) # passed as shared_ptr<A>&, and was created in Python! -Traceback (most recent call last): - File "<stdin>", line 1, in ? -TypeError: bad argument type for built-in operation ->>> ->>> na = New() # now "na" is actually a shared_ptr<A> ->>> Ok(a) -0 ->>> Fail(a) -0 ->>> -</pre> - -If <code>shared_ptr<A></code> is registered as follows: - -<pre> - class_<A, A_Wrapper, shared_ptr<A> >("A") - .def("f", &A::f, &A_Wrapper::default_f) - ; -</pre> - -There will be an error when trying to convert <code>shared_ptr<A></code> to -<code>shared_ptr<A_Wrapper></code>: - -<pre> ->>> a = New() -Traceback (most recent call last): -File "<stdin>", line 1, in ? -TypeError: No to_python (by-value) converter found for C++ type: class boost::shared_ptr<struct A> ->>> -</pre> - -<p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 24 Jun, 2003 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> -</p> -<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> - 2002. </i></p> -</body> -</html> - - diff --git a/libs/python/doc/v2/return_arg.html b/libs/python/doc/v2/return_arg.html deleted file mode 100755 index 44cd58c24e..0000000000 --- a/libs/python/doc/v2/return_arg.html +++ /dev/null @@ -1,224 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/return_arg.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/return_arg.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#return_arg-spec">Class Template - <code>return_arg</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#return_arg-spec-synopsis">Class Template - <code>return_arg</code> synopsis</a></dt> - - <dt><a href="#return_arg-spec-statics">Class - <code>return_arg</code> static functions</a></dt> - </dl> - </dd> - - <dt><a href="#return_self-spec">Class Template - <code>return_self</code></a></dt> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - <code>return_arg</code> and <code>return_self</code> instantiations are - models of <a href="CallPolicies.html">CallPolicies</a> which return the - specified argument parameter (usually <code>*this</code>) of a wrapped - (member) function. - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="return_arg-spec"></a>Class template - <code>return_arg</code></h3> - - <table border="1" summary="return_arg template parameters"> - <caption> - <b><code>return_arg</code> template parameters</b> - </caption> - - <tr> - <th>Parameter</th> - - <th>Requirements</th> - - <th>Description</th> - - <th>Default</th> - </tr> - - <tr> - <td><code>arg_pos</code></td> - - <td>A positive compile-time constant of type - <code>std::size_t</code>.</td> - - <td>the position of the argument to be returned.</td> - - <td>1</td> - </tr> - - <tr> - <td><code>Base</code></td> - - <td>A model of <a href="CallPolicies.html">CallPolicies</a></td> - - <td>Used for policy composition. Any <code>result_converter</code> it - supplies will be overridden by <code>return_arg</code>, but its - <code>precall</code> and <code>postcall</code> policies are composed - as described here <a href= - "CallPolicies.html#composition">CallPolicies</a>.</td> - - <td><code><a href= - "default_call_policies.html#default_call_policies-spec">default_call_policies</a></code></td> - </tr> - </table> - - <h4><a name="return_arg-spec-synopsis"></a>Class template - <code>return_arg</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <size_t arg_pos=1, class Base = default_call_policies> - struct return_arg : Base - { - static PyObject* postcall(PyObject*, PyObject* result); - struct result_converter{ template <class T> struct apply; }; - template <class Sig> struct extract_return_type : mpl::at_c<Sig, arg_pos>{}; - - }; -}} -</pre> - - <h4><a name="return_arg-spec-statics"></a>Class <code>return_arg</code> - static functions</h4> -<pre> -PyObject* postcall(PyObject* args, PyObject* result); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code><a href= - "http://www.python.org/doc/2.2/api/tupleObjects.html#l2h-476">PyTuple_Check</a>(args) - != 0</code> and <code>PyTuple_Size(args) != 0</code></dt> - - <dt><b>Returns:</b> <code>PyTuple_GetItem(args,arg_pos-1)</code></dt> - </dl> - - <h3><a name="return_self-spec"></a>Class template - <code>return_self</code></h3> - - <h4>Class template <code>return_self</code> synopsis:</h4> -<pre> -namespace boost { namespace python -{ - template <class Base = default_call_policies> - struct return_self - : return_arg<1,Base> - {}; -}} -</pre> - - <h2><a name="examples"></a>Example</h2> - - <h3>C++ module definition</h3> -<pre> -#include <boost/python/module.hpp> -#include <boost/python/class.hpp> -#include <boost/python/return_arg.hpp> - -struct Widget -{ - Widget() :sensitive_(true){} - bool get_sensitive() const { return sensitive_; } - void set_sensitive(bool s) { this->sensitive_ = s; } - private: - bool sensitive_; -}; - -struct Label : Widget -{ - Label() {} - - std::string get_label() const { return label_; } - void set_label(const std::string &l){ label_ = l; } - - private: - std::string label_; -}; - -using namespace boost::python; -BOOST_PYTHON_MODULE(return_self_ext) -{ - class_<widget>("Widget") - .def("sensitive", &Widget::get_sensitive) - .def("sensitive", &Widget::set_sensitive, return_self<>()) - ; - - class_<Label, bases<Widget> >("Label") - .def("label", &Label::get_label) - .def("label", &Label::set_label, return_self<>()) - ; -} - - -</pre> - - <h3>Python code</h3> -<pre> ->>> from return_self_ext import * ->>> l1 = Label().label("foo").sensitive(false) ->>> l2 = Label().sensitive(false).label("foo") -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 19 July, 2003 <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> and Nikolay - Mladenov 2003. </i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/return_by_value.html b/libs/python/doc/v2/return_by_value.html deleted file mode 100644 index 12ca3c43fd..0000000000 --- a/libs/python/doc/v2/return_by_value.html +++ /dev/null @@ -1,149 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/return_by_value.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/return_by_value.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#return_by_value-spec">Class - <code>return_by_value</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#return_by_value-spec-synopsis">Class - <code>return_by_value</code> synopsis</a></dt> - - <dt><a href="#return_by_value-spec-metafunctions">Class - <code>return_by_value</code> metafunctions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="return_by_value-spec"></a>Class - <code>return_by_value</code></h3> - - <p><code>return_by_value</code> is a model of <a href= - "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> - which can be used to wrap C++ functions returning any reference or value - type such that the return value is copied into a new Python object.</p> - - <h4><a name="return_by_value-spec-synopsis"></a>Class - <code>return_by_value</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - struct return_by_value - { - template <class T> struct apply; - }; -}} -</pre> - - <h4><a name="return_by_value-spec-metafunctions"></a>Class - <code>return_by_value</code> metafunctions</h4> -<pre> -template <class T> struct apply -</pre> - - <dl class="metafunction-semantics"> - <dt><b>Returns:</b> <code>typedef <a href= - "to_python_value.html#to_python_value-spec">to_python_value</a><T> - type;</code></dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - - <h3>C++ Module Definition</h3> -<pre> -#include <boost/python/module.hpp> -#include <boost/python/class.hpp> -#include <boost/python/return_by_value.hpp> -#include <boost/python/return_value_policy.hpp> - -// classes to wrap -struct Bar { }; - -Bar global_bar; - -// functions to wrap: -Bar b1(); -Bar& b2(); -Bar const& b3(); - -// Wrapper code -using namespace boost::python; -template <class R> -void def_void_function(char const* name, R (*f)()) -{ - def(name, f, return_value_policy<return_by_value>()); -} - -BOOST_PYTHON_MODULE(my_module) -{ - class_<Bar>("Bar"); - def_void_function("b1", b1); - def_void_function("b2", b2); - def_void_function("b3", b3); -} -</pre> - - <h3>Python Code</h3> -<pre> ->>> from my_module import * ->>> b = b1() # each of these calls ->>> b = b2() # creates a brand ->>> b = b3() # new Bar object -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/return_internal_reference.html b/libs/python/doc/v2/return_internal_reference.html deleted file mode 100644 index 87c33f855b..0000000000 --- a/libs/python/doc/v2/return_internal_reference.html +++ /dev/null @@ -1,230 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - - <boost/python/return_internal_reference.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/return_internal_reference.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#return_internal_reference-spec">Class Template - <code>return_internal_reference</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#return_internal_reference-spec-synopsis">Class - Template <code>return_internal_reference</code> - synopsis</a></dt> - - <dt><a href="#return_internal_reference-spec-statics">Class - <code>return_internal_reference</code> static - functions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - <code>return_internal_reference</code> instantiations are models of <a - href="CallPolicies.html">CallPolicies</a> which allow pointers and - references to objects held internally by a free or member function - argument or from the target of a member function to be returned safely - without making a copy of the referent. The default for its first template - argument handles the common case where the containing object is the - target (<code>*this</code>) of a wrapped member function. - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="return_internal_reference-spec"></a>Class template - <code>return_internal_reference</code></h3> - - <table border="1" summary= - "return_internal_reference template parameters"> - <caption> - <b><code>return_internal_reference</code> template parameters</b> - </caption> - - <tr> - <th>Parameter</th> - - <th>Requirements</th> - - <th>Description</th> - - <th>Default</th> - </tr> - - <tr> - <td><code>owner_arg</code></td> - - <td>A positive compile-time constant of type - <code>std::size_t</code>.</td> - - <td>The index of the parameter which contains the object to which the - reference or pointer is being returned. If used to wrap a member - function, parameter 1 is the target object (<code>*this</code>). Note - that if the target Python object type doesn't support weak - references, a Python <code>TypeError</code> exception will be raised - when the function being wrapped is called.</td> - - <td>1</td> - </tr> - - <tr> - <td><code>Base</code></td> - - <td>A model of <a href="CallPolicies.html">CallPolicies</a></td> - - <td>Used for policy composition. Any <code>result_converter</code> it - supplies will be overridden by - <code>return_internal_reference</code>, but its <code>precall</code> - and <code>postcall</code> policies are composed as described here <a - href="CallPolicies.html#composition">CallPolicies</a>.</td> - - <td><code><a href= - "default_call_policies.html#default_call_policies-spec">default_call_policies</a></code></td> - </tr> - </table> - - <h4><a name="return_internal_reference-spec-synopsis"></a>Class template - <code>return_internal_reference</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <std::size_t owner_arg = 1, class Base = default_call_policies> - struct return_internal_reference : Base - { - static PyObject* postcall(PyObject*, PyObject* result); - typedef <a href= -"reference_existing_object.html#reference_existing_object-spec">reference_existing_object</a> result_converter; - }; -}} -</pre> - - <h4><a name="return_internal_reference-spec-statics"></a>Class - <code>return_internal_reference</code> static functions</h4> -<pre> -PyObject* postcall(PyObject* args, PyObject* result); -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code><a href= - "http://www.python.org/doc/2.2/api/tupleObjects.html#l2h-476">PyTuple_Check</a>(args) - != 0</code></dt> - - <dt><b>Returns:</b> <code><a href= - "with_custodian_and_ward.html#with_custodian_and_ward_postcall-spec-statics"> - with_custodian_and_ward_postcall::postcall(args, - result)</a></code></dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - - <h3>C++ module definition</h3> -<pre> -#include <boost/python/module.hpp> -#include <boost/python/class.hpp> -#include <boost/python/return_internal_reference.hpp> - -class Bar -{ - public: - Bar(int x) : x(x) {} - int get_x() const { return x; } - void set_x(int x) { this->x = x; } - private: - int x; -}; - -class Foo -{ - public: - Foo(int x) : b(x) {} - - // Returns an internal reference - Bar const& get_bar() const { return b; } - - private: - Bar b; -}; - -using namespace boost::python; -BOOST_PYTHON_MODULE(internal_refs) -{ - class_<Bar>("Bar", init<int>()) - .def("get_x", &Bar::get_x) - .def("set_x", &Bar::set_x) - ; - - class_<Foo>("Foo", init<int>()) - .def("get_bar", &Foo::get_bar - , return_internal_reference<>()) - ; -} -</pre> - - <h3>Python code</h3> -<pre> ->>> from internal_refs import * ->>> f = Foo(3) ->>> b1 = f.get_bar() ->>> b2 = f.get_bar() ->>> b1.get_x() -3 ->>> b2.get_x() -3 ->>> b1.set_x(42) ->>> b2.get_x() -42 -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/return_opaque_pointer.html b/libs/python/doc/v2/return_opaque_pointer.html deleted file mode 100644 index 52d8396e83..0000000000 --- a/libs/python/doc/v2/return_opaque_pointer.html +++ /dev/null @@ -1,192 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/return_opaque_pointer.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/return_opaque_pointer.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#return_opaque_pointer-spec">Class - <code>return_opaque_pointer</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#return_opaque_pointer-spec-synopsis">Class - <code>return_opaque_pointer</code> synopsis</a></dt> - - <dt><a href="#return_opaque_pointer-spec-metafunctions">Class - <code>return_opaque_pointer</code> metafunctions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - - <dt><a href="#see-also">See Also</a></dt> - </dl> - <hr> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="return_opaque_pointer-spec"></a>Class - <code>return_opaque_pointer</code></h3> - - <p><code>return_opaque_pointer</code> is a model of - <a href="ResultConverter.html#ResultConverterGenerator-concept"> - ResultConverterGenerator</a> - which can be used to wrap C++ functions returning pointers to - undefined types such that the return value is copied into a - new Python object.</p> - <p>In addition to specifying the <code>return_opaque_pointer</code> - policy the <a href="opaque.html#BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID-spec"> - <code>BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</code></a> macro must be - used to define specializations for the - <a href="type_id.html#type_id-spec">type_id</a> function - on the type pointed to by returned pointer.</p> - - <h4><a name="return_opaque_pointer-spec-synopsis"></a>Class - <code>return_opaque_pointer</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - struct return_opaque_pointer - { - template <class R> struct apply; - }; -}} -</pre> - - <h4><a name="return_opaque_pointer-spec-metafunctions"></a>Class - <code>return_opaque_pointer</code> metafunctions</h4> -<pre> -template <class R> struct apply -</pre> - - <dl class="metafunction-semantics"> - <dt><b>Returns:</b> <code>typedef - detail::opaque_conversion_holder<R> - type;</code></dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - - <h3>C++ Module Definition</h3> -<pre> -# include <boost/python/return_opaque_pointer.hpp> -# include <boost/python/def.hpp> -# include <boost/python/module.hpp> -# include <boost/python/return_value_policy.hpp> - -typedef struct opaque_ *opaque; - -opaque the_op = ((opaque) 0x47110815); - -opaque get () { return the_op; } -void use (opaque op) { - if (op != the_op) - throw std::runtime_error (std::string ("failed")); -} - -void failuse (opaque op) { - if (op == the_op) - throw std::runtime_error (std::string ("success")); -} - -BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID(opaque_) - -namespace bpl = boost::python; - -BOOST_PYTHON_MODULE(opaque_ext) -{ - bpl::def ( - "get", &::get, bpl::return_value_policy<bpl::return_opaque_pointer>()); - bpl::def ("use", &::use); - bpl::def ("failuse", &::failuse); -} -</pre> - - <h3>Python Code</h3> -<pre> -""" ->>> from opaque_ext import * ->>> # ->>> # Check for correct conversion ->>> use(get()) ->>> failuse(get()) -Traceback (most recent call last): - ... -RuntimeError: success ->>> # ->>> # Check that there is no conversion from integers ... ->>> use(0) -Traceback (most recent call last): - ... -TypeError: bad argument type for built-in operation ->>> # ->>> # ... and from strings to opaque objects ->>> use("") -Traceback (most recent call last): - ... -TypeError: bad argument type for built-in operation -""" -def run(args = None): - import sys - import doctest - - if args is not None: - sys.argv = args - return doctest.testmod(sys.modules.get(__name__)) - -if __name__ == '__main__': - print "running..." - import sys - sys.exit(run()[0]) -</pre> - - <h2><a name="see-also"></a>See Also</h2> - <p> - <a href="opaque.html"> - opaque</a> - </p> - - <p>Revised - 28 January, 2003 - </p> - - <p><i>© Copyright 2003 Haufe Mediengruppe. All Rights - Reserved.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/return_value_policy.html b/libs/python/doc/v2/return_value_policy.html deleted file mode 100644 index b02d4bc39d..0000000000 --- a/libs/python/doc/v2/return_value_policy.html +++ /dev/null @@ -1,167 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - - <boost/python/return_value_policy.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/return_value_policy.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#return_value_policy-spec">Class Template - <code>return_value_policy</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#return_value_policy-spec-synopsis">Class Template - <code>return_value_policy</code> synopsis</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - <code>return_value_policy</code> instantiations are simply models of <a - href="CallPolicies.html">CallPolicies</a> which are composed of a <a - href= - "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> - and optional <code>Base</code> <a href= - "CallPolicies.html">CallPolicies</a>. - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="return_value_policy-spec"></a>Class template - <code>return_value_policy</code></h3> - - <table border="1" summary="return_value_policy template parameters"> - <caption> - <b><code>return_value_policy</code> template parameters</b> - </caption> - - <tr> - <th>Parameter</th> - - <th>Requirements</th> - - <th>Default</th> - </tr> - - <tr> - <td><a href= - "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a></td> - - <td>A model of <a href= - "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a>.</td> - </tr> - - <tr> - <td><code>Base</code></td> - - <td>A model of <a href="CallPolicies.html">CallPolicies</a></td> - - <td><code><a href= - "default_call_policies.html#default_call_policies-spec">default_call_policies</a></code></td> - </tr> - </table> - - <h4><a name="return_value_policy-spec-synopsis"></a>Class template - <code>return_value_policy</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <class ResultConverterGenerator, class Base = default_call_policies> - struct return_value_policy : Base - { - typedef ResultConverterGenerator result_converter; - }; -}} -</pre> - - <h2><a name="examples"></a>Example</h2> - - <h3>C++ Module Definition</h3> -<pre> -#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(my_module) -{ - class_<Bar>("Bar"); - - class_<Foo>("Foo", init<int>()) - .def("get_bar", &Foo::get_bar - , return_value_policy<copy_const_reference>()) - ; -} -</pre> - - <h3>Python Code</h3> -<pre> ->>> from my_module import * ->>> f = Foo(3) # create a Foo object ->>> b = f.get_bar() # make a copy of the internal Bar object -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/scope.html b/libs/python/doc/v2/scope.html deleted file mode 100644 index 54ef67e3e9..0000000000 --- a/libs/python/doc/v2/scope.html +++ /dev/null @@ -1,173 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/scope.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/scope.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#scope-spec">Class <code>scope</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#scope-spec-synopsis">Class <code>scope</code> - synopsis</a></dt> - - <dt><a href="#scope-spec-ctors">Class <code>scope</code> - constructors and destructor</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>Defines facilities for querying and controlling the Python scope - (namespace) which will contain new wrapped classes and functions.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="scope-spec"></a>Class <code>scope</code></h3> - - <p>The <code>scope</code> 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 <code>scope</code> object - binds it to the associated global Python object. Constructing a - <code>scope</code> object with an argument changes the associated - global Python object to the one held by the argument, until the - lifetime of the <code>scope</code> object ends, at which time the - associated global Python object reverts to what it was before the - <code>scope</code> object was constructed.</p> - - <h4><a name="scope-spec-synopsis"></a>Class <code>scope</code> - synopsis</h4> -<pre> -namespace boost { namespace python -{ - class scope : public <a href= -"object.html#object-spec">object</a> - { - public: - scope(scope const&); - scope(object const&); - scope(); - ~scope() - private: - void operator=(scope const&); - }; -}} -</pre> - - <h4><a name="scope-spec-ctors"></a>Class <code>scope</code> constructors - and destructor</h4> -<pre> -explicit scope(scope const& x); -explicit scope(object const& x); -</pre> - Stores a reference to the current associated scope object, and sets the - associated scope object to the one referred to by <code>x.ptr()</code>. - The <code>object</code> base class is initialized with <code>x</code>. -<pre> -scope(); -</pre> - Stores a reference to the current associated scope object. The - <code>object</code> base class is initialized with the current associated - scope object. Outside any module initialization function, the current - associated Python object is <code>None</code>. -<pre> -~scope() -</pre> - Sets the current associated Python object to the stored object. - - <h2><a name="examples"></a>Example</h2> - The following example shows how scope setting can be used to define - nested classes. - - <p>C++ Module definition:</p> -<pre> -#include <boost/python/module.hpp> -#include <boost/python/class.hpp> -#include <boost/python/scope.hpp> -using namespace boost::python; - -struct X -{ - void f() {} - - struct Y { int g() { return 42; } }; -}; - -BOOST_PYTHON_MODULE(nested) -{ - // add some constants to the current (module) scope - scope().attr("yes") = 1; - scope().attr("no") = 0; - - // Change the current scope - scope outer - = class_<X>("X") - .def("f", &X::f) - ; - - // Define a class Y in the current scope, X - class_<X::Y>("Y") - .def("g", &X::Y::g) - ; -} -</pre> - Interactive Python: -<pre> ->>> import nested ->>> nested.yes -1 ->>> y = nested.X.Y() ->>> y.g() -42 -</pre> - - <p>Revised 09 October, 2002</p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/slice.html b/libs/python/doc/v2/slice.html deleted file mode 100644 index fb6b47c7e3..0000000000 --- a/libs/python/doc/v2/slice.html +++ /dev/null @@ -1,246 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> -<head> - <meta name="generator" - content="HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" - content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - <title>Boost.Python - <boost/python/slice.hpp></title> -</head> -<body> -<table border="0" cellpadding="7" cellspacing="0" width="100%" - summary="header"> - <tbody> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - <h2 align="center">Header <boost/python/slice.hpp></h2> - </td> - </tr> - </tbody> -</table> -<hr> -<h2>Contents</h2> -<dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - <dt><a href="#classes">Classes</a></dt> - <dd> - <dl class="page-index"> - <dt><a href="#slice-spec">Class <code>slice</code></a></dt> - <dd> - <dl class="page-index"> - <dt><a href="#slice-spec-synopsis">Class <code>slice</code> -synopsis</a></dt> - <dt><a href="#slice-spec-ctors">Class <code>slice</code> -constructors</a></dt> - <dt><a href="#slice-spec-observers">Class <code>slice</code> -observer functions</a></dt> - </dl> - </dd> - </dl> - </dd> - <dt><a href="#examples">Example(s)</a></dt> -</dl> -<hr> -<h2><a name="introduction"></a>Introduction</h2> -<p>Exposes a <a href="ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> -for the Python <a - href="http://www.python.org/doc/2.3.3/api/slice-objects.html">slice</a> -type.</p> -<h2><a name="classes"></a>Classes</h2> -<h3><a name="slice-spec"></a>Class <code>slice</code></h3> -<p>Exposes the extended slicing protocol by wrapping the built-in slice -type. The semantics of the constructors and member functions defined -below can be fully understood by reading the <a - href="ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept -definition. Since <code>slice</code> is publicly derived from <code><a - href="object.html#object-spec">object</a></code>, the public object -interface applies to <code>slice</code> instances as well.<br> -</p> -<h4><a name="slice-spec-synopsis"></a>Class <code>slice</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - class slice : public object - { - public: - slice(); // create an empty slice, equivalent to [::] - - template <typename Int1, typename Int2> - slice(Int1 start, Int2 stop); - - template <typename Int1, typename Int2, typename Int3> - slice(Int1 start, Int2 stop, Int3 step); - - // Access the parameters this slice was created with. - object start(); - object stop(); - object step(); - - // The return type of slice::get_indices() - template <typename RandomAccessIterator> - struct range - { - RandomAccessIterator start; - RandomAccessIterator stop; - int step; - }; - - template <typename RandomAccessIterator> - range<RandomAccessIterator> - get_indices( - RandomAccessIterator const& begin, - RandomAccessIterator const& end); - }; -}} -</pre> -<h4><a name="slice-spec-ctors"></a>Class <code>slice</code> -constructors<br> -</h4> -<pre>slice();<br></pre> -<dl class="function-semantics"> - <dt><b>Effects:</b> constructs a <code>slice</code> with default stop, start, and -step values. Equivalent to the slice object created as part of the Python -expression <code>base[::].</code></dt> - <dt><b>Throws:</b> nothing.</dt> -</dl> -<pre> -template <typename Int1, typename Int2> -slice(Int1 start, Int2 stop); -</pre> -<dl class="function-semantics"> - <dt><b>Requires:</b> <code>start</code>, <code>stop</code>, and <code>step</code> - are of type <code><a href="object.html#slice_nil-spec">slice_nil</a></code> - or convertible to type <code>object</code>.</dt> - <dt><b>Effects:</b> constructs a new slice with default step value -and the provided start and stop values. Equivalent to the slice -object -created by the built-in Python function <code><a - href="http://www.python.org/doc/current/lib/built-in-funcs.html#12h-62">slice(start,stop)</a></code>, -or as part of the Python expression <code>base[start:stop]</code>.</dt> - <dt><b>Throws:</b> <code>error_already_set</code> and sets a Python <code>TypeError</code> -exception if no conversion is possible from the arguments to type <code>object</code>.</dt> -</dl> -<pre> -template <typename Int1, typename Int2, typename Int3> -slice(Int1 start, Int2 stop, Int3 step); -</pre> - <dt><b>Requires:</b> <code>start</code>, <code>stop</code>, and <code>step</code> are <code>slice_nil</code> or convertible to type <code>object</code>.</dt> - <dt><b>Effects:</b> constructs a new slice with start stop and step -values. Equivalent to the slice object created -by the built-in Python function <code><a - href="http://www.python.org/doc/current/lib/built-in-funcs.html">slice(start,stop,step)</a></code>, -or as part of the Python expression <code>base[start:stop:step]</code>.</dt> - <dt><b>Throws:</b> <code>error_already_set</code> and sets a Python <code>TypeError</code> -exception if no conversion is possible from the arguments to type -object.</dt> -<h4><a name="slice-spec-observers"></a>Class <code>slice</code> -observer functions<br> -</h4> -<pre> -object slice::start() const; -object slice::stop() const; -object slice::step() const; -</pre> -<dl class="function-semantics"> - <dt><b>Effects:</b> None.</dt> - <dt><b>Throws:</b> nothing.</dt> - <dt><b>Returns:</b>the parameter that -the slice was created with. If the parameter was omitted or -slice_nil was used when the slice was created, than that parameter will -be a reference to PyNone and compare equal to a default-constructed -object. In principal, any object may be used when creating a -slice object, but in practice they are usually integers.</dt> -</dl> -<br> -<pre> -template <typename RandomAccessIterator> -slice::range<RandomAccessIterator> -slice::get_indices( - RandomAccessIterator const& begin, - RandomAccessIterator const& end) const; -</pre> -<dl class="function-semantics"> - <dt><b>Arguments:</b> A pair of STL-conforming Random Access -Iterators that form a half-open range.</dt> - <dt><b>Effects:</b> Create a RandomAccessIterator pair that defines a -fully-closed range within the [begin,end) range of its arguments. -This function translates this slice's indices while accounting for the -effects of any PyNone or negative indices, and non-singular step sizes.</dt> - <dt><b>Returns:</b> a slice::range -that has been initialized with a non-zero value of step and a pair of -RandomAccessIterators that point within the range of this functions -arguments and define a closed interval.</dt> - <dt><b>Throws:</b> <a href="definitions.html#raise">Raises</a> a Python <code>TypeError</code> exception if any of this slice's arguments -are neither references to <code>PyNone</code> nor convertible to <code>int</code>. Throws -<code>std::invalid_argument</code> if the resulting range would be empty. You -should always wrap calls to <code>slice::get_indices()</code> -within <code>try { ...; } catch (std::invalid_argument) {}</code> to -handle this case and take appropriate action.</dt> - <dt><b>Rationale</b>: closed-interval: If -an open interval were used, then for step -size other than 1, the required state for the end iterator would point -beyond the one-past-the-end position or before the beginning of the -specified range.<br> -exceptions on empty slice: It is impossible to define a closed interval -over an empty range, so some other form of error checking would have to -be used to prevent undefined behavior. In the case where the -exception is not caught, it will simply be translated to Python by the -default exception handling mechanisms. </dt> -</dl> -<h2><a name="examples"></a><b>Examples</b></h2> -<pre> -using namespace boost::python; - -// Perform an extended slice of a Python list. -// Warning: extended slicing was not supported for built-in types prior -// to Python 2.3 -list odd_elements(list l) -{ - return l[slice(_,_,2)]; -} - -// Perform a multidimensional extended slice of a Numeric.array -numeric::array even_columns(numeric::array arr) -{ - // select every other column, starting with the second, of a 2-D array. - // Equivalent to "return arr[:, 1::2]" in Python. - return arr[make_tuple( slice(), slice(1,_,2))]; -} - -// Perform a summation over a slice of a std::vector. -double partial_sum(std::vector<double> const& Foo, const slice index) -{ - slice::range<std::vector<double>::const_iterator> bounds; - try { - bounds = index.get_indices<>(Foo.begin(), Foo.end()); - } - catch (std::invalid_argument) { - return 0.0; - } - double sum = 0.0; - while (bounds.start != bounds.stop) { - sum += *bounds.start; - std::advance( bounds.start, bounds.step); - } - sum += *bounds.start; - return sum; -} -</pre> -<p>Revised 07 Febuary, 2004</p> -<p><i>© Copyright <a - href="mailto:jbrandmeyer@users.sourceforge.net">Jonathan Brandmeyer</a>, -2004. Modification, copying and redistribution of this document -is permitted under the terms and conditions of the Boost Software -License, version 1.0.<br> -</i></p> -</body> -</html> diff --git a/libs/python/doc/v2/ssize_t.html b/libs/python/doc/v2/ssize_t.html deleted file mode 100644 index cb4398bb58..0000000000 --- a/libs/python/doc/v2/ssize_t.html +++ /dev/null @@ -1,96 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<!-- Copyright Ralf W. Grosse-Kunstleve 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> - -<html> -<head> - <meta name="generator" content= - "HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org"> - <meta http-equiv="Content-Type" content= - "text/html; charset=us-ascii"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/ssize_t.hpp></title> -</head> - -<body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" - summary="header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width= - "277" alt="C++ Boost" src="../../../../boost.png" border= - "0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href= - "../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/ssize_t.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#typdefs">Typedef</a></dt> - - <dt><a href="#macros">Constants</a></dt> - </dl> - <hr> - - <h2><a name="introduction" id= - "introduction"></a>Introduction</h2> - - <p>Python 2.5 introduces a new <tt>Py_ssize_t</tt> typedef and - two related macros (<a href= - "http://www.python.org/dev/peps/pep-0353/">PEP 353</a>). The - <tt><boost/python/ssize_t.hpp></tt> header imports these - definitions into the <tt>boost::python</tt> namespace as - <tt>ssize_t</tt>, <tt>ssize_t_max</tt>, and <tt>ssize_t_min</tt>. - Appropriate definitions are provided for backward compatibility - with previous Python versions.</p> - - <h2><a name="typedefs" id="typedefs"></a>Typedefs</h2>Imports - <tt>Py_ssize_t</tt> into the <tt>boost::python</tt> namespace if - available, or provides an appropriate typedef for backward - compatibility: - <pre> -#if PY_VERSION_HEX >= 0x02050000 -typedef Py_ssize_t ssize_t; -#else -typedef int ssize_t; -#endif -</pre> - - <h2><a name="constants" id="constants"></a>Constants</h2>Imports - <tt>PY_SSIZE_T_MAX</tt> and <tt>PY_SSIZE_T_MIN</tt> as constants - into the <tt>boost::python</tt> namespace if available, or - provides appropriate constants for backward compatibility: - <pre> -#if PY_VERSION_HEX >= 0x02050000 -ssize_t const ssize_t_max = PY_SSIZE_T_MAX; -ssize_t const ssize_t_min = PY_SSIZE_T_MIN; -#else -ssize_t const ssize_t_max = INT_MAX; -ssize_t const ssize_t_min = INT_MIN; -#endif -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 25 September, 2006 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/ralf_w_grosse_kunstleve.htm">Ralf W. - Grosse-Kunstleve</a> 2006.</i></p> -</body> -</html> diff --git a/libs/python/doc/v2/stl_iterator.html b/libs/python/doc/v2/stl_iterator.html deleted file mode 100755 index ef197b0f82..0000000000 --- a/libs/python/doc/v2/stl_iterator.html +++ /dev/null @@ -1,273 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - - <title>Boost.Python - <boost/python/stl_iterator.hpp></title> - <meta name="generator" content= -"HTML Tidy for Windows (vers 1st August 2002), see www.w3.org" > - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= -header > - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/stl_iterator.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#stl_input_iterator-spec">Class template - <code>stl_input_iterator</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#stl_input_iterator-spec-synopsis">Class - <code>stl_input_iterator</code> synopsis</a></dt> - - <dt><a href="#stl_input_iterator-spec-constructors">Class template - <code>stl_input_iterator</code> constructors</a></dt> - - <dt><a href="#stl_input_iterator-spec-modifiers">Class template - <code>stl_input_iterator</code> modifiers</a></dt> - - <dt><a href="#stl_input_iterator-spec-observers">Class template - <code>stl_input_iterator</code> observers</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Examples</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><boost/python/stl_iterator.hpp></code> provides types - for creating <a href="http://www.sgi.com/tech/stl/Iterators.html">C++ - Iterators</a> from <a href="http://www.python.org/doc/current/lib/typeiter.html"> - Python iterables</a>.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="stl_input_iterator-spec"></a>Class Template - <code>stl_input_iterator</code></h3> - - <p>Instances of <code>stl_input_iterator<T></code> hold a Python - iterator and adapt it for use with STL algorithms. - <code>stl_input_iterator<T></code> satisfies the requirements for - an <a href="http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>. - </p> - - <table border="1" summary="stl_input_iterator template parameters"> - <tr> - <th>Template Parameter</th> - - <th>Requirements</th> - - <th>Semantics</th> - - <th>Default</th> - </tr> - - <tr> - <td><code>ValueType</code></td> - - <td><code>ValueType</code> must be CopyConstructible.</td> - - <td>Dereferencing an instance of <code>stl_input_iterator<ValueType></code> - will return an rvalue of type <code>ValueType</code>.</td> - - <td><i>None</i></td> - </tr> - </table> - - <h4><a name="stl_input_iterator-spec-synopsis"></a>Class Template stl_input_iterator - synopsis</h4> - -<pre> -namespace boost { namespace python -{ - template <class ValueType> - struct stl_input_iterator - { - typedef std::ptrdiff_t difference_type; - typedef ValueType value_type; - typedef ValueType* pointer; - typedef ValueType reference; - typedef std::input_iterator_tag iterator_category; - - stl_input_iterator(); - stl_input_iterator(<a href="object.html#object-spec">object</a> const& ob); - - stl_input_iterator& operator++(); - stl_input_iterator operator++(int); - - ValueType operator*() const; - - friend bool operator==(stl_input_iterator const& lhs, stl_input_iterator const& rhs); - friend bool operator!=(stl_input_iterator const& lhs, stl_input_iterator const& rhs); - private: - <a href="object.html#object-spec">object</a> it; // For exposition only - <a href="object.html#object-spec">object</a> ob; // For exposition only - }; -}} -</pre> - - <h4> - <a name="stl_input_iterator-spec-constructors"></a>Class Template <code>stl_input_iterator</code> - constructors - </h4> - -<pre> -stl_input_iterator() -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - Creates a past-the-end input iterator, useful for signifying the end of a sequence. - </dt> - <dt><b>Postconditions:</b> <code>this</code> is past-the-end.</dt> - <dt><b>Throws:</b> Nothing.</dt> - </dl> - -<pre> -stl_input_iterator(object const& ob) -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - Calls <code>ob.attr("__iter__")()</code> and stores the resulting Python iterator - object in <code>this->it</code>. Then, calls <code>this->it.attr("next")()</code> and - stores the result in <code>this->ob</code>. If the sequence is exhausted, sets - <code>this->ob</code> to <code>object()</code>. - </dt> - - <dt><b>Postconditions:</b> <code>this</code> is a dereferenceable or past-the-end.</dt> - </dl> - - <h4> - <a name="stl_input_iterator-spec-modifiers"></a>Class Template <code>stl_input_iterator</code> - modifiers - </h4> - -<pre> -stl_input_iterator& operator++() -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - Calls <code>this->it.attr("next")()</code> and stores the result in - <code>this->ob</code>. If the sequence is exhausted, sets <code>this->ob</code> - to <code>object()</code>. - </dt> - - <dt><b>Postconditions:</b> <code>this</code> is a dereferenceable or past-the-end.</dt> - - <dt><b>Returns:</b> <code>*this</code>.</dt> - </dl> - -<pre> -stl_input_iterator operator++(int) -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - <code>stl_input_iterator tmp = *this; ++*this; return tmp;</code> - </dt> - - <dt><b>Postconditions:</b> <code>this</code> is a dereferenceable or past-the-end.</dt> - </dl> - - <h4><a name="stl_input_iterator-spec-observers"></a>Class Template<code>stl_input_iterator</code> - observers</h4> - -<pre> -ValueType operator*() const -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - Returns the current element in the sequence. - </dt> - <dt><b>Returns:</b> - <code>extract<ValueType>(this->ob);</code> - </dt> - </dl> - -<pre> -friend bool operator==(stl_input_iterator const& lhs, stl_input_iterator const& rhs) -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - Returns true if both iterators are dereferenceable or if both iterators are past-the-end, - false otherwise. - </dt> - <dt><b>Returns:</b> - <code>(lhs.ob == object()) == (rhs.ob == object())</code> - </dt> - </dl> - -<pre> -friend bool operator!=(stl_input_iterator const& lhs, stl_input_iterator const& rhs) -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> - Returns false if both iterators are dereferenceable or if both iterators are past-the-end, - true otherwise. - </dt> - <dt><b>Returns:</b> - <code>!(lhs == rhs)</code> - </dt> - </dl> - - <h2><a name="examples"></a>Examples</h2> -<pre> -#include <boost/python/object.hpp> -#include <boost/python/stl_iterator.hpp> - -#include <list> - -using namespace boost::python; -std::list<int> sequence_to_int_list(object const& ob) -{ - stl_input_iterator<int> begin(ob), end; - return std::list<int>(begin, end); -} -</pre> - -<hr> - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->30 -October, 2005 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright Eric Niebler 2005.</i></p> - </body> -</html>
\ No newline at end of file diff --git a/libs/python/doc/v2/str.html b/libs/python/doc/v2/str.html deleted file mode 100644 index 11810d8418..0000000000 --- a/libs/python/doc/v2/str.html +++ /dev/null @@ -1,237 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/str.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/str.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#str-spec">Class <code>str</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#str-spec-synopsis">Class <code>str</code> - synopsis</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>Exposes a <a href= - "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> for the Python - <a href= - "http://www.python.org/dev/doc/devel/lib/string-methods.html">str</a> - type.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="str-spec"></a>Class <code>str</code></h3> - - <p>Exposes the <a href= - "http://www.python.org/dev/doc/devel/lib/string-methods.html">string - methods</a> of Python's built-in <code>str</code> type. The - semantics of the constructors and member functions defined below, - except for the two-argument constructors which construct str - objects from a range of characters, can be fully understood by - reading the <a href= - "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept - definition. Since <code>str</code> is publicly derived from - <code><a href="object.html#object-spec">object</a></code>, the - public object interface applies to <code>str</code> instances as - well.</p> - - <h4><a name="str-spec-synopsis"></a>Class <code>str</code> - synopsis</h4> -<pre> -namespace boost { namespace python -{ - class str : public object - { - public: - str(); // new str - - str(char const* s); // new str - - str(char const* start, char const* finish); // new str - str(char const* start, std::size_t length); // 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; - }; -}} -</pre> - - <h2><a name="examples"></a>Example</h2> -<pre> -using namespace boost::python; -str remove_angle_brackets(str x) -{ - return x.strip('<').strip('>'); -} -</pre> - - <p>Revised 3 October, 2002</p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/to_python_converter.html b/libs/python/doc/v2/to_python_converter.html deleted file mode 100644 index 81b61d252b..0000000000 --- a/libs/python/doc/v2/to_python_converter.html +++ /dev/null @@ -1,227 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - - <boost/python/to_python_converter.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/to_python_converter.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#to_python_converter-spec">Class Template - <code>to_python_converter</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#to_python_converter-spec-synopsis">Class Template - <code>to_python_converter</code> synopsis</a></dt> - - <dt><a href="#to_python_converter-spec-ctors">Class Template - <code>to_python_converter</code> constructor</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - <code>to_python_converter</code> registers a conversion from objects of a - given C++ type into a Python object. - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="to_python_converter-spec"></a>Class template - <code>to_python_converter</code></h3> - <code>to_python_converter</code> adds a wrapper around a static member - function of its second template parameter, handling low-level details - such as insertion into the converter registry. - - <table border="1" summary="to_python_converter template parameters"> - <caption> - <b><code>to_python_converter</code> template parameters</b><br> - In the table below, <b><code>x</code></b> denotes an object of type - <code>T</code> - </caption> - - <tr> - <th>Parameter</th> - - <th>Requirements</th> - - <th>Description</th> - </tr> - - <tr> - <td><code>T</code></td> - - <td> - </td> - - <td>The C++ type of the source object in the conversion</td> - </tr> - - <tr> - <td><code>Conversion</code></td> - - <td> - <code>PyObject* p = Conversion::convert(x)</code>,<br> - if <code>p == 0</code>, <code><a href= - "http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>() != 0</code>.</td> - - <td>A class type whose static member function <code>convert</code> - does the real work of the conversion.</td> - </tr> - <tr> - <td><code>bool has_get_pytype = false</code></td> - - <td> - <code>PyTypeObject const * p = Conversion::get_pytype() </code>.</td> - - <td><b>Optional member</b> - if <code>Conversion</code> has <code>get_pytype</code> member supply - <code>true</code> for this parameters. - If present <code>get_pytype</code> is used to document the return type - of functions using this conversion. The <code>get_pytype</code> may be implemented - using the classes and functions - from <a href="pytype_function.html"><code>pytype_function.hpp</code></a> - <b>NOTE :</b> For backward compatibility this parameter may be passed after - checking if <code>BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</code> is defined (see - <a href="pytype_function.html#examples">here</a>). - </td> - </tr> - </table> - - <h4><a name="to_python_converter-spec-synopsis"></a>Class template - <code>to_python_converter</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <class T, class Conversion, bool convertion_has_get_pytype_member=false> - struct to_python_converter - { - to_python_converter(); - }; -}} -</pre> - - <h4><a name="to_python_converter-spec-ctors"></a>Class template - <code>to_python_converter</code> constructor</h4> -<pre> -to_python_converter(); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> Registers a to_python converter which uses - <code>Conversion::convert()</code> to do its work.</dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - This example presumes that someone has implemented the standard <a href= - "http://www.python.org/doc/2.2/ext/dnt-basics.html">noddy example - module</a> from the Python documentation, and placed the corresponding - declarations in <code>"noddy.h"</code>. Because - <code>noddy_NoddyObject</code> is the ultimate trivial extension type, - the example is a bit contrived: it wraps a function for which all - information is contained in the <i>type</i> of its return value. - - <h3>C++ module definition</h3> -<pre> -#include <boost/python/reference.hpp> -#include <boost/python/module.hpp> -#include "noddy.h" - -struct tag {}; -tag make_tag() { return tag(); } - -using namespace boost::python; - -struct tag_to_noddy -{ - static PyObject* convert(tag const& x) - { - return PyObject_New(noddy_NoddyObject, &noddy_NoddyType); - } - static PyTypeObject const* get_pytype() - { - return &noddy_NoddyType; - } -}; - -BOOST_PYTHON_MODULE(to_python_converter) -{ - def("make_tag", make_tag); - to_python_converter<tag, tag_to_noddy, true>(); //"true" because tag_to_noddy has member get_pytype -} -</pre> - - <h3>Python code</h3> -<pre> ->>> import to_python_converter ->>> def always_none(): -... return None -... ->>> def choose_function(x): -... if (x % 2 != 0): -... return to_python_converter.make_tag -... else: -... return always_none -... ->>> a = [ choose_function(x) for x in range(5) ] ->>> b = [ f() for f in a ] ->>> type(b[0]) -<type 'NoneType'> ->>> type(b[1]) -<type 'Noddy'> ->>> type(b[2]) -<type 'NoneType'> ->>> type(b[3]) -<type 'Noddy'> -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 11 June, 2007 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/to_python_indirect.html b/libs/python/doc/v2/to_python_indirect.html deleted file mode 100644 index 17e0a826c4..0000000000 --- a/libs/python/doc/v2/to_python_indirect.html +++ /dev/null @@ -1,196 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - <meta name="generator" content="HTML Tidy, see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/to_python_indirect.hpp></title> - - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/to_python_indirect.hpp></h2> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a> - - - <dt><a href="#classes">Classes</a> - - <dd> - <dl class="page-index"> - <dt><a href="#to_python_indirect-spec">Class Template <code>to_python_indirect</code></a> - - <dd> - <dl class="page-index"> - - <dt><a href="#to_python_indirect-spec-synopsis">Class Template - <code>to_python_indirect</code> synopsis</a> - - <dt><a href="#to_python_indirect-spec-observers">Class Template - <code>to_python_indirect</code> observer functions</a> - - <dt><a href="#to_python_indirect-spec-statics">Class Template - <code>to_python_indirect</code> static functions</a> - </dl> - </dl> - - <dt><a href="#examples">Example</a> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <code><boost/python/to_python_indirect.hpp></code> supplies - a way to construct new Python objects that hold wrapped C++ class - instances via a pointer or smart pointer. - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="to_python_indirect-spec"></a>Class template <code>to_python_indirect</code></h3> - <p>Class template <code>to_python_indirect</code> converts objects -of its first argument type to python as extension class instances, using the ownership policy provided by its 2nd argument. - - <p> - - - <table border="1" summary="to_python_indirect template parameters"> - <caption> - <b><code>to_python_indirect</code> Requirements</b><br> - - In the table below, <b><code>x</code></b> denotes an object of - type <code>T</code>, <b><code>h</code></b> denotes an - object of type - <code>boost::python::objects::instance_holder*</code>, and - <b><code>p</code></b> denotes an object of type - <code>U*</code>. - - </caption> - <tr> - <th>Parameter - - <th>Requirements - - <th>Description - - <tr> - <td><code>T</code> - - <td>Either <code>U</code> <i>cv</i><code>&</code> - (where <i>cv</i> is any optional cv-qualification) or a <a - href="Dereferenceable.html">Dereferenceable</a> type such that - <code>*x</code> is convertible to <code>U const&</code>, where - <code>U</code> is a class type. - - <td>A type deferencing a C++ class exposed to Python using - class template <code><a - href="class.html#class_-spec">class_</a></code>. - - <tr> - <td><code>MakeHolder</code> - - <td>h = MakeHolder::execute(p); - - <td>A class whose static <code>execute()</code> creates an - <code>instance_holder</code>. - - </table> - - Instantiations of <code>to_python_indirect</code> are models of <a - href="ResultConverter.html#ResultConverter-concept">ResultConverter</a>. - - - <h4><a name="to_python_indirect-spec-synopsis"></a>Class template <code>to_python_indirect</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <class T, class MakeHolder> - struct to_python_indirect - { - static bool convertible(); - PyObject* operator()(T ptr_or_reference) const; - private: - static PyTypeObject* type(); - }; -}} -</pre> - - <h4><a name="to_python_indirect-spec-observers"></a>Class template <code>to_python_indirect</code> observers</h4> -<pre> -PyObject* operator()(T x) const; -</pre> - - <dl class="function-semantics"> - - <dt><b>Requires:</b> <code>x</code> refers to an object (if it - is a pointer type, it is non-null). <code>convertible() == - true</code>. - - <dt><b>Effects:</b> Creates an appropriately-typed Boost.Python - extension class instance, uses <code>MakeHolder</code> to create - an <code>instance_holder</code> from <code>x</code>, installs - the <code>instance_holder</code> in the new extension class - instance, and returns a pointer to it. - - </dl> - - - <h4><a name="to_python_indirect-spec-statics"></a>Class template <code>to_python_indirect</code> statics</h4> -<pre> -bool convertible(); -</pre> - - <dt><b>Effects:</b> Returns <code>true</code> iff any module has - registered a Python type corresponding to <code>U</code>. - - <h2><a name="examples"></a>Example</h2> - -This example replicates the functionality of <a -href="reference_existing_object.html#reference_existing_object-spec">reference_existing_object</a>, -but without some of the compile-time error checking. - - -<pre> - -struct make_reference_holder -{ - typedef boost::python::objects::instance_holder* result_type; - template <class T> - static result_type execute(T* p) - { - return new boost::python::objects::pointer_holder<T*, T>(p); - } -}; - -struct reference_existing_object -{ - // metafunction returning the <a href="ResultConverter.html#ResultConverter-concept">ResultConverter</a> - template <class T> - struct apply - { - typedef boost::python::to_python_indirect<T,make_reference_holder> type; - }; -}; -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - - - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002. </i> Distributed - under the Boost Software License, Version 1.0. (See accompanying file - LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</p> - diff --git a/libs/python/doc/v2/to_python_value.html b/libs/python/doc/v2/to_python_value.html deleted file mode 100644 index 3ba0044d1d..0000000000 --- a/libs/python/doc/v2/to_python_value.html +++ /dev/null @@ -1,103 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - <meta name="generator" content="HTML Tidy, see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/to_python_value.hpp></title> - - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header - <boost/python/to_python_value.hpp></h2> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#classes">Classes</a> - - <dd> - <dl class="page-index"> - <dt><a href="#to_python_value-spec">Class - <code>to_python_value</code></a> - - <dd> - <dl class="page-index"> - <dt><a href="#to_python_value-spec-synopsis">Class template - <code>to_python_value</code> synopsis</a> - - <dt><a href="#to_python_value-spec-observers">Class template - <code>to_python_value</code> observer functions</a> - </dl> - </dl> - - </dl> - <hr> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="to_python_value-spec"></a>Class template - <code>to_python_value</code></h3> - - <p><code>to_python_value</code> is a model of <a href= - "ResultConverter.html#ResultConverter-concept">ResultConverter</a> - which copies its argument into a new Python object. - - <h4><a name="to_python_value-spec-synopsis"></a>Class - <code>to_python_value</code> synopsis</h4> -<pre> -namespace boost { namespace python -{ - template <class T> - struct to_python_value - { - typedef typename <a href="../../../type_traits/index.html#transformations">add_reference</a>< - typename <a href="../../../type_traits/index.html#transformations">add_const</a><T>::type - >::type argument_type; - - static bool convertible(); - PyObject* operator()(argument_type) const; - }; -}} -</pre> - - <h4><a name="to_python_value-spec-observers"></a>Class - <code>to_python_value</code> observers</h4> -<pre> -static bool convertible(); -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> <code>true</code> iff a converter has been registered which can convert <code>T</code> to python by-value. - </dl> - -<pre> -PyObject* operator()(argument_type x) const; -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>convertible() == true</code> - <dt><b>Effects:</b> converts <code>x</code> to python - <dt><b>Returns:</b> the resulting Python object iff a converter for <code>T</code> has been registered, <code>0</code> otherwise. - </dl> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - - - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002. </i> Distributed under the Boost Software License, - Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at - http://www.boost.org/LICENSE_1_0.txt)</p> - diff --git a/libs/python/doc/v2/tuple.html b/libs/python/doc/v2/tuple.html deleted file mode 100644 index e90244f3e4..0000000000 --- a/libs/python/doc/v2/tuple.html +++ /dev/null @@ -1,139 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/tuple.hpp></title> - </head> - - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> - </td> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <boost/python/tuple.hpp></h2> - </td> - </tr> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#tuple-spec">Class <code>tuple</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#tuple-spec-synopsis">Class <code>tuple</code> - synopsis</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#make_tuple-spec"><code>make_tuple</code></a></dt> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>Exposes a <a href= - "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> for the Python - <a href= - "http://www.python.org/doc/current/tut/node7.html#SECTION007300000000000000000"> - tuple</a> type.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="tuple-spec"></a>Class <code>tuple</code></h3> - - <p>Exposes the interface of Python's built-in <code>tuple</code> type. - The semantics of the constructors and member functions defined below can - be fully understood by reading the <a href= - "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept - definition. Since <code>tuple</code> is publicly derived from <code><a - href="object.html#object-spec">object</a></code>, the public object - interface applies to <code>tuple</code> instances as well.</p> - - <h4><a name="tuple-spec-synopsis"></a>Class <code>tuple</code> - synopsis</h4> -<pre> -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) - }; -}} -</pre> - - <h2><a name="functions"></a>Functions</h2> - - <h3><a name="make_tuple-spec"></a><code>make_tuple</code></h3> -<pre> -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 A<i>n</i>> - tuple make_tuple(A0 const& a0, A1 const& a1,...A<i>n</i> const& a<i>n</i>); -}} -</pre> - Constructs a new tuple object composed of <code>object(a0), - object(a0),...object(a<i>n</i>)</code>. - - <h2><a name="examples"></a>Example</h2> -<pre> -using namespace boost::python; -tuple head_and_tail(object sequence) -{ - return make_tuple(sequence[0],sequence[-1]); -} -</pre> - - <p>Revised 03 October, 2002</p> - - <p><i>© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> - </body> -</html> - diff --git a/libs/python/doc/v2/type_id.html b/libs/python/doc/v2/type_id.html deleted file mode 100755 index 570846741c..0000000000 --- a/libs/python/doc/v2/type_id.html +++ /dev/null @@ -1,224 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - - <meta name="generator" content="HTML Tidy, see www.w3.org"> - <meta http-equiv="Content-Type" content= - "text/html; charset=iso-8859-1"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <boost/python/type_id.hpp></title> - - <style type="text/css"> - p.c4 {font-style: italic} - span.c3 {color: #ff0000} - h2.c2 {text-align: center} - h1.c1 {text-align: center} -</style> - - <table border="0" cellpadding="7" cellspacing="0" width="100%" - summary="header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width= - "277" alt="C++ Boost" src="../../../../boost.png" border= - "0"></a></h3> - - <td valign="top"> - <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> - - <h2 class="c2">Header <boost/python/type_id.hpp></h2> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#type_info-spec">Class <code>type_info</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#type_info-spec-synopsis">Class - <code>type_info</code> synopsis</a></dt> - - <dt><a href="#type_infospec-ctors">Class <code>type_info</code> - constructor</a></dt> - - <dt><a href="#type_infospec-comparisons">Class - <code>type_info</code> comparison functions</a></dt> - - <dt><a href="#type_infospec-observers">Class - <code>type_info</code> observer functions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#functions">Functions</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#type_id-spec">type_id</a></dt> - </dl> - </dd> - - <dt><a href="#examples">Example</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p><code><boost/python/type_id.hpp></code> provides types and - functions for runtime type identification like those of of - <code><typeinfo></code>. It exists mostly to work around certain - compiler bugs and platform-dependent interactions with shared - libraries.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="type_info-spec"></a>Class <code>type_info</code></h3> - - <p><code>type_info</code> instances identify a type. As - <code>std::type_info</code> is specified to (but unlike its - implementation in some compilers), <code>boost::python::type_info</code> - never represents top-level references or cv-qualification (see section - 5.2.8 in the C++ standard). Unlike <code>std::type_info</code>, - <code>boost::python::type_info</code> instances are copyable, and - comparisons always work reliably across shared library boundaries.</p> - - <h4><a name="type_info-spec-synopsis"></a>Class type_info synopsis</h4> -<pre> -namespace boost { namespace python -{ - class type_info : <a href= -"../../../utility/operators.htm#totally_ordered1">totally_ordered</a><type_info> - { - public: - // constructor - type_info(std::type_info const& = typeid(void)); - - // comparisons - bool operator<(type_info const& rhs) const; - bool operator==(type_info const& rhs) const; - - // observers - char const* name() const; - }; -}} -</pre> - - <h4><a name="type_infospec-ctors">Class <code>type_info</code> - constructor</a></h4> -<pre> -type_info(std::type_info const& = typeid(void)); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> constructs a <code>type_info</code> object which - identifies the same type as its argument.</dt> - - <dt><b>Rationale:</b> Since it is occasionally necessary to make an - array of <code>type_info</code> objects a benign default argument is - supplied. <span class="c3"><b>Note:</b></span> this constructor does - <i>not</i> correct for non-conformance of compiler - <code>typeid()</code> implementations. See <code><a href= - "#type_id-spec">type_id</a></code>, below.</dt> - </dl> - - <h4><a name="type_infospec-comparisons">Class <code>type_info</code> - comparisons</a></h4> -<pre> -bool operator<(type_info const& rhs) const; -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> yields a total order over <code>type_info</code> - objects.</dt> - </dl> -<pre> -bool operator==(type_info const& rhs) const; -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> <code>true</code> iff the two values describe the - same type.</dt> - </dl> - - <dl class="function-semantics"> - <dt><b>Note:</b> The use of <code><a href= - "../../../utility/operators.htm#totally_ordered1">totally_ordered</a><type_info></code> - as a private base class supplies operators <code><=</code>, - <code>>=</code>, <code>></code>, and <code>!=</code></dt> - </dl> - - <h4><a name="type_infospec-observers">Class <code>type_info</code> - observers</a></h4> -<pre> -char const* name() const; -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> The result of calling <code>name()</code> on the - argument used to construct the object.</dt> - </dl> - - <h2><a name="functions"></a>Functions</h2> -<pre> -std::ostream& operator<<(std::ostream&s, type_info const&x); -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> Writes a description of the type described by to - <code>x</code> into <code>s</code>.</dt> - - <dt><b>Rationale:</b> Not every C++ implementation provides a truly - human-readable <code>type_info::name()</code> string, but for some we - may be able to decode the string and produce a reasonable - representation.</dt> - </dl> -<pre> -<a name="type_id-spec">template <class T> type_info type_id</a>() -</pre> - - <dl class="function-semantics"> - <dt><b>Returns:</b> <code>type_info(typeid(T))</code></dt> - - <dt><b>Note:</b> On some non-conforming C++ implementations, the code - is not actually as simple as described above; the semantics are - adjusted to work <i>as-if</i> the C++ implementation were - conforming.</dt> - </dl> - - <h2><a name="examples"></a>Example</h2> - The following example, though silly, illustrates how the - <code>type_id</code> facility might be used -<pre> -#include <boost/python/type_id.hpp> - -// Returns true iff the user passes an int argument -template <class T> -bool is_int(T x) -{ - using boost::python::type_id; - return type_id<T>() == type_id<int>(); -} -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - - <p class="c4">© Copyright <a href= - "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002. Distributed under the Boost Software License, - Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at - http://www.boost.org/LICENSE_1_0.txt)< - - </body> -</html> - diff --git a/libs/python/doc/v2/with_custodian_and_ward.html b/libs/python/doc/v2/with_custodian_and_ward.html deleted file mode 100644 index b8e2a498db..0000000000 --- a/libs/python/doc/v2/with_custodian_and_ward.html +++ /dev/null @@ -1,370 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<!-- Copyright David Abrahams 2006. Distributed under the Boost --> -<!-- Software License, Version 1.0. (See accompanying --> -<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> -<html> - <head> - <meta name="generator" content= - "HTML Tidy for Cygwin (vers 1st February 2003), see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - <title> - Boost.Python - <boost/python/with_custodian_and_ward.hpp> - </title> - </head> - <body> - <table border="0" cellpadding="7" cellspacing="0" width="100%" - summary="header"> - <tr> - <td valign="top" width="300"> - <h3> - <a href="../../../../index.htm"><img height="86" width="277" - alt="C++ Boost" src="../../../../boost.png" border="0"> - </a> - </h3> - </td> - <td valign="top"> - <h1 align="center"> - <a href="../index.html">Boost.Python</a> - </h1> - <h2 align="center"> - Header <boost/python/with_custodian_and_ward.hpp> - </h2> - </td> - </tr> - </table> - <hr> - <h2> - Contents - </h2> - <dl class="page-index"> - <dt> - <a href="#introduction">Introduction</a> - </dt> - <dt> - <a href="#classes">Classes</a> - </dt> - <dd> - <dl class="page-index"> - <dt> - <a href="#with_custodian_and_ward-spec">Class Template - <code>with_custodian_and_ward</code></a> - </dt> - <dd> - <dl class="page-index"> - <dt> - <a href="#with_custodian_and_ward-spec-synopsis">Class - Template <code>with_custodian_and_ward</code> synopsis</a> - </dt> - <dt> - <a href="#with_custodian_and_ward-spec-statics">Class - <code>with_custodian_and_ward</code> static functions</a> - </dt> - </dl> - </dd> - <dt> - <a href="#with_custodian_and_ward_postcall-spec">Class Template - <code>with_custodian_and_ward_postcall</code></a> - </dt> - <dd> - <dl class="page-index"> - <dt> - <a href= - "#with_custodian_and_ward_postcall-spec-synopsis">Class - Template <code>with_custodian_and_ward_postcall</code> - synopsis</a> - </dt> - <dt> - <a href= - "#with_custodian_and_ward_postcall-spec-statics">Class - <code>with_custodian_and_ward_postcall</code> static - functions</a> - </dt> - </dl> - </dd> - </dl> - </dd> - <dt> - <a href="#examples">Example</a> - </dt> - </dl> - <hr> - <h2> - <a name="introduction">Introduction</a> - </h2>This header provides facilities for establishing a lifetime - dependency between two of a function's Python argument or result objects. - The <i>ward</i> object will not be destroyed until after the custodian as - long as the <i>custodian</i> object supports <a href= - "http://www.python.org/doc/current/lib/module-weakref.html">weak - references</a> (Boost.Python extension classes all support weak - references). If the <i>custodian</i> object does not support weak - references and is not <code>None</code>, an appropriate exception will be - thrown. The two class templates <code>with_custodian_and_ward</code> and - <code>with_custodian_and_ward_postcall</code> differ in the point at - which they take effect. - <p> - In order to reduce the chance of inadvertently creating dangling - pointers, the default is to do lifetime binding <i>before</i> the - underlying C++ object is invoked. However, before invocation the result - object is not available, so - <code>with_custodian_and_ward_postcall</code> is provided to bind - lifetimes after invocation. Also, if a C++ exception is thrown after - <code>with_custodian_and_ward<>::precall</code> but before the - underlying C++ object actually stores a pointer, the lifetime of the - custodian and ward objects will be artificially bound together, so one - might choose <code>with_custodian_and_ward_postcall</code> instead, - depending on the semantics of the function being wrapped. - </p> - <p> - Please note that this is <i>not</i> the appropriate tool to use when - wrapping functions which <b>transfer ownership</b> of a raw pointer - across the function-call boundary. Please see the <a href= - "faq.html#ownership">FAQ</a> if you want to do that. - </p> - <h2> - <a name="classes"></a>Classes - </h2> - <h3> - <a name="with_custodian_and_ward-spec"></a>Class template - <code>with_custodian_and_ward</code> - </h3> - <table border="1" summary="with_custodian_and_ward template parameters"> - <caption> - <b><code>with_custodian_and_ward</code> template parameters</b> - </caption> - <tr> - <th> - Parameter - </th> - <th> - Requirements - </th> - <th> - Description - </th> - <th> - Default - </th> - </tr> - <tr> - <td> - <code>custodian</code> - </td> - <td> - A positive compile-time constant of type <code>std::size_t</code>. - </td> - <td> - The 1-based index of the parameter which is the dependency in the - lifetime relationship to be established. If used to wrap a member - function, parameter 1 is the target object (<code>*this</code>). - Note that if the target Python object type doesn't support weak - references, a Python <code>TypeError</code> exception will be - raised when the C++ object being wrapped is called. - </td> - </tr> - <tr> - <td> - <code>ward</code> - </td> - <td> - A positive compile-time constant of type <code>std::size_t</code>. - </td> - <td> - The 1-based index of the parameter which is the dependent in the - lifetime relationship to be established. If used to wrap a member - function, parameter 1 is the target object (<code>*this</code>). - </td> - </tr> - <tr> - <td> - <code>Base</code> - </td> - <td> - A model of <a href="CallPolicies.html">CallPolicies</a> - </td> - <td> - Used for <a href="CallPolicies.html#composition">policy - composition</a>. - </td> - <td> - <code><a href= - "default_call_policies.html#default_call_policies-spec">default_call_policies</a></code> - </td> - </tr> - </table> - <h4> - <a name="with_custodian_and_ward-spec-synopsis"></a>Class template - <code>with_custodian_and_ward</code> synopsis - </h4> - <pre> -namespace boost { namespace python -{ - template <std::size_t custodian, std::size_t ward, class Base = default_call_policies> - struct with_custodian_and_ward : Base - { - static bool precall(PyObject* args); - }; -}} -</pre> - <h4> - <a name="with_custodian_and_ward-spec-statics"></a>Class - <code>with_custodian_and_ward</code> static functions - </h4> - <pre> -bool precall(PyObject* args); -</pre> - <dl class="function-semantics"> - <dt> - <b>Requires:</b> <code><a href= - "http://www.python.org/doc/2.2/api/tupleObjects.html#l2h-476">PyTuple_Check</a>(args) - != 0</code> - </dt> - <dt> - <b>Effects:</b> Makes the lifetime of the argument indicated by - <code>ward</code> dependent on the lifetime of the argument indicated - by <code>custodian</code>. - </dt> - <dt> - <b>Returns:</b> <code>false</code> and <code><a href= - "http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>() != 0</code> - upon failure, <code>true</code> otherwise. - </dt> - </dl><!-- xxxxxx --> - <h3> - <a name="with_custodian_and_ward_postcall-spec"></a>Class template - <code>with_custodian_and_ward_postcall</code> - </h3> - <table border="1" summary= - "with_custodian_and_ward_postcall template parameters"> - <caption> - <b><code>with_custodian_and_ward_postcall</code> template - parameters</b> - </caption> - <tr> - <th> - Parameter - </th> - <th> - Requirements - </th> - <th> - Description - </th> - <th> - Default - </th> - </tr> - <tr> - <td> - <code>custodian</code> - </td> - <td> - A compile-time constant of type <code>std::size_t</code>. - </td> - <td> - The index of the parameter which is the dependency in the lifetime - relationship to be established. Zero indicates the result object; 1 - indicates the first argument. If used to wrap a member function, - parameter 1 is the target object (<code>*this</code>). Note that if - the target Python object type doesn't support weak references, a - Python <code>TypeError</code> exception will be raised when the C++ - object being wrapped is called. - </td> - </tr> - <tr> - <td> - <code>ward</code> - </td> - <td> - A compile-time constant of type <code>std::size_t</code>. - </td> - <td> - The index of the parameter which is the dependent in the lifetime - relationship to be established. Zero indicates the result object; 1 - indicates the first argument. If used to wrap a member function, - parameter 1 is the target object (<code>*this</code>). - </td> - </tr> - <tr> - <td> - <code>Base</code> - </td> - <td> - A model of <a href="CallPolicies.html">CallPolicies</a> - </td> - <td> - Used for <a href="CallPolicies.html#composition">policy - composition</a>. - </td> - <td> - <code><a href= - "default_call_policies.html#default_call_policies-spec">default_call_policies</a></code> - </td> - </tr> - </table> - <h4> - <a name="with_custodian_and_ward_postcall-spec-synopsis"></a>Class - template <code>with_custodian_and_ward_postcall</code> synopsis - </h4> - <pre> -namespace boost { namespace python -{ - template <std::size_t custodian, std::size_t ward, class Base = default_call_policies> - struct with_custodian_and_ward_postcall : Base - { - static PyObject* postcall(PyObject* args, PyObject* result); - }; -}} -</pre> - <h4> - <a name="with_custodian_and_ward_postcall-spec-statics"></a>Class - <code>with_custodian_and_ward_postcall</code> static functions - </h4> - <pre> -PyObject* postcall(PyObject* args, PyObject* result); -</pre> - <dl class="function-semantics"> - <dt> - <b>Requires:</b> <code><a href= - "http://www.python.org/doc/2.2/api/tupleObjects.html#l2h-476">PyTuple_Check</a>(args) - != 0</code>, <code>result != 0</code>. - </dt> - <dt> - <b>Effects:</b> Makes the lifetime of the object indicated by - <code>ward</code> dependent on the lifetime of the object indicated - by <code>custodian</code>. - </dt> - <dt> - <b>Returns:</b> <code>0</code> and <code><a href= - "http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>() != 0</code> - upon failure, <code>true</code> otherwise. - </dt> - </dl> - <h2> - <a name="examples"></a>Example - </h2>The following example shows how - <code>with_custodian_and_ward_postcall</code> is used by the library to - implement <code><a href= - "return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a></code> - - <pre> -template <std::size_t owner_arg = 1, class Base = default_call_policies> -struct return_internal_reference - : with_custodian_and_ward_postcall<0, owner_arg, Base> -{ - typedef <a href= -"reference_existing_object.html#reference_existing_object-spec">reference_existing_object</a> result_converter; -}; -</pre> - <p> - Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 13 November, 2002 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - </p> - <p> - <i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2002. </i> - </p> - </body> -</html> diff --git a/libs/python/doc/v2/wrapper.html b/libs/python/doc/v2/wrapper.html deleted file mode 100755 index 06239754a9..0000000000 --- a/libs/python/doc/v2/wrapper.html +++ /dev/null @@ -1,238 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - <meta name="generator" content="HTML Tidy, see www.w3.org"> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <link rel="stylesheet" type="text/css" href="../boost.css"> - - <title>Boost.Python - <wrapper.hpp></title> - - <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= - "header"> - <tr> - <td valign="top" width="300"> - <h3><a href="../../../../index.htm"><img height="86" width="277" alt= - "C++ Boost" src="../../../../boost.png" border="0"></a></h3> - - <td valign="top"> - <h1 align="center"><a href="../index.html">Boost.Python</a></h1> - - <h2 align="center">Header <wrapper.hpp></h2> - </table> - <hr> - - <h2>Contents</h2> - - <dl class="page-index"> - <dt><a href="#introduction">Introduction</a></dt> - - <dt><a href="#classes">Classes</a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#override-spec">Class template - <code>override</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#override-spec-synopsis">Class - <code>override</code> synopsis</a></dt> - - <dt><a href="#override-spec-observers">Class - <code>override</code> observer functions</a></dt> - </dl> - </dd> - - <dt><a href="#wrapper-spec">Class template - <code>wrapper</code></a></dt> - - <dd> - <dl class="page-index"> - <dt><a href="#wrapper-spec-synopsis">Class <code>wrapper</code> - synopsis</a></dt> - - <dt><a href="#wrapper-spec-observers">Class - <code>wrapper</code> observer functions</a></dt> - </dl> - </dd> - </dl> - </dd> - - <dt><a href="#examples">Example(s)</a></dt> - </dl> - <hr> - - <h2><a name="introduction"></a>Introduction</h2> - - <p>To wrap a class <code>T</code> such that its virtual functions can be - "overridden in Python"—so that the corresponding method of a Python - derived class will be called when the virtual function is invoked from - C++—you must create a C++ wrapper class derived from ``T`` that - overrides those virtual functions so that they call into Python. This - header contains classes that can be used to make that job easier.</p> - - <h2><a name="classes"></a>Classes</h2> - - <h3><a name="override-spec"></a>Class <code>override</code></h3> - - <p>Encapsulates a Python override of a C++ virtual function. An - <code>override</code> object either holds a callable Python object or - <code>None</code>.</p> - - <h4><a name="override-spec-synopsis"></a>Class <code>override</code> - synopsis</h4> -<pre> -namespace boost -{ - class override : object - { - public: - <i>unspecified</i> operator() const; - template <class A0> - <i>unspecified</i> operator(A0) const; - template <class A0, class A1> - <i>unspecified</i> operator(A0, A1) const; - ... - template <class A0, class A1, ...class A<i>n</i>> - <i>unspecified</i> operator(A0, A1, ...A<i>n</i>) const; - }; -}; -</pre> - - <h4><a name="override-spec-observers"></a>Class <code>override</code> - observer functions</h4> -<pre> -<i>unspecified</i> operator() const; -template <class A0> -<i>unspecified</i> operator(A0) const; -template <class A0, class A1> -<i>unspecified</i> operator(A0, A1) const; -... -template <class A0, class A1, ...class A<i>n</i>> -<i>unspecified</i> operator(A0, A1, ...A<i>n</i>) const; -</pre> - - <dl class="function-semantics"> - <dt><b>Effects:</b> If <code>*this</code> holds a callable Python - object, it is invoked with the specified arguments in the manner - specified <a href="callbacks.html">here</a>. Otherwise, throws <code><a - href="errors.html#error_already_set-spec">error_already_set</a></code> - .</dt> - - <dt><b>Returns:</b> An object of unspecified type that holds the Python - result of the invocation and, when converted to a C++ type - <code>R</code>, attempts to convert that result object to - <code>R</code>. If that conversion fails, throws <code><a href= - "errors.html#error_already_set-spec">error_already_set</a></code> - .</dt> - </dl> - - <h3><a name="wrapper-spec"></a>Class template <code>wrapper</code></h3> - - <p>Deriving your wrapper class from both ``T`` <i>and</i> - ``wrapper<T> makes writing that derived class easier.</p> - - <h4><a name="wrapper-spec-synopsis"></a>Class template - <code>wrapper</code> synopsis</h4> -<pre> -namespace boost -{ - class wrapper - { - protected: - override get_override(char const* name) const; - }; -}; -</pre> - - <h4><a name="wrapper-spec-observers"></a>Class <code>wrapper</code> - observer functions</h4> -<pre> -override get_override(char const* name) const; -</pre> - - <dl class="function-semantics"> - <dt><b>Requires:</b> <code>name</code> is a <a href= - "definitions.html#ntbs">ntbs</a>.</dt> - - <dt><b>Returns:</b> If <code>*this</code> is the C++ base class - subobject of a Python derived class instance that overrides the named - function, returns an <code>override</code> object that delegates to the - Python override. Otherwise, returns an <code>override</code> object - that holds <code>None</code>.</dt> - </dl> - - <h2><a name="examples"></a>Example</h2> -<pre> -#include <boost/python/module.hpp> -#include <boost/python/class.hpp> -#include <boost/python/wrapper.hpp> -#include <boost/python/call.hpp> - -using namespace boost::python; - -// Class with one pure virtual function -struct P -{ - virtual ~P(){} - virtual char const* f() = 0; - char const* g() { return "P::g()"; } -}; - -struct PCallback : P, wrapper<P> -{ - char const* f() - { -#if BOOST_WORKAROUND(BOOST_MSVC, <= 1300) // Workaround for vc6/vc7 - return call<char const*>(this->get_override("f").ptr()); -#else - return this->get_override("f")(); -#endif - } -}; - -// Class with one non-pure virtual function -struct A -{ - virtual ~A(){} - virtual char const* f() { return "A::f()"; } -}; - -struct ACallback : A, wrapper<A> -{ - char const* f() - { - if (override f = this->get_override("f")) -#if BOOST_WORKAROUND(BOOST_MSVC, <= 1300) // Workaround for vc6/vc7 - return call<char const*>(f.ptr()); -#else - return f(); -#endif - - return A::f(); - } - - char const* default_f() { return this->A::f(); } -}; - -BOOST_PYTHON_MODULE_INIT(polymorphism) -{ - class_<PCallback,boost::noncopyable>("P") - .def("f", pure_virtual(&P::f)) - ; - - class_<ACallback,boost::noncopyable>("A") - .def("f", &A::f, &ACallback::default_f) - ; -} -</pre> - - <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> - 31 October, 2004 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> - - - <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave - Abrahams</a> 2004</i> Distributed under the Boost Software License, - Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at - http://www.boost.org/LICENSE_1_0.txt)</p> - diff --git a/libs/python/meta/libraries.json b/libs/python/meta/libraries.json index 9fdb065dbc..e2f2a05472 100644 --- a/libs/python/meta/libraries.json +++ b/libs/python/meta/libraries.json @@ -9,7 +9,6 @@ "Inter-language" ], "maintainers": [ - "Ralf Grosse-Kunstleve <rwgrosse-kunstleve -at- lbl.gov>", - "Ravi Rajagopal <lists_ravi -at- lavabit.com>" + "Stefan Seefeld <stefan -at- seefeld.name>" ] } |
