# Поддержка Python в Maguyva: ИИ-поиск по коду и рефакторинг

Canonical source: https://maguyva.ai/ru/languages/python

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Maguyva поддерживает Python с разбором AST и извлечением символов, помогая ИИ-агентам отслеживать декораторы, методы self/cls, импорты и межмодульные зависимости в реальных Python-репозиториях.

## Сводка поддержки

- Уровень: Поддержка AST и символов
- Программирование
- Расширения: .py, .pyi, .pyw
- Настоящий AST-разбор для синтаксически осведомлённого поиска и структурного контекста.
- Именованные символы обеспечивают семантический поиск и перекрёстные ссылки. Навигация по графу доступна, когда включено извлечение связей.
- Этот язык добавляет символы и связи в поиск с учётом графа; поддерживаемые типы рёбер зависят от присущих ему конструкций.
- Доступны и AST-разбор, и извлечение символов.

## Лучше всего подходит

- Репозитории на FastAPI, Django, дата-платформах или внутренних инструментах, где прикладной код и эксплуатационные скрипты живут вместе.
- Команды, рефакторящие долгоживущие сервисы на Python, где уже есть декораторы, фоновые задачи и много неявных связей.
- Сценарии работы агентов, которым нужно больше, чем grep, перед изменением обработчика, сервиса, модели или хелпера.

## Сценарии работы агента

- Проследить эндпоинт, задачу или CLI-команду через хелперы и общие модули перед их изменением.
- Найти, где по репозиторию создаётся экземпляр и повторно используется сервис, класс или служебная функция.
- Сравнить соседние реализации, чтобы агент редактировал нужную абстракцию, а не ближайшее текстовое совпадение.

## Где репозитории Python обычно ломают поверхностные ИИ-инструменты

Python — это территория, где многие ИИ-инструменты для кода сначала выглядят хорошо, а затем начинают гадать в продакшне. Сложные места знакомы: точки входа с декораторами, сервисные классы, тайп-стабы, мелкие вспомогательные модули повсюду и методы, которые обретают смысл только после того, как `self` или `cls` снова связывают с классом, которому они принадлежат.

Для Python настоящий вопрос не «умеет ли он читать файлы `.py`?». Вопрос в том, способен ли агент опираться на факты из кода, перемещаясь от эндпоинта к сервису, от фоновой задачи к хелперу или от имени класса к методам, которые реально реализуют поведение.

## Что Maguyva реально извлекает в Python

Maguyva обеспечивает полноценный структурный анализ Python. Конфигурация охватывает `.py`, `.pyw` и `.pyi`; сопоставляет `decorated_definition` с символом функции и дополняет имена вызываемых методов `self` / `cls` именем содержащего их класса. Это важно, потому что именно в этих местах репозитории Python начинают казаться очевидными человеку и расплывчатыми для LLM.

Она также отфильтровывает большую часть шума стандартной библиотеки при извлечении связей. Это значит, что типичные рантайм-вызовы из модулей вроде `pathlib`, `typing` или `logging` с меньшей вероятностью заглушат специфичные для репозитория связи, которые вас действительно интересуют.

## Полезные MCP-сценарии для репозиториев Python

Самый простой полезный сценарий:

- Начните с `intelligent_search` для вопроса о поведении, например «логика повторных попыток вокруг синхронизации счетов» или «проверки прав доступа в биллинговых эндпоинтах».
- Переключитесь на `find_symbol`, как только узнаете имя класса или функции, которая вас интересует.
- Используйте `dependency_search` с обходом входящих связей перед рефакторингом общего сервиса, хелпера или базового класса.

Такой паттерн лучше, чем просить агента «обновить биллинговый поток» с чистого листа. Он позволяет агенту сначала построить карту, а потом уже менять код.

## Когда эта страница полезна

Эта страница — для репозиториев на Python, у которых уже есть некоторый возраст и сложность: сервисный код, задачи, скрипты, сгенерированные типы и окружающая конфигурация. Если ваше основное сравнение — полиглотные веб-монорепозитории, почитайте также [руководство по TypeScript](/ru/languages/typescript). Если вам нужна просто полная матрица поддержки, используйте [совместимость](/ru/docs/compatibility).

## Детали движка

- Декорированные определения всё равно считаются функциями, поэтому декорированные view и задачи остаются доступными для поиска как символы.
- Вызовы методов через `self` и `cls` дополняются именем содержащего их класса, что помогает графу оставаться полезным в коде с большим количеством классов.
- Нормализаторы импортов, вызовов и символов включены, а типичный шум стандартной библиотеки, такой как `pathlib.*`, `typing.*` и `logging.*`, отфильтровывается из связей.

## Полезные точки входа MCP

- `intelligent_search`: Начните с концептуального запроса вроде «логика повторов вокруг синхронизации счетов» и задайте `language_filter="python"`, если репозиторий полиглотный.
- `find_symbol`: Используйте его, когда знаете имя класса или функции и вам нужно определение и ссылки перед редактированием.
- `dependency_search`: Используйте направление incoming перед рефакторингом общего сервиса или хелпера, чтобы увидеть, что от него зависит.