Пользователь
0,0
рейтинг
10 августа 2012 в 11:39

Разработка → Docstring coverage — покрытие python-кода документацией recovery mode

Как проверить, что python-разработчики (или вы сами) хорошо задокументировали код, кроме как просматривать все руками или генерировать pydoc'ом документацию и сравнивать с исходниками? Вот и я не нашел никакого решения, пока случайно не натолкнулся на старый-престарый скрипт, который вдохновил меня на форк и последующую несложную доработку.

В результате у меня получился простой и полезный (по крайней мере для меня :) ) инструмент Docstring coverage, позволяющий оценить процентное покрытие кода документацией по всему проекту.



Запускается так:
docstring-coverage [опции] <путь к папке или модулю>


Пример вывода:
$ docstring-coverage docstring-coverage/

File docstring-coverage/setup.py
 - No module dostring!
 Needed: 1; Exist: 0; Missing: 1; Coverage: 0.0%

File docstring-coverage/docstringcoverage/__init__.py
 - No module dostring!
 Needed: 1; Exist: 0; Missing: 1; Coverage: 0.0%

File docstring-coverage/docstringcoverage/cover.py
 - No docstring for DocStringCoverageVisitor!
 - No docstring for DocStringCoverageVisitor.__init__!
 - No docstring for DocStringCoverageVisitor.visitModule!
 - No docstring for DocStringCoverageVisitor.visitClass!
 - No docstring for DocStringCoverageVisitor.visitFunction!
 - No docstring for DocStringCoverageVisitor.getResult!
 - No docstring for get_docstring_coverage.printDocstring!
 Needed: 11; Exist: 4; Missing: 7; Coverage: 36.4%


Overall statistics for 3 files:
Docstrings needed: 13; Docstrings exist: 4; Docstrings missing: 9
Total docstring coverage: 30.8%;  Grade: not so good

Среди опций есть -m, которая заставляет утилиту пропускать __магические__ методы python и -v, позволяющая настроить уровень «болтливости» вывода от 0 до 3.

При желании можно импортировать в рабочий проект использовать для получения статистики по покрытию:

import docstringcoverage
cover_results = docstringcoverage.get_docstring_coverage(['somefolder/somefile.py'])


Отдается в виде списка с двумя элементами типа dict:

[
    {'<имя файла>': 
        {
            'missing': ["<имя метода, класса или функции","..."],                                    
            'module_doc': <True or False>,  #есть ли докстринг для модуля
            'missing_count': <missing_count>, #сколько пропущено докстрингов
            'needed_count': <needed_docstrings_count>, #сколько всего должно быть докстрингов
            'coverage': <percent_of_coverage>,      #процент покрытия
            'empty': <True or False> #True, если файл пуст 
                                               #(нет импортов, функций, классов или переменных)
        },
        ...
    },
                  
    #всего по проекту
    {
        'missing_count': <total_missing_count>,
        'needed_count': <total_needed_docstrings_count>,
        'coverage': <total_percent_of_coverage>,                                
    }               


Вся документация с примерами есть на странице проекта.
Алексей @loststylus
карма
2,0
рейтинг 0,0
Реклама помогает поддерживать и развивать наши сервисы

Подробнее
Реклама

Самое читаемое Разработка

Комментарии (9)

  • 0
    Нямка, воспользуюсь. Как-раз есть 2 проекта, которые нужно обязательно сильно покрывать документацией.
    Вот и проверю)

    Жаль что качество доков оценить невозможно(
    • +1
      Это да. Я планирую добавить в будущем прстенький анализ длины докстрингов, чтобы предупреждать если они уж слишком короткие — конечно, не замена ручной проверке качества, но хоть что-то :)
  • 0
    Я, например, проверяю покрытие кода docstring'ами с помощью PyLint — он как раз тоже в процентном соотношении всё выводит.
    • 0
      Упс, был не в курсе что он это умеет. В гугле по docstring coverage ничего полезного не находилось, когда я искал :(
      • 0
        Он же как раз проверяет соответствие кода на PEP 8 и Python style guide, соответственно docstring туда тоже входит (PEP 257), вполне удобно, попробуйте :)
        • +1
          Посмотрел, здорово, действительно есть, правда придется править кофиг, если потребуется проверить только наличие докстрингов без другого анализа :(
  • +2
    Занятно :)

    $> cover.py cover.py
    ....
    Overall statistics:
    Docstrings needed: 11; Docstrings exist: 4; Docstrings missing: 7
    Total docstring coverage: 36.4%;  Grade: not so good
    


    ЗЫ Спасибо, воспользуюсь. Хотя в PyCharm есть встроенная система оценки покрытия…
    • 0
      Все никак не оценю PyCharm, надо будет опробовать — буду теперь знать, что хоть где-то еще есть встроенное :)

      Кстати, docstring-coverage можно с помощью setup.py install поставить ;)
  • 0
    Отложил для быстрой проверки наряду с pep8…

    Сейчас активно используют sphinx-doc для документирования, а у него есть опция ругаться на неполное покрытие… Пока обхожусь им, если надо именно полостью всё описать. Правда, на недокументированных полях и срытых классах его корёжит, а как отключить ему «respect __all__» при генерации док — пока не разобрался ((

Только зарегистрированные пользователи могут оставлять комментарии. Войдите, пожалуйста.