modern-python

name	modern-python
description	Modern Python tooling practices for the mycelium project. Use when installing dependencies, running tools, managing environments, or writing Python code. Always active as a background reference.

Modern Python Practices

This project uses uv for package management, ruff for linting/formatting, and pytest for testing.

Core Rules

Do	Don't
uv add <pkg>	Edit pyproject.toml deps manually
uv add --group dev <pkg>	pip install <pkg>
uv sync --group dev	pip install -r requirements.txt
uv run pytest	python -m pytest or bare pytest
uv run ruff check .	Bare ruff check .
[dependency-groups] for dev tools	[project.optional-dependencies]
uv run python script.py	python script.py (may use wrong env)

Quick Reference

# Install all deps (including dev)
uv sync --group dev

# Add a new dependency
uv add httpx
uv add --group dev pytest-cov

# Remove a dependency
uv remove some-package

# Run any tool through uv
uv run pytest tests/ -x -q
uv run ruff check .
uv run ruff format .
uv run python -c "import mycelium"

# Run with a temporary dep (not added to project)
uv run --with rich python -c "from rich import print; print('hello')"

Project Structure

This project has two Python packages:

Package	Path	Entry
fastapi-backend	fastapi-backend/	app/main.py
mycelium-cli	mycelium-cli/	mycelium.cli:app

Each has its own pyproject.toml. Run uv sync from within each directory.

Linting & Formatting

# Check (don't fix)
uv run ruff check .
uv run ruff format --check .

# Fix
uv run ruff check --fix .
uv run ruff format .

Ruff config is in each pyproject.toml under [tool.ruff]. We use select = ["ALL"] with explicit ignores.

Testing

# Run tests
cd fastapi-backend && uv run pytest tests/ -x -q

# Run specific test
uv run pytest tests/test_memory.py -x -q

# Run with verbose output
uv run pytest tests/ -v

Tests use SQLite in-memory (see tests/conftest.py) — no Postgres needed for unit tests.

Installing the CLI Globally

The CLI has a dependency on the generated OpenAPI client (mycelium-client/). When installing globally via uv tool:

cd mycelium-cli
uv tool install -e . --with mycelium-backend-client@../mycelium-client --force

The --with flag adds the sibling package. Use --force to reinstall after code changes.

For local dev (just running from the repo):

pip install -e ../mycelium-client -e .

Key Patterns

• Python 3.12+ — we use modern syntax (X | Y unions, match/case if needed)
• async/await — FastAPI backend is fully async (asyncpg, AsyncSession)
• Pydantic v2 — BaseModel with model_config = {"from_attributes": True}
• Type hints — always, but don't over-annotate obvious cases
• uv.lock — committed to version control for reproducible builds