new docstring_options to support customization of __doc__ attributes of Boost.Python functions

[SVN r32297]

include/boost/python/docstring_options.hpp

@@ -0,0 +1,76 @@
+// Copyright Ralf W. Grosse-Kunstleve 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)
+#ifndef DOCSTRING_OPTIONS_RWGK20060111_HPP
+# define DOCSTRING_OPTIONS_RWGK20060111_HPP
+
+#include <boost/python/object/function.hpp>
+
+namespace boost { namespace python {
+
+// Note: the static data members are defined in object/function.cpp
+
+class docstring_options : boost::noncopyable
+{
+  public:
+      docstring_options(bool show_all=true)
+      {
+          previous_show_user_defined_ = show_user_defined_;
+          previous_show_signatures_ = show_signatures_;
+          show_user_defined_ = show_all;
+          show_signatures_ = show_all;
+      }
+
+      docstring_options(bool show_user_defined, bool show_signatures)
+      {
+          previous_show_user_defined_ = show_user_defined_;
+          previous_show_signatures_ = show_signatures_;
+          show_user_defined_ = show_user_defined;
+          show_signatures_ = show_signatures;
+      }
+
+      ~docstring_options()
+      {
+          show_user_defined_ = previous_show_user_defined_;
+          show_signatures_ = previous_show_signatures_;
+      }
+
+      void
+      disable_user_defined() { show_user_defined_ = false; }
+
+      void
+      enable_user_defined() { show_user_defined_ = true; }
+
+      void
+      disable_signatures() { show_signatures_ = false; }
+
+      void
+      enable_signatures() { show_signatures_ = true; }
+
+      void
+      disable_all()
+      {
+        show_user_defined_ = false;
+        show_signatures_ = false;
+      }
+
+      void
+      enable_all()
+      {
+        show_user_defined_ = true;
+        show_signatures_ = true;
+      }
+
+      friend class objects::function;
+
+  private:
+      BOOST_PYTHON_DECL static volatile bool show_user_defined_;
+      BOOST_PYTHON_DECL static volatile bool show_signatures_;
+      bool previous_show_user_defined_;
+      bool previous_show_signatures_;
+};
+
+}} // namespace boost::python
+
+#endif // DOCSTRING_OPTIONS_RWGK20060111_HPP

src/object/function.cpp

@@ -3,7 +3,7 @@
 // accompanying file LICENSE_1_0.txt or copy at
 // http://www.boost.org/LICENSE_1_0.txt)
 
-#include <boost/python/object/function.hpp>
+#include <boost/python/docstring_options.hpp>
 #include <boost/python/object/function_object.hpp>
 #include <boost/python/object/function_handle.hpp>
 #include <boost/python/errors.hpp>
@@ -28,6 +28,11 @@
 # include <cstdio>
 #endif
 
