214 lines
7.0 KiB
Plaintext
214 lines
7.0 KiB
Plaintext
[section boost/python/docstring_options.hpp]
|
|
[section Introduction]
|
|
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.
|
|
[endsect]
|
|
[section Class `docstring_options`]
|
|
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();
|
|
};
|
|
}}
|
|
|
|
``
|
|
[endsect]
|
|
[section Class dostring_options constructors]
|
|
``
|
|
docstring_options(bool show_all=true);
|
|
``
|
|
[variablelist
|
|
[[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`.]]
|
|
]
|
|
``
|
|
docstring_options(bool show_user_defined, bool show_signatures);
|
|
``
|
|
[variablelist
|
|
[[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`.]]
|
|
]
|
|
``
|
|
docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures);
|
|
``
|
|
[variablelist
|
|
[[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`.]]
|
|
]
|
|
[endsect]
|
|
[section Class docstring_options destructor]
|
|
``~docstring_options();``
|
|
[variablelist
|
|
[[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.]]]
|
|
[endsect]
|
|
[section Class `docstring_options` modifier functions]
|
|
``
|
|
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.
|
|
[endsect]
|
|
[section Example]
|
|
[section Docstring options defined at compile time]
|
|
``
|
|
#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
|
|
``
|
|
[endsect]
|
|
[section Selective suppressions]
|
|
``
|
|
#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
|
|
``
|
|
[endsect]
|
|
[section Wrapping from multiple C++ scopes]
|
|
``
|
|
#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
|
|
``
|
|
|
|
[endsect]
|
|
[endsect]
|
|
[endsect]
|