Python Extension

The @putnami/python extension provides test, lint, and serve jobs for Python projects in a Putnami workspace.

Scope: All jobs are project-only — they require a project context.

External tools

• Python
• uv
• Ruff
• pytest

Enable the extension

putnami deps add @putnami/python

The extension is auto-discovered from workspace dependencies.

Jobs

test

Run tests using pytest.

• Discovers tests with **/test_*.py
• If no tests are found, returns SKIP
• Executes uv run pytest

Options:

• --log — Enable pytest log output
• --update-snapshots
• --test <filter> / -t

putnami test . --log

lint

Lint Python code with Ruff.

• Runs uv run ruff check in the project directory

Options:

• --fix <boolean> (default: true)

putnami lint . --fix

serve

Run a Python entrypoint as a server.

• Uses project.main if set, otherwise src/main.py
• Executes uv run <entrypoint>

Options:

• --entrypoint <path>
• --port <number> (default: 3000)

putnami serve . --entrypoint src/server.py

Docker

When the docker publish channel is enabled, the Python extension generates a Dockerfile using ghcr.io/astral-sh/uv:python3.12-bookworm-slim as the base image and uses uv for dependency resolution.

Enable in project config:

{
  "publish": ["docker"]
}

Caching and dependencies

Each job declares its own task inputs and outputs in putnami.extension.json. Cache invalidation is driven by file patterns defined on each task.

Project templates

Template	Description
python-server	FastAPI server with uvicorn and tests
python-library	Python library with importable module and tests

putnami projects create my-api --template python-server
putnami projects create my-lib --template python-library

Python module names are normalized with underscores (e.g., my-lib becomes my_lib).

After creating a Python project, sync the UV workspace before serving:

putnami deps install
putnami serve my-api