如何覆盖升压自动创建的文档字符串数据:: Python的？ [英] How to override the automatically created docstring data for Boost::Python?
问题描述
我目前正在开发一个C ++ - 为基于Python的模块。我发现的boost :: Python的状态相当好什么我要完成。不过，我现在运行到与正在通过的boost :: Python中产生的文档字符串一些问题。考虑下面的boost :: Python的定义：
BOOST_PYTHON_MODULE（gcsmt）
{
class_＆LT; gcsmt ::单位和GT（单位，设置为输入单位，NO_INIT）
.DEF（PrintSupported，＆安培; gcsmt ::单位:: printSupported，打印出所有支持单位。）
.DEF（SetDefault，＆安培; gcsmt ::单位:: setDefaultUnit设置用于输入/输出默认单位。）
.staticmethod（PrintSupported）
.staticmethod（SetDefault）
.DEF（self_ns :: STR（self_ns ::个体经营））
;
}
如果我编译，加载我在Python模块，并获得了gscmt.Units类帮助，输出的是以下内容：
＆GT;＆GT;＆GT;帮助（gcsmt.Units）帮助的模块gcsmt类单位：类单位（Boost.Python.instance）
|设置用于作为输入的单位。
|
|方法解析顺序：
|单位
| Boost.Python.instance
| __builtin __。对象
|
|方法定义如下：
|
| __reduce__ =＆LT;无名Boost.Python的功能＆GT;（...）
|
| __str __（...）
| __str __（（单位）ARG1） - GT;对象：
|
| C ++签名：
| _object * __str __（gcsmt ::单元{}左值）
|
| -------------------------------------------------- --------------------
|静态方法定义如下：
|
| PrintSupported（...）
| PrintSupported（） - ＆GT;没有 ：
|打印出所有支持单位。
|
| C ++签名：
|无效PrintSupported（）
|
|默认设置（...）
| SetDefault（（UNITTYPE）ARG1，（STR）ARG2） - GT;没有 ：
|设置默认单元用于输入/输出。
|
| C ++签名：
|无效SetDefault（gcsmt :: UNITTYPE，标准::字符串）
|
| -------------------------------------------------- --------------------
|数据和其它属性定义如下：
|
| __init__ =＆LT;内置函数__init __＆GT;
|抛出一个异常
|这个类不能从Python的实例化
|
| -------------------------------------------------- --------------------
|从Boost.Python.instance继承的数据描述：
|
| __dict__
|
| __weakref__
|
| -------------------------------------------------- --------------------
|数据和其他属性从Boost.Python.instance继承：
|
| __new__ =＆LT;内置Boost.Python.class对象方法＆gt __new__;
| ŧ.__新__（S，...） - GT;与S型的新对象，T的一个亚型
虽然大部分的文档被输出的是有价值的我作为一名开发人员，其中大部分是噪音，甚至更糟糕，混乱，给最终用户。 （E.g.-我的用户并不关心一个给定的方法C ++签名是什么，他们也不需要看到的方法解析顺序，或额外的隐藏方法所显示）。有什么办法来覆盖，并减少升压:: Python的设置文档的水平/冗长？理想情况下，我想我的文档看起来是这样的：
＆GT;＆GT;＆GT;帮助（gcsmt.Units）帮助的模块gcsmt类单位：类单位
|设置用于作为输入的单位。
|
| PrintSupported（） - ＆GT;没有 ：
|打印出所有支持单位。
|
| SetDefault（（UNITTYPE）ARG1，（STR）ARG2） - GT;没有 ：
|设置默认单元用于输入/输出。
- 使用的boost ::蟒蛇:: docstring_options 类来定义自动创建的文档字符串选项。
- 所有的高清函数需要一个文档字符串作为最后一个参数。
- 所有的类_ 定义取类文档字符串作为最后一个参数
即：
使用boost :: python的;
BOOST_PYTHON_MODULE（富）
{
//这将使用户自定义文档字符串和python签名，
//而禁止C ++签名
docstring_options local_docstring_options（真，真，假）; class_＆LT;酒吧和GT（酒吧，INIT＆LT;＆GT;（），酒吧班/ *类的文档字符串这里* /）
.DEF（FOOBAR，＆安培;酒吧:: foobar的，foobar的功能/ *函数文档字符串这里* /）;
}
I am currently working developing a C++-based module for Python. I have found that Boost::Python is working quite well for what I want to accomplish. However, I am now running into some issues with the docstring that is being generated by Boost::Python. Given the following Boost::Python definitions:
BOOST_PYTHON_MODULE(gcsmt)
{
class_<gcsmt::Units>("Units", "Sets the units used as input.", no_init)
.def("PrintSupported", &gcsmt::Units::printSupported, "Print out all supported units.")
.def("SetDefault", &gcsmt::Units::setDefaultUnit, "Sets the default unit to be used for inputs/outputs.")
.staticmethod("PrintSupported")
.staticmethod("SetDefault")
.def(self_ns::str(self_ns::self))
;
}
If I compile, load my module in Python, and get help on the gscmt.Units class, the output is the following:
>>> help(gcsmt.Units)
Help on class Units in module gcsmt:
class Units(Boost.Python.instance)
| Sets the units used as input.
|
| Method resolution order:
| Units
| Boost.Python.instance
| __builtin__.object
|
| Methods defined here:
|
| __reduce__ = <unnamed Boost.Python function>(...)
|
| __str__(...)
| __str__( (Units)arg1) -> object :
|
| C++ signature :
| _object* __str__(gcsmt::Units {lvalue})
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| PrintSupported(...)
| PrintSupported() -> None :
| Print out all supported units.
|
| C++ signature :
| void PrintSupported()
|
| SetDefault(...)
| SetDefault( (UnitType)arg1, (str)arg2) -> None :
| Sets the default unit to be used for inputs/outputs.
|
| C++ signature :
| void SetDefault(gcsmt::unitType,std::string)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __init__ = <built-in function __init__>
| Raises an exception
| This class cannot be instantiated from Python
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Boost.Python.instance:
|
| __dict__
|
| __weakref__
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Boost.Python.instance:
|
| __new__ = <built-in method __new__ of Boost.Python.class object>
| T.__new__(S, ...) -> a new object with type S, a subtype of T
While much of the documentation being output is valuable to me as a developer, most of it would be noise, or even worse, confusing, to an end user. (E.g.- my users don't care what the C++ signature of a given method is, nor do they need to see the Method resolution order, or additional hidden methods that are shown). Is there any way to override, and reduce the level/verbosity of the documentation set up by Boost::Python? Ideally, I'd like my documentation to look something like:
>>> help(gcsmt.Units)
Help on class Units in module gcsmt:
class Units
| Sets the units used as input.
|
| PrintSupported() -> None :
| Print out all supported units.
|
| SetDefault( (UnitType)arg1, (str)arg2) -> None :
| Sets the default unit to be used for inputs/outputs.
- Use the boost::python::docstring_options class to define your auto-created docstring options.
- All def functions take a docstring as the last parameter.
- All class_ definitions take the class docstring as the last parameter
I.e.:
using boost::python;
BOOST_PYTHON_MODULE(foo)
{
// This will enable user-defined docstrings and python signatures,
// while disabling the C++ signatures
docstring_options local_docstring_options(true, true, false);
class_<Bar>("Bar", init<>(), "Bar class" /* class docstring here */ )
.def("foobar", &Bar::foobar, "foobar function" /* function docstring here */);
}
这篇关于如何覆盖升压自动创建的文档字符串数据:: Python的？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
