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