provost 0.1.0__tar.gz

provost-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,137 @@
+# 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/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "provost"
+dynamic = ["version"]
+description = "Simple, dependency-free data automation for church administration (attendance, giving and membership analytics)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Martin Gallagher", email = "martinjgallagher@icloud.com" }]
+keywords = [
+    "church",
+    "congregation",
+    "administration",
+    "attendance",
+    "giving",
+    "membership",
+    "analytics",
+    "csv",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Religion",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business",
+    "Topic :: Religion",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/MartinGallagher-code/provost"
+Repository = "https://github.com/MartinGallagher-code/provost"
+Documentation = "https://github.com/MartinGallagher-code/provost/tree/main/docs"
+Issues = "https://github.com/MartinGallagher-code/provost/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+docs = [
+    "mkdocs>=1.5",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.24",
+]
+
+[project.scripts]
+provost = "provost.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "provost.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+provost = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

provost-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

provost-0.1.0/src/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-0.1.0/src/provost/__main__.py

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

provost-0.1.0/src/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-0.1.0/src/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())