# Suporte a Python no Maguyva: Busca de Código e Refatoração com IA

Canonical source: https://maguyva.ai/pt-br/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).

O Maguyva oferece suporte a Python com parsing de AST e extração de símbolos, ajudando agentes de IA a seguir decorators, métodos self/cls, imports e dependências entre módulos em repositórios Python reais.

## Panorama de suporte

- Nível: Suporte a AST e símbolos
- Programação
- Extensões: .py, .pyi, .pyw
- Parsing real de AST para busca com consciência de sintaxe e contexto estrutural.
- Símbolos nomeados alimentam a busca semântica e as referências cruzadas. A navegação por grafo fica disponível quando a extração de relações está habilitada.
- Esta linguagem fornece símbolos e relações para a busca orientada por grafo; os tipos de aresta compatíveis variam de acordo com seus construtos nativos.
- A análise de AST e a extração de símbolos estão disponíveis.

## Uso ideal

- Repositórios FastAPI, Django, de plataformas de dados ou de ferramentas internas em que código de aplicação e scripts operacionais convivem.
- Equipes refatorando serviços Python de longa vida que já têm decorators, jobs em background e muita conexão implícita.
- Fluxos de trabalho de agentes que precisam de mais do que grep antes de mudar um handler, service, model ou helper.

## Fluxos de trabalho de agente

- Rastrear um endpoint, task ou comando de CLI através de helpers e módulos compartilhados antes de editá-lo.
- Encontrar onde um service, classe ou função utilitária é instanciado e reutilizado em todo o repositório.
- Comparar implementações adjacentes para que o agente edite a abstração certa, em vez da correspondência de string mais próxima.

## Onde repositórios Python costumam quebrar ferramentas de IA superficiais

Python é onde muitas ferramentas de IA para código parecem boas no início e depois começam a chutar em produção. As partes difíceis são conhecidas: pontos de entrada decorados, classes de serviço, type stubs, pequenos módulos auxiliares por toda parte, e métodos que só fazem sentido depois de reconectar `self` ou `cls` à classe a que pertencem.

Para Python, a pergunta real não é "ele consegue ler arquivos `.py`?". A pergunta é se o agente consegue se manter fundamentado enquanto se move de um endpoint para um service, de uma task em background para um helper, ou de um nome de classe para os métodos que de fato implementam o comportamento.

## O que o Maguyva realmente extrai em Python

O Maguyva oferece suporte completo à análise estrutural de Python. A configuração cobre `.py`, `.pyw` e `.pyi`; mapeia `decorated_definition` de volta a um símbolo de função; e qualifica chamadas de método `self` / `cls` com o nome da classe que as contém. Isso importa porque são exatamente os pontos em que repositórios Python começam a parecer óbvios para um humano e nebulosos para um LLM.

Ele também filtra bastante ruído de biblioteca padrão na extração de relacionamentos. Isso significa que chamadas comuns de runtime vindas de módulos como `pathlib`, `typing` ou `logging` têm menos chance de afogar os relacionamentos específicos do repositório que realmente importam para você.

## Fluxos de trabalho com MCP úteis para repositórios Python

O fluxo de trabalho útil mais simples é:

- Comece com `intelligent_search` para uma pergunta de comportamento, como "lógica de retry em torno da sincronização de faturas" ou "verificações de permissão em endpoints de cobrança".
- Mude para `find_symbol` assim que souber o nome da classe ou função de interesse.
- Use `dependency_search` com travessia de entrada antes de refatorar um service, helper ou classe base compartilhada.

Esse padrão é melhor do que pedir a um agente para "atualizar o fluxo de cobrança" a partir do zero. Ele deixa o agente construir um mapa primeiro e mudar o código depois.

## Quando esta página é útil

Esta página é para repositórios Python que já têm alguma idade e complexidade: código de serviço, jobs, scripts, tipos gerados e configuração ao redor. Se a sua principal comparação é entre monorepos web poliglotas, leia também o [guia de TypeScript](/pt-br/languages/typescript). Se você só precisa da matriz de suporte completa, use [compatibilidade](/pt-br/docs/compatibility).

## Detalhes do motor

- Definições decoradas ainda são tratadas como funções, então views e tasks decoradas continuam pesquisáveis como símbolos.
- Chamadas de método via `self` e `cls` são qualificadas com o nome da classe que as contém, o que ajuda o grafo a se manter útil em código de serviço rico em classes.
- Normalizadores de import, chamada e símbolo ficam habilitados, enquanto ruído comum da stdlib como `pathlib.*`, `typing.*` e `logging.*` é filtrado das relações.

## Pontos de entrada MCP úteis

- `intelligent_search`: Comece com uma consulta conceitual como “lógica de retry ao redor da sincronização de fatura” e defina `language_filter="python"` se o repositório for poliglota.
- `find_symbol`: Use quando você souber o nome da classe ou função e precisar da definição mais as referências antes de editar.
- `dependency_search`: Use a direção incoming antes de refatorar um serviço ou helper compartilhado, para ver o que depende dele.