bump version to 12.2.2-pve1

[ceph.git] / ceph / src / boost / libs / python / doc / reference / object.qbk

[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]