Задать вопрос
2ord
@2ord

Какие существуют средства автодокументации кода Python для недокументированного кода?

В одном проекте, доставшемся "по наследству", написанному на фреймворке FastAPI (если это имеет значение), имеется более тысячи строк едва документированного кода, все в одном файле (!). Понятное дело, в этой мешанине трудно ориентироваться и хочется начать с автодокументации кода. Я имею в виду не просто генерацию названия функций с их сигнатурами, а больше про то какое у них предназначение. А для этого, насколько я понимаю, нужно использовать ИИ модели, понимающие код и умеющие делать подытоживание.
Пробовал Sphinx расширение AutoAPI, но оно не решает саму проблему с отсутствующими комментариями. А мне очень важно, чтобы хотя бы вкратце функции и методы говорили об их предназначении.
В общем, исходя из возможностей инструментов автодокументирования, прихожу к выводу, что они не умеют делать вышесказанного. Или я не прав?

Пример исходного кода:
def get_docs_time_range(docs: list[DTOStatus]) -> tuple[datetime, datetime]:
    dates = [doc.created_at_timestamp for doc in docs]
    dates.sort()
    earliest = dates[0]
    latest = dates[-1]
    return (earliest, latest)


Желаемый результат:
def get_docs_time_range(docs: list[DTOStatus]) -> tuple[datetime, datetime]:
    """
    Returns the earliest and latest timestamp from the given list of DTOStatus objects.
    
    Args:
        docs (list[DTOStatus]): A list of DTOStatus objects containing the timestamps to analyze.
    
    Returns:
        tuple[datetime, datetime]: A tuple containing the earliest and latest timestamps from the input list.
    """
    dates = [doc.created_at_timestamp for doc in docs]
    dates.sort()
    earliest = dates[0]
    latest = dates[-1]
    return (earliest, latest)
  • Вопрос задан
  • 138 просмотров
Подписаться 1 Простой 2 комментария
Решения вопроса 1
2ord
@2ord Автор вопроса
В итоге я написал своей инструмент для автодокументации.
Как это работает:
Код парсится в AST при помощи модуля ast. Ходим по узлам я проверяем не является ли функцией, проверяя, нет ли существующей документации функции ast.get_docstring(node).
Если отсутствует, то получаем тело функции ast.unparse(node) и отправляем запрос LLM с промптом (использовал Codestral), прося подготовить краткое описание назначения функции согласно PEP 257. Полученный ответ вставляется обратно в тело функции в ее узле.

Из минусов следует отметить, что модуль "ast" отбрасывает комментарии в коде при его парсинге, что потенциально могло добавить некоторые нюансы при генерации docstring.

В итоге, модифицированное дерево AST дампится в новый файл.
Затем этот файл заменяет исходный файл в коде проекта и мне необходимо было сделать вручную откат на код с комментариями и тем места, где была разница с кавычками и форматированием (благо, их было немного).

В качестве оптимизации, чтобы сберечь запросы при дебагинге, воспользовался хранилищем K/V.
Ответ написан
Комментировать
Пригласить эксперта
Ответы на вопрос 1
@rPman
Топовые ИИ могут это сделать (openai o1/gpt4o, anthropic claude opus/sonet, google gemini pro, qwen 2.5 72b, llama3.2 70b,.. изучи lmsys арену lmarena.ai там можно выбрать домен задачи), у тебя не очень большой объем кода.

Главная ошибка - пытаться одним промптом решить задачу (хотя o1 может быть близок к этому). Поиграй с промптами, твоя задача собрать описание работы твоего кода, опиши все что знаешь сам, напиши запрос, которым можно собрать информацию по функционалу, информацию по структуре кода,.. если есть время, попробуй разобрать код на структурные элементы, хотя бы 3 уровня (например модули - классы - методы) и задавать ИИ один и тот же вопрос, собрав в контексте весь код, структурное описание и в конце задавай вопрос о назначении конкретного элемента, и так повторить для каждого. Собирай ответы в один большой запрос, который уже в последствии можно передать o1 на итоговый анализ (можно и без нее, внутри o1 по уму делает именно это, но так как openai на столько закрытая что готова жестоко наказывать любого, кто попытается узнать этот алгоритм).

Я помню мне хватило одной модели claude sonet и с десяток запросов, чтобы проанализировать исходный код чужого проекта и понять, на сколько ограничен или нет его функционал, при этом я спрашивал у модели итеративно, какой файл исходников ему нужен, в твоем случае все влезет за раз.

Помни что чем больше размер контекстного окна, тем сильнее llm теряет информацию в нем (случайно), но повторение этой информации наоборот увеличивает ее значимость для нее, т.е. исходный код + описание этого кода облегчает для модели анализ. Есть и недостатки, даже топовые модели - переобучены (это болезнь всех нейронок), и какое-нибудь неосторожное ключеове слово или название может заставить модель думать не так как надо а как было написано в обучающих данных, тупой пример - если я хочу написать проект, работающий с api openai, и модель научена на ней, то мне было невероятно сложно заставить модель не генерировать сложный метод формирования api запроса, вместо вызова одной строчки (как я требовал в промпте) curl, прописанной в конфиге... но как только я убрал везде упоминание openai и подробно описал требования, так все прошло на ура. Поэтому, экспериментируй, изучай, перепроверяй все что тебе сгенерирует ИИ. Современный ИИ это не замена, а очень мощный инструмент помощник, который возьмет на себя скучную рутину.

p.s. рекомендую лайфхак
когда тебе нужен короткий ответ на твой вопрос, следуй следующему сценарию (особенно если используешь слабые модели, но работает для нетиповых задач и у топовых), в виде чат-сессии:
{твой вопрос}
{добавь текст: 'глубоко вдохни и подумай шаг за шагом'/'take a deep breath and think step by step'}
[получи ответ, читать его не обязательно но оставь его в контекстном окне]
{задай вопрос: 'а если подумать еще раз'/'but if you think about it again'}
[получи еще один ответ, читать его так же не обязательно но оставь его в контекстном окне]
{задай окончательный вопрос: 'Итак, какой будет твой ответ?'/'So, what will be your answer?', тут можно определить, в каком виде нужен ответ}
[получи окончательный ответ]

По поводу 'take a deep breath' была исследовательская работа, которая показала что эта просьба повышает качество моделей очень значительно, а мои исследования показали что просьба 'подумать еще раз' позволяет модели сомневаться в предыдущем тексте и искать альтернативные варианты, обычно это исправляет ошибки, если это в принципе возможно.

Еще странный совет - попробуй решить задачу на разных языках, не только на английском, сравни ответ, тебя может это удивить.
Ответ написан
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Похожие вопросы