Как я могу разобрать строку документации numpydoc и получить доступ к компонентам?

Question

Я хотел бы проанализировать строку документации numpydoc и получить программный доступ к каждому компоненту.

Например:

def foobar(a, b):
   '''Something something

   Parameters
   ----------
   a : int, default: 5
        Does something cool
   b : str
        Wow
'''

Что я хотел бы сделать, это:

parsed = magic_parser(foobar)
parsed.text  # Something something
parsed.a.text  # Does something cool
parsed.a.type  # int
parsed.a.default  # 5

Я искал вокруг и нашел такие вещи, как numpydoc и napoleon, но я не нашел никаких хороших указаний о том, как использовать их в моей собственной программе. Буду признателен за любую помощь.

Answer 1

Вы можете использовать NumpyDocString из numpydoc разобрать строки документации в Python-дружественную структуру.

Это пример того, как его использовать:

from numpydoc.docscrape import NumpyDocString


class Photo():
    """
    Array with associated photographic information.


    Parameters
    ----------
    x : type
        Description of parameter `x`.
    y
        Description of parameter `y` (with type not specified)

    Attributes
    ----------
    exposure : float
        Exposure in seconds.

    Methods
    -------
    colorspace(c='rgb')
        Represent the photo in the given colorspace.
    gamma(n=1.0)
        Change the photo's gamma exposure.

    """

    def __init__(x, y):
        print("Snap!")

doc = NumpyDocString(Photo.__doc__)
print(doc["Summary"])
print(doc["Parameters"])
print(doc["Attributes"])
print(doc["Methods"])

Тем не менее, это не будет работать с примером, который вы дали (а также с большим количеством кода, на котором я хочу это выполнить) по причинам, которые я не понимаю. Вместо этого вам нужно использовать конкретные FunctionDoc или же ClassDoc класс, в зависимости от вашего варианта использования.

from numpydoc.docscrape import FunctionDoc

def foobar(a, b):
   '''Something something

   Parameters
   ----------
   a : int, default: 5
        Does something cool
   b : str
        Wow
'''

doc = FunctionDoc(foobar)
print(doc["Parameters"])

Я понял все это, посмотрев на этот тест в их исходном коде. Итак, это не совсем задокументировано, но, надеюсь, этого достаточно, чтобы вы начали.