Skip to content

Commit 2261e7e

Browse files
author
Ralf W. Grosse-Kunstleve
committed
new docstring_options to support customization of __doc__ attributes of Boost.Python functions
[SVN r32297]
1 parent 19a1964 commit 2261e7e

File tree

4 files changed

+172
-2
lines changed

4 files changed

+172
-2
lines changed

‎include/boost/python/docstring_options.hpp‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
// Copyright Ralf W. Grosse-Kunstleve 2006.
2+
// Distributed under the Boost Software License, Version 1.0. (See
3+
// accompanying file LICENSE_1_0.txt or copy at
4+
// http://www.boost.org/LICENSE_1_0.txt)
5+
#ifndef DOCSTRING_OPTIONS_RWGK20060111_HPP
6+
# define DOCSTRING_OPTIONS_RWGK20060111_HPP
7+
8+
#include <boost/python/object/function.hpp>
9+
10+
namespace boost { namespace python {
11+
12+
// Note: the static data members are defined in object/function.cpp
13+
14+
class docstring_options : boost::noncopyable
15+
{
16+
public:
17+
docstring_options(bool show_all=true)
18+
{
19+
previous_show_user_defined_ = show_user_defined_;
20+
previous_show_signatures_ = show_signatures_;
21+
show_user_defined_ = show_all;
22+
show_signatures_ = show_all;
23+
}
24+
25+
docstring_options(bool show_user_defined, bool show_signatures)
26+
{
27+
previous_show_user_defined_ = show_user_defined_;
28+
previous_show_signatures_ = show_signatures_;
29+
show_user_defined_ = show_user_defined;
30+
show_signatures_ = show_signatures;
31+
}
32+
33+
~docstring_options()
34+
{
35+
show_user_defined_ = previous_show_user_defined_;
36+
show_signatures_ = previous_show_signatures_;
37+
}
38+
39+
void
40+
disable_user_defined() { show_user_defined_ = false; }
41+
42+
void
43+
enable_user_defined() { show_user_defined_ = true; }
44+
45+
void
46+
disable_signatures() { show_signatures_ = false; }
47+
48+
void
49+
enable_signatures() { show_signatures_ = true; }
50+
51+
void
52+
disable_all()
53+
{
54+
show_user_defined_ = false;
55+
show_signatures_ = false;
56+
}
57+
58+
void
59+
enable_all()
60+
{
61+
show_user_defined_ = true;
62+
show_signatures_ = true;
63+
}
64+
65+
friend class objects::function;
66+
67+
private:
68+
BOOST_PYTHON_DECL static volatile bool show_user_defined_;
69+
BOOST_PYTHON_DECL static volatile bool show_signatures_;
70+
bool previous_show_user_defined_;
71+
bool previous_show_signatures_;
72+
};
73+
74+
}} // namespace boost::python
75+
76+
#endif // DOCSTRING_OPTIONS_RWGK20060111_HPP

‎src/object/function.cpp‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
// accompanying file LICENSE_1_0.txt or copy at
44
// http://www.boost.org/LICENSE_1_0.txt)
55

6-
#include <boost/python/object/function.hpp>
6+
#include <boost/python/docstring_options.hpp>
77
#include <boost/python/object/function_object.hpp>
88
#include <boost/python/object/function_handle.hpp>
99
#include <boost/python/errors.hpp>
@@ -28,6 +28,11 @@
2828
# include <cstdio>
2929
#endif
3030

