ceph/src/boost/libs/python/doc/reference/scope.qbk

   1 [section boost/python/scope.hpp]
   2 [section Introduction]
   3 Defines facilities for querying and controlling the Python scope (namespace) which will contain new wrapped classes and functions.
   4 [endsect]
   5 [section Class `scope`]
   6 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.
   7 ``
   8 namespace boost { namespace python
   9 {
  10   class scope : public object
  11   {
  12    public:
  13       scope(scope const&);
  14       scope(object const&);
  15       scope();
  16       ~scope()
  17    private:
  18       void operator=(scope const&);
  19   };
  20 }}
  21 ``
  22 [endsect]
  23 [section Class scope constructors and destructor]
  24 ``
  25 explicit scope(scope const& x);
  26 explicit scope(object const& x);
  27 ``
  28 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.
  29
  30 ``scope();``
  31
  32 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.
  33
  34 ``~scope()``
  35
  36 Sets the current associated Python object to the stored object.
  37 [endsect]
  38 [section Example]
  39 The following example shows how scope setting can be used to define nested classes.
  40
  41 C++ Module definition:
  42 ``
  43 #include <boost/python/module.hpp>
  44 #include <boost/python/class.hpp>
  45 #include <boost/python/scope.hpp>
  46 using namespace boost::python;
  47
  48 struct X
  49 {
  50   void f() {}
  51
  52   struct Y { int g() { return 42; } };
  53 };
  54
  55 BOOST_PYTHON_MODULE(nested)
  56 {
  57    // add some constants to the current (module) scope
  58    scope().attr("yes") = 1;
  59    scope().attr("no") = 0;
  60
  61    // Change the current scope
  62    scope outer
  63        = class_<X>("X")
  64             .def("f", &X::f)
  65             ;
  66
  67    // Define a class Y in the current scope, X
  68    class_<X::Y>("Y")
  69       .def("g", &X::Y::g)
  70       ;
  71 }
  72 ``
  73 Interactive Python:
  74 ``
  75 >>> import nested
  76 >>> nested.yes
  77 1
  78 >>> y = nested.X.Y()
  79 >>> y.g()
  80 42
  81 ``
  82 [endsect]
  83 [endsect]