provost 0.1.0__py3-none-any.whl

provost/__init__.py

@@ -0,0 +1,84 @@
+"""provost — simple, transparent 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.
+
+Design principles:
+
+* **Standard library only.** No third-party runtime dependencies.
+* **No side effects.** Nothing here touches the network, reads the system
+  clock implicitly, or executes anything from the data it reads.
+* **Explainable maths.** Every metric is a short, auditable function.
+
+Example
+-------
+>>> from provost import read_attendance, attendance_summary
+>>> records = read_attendance("attendance.csv")
+>>> attendance_summary(records)["mean"]           # doctest: +SKIP
+182.5
+"""
+
+from __future__ import annotations
+
+from .io import read_attendance, read_giving, read_members
+from .models import AttendanceRecord, GivingRecord, Member
+from . import attendance, giving, membership, metrics
+from .attendance import (
+    attendance_summary,
+    forecast_next,
+    rolling_average,
+    weekly_totals,
+    year_over_year,
+)
+from .giving import (
+    average_gift,
+    giving_by_fund,
+    giving_by_member,
+    giving_summary,
+    recurring_donors,
+    total_giving,
+)
+from .membership import (
+    active_members,
+    net_growth,
+    new_members,
+    retention_rate,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # io
+    "read_attendance",
+    "read_giving",
+    "read_members",
+    # models
+    "AttendanceRecord",
+    "GivingRecord",
+    "Member",
+    # submodules
+    "attendance",
+    "giving",
+    "membership",
+    "metrics",
+    # attendance
+    "attendance_summary",
+    "forecast_next",
+    "rolling_average",
+    "weekly_totals",
+    "year_over_year",
+    # giving
+    "average_gift",
+    "giving_by_fund",
+    "giving_by_member",
+    "giving_summary",
+    "recurring_donors",
+    "total_giving",
+    # membership
+    "active_members",
+    "net_growth",
+    "new_members",
+    "retention_rate",
+]

provost/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m provost``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

provost/attendance.py

