像文档那样解析狮身人面像

Question

我有一个sphinx格式的docstring,我想从中提取不同的部分(param,return,type,rtype等)以供进一步处理.我怎样才能做到这一点？

Answer 1

你可以使用docutils,这是Sphinx的基础.在另一个答案中,我docutils.core.publish_doctree用来获取reStructuredText文档的XML表示(实际上是一串文本),然后使用xml.minidom方法从该XML中提取字段列表.另一种方法是使用xml.etree.ElementTree,这在我看来更容易使用.

然而,首先,每次docutils遇到一个reStructuredText块时

:param x: Some parameter

得到的XML表示(我知道,它非常详细):

<field_list>
    <field>
        <field_name>
            param x
        </field_name>
        <field_body>
            <paragraph>
                Some parameter
            </paragraph>
        </field_body>
    </field>
</field_list>

下面的代码将采取所有field_list文档中的元素,并从把文本field/field_name,并field/field_body/paragraph在列表中的2元组.然后,您可以按照您希望的方式操作后期处理.

from docutils.core import publish_doctree
import xml.etree.ElementTree as etree

source = """Some help text

:param x: some parameter
:type x: and it's type

:return: Some text
:rtype: Return type

Some trailing text. I have no idea if the above is valid Sphinx
documentation!
"""

doctree = publish_doctree(source).asdom()

# Convert to etree.ElementTree since this is easier to work with than
# xml.minidom
doctree = etree.fromstring(doctree.toxml())

# Get all field lists in the document.
field_lists = doctree.findall('field_list')

fields = [f for field_list in field_lists \
    for f in field_list.findall('field')]

field_names = [name.text for field in fields \
    for name in field.findall('field_name')]

field_text = [etree.tostring(element) for field in fields \
    for element in field.findall('field_body')]

print zip(field_names, field_text)

这产生了列表:

[('param x', '<field_body><paragraph>some parameter</paragraph></field_body>'),
 ('type x', "<field_body><paragraph>and it's type</paragraph></field_body>"), 
 ('return', '<field_body><paragraph>Some text</paragraph></field_body>'), 
 ('rtype', '<field_body><paragraph>Return type</paragraph></field_body>')]

因此,在每个元组中的第一项是字段列表项(即:return:,:param x:等),并且第二项是相应的文本.显然这个文本并不是最干净的输出 - 但上面的代码很容易修改,所以我把它留给OP来获得他们想要的确切输出.