provost 0.1.0

Simple, dependency-free data automation for church administration (attendance, giving and membership analytics).

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

Module	Highlights
provost.attendance	weekly totals, rolling average, year-over-year, naive forecast
provost.giving	totals, split by fund/member, average gift, recurring donors
provost.membership	active members, joiners, leavers, net growth, retention
provost.metrics	moving average, growth rate, CAGR, percentile, summary stats
provost.io	tolerant CSV loaders with clear per-row error messages

Development

pip install -e ".[dev]"
pytest

License

MIT