Development¶

Prerequisites¶

Python 3.13 or later
uv for dependency management

Setup¶

git clone https://github.com/juanjosegarciaripoll/pony.git
cd pony
uv sync

Running¶

# Run the TUI
uv run pony tui

# Run any command
uv run pony doctor
uv run pony sync
uv run pony compose --to alice@example.com

Quality gates¶

All three checks must pass before merging:

# Lint and format
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# Type checking (both checkers must pass)
uv run mypy src/
uv run basedpyright src/

# Tests
uv run python -m pytest tests/

Lint¶

Ruff handles both linting and formatting. Selected rule sets: E, F, I, B, UP, N, ARG, SIM.

Type checking¶

Both mypy (strict mode) and basedpyright (strict mode) are required. The Textual framework's generic types produce some reportUnknownMemberType warnings in basedpyright that are suppressed with inline comments.

Tests¶

Tests use Python's built-in unittest framework, organized in tests/. Run them with pytest for better output:

uv run python -m pytest tests/ -v

The test suite includes:

Unit tests: MIME parsing, flag mapping, reply/forward quoting, attachment extraction, search query compilation, BBDB roundtrip
Conformance tests: both Maildir and mbox backends run the same CRUD/flag test suite
Sync tests: deterministic fixtures via FakeImapSession cover new message ingestion, flag reconciliation, conflict resolution, UIDVALIDITY reset
Index tests: SQLite schema, multi-field search, case sensitivity, checkpoints, pending operations, delete, batched transactions
Contacts tests: upsert, search, harvest, delete, merge (two-way and three-way), BBDB import/export
Mirror integrity tests: orphan file detection, stale index row detection
Renderer tests: HTML stripping (style/script block removal), nested email rendering

Building documentation¶

The documentation uses MkDocs with the Material theme.

# Install docs dependencies
uv sync --group docs

# Serve locally with live reload
uv run mkdocs serve

# Build static site
uv run mkdocs build

The built site goes to site/ (gitignored). GitHub Pages deployment is automated via the .github/workflows/docs.yml workflow.

Building standalone executables¶

The primary distribution format is a platform-native binary built with PyInstaller. Each release produces two artifacts per platform: a platform installer and a portable archive suitable for package managers such as Homebrew (macOS) or Scoop (Windows).

Platform	Installer	Portable archive
Windows	`pony-windows-vX.Y.Z-setup.exe`	`pony-windows-vX.Y.Z.zip`
macOS	`pony-macos-vX.Y.Z.dmg`	`pony-macos-vX.Y.Z.tar.gz`
Linux	`pony-linux-vX.Y.Z.AppImage`	`pony-linux-vX.Y.Z.tar.gz`

Prerequisites¶

uv sync --group build --group docs

This installs pyinstaller and mkdocs-material alongside the regular dev dependencies.

Local build¶

# Full build: tests + docs + binary + portable archive
uv run python scripts/build.py

# Also produce the platform installer
uv run python scripts/build.py --installer

# Skip slow steps while iterating
uv run python scripts/build.py --skip-tests --skip-docs --installer

Artifacts land in artifacts/. An artifacts.json manifest lists every path.

What is bundled¶

pony.spec controls what goes into the binary. Two data trees are always included:

site/ — the pre-built HTML documentation (generated by mkdocs build)
config-sample.toml — annotated configuration template

The pony docs command uses the bundled docs when running as a binary, falling back to the online documentation when running from source.

Platform installer notes¶

Platform	Tool	Notes
Windows	Inno Setup 6+	`iscc` must be on `PATH`. Script: `installers/windows/pony.iss`. Offers optional PATH registration.
macOS	`hdiutil` (built-in)	Creates a drag-to-Applications DMG.
Linux	`appimagetool`	Downloaded automatically on first run if absent. Produces a single portable AppImage.

CI¶

The release-build.yml workflow runs on every version tag and on GitHub Release publication. It runs tests, builds the docs, compiles the binary, and uploads both the installer and the portable archive for each platform.

Project structure¶

pony/
  src/pony/           # main package
  tests/              # test suite
  docs/               # documentation (MkDocs source)
  .github/workflows/  # CI/CD workflows
  mkdocs.yml          # MkDocs configuration
  pyproject.toml      # project metadata and tool config
  PLAN.md             # development roadmap
  ARCHITECTURE.md     # technical design
  SPECIFICATIONS.md   # product goals and scope
  MEMORY.md           # session restart context
  config-sample.toml  # annotated config template
  LICENSE             # MIT license

GitHub Pages setup¶

To enable GitHub Pages for this repository:

Go to Settings > Pages in the GitHub repository.
Under Build and deployment, set Source to GitHub Actions.
Push to the main branch. The docs.yml workflow will build and deploy the documentation automatically.
The site will be available at https://<username>.github.io/pony/.

No additional configuration is needed. The workflow uses the actions/deploy-pages action with the github-pages environment.