<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!-- Copyright David Abrahams 2006. Distributed under the Boost --> <!-- Software License, Version 1.0. (See accompanying --> <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> <html> <head> <meta name="generator" content= "HTML Tidy for Linux/x86 (vers 1st September 2004), see www.w3.org"> <meta http-equiv="Content-Type" content= "text/html; charset=us-ascii"> <link rel="stylesheet" type="text/css" href="../boost.css"> <title>Boost.Python - <boost/python/docstring_options.hpp></title> </head> <body> <table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header"> <tr> <td valign="top" width="300"> <h3><a href="../../../../index.htm"><img height="86" width= "277" alt="C++ Boost" src="../../../../boost.png" border= "0"></a></h3> </td> <td valign="top"> <h1 align="center"><a href= "../index.html">Boost.Python</a></h1> <h2 align="center">Header <boost/python/docstring_options.hpp></h2> </td> </tr> </table> <hr> <h2>Contents</h2> <dl class="page-index"> <dt><a href="#introduction">Introduction</a></dt> <dt><a href="#classes">Classes</a></dt> <dd> <dl class="page-index"> <dt><a href="#docstring_options-spec">Class <code>docstring_options</code></a></dt> <dd> <dl class="page-index"> <dt><a href="#docstring_options-spec-synopsis">Class <code>docstring_options</code> synopsis</a></dt> <dt><a href="#docstring_options-spec-ctors">Class <code>docstring_options</code> constructors</a></dt> <dt><a href="#docstring_options-spec-dtors">Class <code>docstring_options</code> destructors</a></dt> <dt><a href="#docstring_options-spec-modifiers">Class <code>docstring_options</code> modifiers</a></dt> </dl> </dd> </dl> </dd> <dt><a href="#examples">Examples</a></dt> </dl> <hr> <h2><a name="introduction" id= "introduction"></a>Introduction</h2> <p>Boost.Python supports user-defined docstrings with automatic appending of C++ signatures. These features are enabled by default. The <code>class docstring_options</code> is available to selectively suppress the user-defined docstrings, signatures, or both.</p> <h2><a name="classes" id="classes"></a>Classes</h2> <h3><a name="docstring_options-spec" id= "docstring_options-spec"></a>Class <code>docstring_options</code></h3> <p>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.</p> <h4><a name="docstring_options-spec-synopsis" id= "docstring_options-spec-synopsis"></a>Class <code>docstring_options</code> synopsis</h4> <pre> 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(); }; }} </pre> <h4><a name="docstring_options-spec-ctors" id= "docstring_options-spec-ctors"></a>Class <code>docstring_options</code> constructors</h4> <pre> docstring_options(bool show_all=true); </pre> <dl class="function-semantics"> <dt><b>Effects:</b> Constructs a <code>docstring_options</code> object which controls the appearance of function and member-function docstrings defined in the code that follows. If <code>show_all</code> is <code>true</code>, both the user-defined docstrings and the automatically generated Python and C++ signatures are shown. If <code>show_all</code> is <code>false</code> the <code>__doc__</code> attributes are <code>None</code>.</dt> </dl> <pre> docstring_options(bool show_user_defined, bool show_signatures); </pre> <dl class="function-semantics"> <dt><b>Effects:</b> Constructs a <code>docstring_options</code> object which controls the appearance of function and member-function docstrings defined in the code that follows. Iff <code>show_user_defined</code> is <code>true</code>, the user-defined docstrings are shown. Iff <code>show_signatures</code> is <code>true</code>, Python and C++ signatures are automatically added. If both <code>show_user_defined</code> and <code>show_signatures</code> are <code>false</code>, the <code>__doc__</code> attributes are <code>None</code>.</dt> </dl> <pre> docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures); </pre> <dl class="function-semantics"> <dt><b>Effects:</b> Constructs a <code>docstring_options</code> object which controls the appearance of function and member-function docstrings defined in the code that follows. Iff <code>show_user_defined</code> is <code>true</code>, the user-defined docstrings are shown. Iff <code>show_py_signatures</code> is <code>true</code>, Python signatures are automatically added. Iff <code>show_cpp_signatures</code> is <code>true</code>, C++ signatures are automatically added. If all parameters are <code>false</code>, the <code>__doc__</code> attributes are <code>None</code>.</dt> </dl> <h4><a name="docstring_options-spec-dtors" id= "docstring_options-spec-dtors"></a>Class <code>docstring_options</code> destructors</h4> <pre> ~docstring_options(); </pre> <dl class="function-semantics"> <dt><b>Effects:</b> Restores the previous state of the docstring options. In particular, if <code>docstring_options</code> instances are in nested C++ scopes the settings effective in the enclosing scope are restored. If the last <code>docstring_options</code> instance goes out of scope the default "all on" settings are restored.</dt> </dl> <h4><a name="docstring_options-spec-modifiers" id= "docstring_options-spec-modifiers"></a>Class <code>docstring_options</code> modifier functions</h4> <pre> 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(); </pre> <dl class="function-semantics"> <dt>These member functions dynamically change the appearance of docstrings in the code that follows. The <code>*_user_defined()</code> and <code>*_signatures()</code> member functions are provided for fine-grained control. The <code>*_all()</code> member functions are convenient shortcuts to manipulate all settings simultaneously.</dt> </dl> <h2><a name="examples" id="examples"></a>Examples</h2> <h4>Docstring options defined at compile time</h4> <pre> #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"); } </pre>If compiled with <code>-DDEMO_DOCSTRING_SHOW_ALL=true</code>: <pre> >>> import demo >>> print demo.foo.__doc__ foo() -> None : foo doc C++ signature: foo(void) -> void </pre>If compiled with <code>-DDEMO_DOCSTRING_SHOW_ALL=false</code>: <pre> >>> import demo >>> print demo.foo.__doc__ None </pre> <h4>Selective suppressions</h4> <pre> #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"); } </pre>Python code: <pre> >>> 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 </pre> <h4>Wrapping from multiple C++ scopes</h4> <pre> #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(); } </pre>Python code: <pre> >>> import demo >>> print demo.foo1.__doc__ None >>> print demo.foo2.__doc__ None >>> print demo.bar1.__doc__ bar1 doc >>> print demo.bar2.__doc__ bar2 doc </pre> <h4>See also: <code>boost/libs/python/test/docstring.cpp</code> and <code>docstring.py</code></h4> <p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> 16 January, 2006 <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p> <p><i>© Copyright <a href= "http://www.boost.org/people/ralf_w_grosse_kunstleve.htm">Ralf W. Grosse-Kunstleve</a> 2006.</i></p> </body> </html>