Skip to content
cd /languages
Dynamic systems Programming Full graph support

Python Support in Maguyva: AI Code Search and Refactoring

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.

Start free Compatibility details

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 too. If you just need the full support matrix, use compatibility.

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.

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.

Related guides

Adjacent repo surfaces

Browse all guides
MAGUYVA.NFO