Catholic Daily App

Small Python script that fetches daily Catholic readings and produces both human-readable text and JSON output for automation (email, Telegram, cron jobs, AI agents).

What It Does

• Liturgical day title (via calendarium-romanum Ruby gem when available).
• Saints/feasts and liturgical season (calapi.inadiutorium.cz).
• Mass readings (First, Psalm, Second, Gospel) from USCCB via catholic-mass-readings.
• Office of Readings Second Reading from Universalis (USA calendar).
• Writes output to stdout and to known file paths in the chosen output location.

Requirements

• Linux with Python 3.10+ (venv already included in this repo)
• Python packages: requests, catholic-mass-readings
• Ruby (optional but recommended) and calendarium-romanum gem for precise liturgical day titles

Installation

Option A: venv (repo-local)

source venv/bin/activate
pip install -r requirements.txt  # if present
# or
pip install requests catholic-mass-readings

# Install CLI entry point (from repo root)
pip install -e .

# Optional (for accurate day titles)
gem install calendarium-romanum

Option B: pipx (global CLI, recommended)

brew install pipx
pipx install -e .

Ensure pipx binaries are on PATH:

pipx ensurepath

Restart your shell (or open a new terminal) so PATH changes take effect.

PATH troubleshooting (should include ~/.local/bin):

echo "$PATH" | grep -q "$HOME/.local/bin" && echo "PATH OK"

Option C: system Python (user install)

python3 -m pip install --user -e .

If this is blocked by PEP 668, use the venv or pipx options instead.

Usage

Basic:

daily-inspiration

Help:

daily-inspiration --help

Help output (current flags):

--json          Write JSON output to file only.
--json-stdout   Print JSON output to stdout (use with --json).
--tomorrow      Fetch tomorrow's readings instead of today's.
--path          Output file or directory. Directories must already exist; file
                paths require an existing parent directory.
--quiet         Suppress stdout in text mode.

JSON output (file only):

daily-inspiration --json

JSON output with stdout:

daily-inspiration --json --json-stdout

Quiet text mode (no stdout):

daily-inspiration --quiet

Tomorrow's readings (useful for validation):

daily-inspiration --tomorrow
daily-inspiration --tomorrow --json

Custom output location:

daily-inspiration --path /tmp
daily-inspiration --json --path ./out/readings.json

Run without activating venv:

./venv/bin/daily-inspiration

Run with system Python user install:

~/.local/bin/daily-inspiration

Outputs

• Text (default): ./daily_catholic_readings.txt
• JSON (with --json): ./daily_catholic_readings.json

Text mode prints to stdout unless --quiet is set. JSON mode writes only the JSON file; use --json-stdout to also print.

Use --path to control output location:

• If --path is a directory, it must already exist and the default filenames are used in that directory.
• If --path is a file, its parent directory must already exist and the exact filename is used for the active output mode.

JSON Structure (High Level)

{
  "date": "YYYY-MM-DD",
  "date_formatted": "Weekday, Month DD, YYYY",
  "liturgical_season": "lent",
  "day_title": "Thursday after Ash Wednesday",
  "feast": "Ash Wednesday",
  "celebrations": ["Ash Wednesday"],
  "mass_readings": {
    "first_reading": "...",
    "psalm": "...",
    "second_reading": "...",
    "gospel": "...",
    "alleluia": "..."
  },
  "office_of_readings": {
    "second_reading": "...",
    "source": "...",
    "url": "...",
    "error": null,
    "attribution": "Universalis Publishing Ltd (universalis.com)"
  }
}

Notes

• If Ruby or the calendarium-romanum gem is missing, the script falls back to a simpler day-title calculation.
• Universalis content is sourced from https://universalis.com/usa/YYYYMMDD/readings.htm.

Troubleshooting

• daily-inspiration: command not found: ensure PATH includes ~/.local/bin, then restart your shell.
• Empty or partial readings: external sources may be down or rate-limited; retry later.
• Slow responses: the script uses multiple network calls; check network or try again.
• Ruby day titles missing: install calendarium-romanum and ensure ruby is on PATH.

Uninstall / Upgrade

pipx:

pipx upgrade catholic-daily-app
pipx uninstall catholic-daily-app

venv:

pip uninstall catholic-daily-app
deactivate  # if active
rm -rf venv

system Python user install:

python3 -m pip install --user -U -e .
python3 -m pip uninstall catholic-daily-app

Data Sources

• Liturgical calendar: https://calapi.inadiutorium.cz
• Mass readings: https://bible.usccb.org (via catholic-mass-readings)
• Office of Readings (Second Reading): https://universalis.com (USA)