From 67b3cdc7b7610ae0cfd5d9706b73c8983bed0cc2 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Thu, 23 May 2002 16:38:44 +0000 Subject: [PATCH] lvalue_from_pytype + documentation [SVN r14030] --- doc/v2/Extractor.html | 93 +++++++++++ doc/v2/lvalue_from_pytype.html | 283 +++++++++++++++++++++++++++++++++ doc/v2/reference.html | 47 +++--- test/m1.cpp | 18 +-- 4 files changed, 410 insertions(+), 31 deletions(-) create mode 100755 doc/v2/Extractor.html create mode 100755 doc/v2/lvalue_from_pytype.html diff --git a/doc/v2/Extractor.html b/doc/v2/Extractor.html new file mode 100755 index 00000000..97ef6fd4 --- /dev/null +++ b/doc/v2/Extractor.html @@ -0,0 +1,93 @@ + + + + +Boost.Python - Extractor Concept + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Extractor Concept

+
+
+
+
Introduction
+
Concept Requirements
+
+
Extractor Concept
+
+
Notes
+
+ +

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. + +

Concept Requirements

+

Extractor Concept

+ +

In the table below, X denotes a model of +Extractor and a denotes an instance of a Python +object type. + + + + + + + + + + + + + + + + + + +
ExpressionTypeSemantics
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 +
+ +

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. + +
+

Revised + + 22 May, 2002 + +

+

© Copyright Dave + Abrahams 2002. All Rights Reserved. + +

Permission to copy, use, modify, sell + and distribute this software is granted provided this copyright notice appears + in all copies. This software is provided "as is" without express or implied + warranty, and with no claim as to its suitability for any purpose. + + diff --git a/doc/v2/lvalue_from_pytype.html b/doc/v2/lvalue_from_pytype.html new file mode 100755 index 00000000..8b3cb49e --- /dev/null +++ b/doc/v2/lvalue_from_pytype.html @@ -0,0 +1,283 @@ + + + + + + Boost.Python - <boost/python/lvalue_from_python.hpp> + + + +
+

+

+ + 		+

Boost.Python

+ +

Header <boost/python/lvalue_from_pytype.hpp>

+
+

+ +

Contents

+ +
+
Introduction + + +
Classes + +
+
+
Class Template lvalue_from_pytype + +
+
+ +
Class Template + lvalue_from_pytype synopsis + +
Class Template + lvalue_from_pytype constructor +
+
+ +
+
Class Template extract_identity +
+
+ +
Class Template + extract_identity synopsis + +
Class Template + extract_identity static functions +
+
Class Template extract_member +
+
+ +
Class Template + extract_member synopsis + +
Class Template + extract_member static functions +
+
+ +
Example +
+
+ +

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. + +

Classes

+ +

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: + +

+ + + + + + + +
+ lvalue_from_pytype Requirements
+ + In the table below, x denotes an object of type PythonObject& + +
Parameter + + Requirements + + Semantics + +
Extractor + + a model of 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 PyTypeObject* + + The Python type of instances convertible by this + converter. Python subtypes are also convertible. + +
+ +

Class template lvalue_from_pytype synopsis

+
+namespace boost { namespace python
+{
+   template <class Extractor, PyTypeObject const* python_type>
+   struct lvalue_from_pytype
+   {
+       lvalue_from_pytype();
+   };
+}}
+
+ +

Class template lvalue_from_pytype constructor

+
+lvalue_from_pytype();
+
+ +
+ +
Effects: Registers converters which can convert + Python objects of the given type to lvalues of the type returned + by Extractor::execute. + +
+ +

Class template extract_identity

+ +

extract_identity is a model of Extractor which can be + used in the common case where the C++ type to be extracted is the + same as the Python object type. + +

Class template + extract_identity synopsis

+
+namespace boost { namespace python
+{
+   template <class InstanceType>
+   struct extract_identity
+   {
+      static InstanceType& execute(InstanceType& c);
+   };
+}}
+
+ +

Class template extract_identity static functions

+
+InstanceType& execute(InstanceType& c);
+
+ +
+ +
Returns: c + +
+ + +

Class template extract_member

+ +

extract_member is a model of 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. + +

Class template extract_member synopsis

+
+namespace boost { namespace python
+{
+   template <class InstanceType, class MemberType, MemberType (InstanceType::*member)>
+   struct extract_member
+   {
+      static MemberType& execute(InstanceType& c);
+   };
+}}
+
+ +

Class template extract_member static functions

+
+static MemberType& execute(InstanceType& c);
+
+ +
+ +
Returns: c.*member + +
+ +

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. + +

C++ module definition

+ +
+#include <boost/python/reference.hpp>
+#include <boost/python/module.hpp>
+
+// definition lifted from the Python docs
+typedef struct {
+   PyObject_HEAD
+} noddy_NoddyObject;
+
+using namespace boost::python;
+static reference<PyObject> cache;
+
+bool is_cached(noddy_NoddyObject* x)
+{
+   return x == cache.get();
+}
+
+void set_cache(noddy_NoddyObject* x)
+{
+   cache.reset((PyObject*)x, ref::increment_count);
+}
+
+BOOST_PYTHON_MODULE_INIT(noddy_cache)
+{
+   module noddy_cache("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>();
+}
+
+ +

Python code

+ +
+>>> 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
+
+ +

Revised + + 05 November, 2001 + + + +

© Copyright Dave + Abrahams 2002. All Rights Reserved. + diff --git a/doc/v2/reference.html b/doc/v2/reference.html index 71191cee..06fc346f 100644 --- a/doc/v2/reference.html +++ b/doc/v2/reference.html @@ -61,6 +61,9 @@

Dereferenceable +
Extractor +
HolderGenerator @@ -350,7 +353,6 @@
copy_non_const_reference.hpp -
manage_new_object.hpp -
Classes @@ -380,7 +381,6 @@
reference_existing_object.hpp -
-
reference_from_python.hpp - -
-
-
Classes - -
-
-
reference_from_python - -
get_member -
-
@@ -443,6 +427,23 @@ +
lvalue_from_pytype.hpp +
+
+
Classes + +
+
+
lvalue_from_pytype +
extract_identity +
extract_member +
+
+
to_python_converter.hpp @@ -483,16 +484,18 @@ -
type_from_python.hpp - +
type_from_python.hpp
Classes -
type_from_python +
identity_extractor +
member_extractor
diff --git a/test/m1.cpp b/test/m1.cpp index 42412c5d..fe5ef68d 100644 --- a/test/m1.cpp +++ b/test/m1.cpp @@ -9,7 +9,7 @@ #include "complicated.hpp" #include #include -#include +#include #include #include #include @@ -111,7 +111,7 @@ struct simple_to_python } }; -struct int_from_noddy_extractor +struct int_from_noddy { static int& execute(NoddyObject& p) { @@ -198,18 +198,18 @@ BOOST_PYTHON_MODULE_INIT(m1) simple_to_python(); - type_from_python<&NoddyType,int_from_noddy_extractor>(); + lvalue_from_pytype(); - boost::python::type_from_python< - &SimpleType -#if !defined(BOOST_MSVC) || BOOST_MSVC > 1300 - , member_extractor + lvalue_from_pytype< +#if !defined(BOOST_MSVC) || BOOST_MSVC > 1300 // doesn't support non-type member pointer parameters + extract_member #else - , extract_simple_object + extract_simple_object #endif + , &SimpleType >(); - type_from_python<&SimpleType, identity_extractor >(); + lvalue_from_pytype,&SimpleType>(); module m1("m1");