calverse — Scripture verse calendars, in any language and script

Turn a list of dated Scripture verses into a print-ready PDF wall calendar: one month per page, A4 landscape, a verse and its reference in every day cell.

▶ Try it now — no install: calverse.onrender.com

Paste a CSV (or click Load sample, or upload a USFM/Paratext .zip), pick a language, and download a PDF right in your browser. Nothing you submit is stored. It's a free instance that sleeps when idle, so the first request after a while may take ~30–60 s to wake up — then it's fast.

calverse is script-neutral by design — Devanagari, Telugu, Arabic, Thai, Khmer, Ethiopic, CJK and Latin all render with correct shaping given a suitable font — and it prompts for whatever it needs: it detects the script from the text, canonicalises the language tag, finds a licence-cleared font, fills in localized month and weekday names, and asks you only for the gaps.

Its first rule (from SPEC.md) is never silently truncate Scripture: every generation runs a layout-level clip audit and a character-coverage check, and refuses to hide a verse that does not fit.

pip install -e .                 # or: pip install -e ".[web]" for the web UI
calverse sample --out data/versesEn.csv
calverse wizard --csv data/versesEn.csv --tag en --out calendar.pdf

WeasyPrint needs Pango + HarfBuzz + fontconfig at runtime. On Linux install the system libs (see Install); the easiest cross-platform path is the Docker image. The pure-Python parts (detection, USFM parsing, selection, locale/font lookup) run anywhere.

---

Three ways to use it

Prong	What	Command
CLI / library (primary)	Offline, your text never leaves your machine	calverse …
Web service	A browser UI — live at calverse.onrender.com	calverse serve / Docker
Static browser	(future) client-side render, GitHub Pages	see docs/DEPLOY.md

How it stays generic across languages

calverse leans on three SIL language-technology services, each cached and each with a graceful fallback so a slow or down service never fails a generation (docs/LANGUAGES.md):

• Script detection — fontTools.unicodedata reads the dominant ISO 15924 script straight off your verse text.
• langtags.json — canonicalises a tag and fills in the likely script: wsg → wsg-Telu-IN (Adilabad Gondi, Telugu script).
• Language Font Finder — ranked, licence-gated font families that cover the script, with a direct URL for each weight (so day numbers get a real Bold in the right script, not a Latin fallback).
• SLDR + CLDR/babel — authoritative month names, weekday names, first day of week, text direction and numbering system. babel answers offline for major locales; SLDR is the authority for minority tags. When neither has the data, calverse says so and asks you — it never ships a guess.

calverse analyze --csv verses.csv --tag wsg
#  script       : Telu (Telugu), dir ltr
#  language     : Gondi, Adilabad [wsg-Telu-IN]
#  localisation : fallback-english (ok=False)   ← will ask you for names
#  fonts (lff)  : Noto Sans Telugu  OFL v2.005 …
#  ! No localized month/weekday names for wsg; English is a placeholder.

Commands

calverse wizard   --csv F [--tag T]      interactive: detect, prompt, generate
calverse generate --csv F …              CSV → PDF (all legacy flags preserved)
calverse analyze  --csv F [--tag T]      show what it detects / would ask
calverse select   --usfm ZIP|DIR|FILE    whole Bible → dated, spread, stable CSV
calverse usfm     --usfm ZIP|DIR|FILE    USFM → candidate CSV of every verse
calverse fonts    --tag T | --script S   find / download licence-cleared fonts
calverse metrics  in.ttf out.ttf --csv F retune a font's vertical metrics
calverse check    --csv F                fit / clip / coverage report, no PDF
calverse audit    cal.html cal.css .     run the clip audit on generated HTML
calverse serve                           launch the web UI (needs [web] extra)

The bare form calverse --csv … --year … still works — it defaults to generate, so the reproduction commands in SPEC.md §19 are unchanged.

Getting text in

1. Upload USFM (calverse usfm / select) — what translation teams already have out of Paratext. Handles bridged verses, nested markers, word-attribute pipes, non-standard cross-references, and preserves ZWJ/ZWNJ (SPEC §12).
2. Bring a CSV — date,text,reference, dates as MM-DD so a set is reusable year to year. The CSV is the canonical artefact; everything else produces one.
3. Repository fetch (eBible etc.) — planned; see SPEC.md §4 Route B.

Install

# Debian/Ubuntu system libs for WeasyPrint (SPEC §2):
sudo apt-get install -y libpango-1.0-0 libpangocairo-1.0-0 libpangoft2-1.0-0 \
     libharfbuzz0b libharfbuzz-subset0 libfontconfig1 fonts-dejavu fonts-noto-core

pip install -e ".[web,dev]"
pytest                      # 54 unit tests + the clip-audit negative control

Run the web service

The simplest option is the hosted instance — https://calverse.onrender.com/ — no install required. To run your own:

calverse serve                                  # http://127.0.0.1:8000
# or, self-contained (recommended — bundles the native libs):
docker build -t calverse . && docker run -p 8080:8080 calverse

The UI: paste or upload a CSV (or a USFM file), click Analyze, confirm the detected script / font / names, Check fit, then Generate. The fit and coverage report is shown before the download. Nothing you submit is stored. (The hosted instance is a free tier that sleeps when idle — the first request after a nap takes ~30–60 s to wake.)

Design guarantees (from SPEC.md)

• No silent truncation. The clip audit walks WeasyPrint's laid-out box tree; it is validated against known-bad input in CI (SPEC §10).
• Auto-fit by measurement, not character counts — correct for any script.
• Stable review loop. Per-date verse ranking means dropping one verse changes one date, not the whole year (SPEC §7).
• Fonts retuned to the glyphs your text actually uses, so leading is honest for any font (SPEC §11).

Repository layout

calverse/            the package
  render.py            CSV → month grids → HTML → PDF (proven core)
  autofit.py clipaudit.py fontmetrics.py
  scripts.py           ISO-15924 detection + per-script defaults
  localedata.py        CLDR/babel names, digits, direction, first weekday
  langtags.py langfont.py sldr.py netcache.py   SIL services + caching
  fonts.py             resolve → download → retune
  usfm.py select.py    ingestion + length-aware, spread, stable selection
  analyze.py wizard.py cli.py samples.py
  templates/           calendar.html.j2, calendar.css (all visual design)
  data/chapter_pool.json
web/                 FastAPI service (app.py) + static UI (static/index.html)
tests/               pytest suite + saved API fixtures
Dockerfile  .github/workflows/ci.yml
SPEC.md              the authoritative specification and its hard-won lessons
calverse-source/     the original verified prototype, kept for reference
docs/                GETTING_STARTED, LANGUAGES, DEPLOY

Licence

Code: MIT (LICENSE). Fetched fonts: OFL / Apache-2.0, licence files preserved. Sample verse texts carry their own licences (SPEC §16); you are responsible for the rights to any Scripture you supply.