catholic-mass-readings

Provides an API for scraping the web page from Daily Readings website of United States Conference of Catholic Bishops.

About catholic-mass-readings

This package was built to facilitate pulling the mass readings used as the description when scheduling the YouTube live stream. I'm happy if others want to use it. Please open new issues for any bugs you find, support is greatly appreciated! If you have a new feature, feel free to open a pull request.

Installation

To install catholic-mass-readings from PyPI, use the following command:

$ pip install catholic-mass-readings

You can also clone the repo and run the following command in the project root to install the source code as editable:

$ pip install -e .

API Usage:

import asyncio
import datetime

from catholic_mass_readings import USCCB, models

# To get a mass for a particular date:
async with USCCB() as usccb:
    mass = await usccb.get_mass(datetime.date(2024, 12, 25), models.MassType.VIGIL)
    print(mass)

# To query for a range of Sunday masses:
async with USCCB() as usccb:
    dates = usccb.get_sunday_mass_dates(datetime.date(2024, 12, 25), datetime.date(2025, 1, 25))
    tasks = [usccb.get_mass_from_date(dt, types) for dt in dates]
    responses = await asyncio.gather(*tasks)
    masses = [m for m in responses if m]
    masses.sort(key=lambda m: m.date.toordinal() if m.date else -1)
    for mass in masses:
        end = "\n" if mass is masses[-1] else "\n\n"
        print(mass, end=end)

# To query for a range of masses (step how you want to):
async with USCCB() as usccb:
    dates = usccb.get_mass_dates(datetime.date(2024, 12, 25), datetime.date(2025, 1, 25), step=datetime.timedelta(days=1))
    tasks = [usccb.get_mass_from_date(dt) for dt in dates]
    responses = await asyncio.gather(*tasks)
    masses = [m for m in responses if m]
    masses.sort(key=lambda m: m.date.toordinal() if m.date else -1)
    for mass in masses:
        end = "\n" if mass is masses[-1] else "\n\n"
        print(mass, end=end)

# To query for a list of all the mass types on a particular date:
async with USCCB() as usccb:
    mass_types = await usccb.get_mass_types(datetime.date(2024, 12, 25))
    for mass_type in mass_types:
        print(mass_type.name)

As a CLI

# To get a mass for a particular date:
python -m catholic_mass_readings get-mass --date 2024-12-25 --type vigil

# To query for a range of Sunday masses:
python -m catholic_mass_readings get-sunday-mass-range --start 2024-12-25 --end 2025-01-01

# To query for a range of masses (step how you want to):
python -m catholic_mass_readings get-mass-range --start 2024-12-25 --end 2025-01-01 --step 7

# To query for a list of mass types on a particular date:
python -m catholic_mass_readings get-mass-types --date 2025-12-25

# or saving to a file...

# To get a mass for a particular date:
python -m catholic_mass_readings get-mass --date 2024-12-25 --type vigil --save mass.json

# To query for a range of Sunday masses:
python -m catholic_mass_readings get-sunday-mass-range --start 2024-12-25 --end 2025-01-01 --save mass.json

# To query for a range of masses (step how you want to):
python -m catholic_mass_readings get-mass-range --start 2024-12-25 --end 2025-01-01 --step 7 --save mass.json

Documentation

The documentation for catholic-mass-readings can be found here or in the project's docstrings.

Development

Setup Python Environment:

Run scripts/console.sh uv install

The first time run

uvx pre-commit install

If you need to relock:

Run scripts/lock.sh

Run code

Run scripts/console.sh uv run python -m catholic_mass_readings

Testing

Generating Test Data

uv run python -m catholic_mass_readings get-mass --date "2025-08-06" -t DEFAULT --save tests/data/mass-single-reading.json

uv run python -m catholic_mass_readings get-mass --date "2025-08-10" -t DEFAULT --save tests/data/mass-multiple-readings.json

Run tests

uv run pytest