Python Extension

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

Scope: All jobs are project-only. They require a project context (no workspace-level runs).

External tools

• Python
• uv
• Ruff
• pytest

Enable the extension

Install the package at the workspace root:

bun add @putnami/python

{
  "name": "my-workspace",
  "plugins": ["@putnami/python"]
}

Jobs

run

Execute a Python entrypoint.

Behavior:

• Runs the entrypoint via bun run in the project directory.

Options:

• entrypoint (default: src/main.py)

Example:

bunx putnami run . src/scripts/migrate.py

test

Run tests using pytest.

Behavior:

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

Options:

• --log (enables pytest log output)
• --update-snapshots
• --test <filter> (short: -t)

Example:

bunx putnami test . --log

lint

Lint Python code with Ruff.

Behavior:

• Runs uv run ruff check in the project directory.

Options:

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

Example:

bunx putnami lint . --fix

serve

Run a Python entrypoint as a server.

Behavior:

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

Options:

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

Example:

bunx putnami serve . --entrypoint src/server.py

Caching and dependencies

The Python plugin does not declare custom cache patterns or dependency relationships in putnami.extension.json.

Project Templates

The Python extension ships two project templates for quick scaffolding:

python-server

A FastAPI server with uvicorn and tests.

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

Generates:

packages/my-api/
├── package.json          # putnami.runtime = python
├── pyproject.toml        # FastAPI + uvicorn dependencies
├── src/
│   └── my_api/
│       └── __init__.py   # FastAPI app with health endpoint
└── tests/
    └── test_server.py    # Server test

After creation, sync the UV workspace and serve:

bunx putnami workspace-install --force
putnami serve my-api

python-library

A Python library skeleton with an importable module and tests.

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

Generates:

packages/my-lib/
├── package.json          # putnami.runtime = python
├── pyproject.toml        # Library config
├── src/
│   └── my_lib/
│       ├── __init__.py   # Package entry
│       └── hello.py      # hello(name) function
└── tests/
    └── test_hello.py     # Unit test

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

Examples

# Run a script
bunx putnami run . src/scripts/migrate.py

# Run tests
bunx putnami test .

# Lint and fix
bunx putnami lint . --fix

# Serve with a custom entrypoint
bunx putnami serve . --entrypoint src/server.py

Next steps

• Previous: Go
• Next: Docker