python-code-context

name	python-code-context
description	Load Python API surfaces into context before working on code. Use when you need to understand a Python project's structure before generating code, writing tests, reviewing a PR, planning a refactor, or answering architecture questions — even if the user doesn't ask for a summary explicitly. Also use when starting work in an unfamiliar Python codebase, when the user says 'look at the code first', or when you need to know what classes and functions exist before making changes. Do NOT use for non-Python projects.
compatibility	{"platform":"universal"}
metadata	{"author":"b-j-karl","version":"1.0"}

Python Code Context

Use api-squash to load Python API surfaces into your context so you can reason about codebase structure without reading every source file.

CLI reference: For command syntax, flags, and output format details, invoke the api-squash-cli skill.

Use for

• Loading structural context before generating code in a Python project
• Understanding what classes, functions, and signatures exist before writing tests or making changes
• Orienting yourself in an unfamiliar Python codebase
• Answering "what does this project expose?" or "how is this structured?"
• Preparing context before a code review or refactor
• Reducing token costs — api-squash typically cuts output by 60–90% compared to reading full source files

Do not use for

• Non-Python projects
• Tasks where you already have sufficient context
• When the user explicitly asks to read full source files

---

Workflow

Step 1 — Decide scope

Before running anything, decide what you need:

You need to…	Run
Understand one module	api-squash file <path>
Survey a whole project or package	api-squash project <path>
Get a high-level overview only	api-squash project --max-depth 1 --no-docstrings <path>
Minimise tokens (large codebase)	api-squash project --no-docstrings --no-private <path>
Focus on public API only	api-squash project --no-private <path>
Only strict __all__ exports	api-squash project --public-only <path>

Step 2 — Run api-squash and read the output

Run the appropriate command and read the output directly. The output is Markdown that lists every class and function signature in the target.

If api-squash is not on PATH, use uvx api-squash instead.

# Example: survey a project's public API
api-squash project --no-private src/

Do not save to a file unless the user asks — read the stdout directly.

Step 3 — Use the context

Now that you have the API surface loaded, proceed with the user's actual task (code generation, test writing, refactoring, review, etc.) using the structural knowledge you've gained.

---

Decision guide

When to use file vs project

• file — you already know which module matters (e.g. the user pointed at a specific file, or you're writing tests for one module)
• project — you need cross-module awareness (e.g. understanding imports, finding the right class to extend, planning a refactor across packages)

When to strip docstrings / private methods

• Keep docstrings when you need to understand what functions do (writing tests, answering usage questions)
• Strip docstrings (--no-docstrings) when you only need the shape of the API (planning, architecture, finding the right hook point)
• Strip private (--no-private) when you only care about the public interface (integration work, SDK consumers)

--public-only vs --no-private

Both flags reduce output size but filter differently:

• --no-private removes _-prefixed names but keeps __init__ and any private items referenced by public signatures.
• --public-only filters to only names listed in __all__. Modules without __all__ are unaffected.

Use --no-private to hide implementation internals while keeping the full exported interface. Use --public-only when you need only what the module explicitly declares as its public API.

When to limit depth

• --max-depth 1 for a quick top-level orientation in a large project
• No depth limit when you need the full picture

---

Anti-patterns

• Don't skip this step. Reading individual files one by one wastes tokens and misses the big picture. Run api-squash first, then drill into specific files only if needed.
• Don't dump everything. For large codebases, start with --max-depth 1 --no-docstrings and drill deeper only into relevant packages.
• Don't save to a file by default. Read the output directly — saving creates cleanup work and the output is already compact.