1[section boost/python/docstring_options.hpp] 2[section Introduction] 3Boost.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. 4[endsect] 5[section Class `docstring_options`] 6Controls 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. 7 8``namespace boost { namespace python { 9 10 class docstring_options : boost::noncopyable 11 { 12 public: 13 docstring_options(bool show_all=true); 14 docstring_options(bool show_user_defined, bool show_signatures); 15 docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures); 16 ~docstring_options(); 17 void disable_user_defined(); 18 void enable_user_defined(); 19 void disable_signatures(); 20 void enable_signatures(); 21 void disable_py_signatures(); 22 void enable_py_signatures(); 23 void disable_cpp_signatures(); 24 void enable_cpp_signatures(); 25 void disable_all(); 26 void enable_all(); 27 }; 28}} 29 30`` 31[endsect] 32[section Class dostring_options constructors] 33`` 34docstring_options(bool show_all=true); 35`` 36[variablelist 37[[Effects][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`.]] 38] 39`` 40docstring_options(bool show_user_defined, bool show_signatures); 41`` 42[variablelist 43[[Effects][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`.]] 44] 45`` 46docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures); 47`` 48[variablelist 49[[Effects][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`.]] 50] 51[endsect] 52[section Class docstring_options destructor] 53``~docstring_options();`` 54[variablelist 55[[Effects][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.]]] 56[endsect] 57[section Class `docstring_options` modifier functions] 58`` 59void disable_user_defined(); 60void enable_user_defined(); 61void disable_signatures(); 62void enable_signatures(); 63void disable_py_signatures(); 64void enable_py_signatures(); 65void disable_cpp_signatures(); 66void enable_cpp_signatures(); 67void disable_all(); 68void enable_all(); 69`` 70These 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. 71[endsect] 72[section Example] 73[section Docstring options defined at compile time] 74`` 75#include <boost/python/module.hpp> 76#include <boost/python/def.hpp> 77#include <boost/python/docstring_options.hpp> 78 79void foo() {} 80 81BOOST_PYTHON_MODULE(demo) 82{ 83 using namespace boost::python; 84 docstring_options doc_options(DEMO_DOCSTRING_SHOW_ALL); 85 def("foo", foo, "foo doc"); 86} 87`` 88If compiled with `-DDEMO_DOCSTRING_SHOW_ALL=true`: 89`` 90>>> import demo 91>>> print demo.foo.__doc__ 92foo() -> None : foo doc 93C++ signature: 94 foo(void) -> void 95`` 96If compiled with `-DDEMO_DOCSTRING_SHOW_ALL=false`: 97`` 98>>> import demo 99>>> print demo.foo.__doc__ 100None 101`` 102[endsect] 103[section Selective suppressions] 104`` 105#include <boost/python/module.hpp> 106#include <boost/python/def.hpp> 107#include <boost/python/args.hpp> 108#include <boost/python/docstring_options.hpp> 109 110int foo1(int i) { return i; } 111int foo2(long l) { return static_cast<int>(l); } 112int foo3(float f) { return static_cast<int>(f); } 113int foo4(double d) { return static_cast<int>(d); } 114 115BOOST_PYTHON_MODULE(demo) 116{ 117 using namespace boost::python; 118 docstring_options doc_options; 119 def("foo1", foo1, arg("i"), "foo1 doc"); 120 doc_options.disable_user_defined(); 121 def("foo2", foo2, arg("l"), "foo2 doc"); 122 doc_options.disable_signatures(); 123 def("foo3", foo3, arg("f"), "foo3 doc"); 124 doc_options.enable_user_defined(); 125 def("foo4", foo4, arg("d"), "foo4 doc"); 126 doc_options.enable_py_signatures(); 127 def("foo5", foo4, arg("d"), "foo5 doc"); 128 doc_options.disable_py_signatures(); 129 doc_options.enable_cpp_signatures(); 130 def("foo6", foo4, arg("d"), "foo6 doc"); 131} 132`` 133Python code: 134`` 135>>> import demo 136>>> print demo.foo1.__doc__ 137foo1( (int)i) -> int : foo1 doc 138C++ signature: 139 foo1(int i) -> int 140>>> print demo.foo2.__doc__ 141foo2( (int)l) -> int : 142C++ signature: 143 foo2(long l) -> int 144>>> print demo.foo3.__doc__ 145None 146>>> print demo.foo4.__doc__ 147foo4 doc 148>>> print demo.foo5.__doc__ 149foo5( (float)d) -> int : foo5 doc 150>>> print demo.foo6.__doc__ 151foo6 doc 152C++ signature: 153 foo6(double d) -> int 154`` 155[endsect] 156[section Wrapping from multiple C++ scopes] 157`` 158#include <boost/python/module.hpp> 159#include <boost/python/def.hpp> 160#include <boost/python/args.hpp> 161#include <boost/python/docstring_options.hpp> 162 163int foo1(int i) { return i; } 164int foo2(long l) { return static_cast<int>(l); } 165 166int bar1(int i) { return i; } 167int bar2(long l) { return static_cast<int>(l); } 168 169namespace { 170 171 void wrap_foos() 172 { 173 using namespace boost::python; 174 // no docstring_options here 175 // -> settings from outer C++ scope are in effect 176 def("foo1", foo1, arg("i"), "foo1 doc"); 177 def("foo2", foo2, arg("l"), "foo2 doc"); 178 } 179 180 void wrap_bars() 181 { 182 using namespace boost::python; 183 bool show_user_defined = true; 184 bool show_signatures = false; 185 docstring_options doc_options(show_user_defined, show_signatures); 186 def("bar1", bar1, arg("i"), "bar1 doc"); 187 def("bar2", bar2, arg("l"), "bar2 doc"); 188 } 189} 190 191BOOST_PYTHON_MODULE(demo) 192{ 193 boost::python::docstring_options doc_options(false); 194 wrap_foos(); 195 wrap_bars(); 196} 197`` 198Python code: 199`` 200>>> import demo 201>>> print demo.foo1.__doc__ 202None 203>>> print demo.foo2.__doc__ 204None 205>>> print demo.bar1.__doc__ 206bar1 doc 207>>> print demo.bar2.__doc__ 208bar2 doc 209`` 210 211[endsect] 212[endsect] 213[endsect] 214