provost

Simple, dependency-free data automation for church administration.

provost helps church and congregation administrators turn the CSV exports their management software already produces into plain-English summaries: attendance trends, giving analytics and membership lifecycle metrics — without a spreadsheet wrestling match.

The name is a nod to the traditional role of a provost: the person who keeps the day-to-day administration of a church running.

📚 Full documentation lives in docs/ and builds into a searchable site with MkDocs (pip install ".[docs]" && mkdocs serve).

Why provost?

• No third-party runtime dependencies. It is built entirely on the Python standard library, so it installs instantly and audits easily.
• No surprises. It reads only the CSV files you point it at and writes only to stdout. It never touches the network, phones home, collects telemetry, or runs anything at install time. What you see in the source is all it does.
• Explainable maths. Every metric is a short, readable function you can check yourself. No black boxes.

Install

pip install provost

Python 3.9 or newer.

Quick start

As a command-line tool

provost attendance attendance.csv
provost giving giving.csv
provost members members.csv

Example output:

Attendance summary for attendance.csv
  weeks recorded : 12
  mean / week    : 182.5
  median / week  : 180.0
  best week      : 240
  quietest week  : 150
  next-week est. : 188.0
  by year:
    2024: 2190

As a library

from provost import read_attendance, attendance_summary, forecast_next

records = read_attendance("attendance.csv")
print(attendance_summary(records))     # mean, median, min, max, stdev...
print(forecast_next(records))          # naive next-week estimate

from provost import read_giving, giving_by_fund, recurring_donors

gifts = read_giving("giving.csv")
print(giving_by_fund(gifts))           # {"general": 12450.0, "building": 3200.0}
print(recurring_donors(gifts))         # members who gave in 3+ distinct months

from provost import read_members, active_members, retention_rate
from datetime import date

members = read_members("members.csv")
print(len(active_members(members)))
print(retention_rate(members, date(2023, 1, 1), date(2024, 1, 1)))

Expected CSV formats

Attendance — date,service,count (service optional, defaults to main):

date,service,count
2024-01-07,morning,182
2024-01-07,evening,64

Giving — date,member_id,amount (plus optional fund, method):

date,member_id,amount,fund,method
2024-01-07,M001,100.00,general,card

Members — member_id,join_date (plus optional status, left_date):

member_id,join_date,status,left_date
M001,2019-03-01,active,

Sample files live in examples/.

What's included

Development

pip install -e ".[dev]"
pytest

License

MIT