|
+ |
+
+
+ Boost.Python+ +Header + <boost/python/docstring_options.hpp>+ |
+
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.
docstring_optionsControls 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.
+ +docstring_options synopsis
+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();
+
+ void
+ disable_user_defined();
+
+ void
+ enable_user_defined();
+
+ void
+ disable_signatures();
+
+ void
+ enable_signatures();
+
+ void
+ disable_all();
+
+ void
+ enable_all();
+ };
+
+}}
+
+
+ docstring_options constructors+docstring_options(bool show_all=true); ++ +
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 C++
+ signatures are shown. If show_all is
+ false the __doc__ attributes are
+ None.+docstring_options(bool show_user_defined, bool show_signatures); ++ +
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, C++
+ signatures are automatically added. If both
+ show_user_defined and show_signatures
+ are false, the __doc__ attributes are
+ None.docstring_options destructors+~docstring_options(); ++ +
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.docstring_options modifier functions+void disable_user_defined(); +void enable_user_defined(); +void disable_signatures(); +void enable_signatures(); +void disable_all(); +void enable_all(); ++ +
*_user_defined() and *_signatures()
+ member functions are provided for fine-grained control. The
+ *_all() member functions are convenient shortcuts
+ to manipulate both settings simultaneously.
+#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 doc +C++ signature: + foo(void) -> void +If compiled with +
-DDEMO_DOCSTRING_SHOW_ALL=false:
+ +>>> import demo +>>> print demo.foo.__doc__ +None ++ +
+#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");
+}
+Python code:
+ +>>> import demo +>>> print demo.foo1.__doc__ +foo1 doc +C++ signature: + foo1(int i) -> int +>>> print demo.foo2.__doc__ +C++ signature: + foo2(long l) -> int +>>> print demo.foo3.__doc__ +None +>>> print demo.foo4.__doc__ +foo4 doc ++ +
+#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 ++ +
boost/libs/python/test/docstring.cpp
+ and docstring.pyRevised + + 16 January, 2006 +
+ +© Copyright Ralf W. + Grosse-Kunstleve 2006.
+ + diff --git a/doc/v2/reference.html b/doc/v2/reference.html index 5ccf5329..db533baa 100644 --- a/doc/v2/reference.html +++ b/doc/v2/reference.html @@ -137,6 +137,14 @@ +