coiled

Coiled utils

Installation

Install using pip:

pip install coiled

Or using uv:

uv pip install coiled

Usage

from pdum import coiled

print(coiled.__version__)

Development

This project uses UV for dependency management.

Setup

# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install pnpm (required for the widgets workspace)
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Clone the repository
git clone https://github.com/habemus-papadum/coiled.git
cd coiled

# Provision the entire toolchain (uv sync, pnpm install, widget build, pre-commit hooks)
./scripts/setup.sh

Important for Development:

• ./scripts/setup.sh is idempotent—rerun it after pulling dependency changes
• Use uv sync --frozen to ensure the lockfile is respected when installing Python deps
• The widgets live in widgets/ and are managed with pnpm (see "TypeScript widgets" below)

Running Tests

# Run all tests
uv run pytest

# Run a specific test file
uv run pytest tests/test_example.py

# Run a specific test function
uv run pytest tests/test_example.py::test_version

# Run tests with coverage
uv run pytest --cov=src/pdum/coiled --cov-report=xml --cov-report=term

Code Quality

# Check code with ruff
uv run ruff check .

# Format code with ruff
uv run ruff format .

# Fix auto-fixable issues
uv run ruff check --fix .

TypeScript widgets (pnpm)

# Lint the widget source
pnpm lint

# Type-check only the widgets package
pnpm --filter '@habemus-papadum/coiled-widgets' typecheck

# Build the browser bundle and copy it into the Python package
pnpm --filter '@habemus-papadum/coiled-widgets' build:python

# Run Vitest (or add --coverage)
pnpm --filter '@habemus-papadum/coiled-widgets' test

Building

# Build Python + TypeScript artifacts
./scripts/build.sh

# Or build just the Python distribution artifacts
uv build

Publishing

# Build and publish to PyPI (requires credentials)
./scripts/publish.sh

Automation scripts

• ./scripts/setup.sh – bootstrap uv, pnpm, widget bundle, and pre-commit hooks
• ./scripts/build.sh – reproduce the release build locally
• ./scripts/pre-release.sh – run the full battery of quality checks
• ./scripts/release.sh – orchestrate the release (creates tags, publishes to PyPI/GitHub)
• ./scripts/test_notebooks.sh – execute demo notebooks (uses ./scripts/nb.sh under the hood)
• ./scripts/setup-visual-tests.sh – install Playwright browsers for visual tests

License

MIT License - see LICENSE file for details.