Atlas locates where a behavior is implemented in Python by attacking the problem from three angles at once: codebase_search for meaning, grep for exact text, and the lsp tool for the symbol graph. You describe what the software does, the semantic index returns candidate declarations even when your words never appear in the source, grep confirms the string through ripgrep with include and path filters scoped to *.py, and findReferences lists every callsite. Then pytest proves the file you found is the code that actually runs.
How do you find which Python file implements a behavior?
Atlas finds the Python file behind a behavior by describing the behavior to codebase_search. The semantic index returns candidate declarations even when your words do not appear in the source, because Atlas indexes code by AST declarations using tree-sitter, not blind line windows, and ranks with reciprocal rank fusion in 2026.
Locating behavior is a retrieval problem, and the hard part in Python is that the name you would search for often does not exist. A retry policy may live in a decorator called with_backoff, a permission check may live in a Django middleware class, and a webhook signature check may be a FastAPI dependency named verify. codebase_search takes the description, not the identifier, so a query such as where do we reject expired tokens ranks the def that actually does the rejecting. Every returned snippet carries its .py path, which means the next step is a read, not another guess.
When should you use grep instead of codebase_search in Python?
Atlas ships grep alongside codebase_search because the 2 tools answer different questions. grep takes a real regex plus include and path filters and runs through ripgrep, so a pattern scoped to *.py confirms an exact string such as SECRET_KEY or a decorator name in milliseconds, with zero ranking involved.
grep is the confirmation step. Once codebase_search has proposed a candidate, a regex through ripgrep tells you every literal occurrence of the symbol across the package, including places the semantic index deprioritized: a settings module, a conftest.py fixture, or a call in tests that pytest exercises. Include and path filters keep the sweep inside the Python source instead of dragging in the virtualenv or vendored assets. Semantic search proposes, grep verifies, and the combination is why Atlas ships all three retrieval tools rather than a single fuzzy search box.
How do you find every callsite of a Python function with the lsp tool?
Atlas uses the lsp tool's findReferences operation to list every callsite of a Python symbol, and workspaceSymbol to jump straight to a declaration by name. The symbol graph is the third of 3 angles, after codebase_search for meaning and grep for exact text, and it is the one that proves nothing was missed.
findReferences is what turns a candidate into a call path. Given the authenticate function that codebase_search surfaced, the lsp tool lists each callsite across the package: the FastAPI router that depends on it, the Django view that wraps it, and the pytest module that asserts on its failure branch. workspaceSymbol goes the other direction, taking a name you already know and jumping to the declaration without a directory hunt. Atlas then summarizes the call path back to you with concrete file and line references, so you can open each hop with read rather than trusting a paraphrase.
What happens when Atlas opens the wrong Python file path?
Atlas fails loudly on a bad path. Open the best candidate with read, and a wrong guess returns File not found plus a Did you mean list, so a typo in app/serivces/auth.py does not silently return nothing. Bad paths never go unnoticed during a Python search in 2026.
Silent failure is the real danger in code search, because an empty result reads like proof that the behavior does not exist. Atlas's read tool refuses to be quiet about it: a missing path produces File not found along with a Did you mean list of near matches, which in a Python package usually points straight at the module you meant. Safety extends past reading, too. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so a Python search session cannot turn into an edit of a .py module without you seeing it.
How do you prove the Python code you found is the code that runs?
Atlas proves a located Python symbol is live by running pytest against the module that contains it. A failing assertion you deliberately introduce, or an existing test that exercises the branch, confirms the call path in 1 pytest run, and uv keeps the virtualenv matching pyproject.toml while you check.
Reading a function tells you what it should do, and pytest tells you what it does. Once the lsp tool's findReferences operation has produced the callsites, run pytest on the test module that covers them and watch which assertions touch the branch you care about. If the suite is silent about that branch, you have found a real gap rather than a wrong file. uv keeps dependency resolution honest so the run reflects the pinned tree, and ruff format keeps any exploratory edit from turning into a formatting diff that obscures your actual change.
Which Python idioms hide a behavior from a text search?
Atlas handles the 3 Python idioms that hide behavior from a text search: a decorator that wraps the real function, a Django middleware class registered by dotted string path, and a FastAPI dependency injected by type annotation. codebase_search ranks all 3 by meaning.
Decorators are the classic Python misdirection: grep for the endpoint name and you find the route, not the retry logic wrapping it. Django middleware is registered by dotted string path, so the class name never appears at the callsite. FastAPI dependencies are wired by type annotation, which means the function that authenticates a request can be referenced nowhere near the router. codebase_search ranks by meaning and returns the def that actually runs. grep then confirms the literal decorator name across your .py files and conftest.py, and pytest proves which branch executes under uv.
Which commands do you run while tracking down Python behavior?
Tracking down a behavior in a Python repo takes 3 commands beyond the Atlas tools: uv to sync the virtualenv from pyproject.toml, pytest to run the module that covers the callsite, and ruff format to keep an exploratory edit from becoming a formatting diff.
uv comes first because a pytest run against the wrong virtualenv proves nothing: the import you are chasing may resolve to a different version of the package. pytest comes second, aimed at the specific test module that covers the callsite the lsp tool listed, not the whole suite. ruff format comes last, and only if you edited anything while looking, because a reformatted .py file buries the one line you care about. conftest.py is worth a read before any of them, since a fixture there often explains why the behavior looks different under pytest than it does in production.
Step by step
- 01Describe the behavior to codebase_search in plain language; the semantic index returns candidate Python declarations even when your words do not appear in the source.
- 02Confirm with grep, which takes a real regex plus include and path filters and runs through ripgrep, scoping the sweep to *.py files.
- 03Open the best candidate with read; a wrong guess fails loudly with File not found plus a Did you mean list, so bad paths do not go unnoticed.
- 04Use the lsp tool's findReferences operation to see every callsite of the Python symbol, and workspaceSymbol to jump to the declaration by name.
- 05Run pytest on the test module covering that callsite to prove the code path is live, with uv keeping the virtualenv aligned to pyproject.toml.
- 06Run ruff format before any exploratory edit so formatting noise never hides the change you are inspecting.
- 07Ask Atlas to summarize the call path back to you with concrete file and line references.
Frequently asked questions
- how do I find where a function is defined in a large Python project
- Use the lsp tool's workspaceSymbol operation to jump to the declaration by name, or describe the behavior to codebase_search when you do not know the name. Atlas indexes code by AST declarations using tree-sitter, so it returns the actual def or class.
- how do I find all callers of a Python function
- Run the lsp tool's findReferences operation on the symbol. Atlas returns every callsite with concrete file and line references, which is more reliable than grepping a name that may be shadowed or re-exported across your Python packages.
- grep vs semantic search for finding code in Python
- Use both. grep takes a real regex plus include and path filters and runs through ripgrep, so it confirms exact text in *.py files. codebase_search finds candidate declarations by meaning even when your words never appear in the source.
- how do I find which Django or FastAPI handler implements a behavior
- Describe the behavior to codebase_search rather than guessing the route name. The semantic index ranks the declaration that implements it, then the lsp tool's findReferences operation shows the router or view that wires the handler in.
- why does Atlas say File not found when I ask it to read a Python module
- Atlas's read tool fails loudly on a bad path and returns File not found plus a Did you mean list of near matches. The message means the path is wrong, not that the code is missing, so pick the suggested .py path and retry.
- can Atlas run pytest to confirm the code path it found
- Yes. Atlas can run pytest against the module covering the callsite, with uv keeping the virtualenv aligned to pyproject.toml. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs.
- can I search Python code with an AI agent without uploading it
- Yes. Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers, so codebase_search still works on a private Python repository.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Locate Where a Behavior Is Implemented with Atlas in 2026
How to locate where a behavior is implemented with Atlas in 2026: codebase_search for meaning, grep for exact text, and the lsp tool for the symbol graph.
Atlas for Python in 2026
Atlas is a terminal-native AI coding agent for Python in 2026. Run it in a repo with a pyproject.toml or requirements.txt and review every diff before it lands.
Run the Test Suite and Triage the Failures in Python with Atlas (2026)
How Atlas runs pytest and triages a wall of Python failures in 2026: bash truncates at 2000 lines, saves the full log, and grep groups failures into a todowrite list.
Diagnose a Hanging or Long-Running Command in Python with Atlas (2026)
Is your Python command slow or blocked on stdin? In 2026 Atlas races every bash command against a timeout and its shell_metadata tells you which, so pytest and uv stop hanging.
Automate GitHub Issue and Pull Request Triage in Python with Atlas (2026)
Wire the atlas github command into a Python repo's workflow in 2026. Require MODEL in provider/model form, gate on write permission, and verify with pytest and ruff format.
Research a Third-Party API Before Integrating It in Python with Atlas in 2026
Research a third-party API before integrating it in Python in 2026. Atlas uses websearch and webfetch to pull live docs, then writes against real signatures.
Plan a Multi-File Change Before Editing in Python with Atlas in 2026
Plan a multi-file Python change before editing in 2026. Atlas's plan agent denies edit for every path except .atlas/plans/*.md, then plan_exit hands off to build.
Upgrade Python Dependencies and Fix Breakage with Atlas in 2026
In 2026, Python developers use Atlas to upgrade dependencies like Django or FastAPI, automatically fixing compile and test failures with `uv`, `pytest`, and `ruff format`.