Вставить атрибуты документации в файл Python

Question

Мы используем строку документации в наполеоновском стиле для модулей Python.Но необходимо автоматически заполнить дополнительные атрибуты в строке документации с именами Data Owner и DAL Owner, чтобы данная функция выглядела следующим образом:

def func(self, arg1=None, arg2=None):
"""
Returns the timeseries for the specified arg1 and arg2.
Args:
    arg1: argument 1
    arg2: argument 2
Returns:
    DataFrame containing timeseries of arg1 for arg2.

DAL Owner: Team IT
Data Owner: Team A
"""

Эти дополнительные атрибуты и их значения для данной функциипредоставляется в отдельном файле CSV.Я думал о том, чтобы иметь скрипт (awk, sed?), Который

• извлекает все имена функций в данном файле Python.Можно легко сделать это в python
• для этих имен функций, проверить, есть ли владельцы в файле csv и, если это так, создайте отображение имени функции и владельцев.Doable

Так вот, это та часть, которую я не понял и не знаю лучшего пути вперед.Для заданного имени функции и владельцев мне нужно вернуться в файл python и добавить владельцев в строку документации, если она существует.Я думаю, что-то вроде сценария awk, но не совсем уверен

• Найдите функцию, которая соответствует шаблону
• Для этого шаблона посмотрите, существует ли doctsring, тройные кавычки после закрывающей скобки
• Если есть строка документации, добавьте две дополнительные строки для владельцев перед закрывающей тройной кавычкой
• Если строка документа не существует, вставьте две строки для владельцев между тройными кавычками в строке после объявления функции.

Я знаю, что это много шагов, но кто-нибудь может дать представление о предыдущих 4 пунктах, чтобы вставить дополнительные атрибуты в строку документации, учитывая функцию, атрибуты и файл python.Будет ли полезна Linux-утилита, такая как sed, awk, или я должен пойти по пути Python.Есть ли другой вариант, который проще реализовать.

Answer 1

Процесс назначения новой строки документации в ast:

1. Получить существующую строку документации, используя ast.get_docstring
2. Создать новый узел ast сизмененное содержимое
3. Если существующей строкой является None, вставьте новый узел в начало тела родительского узла
4. Если существовала строка документации, замените ее на новый узел
5. Используйте инструмент unparse от Cpython Tools для генерации нового источника (вам может потребоваться загрузить его с github - убедитесь, что вы получаете версию, соответствующую вашей версии Python)

Вот пример кода:

$  cat fixdocstrings.py                            
import ast                                                                               
import io
from unparse import Unparser


class DocstringWriter(ast.NodeTransformer):
    def visit_FunctionDef(self, node):
        docstring = ast.get_docstring(node)
        new_docstring_node = make_docstring_node(docstring)
        if docstring:
            # Assumes the existing docstring is the first node 
            # in the function body.
            node.body[0] = new_docstring_node
        else:
            node.body.insert(0, new_docstring_node)
        return node


def make_docstring_node(docstring):
    if docstring is None:
        content = "A new docstring"
    else:
        content = docstring + " -- amended"
    s = ast.Str(content)
    return ast.Expr(value=s)


if __name__ == "__main__":
    tree = ast.parse(open("docstringtest.py").read())
    transformer = DocstringWriter()
    new_tree = transformer.visit(tree)
    ast.fix_missing_locations(new_tree)
    buf = io.StringIO()
    Unparser(new_tree, buf)
    buf.seek(0)
    print(buf.read())

$  cat docstringtest.py 
def foo():
    pass


def bar():
    """A docstring."""

$  python fixdocstrings.py 


def foo():
    'A new docstring'
    pass

def bar():
    'A docstring. -- amended'

(я ответил на что-то подобное для себя для python2.7, здесь )