+namespace boost { namespace python {
+  volatile bool docstring_options::show_user_defined_ = true;
+  volatile bool docstring_options::show_signatures_ = true;
+}}
+
 namespace boost { namespace python { namespace objects { 
 
 py_function_impl_base::~py_function_impl_base()
@@ -480,7 +485,7 @@ void function::add_to_namespace(
         throw_error_already_set();
 
     object mutable_attribute(attribute);
-    if (doc != 0)
+    if (doc != 0 && docstring_options::show_user_defined_)
     {
         // Accumulate documentation
         
@@ -496,6 +501,7 @@ void function::add_to_namespace(
         }
     }
 
+    if (docstring_options::show_signatures_)
     {
         if (   PyObject_HasAttrString(mutable_attribute.ptr(), "__doc__")
             && mutable_attribute.attr("__doc__")) {

test/docstring.cpp

@@ -6,6 +6,7 @@
 #include <boost/python/class.hpp>
 #include <boost/python/module.hpp>
 #include <boost/python/def.hpp>
+#include <boost/python/docstring_options.hpp>
 #include <boost/python/scope.hpp>
 #include <boost/python/manage_new_object.hpp>
 #include "test_class.hpp"
@@ -55,6 +56,42 @@ BOOST_PYTHON_MODULE(docstring_ext)
         "creates a new X object");
 
     def("fact", fact, "compute the factorial");
+
+    {
+      docstring_options doc_options;
+      doc_options.disable_user_defined();
+      def("fact_usr_off_1", fact, "usr off 1");
+      doc_options.enable_user_defined();
+      def("fact_usr_on_1", fact, "usr on 1");
+      doc_options.disable_user_defined();
+      def("fact_usr_off_2", fact, "usr off 2");
+    }
+    def("fact_usr_on_2", fact, "usr on 2");
+
+    {
+      docstring_options doc_options(true, false);
+      def("fact_sig_off_1", fact, "sig off 1");
+      doc_options.enable_signatures();
+      def("fact_sig_on_1", fact, "sig on 1");
+      doc_options.disable_signatures();
+      def("fact_sig_off_2", fact, "sig off 2");
+    }
+    def("fact_sig_on_2", fact, "sig on 2");
+
+    {
+      docstring_options doc_options(false);
+      def("fact_usr_off_sig_off_1", fact, "usr off sig off 1");
+      {
+        docstring_options nested_doc_options;
+        def("fact_usr_on_sig_on_1", fact, "usr on sig on 1");
+        nested_doc_options.disable_all();
+        nested_doc_options.enable_user_defined();
+        def("fact_usr_on_sig_off_1", fact, "usr on sig off 1");
+        nested_doc_options.enable_all();
+        def("fact_usr_on_sig_on_2", fact, "usr on sig on 2");
+      }
+      def("fact_usr_off_sig_off_2", fact, "usr off sig off 2");
+    }
 }
 
 #include "module_tail.cpp"

test/docstring.py

@@ -20,6 +20,57 @@
 >>> selected_doc(fact, 0, 1)
 ['compute the factorial', 'C++ signature:']
 
+>>> len(fact_usr_off_1.__doc__.splitlines())
+2
+>>> selected_doc(fact_usr_off_1, 0)
+['C++ signature:']
+>>> len(fact_usr_on_1.__doc__.splitlines())
+3
+>>> selected_doc(fact_usr_on_1, 0, 1)
+['usr on 1', 'C++ signature:']
+>>> len(fact_usr_off_2.__doc__.splitlines())
+2
+>>> selected_doc(fact_usr_off_2, 0)
+['C++ signature:']
+>>> len(fact_usr_on_2.__doc__.splitlines())
+3
+>>> selected_doc(fact_usr_on_2, 0, 1)
+['usr on 2', 'C++ signature:']
+
+>>> len(fact_sig_off_1.__doc__.splitlines())
+1
+>>> selected_doc(fact_sig_off_1, 0)
+['sig off 1']
+>>> len(fact_sig_on_1.__doc__.splitlines())
+3
+>>> selected_doc(fact_sig_on_1, 0, 1)
+['sig on 1', 'C++ signature:']
+>>> len(fact_sig_off_2.__doc__.splitlines())
+1
+>>> selected_doc(fact_sig_off_2, 0)
+['sig off 2']
+>>> len(fact_sig_on_2.__doc__.splitlines())
+3
+>>> selected_doc(fact_sig_on_2, 0, 1)
+['sig on 2', 'C++ signature:']
+
+>>> print fact_usr_off_sig_off_1.__doc__
+None
+>>> len(fact_usr_on_sig_on_1.__doc__.splitlines())
+3
+>>> selected_doc(fact_usr_on_sig_on_1, 0, 1)
+['usr on sig on 1', 'C++ signature:']
+>>> len(fact_usr_on_sig_off_1.__doc__.splitlines())
+1
+>>> selected_doc(fact_usr_on_sig_off_1, 0)
+['usr on sig off 1']
+>>> len(fact_usr_on_sig_on_2.__doc__.splitlines())
+3
+>>> selected_doc(fact_usr_on_sig_on_2, 0, 1)
+['usr on sig on 2', 'C++ signature:']
+>>> print fact_usr_off_sig_off_2.__doc__
+None
+
 '''
 
 def run(args = None):