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)
