...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
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.
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(); }; }}
docstring_options(bool show_all=true);
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);
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);
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
.
~docstring_options();
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.
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.
#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
#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
#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