@@ -0,0 +1,75 @@
+"""Attendance analytics.
+
+Turns a list of :class:`~provost.models.AttendanceRecord` into weekly totals,
+rolling averages, year-over-year comparisons and a naive next-period forecast.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import date
+from typing import Sequence
+
+from .metrics import moving_average, summarize
+from .models import AttendanceRecord
+
+
+def weekly_totals(records: Sequence[AttendanceRecord]) -> dict[date, int]:
+    """Sum attendance per ISO-week, keyed by that week's Monday.
+
+    Every service on the same date is combined, then dates are grouped into
+    their week. The result is ordered oldest-first.
+    """
+    by_week: dict[date, int] = defaultdict(int)
+    for record in records:
+        monday = record.date.fromordinal(
+            record.date.toordinal() - record.date.weekday()
+        )
+        by_week[monday] += record.count
+    return dict(sorted(by_week.items()))
+
+
+def rolling_average(
+    records: Sequence[AttendanceRecord], window: int = 4
+) -> list[tuple[date, float]]:
+    """Rolling average of weekly totals over ``window`` weeks.
+
+    Returns ``(week_start, average)`` pairs. An empty list is returned when
+    there are fewer weeks of data than ``window``.
+    """
+    weeks = weekly_totals(records)
+    if len(weeks) < window:
+        return []
+    starts = list(weeks.keys())
+    counts = list(weeks.values())
+    averages = moving_average(counts, window)
+    return list(zip(starts[window - 1 :], averages))
+
+
+def year_over_year(records: Sequence[AttendanceRecord]) -> dict[int, int]:
+    """Total attendance grouped by calendar year, ordered oldest-first."""
+    by_year: dict[int, int] = defaultdict(int)
+    for record in records:
+        by_year[record.date.year] += record.count
+    return dict(sorted(by_year.items()))
+
+
+def forecast_next(records: Sequence[AttendanceRecord], window: int = 4) -> float:
+    """Naive forecast for the next week: the mean of the last ``window`` weeks.
+
+    This is deliberately simple and explainable — it is a baseline, not a
+    statistical model. Raises ``ValueError`` when there is no data.
+    """
+    weeks = weekly_totals(records)
+    if not weeks:
+        raise ValueError("no attendance data to forecast from")
+    recent = list(weeks.values())[-window:]
+    return sum(recent) / len(recent)
+
+
+def attendance_summary(records: Sequence[AttendanceRecord]) -> dict[str, float]:
+    """Descriptive statistics of weekly attendance totals."""
+    weeks = weekly_totals(records)
+    if not weeks:
+        raise ValueError("no attendance data to summarize")
+    return summarize(weeks.values())

provost/cli.py

@@ -0,0 +1,118 @@
+"""Command-line interface for provost.
+
+Usage::
+
+    provost attendance path/to/attendance.csv
+    provost giving path/to/giving.csv
+    provost members path/to/members.csv
+
+Each command prints a human-readable summary to stdout. The CLI reads only the
+file you point it at and writes only to stdout.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Sequence
+
+from . import __version__
+from .attendance import attendance_summary, forecast_next, year_over_year
+from .giving import (
+    average_gift,
+    giving_by_fund,
+    recurring_donors,
+    total_giving,
+)
+from .io import read_attendance, read_giving, read_members
+from .membership import active_members
+
+
+def _money(value: float) -> str:
+    return f"{value:,.2f}"
+
+
+def _cmd_attendance(path: str) -> int:
+    records = read_attendance(path)
+    if not records:
+        print("No attendance records found.")
+        return 0
+    stats = attendance_summary(records)
+    print(f"Attendance summary for {path}")
+    print(f"  weeks recorded : {int(stats['count'])}")
+    print(f"  mean / week    : {stats['mean']:.1f}")
+    print(f"  median / week  : {stats['median']:.1f}")
+    print(f"  best week      : {int(stats['max'])}")
+    print(f"  quietest week  : {int(stats['min'])}")
+    print(f"  next-week est. : {forecast_next(records):.1f}")
+    print("  by year:")
+    for year, total in year_over_year(records).items():
+        print(f"    {year}: {total}")
+    return 0
+
+
+def _cmd_giving(path: str) -> int:
+    records = read_giving(path)
+    if not records:
+        print("No giving records found.")
+        return 0
+    print(f"Giving summary for {path}")
+    print(f"  gifts recorded : {len(records)}")
+    print(f"  total given    : {_money(total_giving(records))}")
+    print(f"  average gift   : {_money(average_gift(records))}")
+    print("  by fund:")
+    for fund, amount in giving_by_fund(records).items():
+        print(f"    {fund}: {_money(amount)}")
+    recurring = recurring_donors(records)
+    print(f"  recurring donors (3+ months): {len(recurring)}")
+    return 0
+
+
+def _cmd_members(path: str) -> int:
+    members = read_members(path)
+    if not members:
+        print("No member records found.")
+        return 0
+    active = active_members(members)
+    print(f"Membership summary for {path}")
+    print(f"  members on file : {len(members)}")
+    print(f"  currently active: {len(active)}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="provost",
+        description="Simple data automation for church administration.",
+    )
+    parser.add_argument("--version", action="version", version=f"provost {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    for name, help_text in (
+        ("attendance", "Summarise an attendance CSV."),
+        ("giving", "Summarise a giving CSV."),
+        ("members", "Summarise a members CSV."),
+    ):
+        p = sub.add_parser(name, help=help_text)
+        p.add_argument("path", help="Path to the CSV file.")
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handlers = {
+        "attendance": _cmd_attendance,
+        "giving": _cmd_giving,
+        "members": _cmd_members,
+    }
+    try:
+        return handlers[args.command](args.path)
+    except (OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

provost/giving.py

@@ -0,0 +1,73 @@
+"""Giving / contribution analytics.
+
+Summaries over a list of :class:`~provost.models.GivingRecord`: totals, splits
+by fund and by member, average gift size and identification of recurring
+donors. All figures are computed directly from the records passed in.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Sequence
+
+from .metrics import summarize
+from .models import GivingRecord
+
+
+def total_giving(records: Sequence[GivingRecord]) -> float:
+    """Sum of all gift amounts."""
+    return sum(record.amount for record in records)
+
+
+def giving_by_fund(records: Sequence[GivingRecord]) -> dict[str, float]:
+    """Total given to each fund, ordered largest-first."""
+    by_fund: dict[str, float] = defaultdict(float)
+    for record in records:
+        by_fund[record.fund] += record.amount
+    return dict(sorted(by_fund.items(), key=lambda kv: kv[1], reverse=True))
+
+
+def giving_by_member(records: Sequence[GivingRecord]) -> dict[str, float]:
+    """Total given by each member, ordered largest-first."""
+    by_member: dict[str, float] = defaultdict(float)
+    for record in records:
+        by_member[record.member_id] += record.amount
+    return dict(sorted(by_member.items(), key=lambda kv: kv[1], reverse=True))
+
+
+def average_gift(records: Sequence[GivingRecord]) -> float:
+    """Mean gift amount. Raises ``ValueError`` when there are no records."""
+    if not records:
+        raise ValueError("no giving records")
+    return total_giving(records) / len(records)
+
+
+def recurring_donors(
+    records: Sequence[GivingRecord], min_months: int = 3
+) -> list[str]:
+    """Members who gave in at least ``min_months`` distinct calendar months.
+
+    Returns member ids ordered by their number of active months, most
+    frequent first.
+    """
+    months: dict[str, set[tuple[int, int]]] = defaultdict(set)
+    for record in records:
+        months[record.member_id].add((record.date.year, record.date.month))
+    qualifying = {
+        member: len(active)
+        for member, active in months.items()
+        if len(active) >= min_months
+    }
+    return [
+        member
+        for member, _ in sorted(
+            qualifying.items(), key=lambda kv: kv[1], reverse=True
+        )
+    ]
+
+
+def giving_summary(records: Sequence[GivingRecord]) -> dict[str, float]:
+    """Descriptive statistics of individual gift amounts."""
+    if not records:
+        raise ValueError("no giving records to summarize")
+    return summarize(record.amount for record in records)

provost/io.py

@@ -0,0 +1,43 @@
+"""CSV loading helpers.
+
+Reads use the standard-library :mod:`csv` module and never touch the network
+or execute anything from the files they read. A CSV is only ever parsed as
+data.
+"""
+
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+from typing import Callable, TypeVar
+
+from .models import AttendanceRecord, GivingRecord, Member
+
+T = TypeVar("T")
+
+
+def _read_records(path: str | Path, factory: Callable[[dict[str, str]], T]) -> list[T]:
+    records: list[T] = []
+    with open(path, newline="", encoding="utf-8") as handle:
+        reader = csv.DictReader(handle)
+        for line_no, row in enumerate(reader, start=2):
+            try:
+                records.append(factory(row))
+            except (KeyError, ValueError) as exc:
+                raise ValueError(f"{path}: could not parse row {line_no}: {exc}") from exc
+    return records
+
+
+def read_attendance(path: str | Path) -> list[AttendanceRecord]:
+    """Load attendance records from a CSV with ``date,service,count`` columns."""
+    return _read_records(path, AttendanceRecord.from_row)
+
+
+def read_giving(path: str | Path) -> list[GivingRecord]:
+    """Load giving records from a CSV with ``date,member_id,amount[,fund,method]``."""
+    return _read_records(path, GivingRecord.from_row)
+
+
+def read_members(path: str | Path) -> list[Member]:
+    """Load members from a CSV with ``member_id,join_date[,status,left_date]``."""
+    return _read_records(path, Member.from_row)

provost/membership.py

@@ -0,0 +1,70 @@
+"""Membership lifecycle analytics.
+
+Works out active headcount, new joiners, leavers and simple retention from a
+list of :class:`~provost.models.Member` records.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Sequence
+
+from .models import Member
+
+
+def active_members(members: Sequence[Member], as_of: date | None = None) -> list[Member]:
+    """Members who had joined by ``as_of`` and had not left by then.
+
+    ``as_of`` defaults to the latest join or leave date found in the data, so
+    the function is deterministic and never reads the system clock.
+    """
+    if as_of is None:
+        as_of = _latest_date(members)
+    if as_of is None:
+        return []
+    return [
+        member
+        for member in members
+        if member.join_date <= as_of
+        and (member.left_date is None or member.left_date > as_of)
+    ]
+
+
+def new_members(members: Sequence[Member], start: date, end: date) -> list[Member]:
+    """Members who joined within the inclusive ``[start, end]`` window."""
+    return [m for m in members if start <= m.join_date <= end]
+
+
+def leavers(members: Sequence[Member], start: date, end: date) -> list[Member]:
+    """Members who left within the inclusive ``[start, end]`` window."""
+    return [
+        m for m in members if m.left_date is not None and start <= m.left_date <= end
+    ]
+
+
+def net_growth(members: Sequence[Member], start: date, end: date) -> int:
+    """Joiners minus leavers over the inclusive ``[start, end]`` window."""
+    return len(new_members(members, start, end)) - len(leavers(members, start, end))
+
+
+def retention_rate(members: Sequence[Member], start: date, end: date) -> float:
+    """Fraction of members active at ``start`` who are still active at ``end``.
+
+    Returns ``0.0`` when nobody was active at ``start``.
+    """
+    active_at_start = active_members(members, start)
+    if not active_at_start:
+        return 0.0
+    ids_at_start = {m.member_id for m in active_at_start}
+    still_active = {m.member_id for m in active_members(members, end)}
+    retained = ids_at_start & still_active
+    return len(retained) / len(ids_at_start)
+
+
+def _latest_date(members: Sequence[Member]) -> date | None:
+    dates: list[date] = []
+    for member in members:
+        dates.append(member.join_date)
+        if member.left_date is not None:
+            dates.append(member.left_date)
+    return max(dates) if dates else None

provost/metrics.py

@@ -0,0 +1,91 @@
+"""General-purpose numeric helpers used across provost.
+
+Everything here operates on plain Python numbers and lists using only the
+standard library, so the results are easy to audit and there are no hidden
+side effects.
+"""
+
+from __future__ import annotations
+
+import statistics
+from typing import Iterable, Sequence
+
+
+def moving_average(values: Sequence[float], window: int) -> list[float]:
+    """Return the simple moving average of ``values``.
+
+    The output has ``len(values) - window + 1`` elements. Raises
+    ``ValueError`` if ``window`` is smaller than 1 or larger than the number
+    of values supplied.
+    """
+    if window < 1:
+        raise ValueError("window must be >= 1")
+    if window > len(values):
+        raise ValueError("window is larger than the number of values")
+    result: list[float] = []
+    running = sum(values[:window])
+    result.append(running / window)
+    for i in range(window, len(values)):
+        running += values[i] - values[i - window]
+        result.append(running / window)
+    return result
+
+
+def growth_rate(previous: float, current: float) -> float:
+    """Fractional growth from ``previous`` to ``current``.
+
+    Returns e.g. ``0.1`` for a 10% increase. Raises ``ValueError`` if
+    ``previous`` is zero, where a growth rate is undefined.
+    """
+    if previous == 0:
+        raise ValueError("growth rate is undefined when previous is zero")
+    return (current - previous) / previous
+
+
+def cagr(begin_value: float, end_value: float, periods: float) -> float:
+    """Compound annual (or per-period) growth rate.
+
+    ``periods`` is the number of periods between the two values.
+    """
+    if begin_value <= 0:
+        raise ValueError("begin_value must be positive")
+    if periods <= 0:
+        raise ValueError("periods must be positive")
+    return (end_value / begin_value) ** (1 / periods) - 1
+
+
+def percentile(values: Sequence[float], p: float) -> float:
+    """Linear-interpolation percentile, with ``p`` in the range [0, 100]."""
+    if not values:
+        raise ValueError("cannot compute a percentile of no values")
+    if not 0 <= p <= 100:
+        raise ValueError("p must be between 0 and 100")
+    ordered = sorted(values)
+    if len(ordered) == 1:
+        return float(ordered[0])
+    rank = (p / 100) * (len(ordered) - 1)
+    low = int(rank)
+    high = min(low + 1, len(ordered) - 1)
+    frac = rank - low
+    return ordered[low] + (ordered[high] - ordered[low]) * frac
+
+
+def summarize(values: Iterable[float]) -> dict[str, float]:
+    """Return a small dictionary of descriptive statistics.
+
+    Keys: ``count``, ``sum``, ``mean``, ``median``, ``min``, ``max`` and
+    ``stdev`` (population-sample standard deviation, ``0.0`` for a single
+    value).
+    """
+    data = list(values)
+    if not data:
+        raise ValueError("cannot summarize an empty sequence")
+    return {
+        "count": float(len(data)),
+        "sum": float(sum(data)),
+        "mean": statistics.fmean(data),
+        "median": statistics.median(data),
+        "min": float(min(data)),
+        "max": float(max(data)),
+        "stdev": statistics.stdev(data) if len(data) > 1 else 0.0,
+    }

provost/models.py

@@ -0,0 +1,75 @@
+"""Lightweight record types for the data provost works with.
+
+These are plain dataclasses. They carry no behaviour beyond parsing helpers,
+which keeps the data model transparent and trivial to serialise.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime
+
+
+def parse_date(value: str | date) -> date:
+    """Parse an ISO ``YYYY-MM-DD`` string (or pass through a ``date``)."""
+    if isinstance(value, date):
+        return value
+    return datetime.strptime(value.strip(), "%Y-%m-%d").date()
+
+
+@dataclass(frozen=True)
+class AttendanceRecord:
+    """A count of people attending a single service on a given date."""
+
+    date: date
+    service: str
+    count: int
+
+    @classmethod
+    def from_row(cls, row: dict[str, str]) -> "AttendanceRecord":
+        return cls(
+            date=parse_date(row["date"]),
+            service=row.get("service", "").strip() or "main",
+            count=int(row["count"]),
+        )
+
+
+@dataclass(frozen=True)
+class GivingRecord:
+    """A single financial gift or contribution."""
+
+    date: date
+    member_id: str
+    amount: float
+    fund: str = "general"
+    method: str = "unspecified"
+
+    @classmethod
+    def from_row(cls, row: dict[str, str]) -> "GivingRecord":
+        return cls(
+            date=parse_date(row["date"]),
+            member_id=row["member_id"].strip(),
+            amount=float(row["amount"]),
+            fund=row.get("fund", "").strip() or "general",
+            method=row.get("method", "").strip() or "unspecified",
+        )
+
+
+@dataclass(frozen=True)
+class Member:
+    """A congregation member and their lifecycle dates."""
+
+    member_id: str
+    join_date: date
+    status: str = "active"
+    left_date: date | None = None
+
+    @classmethod
+    def from_row(cls, row: dict[str, str]) -> "Member":
+        left = row.get("left_date", "").strip()
+        return cls(
+            member_id=row["member_id"].strip(),
+            join_date=parse_date(row["join_date"]),
+            status=row.get("status", "").strip() or "active",
+            left_date=parse_date(left) if left else None,
+        )

provost-0.1.0.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: provost
+Version: 0.1.0
+Summary: Simple, dependency-free data automation for church administration (attendance, giving and membership analytics).
+Author-email: Martin Gallagher <martinjgallagher@icloud.com>
+License: MIT
+Project-URL: Homepage, https://github.com/MartinGallagher-code/provost
+Project-URL: Repository, https://github.com/MartinGallagher-code/provost
+Project-URL: Documentation, https://github.com/MartinGallagher-code/provost/tree/main/docs
+Project-URL: Issues, https://github.com/MartinGallagher-code/provost/issues
+Keywords: church,congregation,administration,attendance,giving,membership,analytics,csv
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Religion
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Religion
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Dynamic: license-file
+
+# provost
+
+[![PyPI version](https://img.shields.io/pypi/v/provost.svg)](https://pypi.org/project/provost/)
+[![Python versions](https://img.shields.io/pypi/pyversions/provost.svg)](https://pypi.org/project/provost/)
+[![License: MIT](https://img.shields.io/pypi/l/provost.svg)](https://github.com/MartinGallagher-code/provost/blob/main/LICENSE)
+[![CI](https://github.com/MartinGallagher-code/provost/actions/workflows/ci.yml/badge.svg)](https://github.com/MartinGallagher-code/provost/actions/workflows/ci.yml)
+[![Wheel](https://img.shields.io/pypi/wheel/provost.svg)](https://pypi.org/project/provost/)
+[![Downloads](https://img.shields.io/pypi/dm/provost.svg)](https://pypi.org/project/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/`](docs/index.md) 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
+
+```bash
+pip install provost
+```
+
+Python 3.9 or newer.
+
+## Quick start
+
+### As a command-line tool
+
+```bash
+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
+
+```python
+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
+```
+
+```python
+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
+```
+
+```python
+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`):
+
+```csv
+date,service,count
+2024-01-07,morning,182
+2024-01-07,evening,64
+```
+
+**Giving** — `date,member_id,amount` (plus optional `fund`, `method`):
+
+```csv
+date,member_id,amount,fund,method
+2024-01-07,M001,100.00,general,card
+```
+
+**Members** — `member_id,join_date` (plus optional `status`, `left_date`):
+
+```csv
+member_id,join_date,status,left_date
+M001,2019-03-01,active,
+```
+
+Sample files live in [`examples/`](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
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+[MIT](LICENSE)

provost-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+provost/__init__.py,sha256=rltMOKMr1SvhMUDfnaT2jMaPJnsELYM8jPL4UheBKLI,2037
+provost/__main__.py,sha256=oYuPMJ53ufYd9WR4N02jygHr1bjJ1rQEAiAPGoHdTgQ,116
+provost/attendance.py,sha256=rmXHIkYt8alIfSHgIKXQQTMKDB3hw30u-fYSXNjm-Ms,2629
+provost/cli.py,sha256=q8ojrz7xQq63ZttI89JlfU-peolrvXWndCBwPs0gF3c,3564
+provost/giving.py,sha256=3MaRPHZZ1rGpGdwueSYidu8JEd4wAn0K-jsDiIXCOu0,2507
+provost/io.py,sha256=PaJ-AzavCK3DKMKdO007p6W9aMJEF8XVUJDGILfuqSA,1462
+provost/membership.py,sha256=Sw4Igm351AnmVpfl-9N4DM9PzoGGmT2ff0LsUopJhSM,2415
+provost/metrics.py,sha256=qXhVCPEdZdui3sv8crDSP0y_xtBlMFEazUdn6wudei4,3136
+provost/models.py,sha256=S3U4nk0eodnVMnzUXdGdFivFG0jHoUSlvGn51SUBIHs,2123
+provost/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+provost-0.1.0.dist-info/licenses/LICENSE,sha256=HdV2oyF96eYrFTYdfFqVRHyze9hjI_OIDkmUWBWvj2g,1073
+provost-0.1.0.dist-info/METADATA,sha256=ef2iTyqvvxx_XJrUZYdRmJ8dMNxKAZXKc_L2QNRF3m8,5810
+provost-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+provost-0.1.0.dist-info/entry_points.txt,sha256=PdW3-SZen3G6hZRQwUy7CMu9MxL-CwUZ5TczucaytZo,45
+provost-0.1.0.dist-info/top_level.txt,sha256=clsMcOzC2aBz5acf2S0WBr8JVXKPNR9zEw7cwmYYky0,8
+provost-0.1.0.dist-info/RECORD,,

provost-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

provost-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+provost = provost.cli:main

provost-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Gallagher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

provost-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+provost