31+
namespace boost { namespace python {
32+
volatile bool docstring_options::show_user_defined_ = true;
33+
volatile bool docstring_options::show_signatures_ = true;
34+
}}
35+
3136
namespace boost { namespace python { namespace objects {
3237

3338
py_function_impl_base::~py_function_impl_base()
@@ -480,7 +485,7 @@ void function::add_to_namespace(
480485
throw_error_already_set();
481486

482487
object mutable_attribute(attribute);
483-
if (doc != 0)
488+
if (doc != 0 && docstring_options::show_user_defined_)
484489
{
485490
// Accumulate documentation
486491

@@ -496,6 +501,7 @@ void function::add_to_namespace(
496501
}
497502
}
498503

504+
if (docstring_options::show_signatures_)
499505
{
500506
if ( PyObject_HasAttrString(mutable_attribute.ptr(), "__doc__")
501507
&& mutable_attribute.attr("__doc__")) {

‎test/docstring.cpp‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
#include <boost/python/class.hpp>
77
#include <boost/python/module.hpp>
88
#include <boost/python/def.hpp>
9+
#include <boost/python/docstring_options.hpp>
910
#include <boost/python/scope.hpp>
1011
#include <boost/python/manage_new_object.hpp>
1112
#include "test_class.hpp"
@@ -55,6 +56,42 @@ BOOST_PYTHON_MODULE(docstring_ext)
5556
"creates a new X object");
5657

5758
def("fact", fact, "compute the factorial");
59+
60+
{
61+
docstring_options doc_options;
62+
doc_options.disable_user_defined();
63+
def("fact_usr_off_1", fact, "usr off 1");
64+
doc_options.enable_user_defined();
65+
def("fact_usr_on_1", fact, "usr on 1");
66+
doc_options.disable_user_defined();
67+
def("fact_usr_off_2", fact, "usr off 2");
68+
}
69+
def("fact_usr_on_2", fact, "usr on 2");
70+
71+
{
72+
docstring_options doc_options(true, false);
73+
def("fact_sig_off_1", fact, "sig off 1");
74+
doc_options.enable_signatures();
75+
def("fact_sig_on_1", fact, "sig on 1");
76+
doc_options.disable_signatures();
77+
def("fact_sig_off_2", fact, "sig off 2");
78+
}
79+
def("fact_sig_on_2", fact, "sig on 2");
80+
81+
{
82+
docstring_options doc_options(false);
83+
def("fact_usr_off_sig_off_1", fact, "usr off sig off 1");
84+
{
85+
docstring_options nested_doc_options;
86+
def("fact_usr_on_sig_on_1", fact, "usr on sig on 1");
87+
nested_doc_options.disable_all();
88+
nested_doc_options.enable_user_defined();
89+
def("fact_usr_on_sig_off_1", fact, "usr on sig off 1");
90+
nested_doc_options.enable_all();
91+
def("fact_usr_on_sig_on_2", fact, "usr on sig on 2");
92+
}
93+
def("fact_usr_off_sig_off_2", fact, "usr off sig off 2");
94+
}
5895
}
5996

6097
#include "module_tail.cpp"

‎test/docstring.py‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,57 @@
2020
>>> selected_doc(fact, 0, 1)
2121
['compute the factorial', 'C++ signature:']
2222
23+
>>> len(fact_usr_off_1.__doc__.splitlines())
24+
2
25+
>>> selected_doc(fact_usr_off_1, 0)
26+
['C++ signature:']
27+
>>> len(fact_usr_on_1.__doc__.splitlines())
28+
3
29+
>>> selected_doc(fact_usr_on_1, 0, 1)
30+
['usr on 1', 'C++ signature:']
31+
>>> len(fact_usr_off_2.__doc__.splitlines())
32+
2
33+
>>> selected_doc(fact_usr_off_2, 0)
34+
['C++ signature:']
35+
>>> len(fact_usr_on_2.__doc__.splitlines())
36+
3
37+
>>> selected_doc(fact_usr_on_2, 0, 1)
38+
['usr on 2', 'C++ signature:']
39+
40+
>>> len(fact_sig_off_1.__doc__.splitlines())
41+
1
42+
>>> selected_doc(fact_sig_off_1, 0)
43+
['sig off 1']
44+
>>> len(fact_sig_on_1.__doc__.splitlines())
45+
3
46+
>>> selected_doc(fact_sig_on_1, 0, 1)
47+
['sig on 1', 'C++ signature:']
48+
>>> len(fact_sig_off_2.__doc__.splitlines())
49+
1
50+
>>> selected_doc(fact_sig_off_2, 0)
51+
['sig off 2']
52+
>>> len(fact_sig_on_2.__doc__.splitlines())
53+
3
54+
>>> selected_doc(fact_sig_on_2, 0, 1)
55+
['sig on 2', 'C++ signature:']
56+
57+
>>> print fact_usr_off_sig_off_1.__doc__
58+
None
59+
>>> len(fact_usr_on_sig_on_1.__doc__.splitlines())
60+
3
61+
>>> selected_doc(fact_usr_on_sig_on_1, 0, 1)
62+
['usr on sig on 1', 'C++ signature:']
63+
>>> len(fact_usr_on_sig_off_1.__doc__.splitlines())
64+
1
65+
>>> selected_doc(fact_usr_on_sig_off_1, 0)
66+
['usr on sig off 1']
67+
>>> len(fact_usr_on_sig_on_2.__doc__.splitlines())
68+
3
69+
>>> selected_doc(fact_usr_on_sig_on_2, 0, 1)
70+
['usr on sig on 2', 'C++ signature:']
71+
>>> print fact_usr_off_sig_off_2.__doc__
72+
None
73+
2374
'''
2475

2576
def run(args = None):

0 commit comments

Comments
 (0)