|
|
Boost.PythonHeader <boost/python/docstring_options.hpp> |
docstring_optionsdocstring_options synopsisdocstring_options constructorsdocstring_options destructorsdocstring_options modifiersBoost.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(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 constructorsdocstring_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 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);
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);
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 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 functionsvoid 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();
*_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
boost/libs/python/test/docstring.cpp
and docstring.pyRevised 16 January, 2006
© Copyright Ralf W. Grosse-Kunstleve 2006.