# Python Support in Maguyva: AI Code Search and Refactoring

Canonical source: https://maguyva.ai/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 supports Python with AST parsing and symbol extraction, helping AI agents follow decorators, self/cls methods, imports, and cross-module dependencies in real Python repositories.

## Support snapshot

- Tier: AST and symbol support
- Programming
- Extensions: .py, .pyi, .pyw
- Real AST parsing for syntax-aware search and structural context.
- Named symbols feed semantic lookup and cross-reference. Graph navigation is available when relationship extraction is enabled.
- This language contributes symbols and relationships to graph-aware search; supported edge types vary with its native constructs.
- AST parsing and symbol extraction are both available.

## Best fit

- FastAPI, Django, data-platform, or internal tooling repos where application code and operational scripts live together.
- Teams refactoring long-lived Python services that already have decorators, background jobs, and a lot of implied wiring.
- Agent workflows that need more than grep before changing a handler, service, model, or helper.

## Agent workflows

- Trace an endpoint, task, or CLI command through helpers and shared modules before editing it.
- Find where a service, class, or utility function is instantiated and reused across the repo.
- Compare adjacent implementations so the agent edits the right abstraction instead of the closest string match.

## Where Python repos usually break shallow AI tools

Python is where a lot of AI coding tools look good at first and then start guessing in production. The difficult parts are familiar: decorated entry points, service classes, type stubs, small helper modules everywhere, and methods that only make sense once you reconnect `self` or `cls` to the class they belong to.

For Python, the real question is not "can it read `.py` files?" The question is whether the agent can stay grounded while it moves from an endpoint to a service, from a background task to a helper, or from a class name to the methods that actually implement the behavior.

## What Maguyva actually extracts in Python

Maguyva treats Python as a full structural language. The config covers `.py`, `.pyw`, and `.pyi`; maps `decorated_definition` back to a function symbol; and qualifies `self` / `cls` method calls back to the enclosing class. That matters because those are the exact places where Python repositories start feeling obvious to a human and fuzzy to an LLM.

It also filters a lot of standard-library noise out of relationship extraction. That means common runtime calls from modules like `pathlib`, `typing`, or `logging` are less likely to drown out the repository-specific relationships you actually care about.

## Useful MCP workflows for Python repos

The simplest useful workflow is:

- Start with `intelligent_search` for a behavior question such as "retry logic around invoice sync" or "permission checks in billing endpoints".
- Switch to `find_symbol` once you know the class or function name you care about.
- Use `dependency_search` with incoming traversal before refactoring a shared service, helper, or base class.

That pattern is better than asking an agent to "update the billing flow" from a cold start. It lets the agent build a map first and change code second.

## When this page is useful

This page is for Python repos that already have some age and complexity: service code, jobs, scripts, generated types, and surrounding config. If your main comparison is across polyglot web monorepos, read the [TypeScript guide](/languages/typescript) too. If you just need the full support matrix, use [compatibility](/docs/compatibility).

## Engine details

- Decorated definitions are still treated as functions, so decorated views and tasks remain searchable as symbols.
- `self` and `cls` method calls are qualified back to the enclosing class, which helps the graph stay useful in class-heavy service code.
- Import, call, and symbol normalizers are enabled while common stdlib noise such as `pathlib.*`, `typing.*`, and `logging.*` is filtered out of relationships.

## Useful MCP entry points

- `intelligent_search`: Start with a conceptual query like “retry logic around invoice sync” and set `language_filter="python"` if the repo is polyglot.
- `find_symbol`: Use it when you know the class or function name and need the definition plus references before editing.
- `dependency_search`: Use incoming direction before refactoring a shared service or helper to see what depends on it.