feat: add a Virtuous gift export reader (ingest preset)

Aperta
  • Qualcosa non va?
#239 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@Atharvatonape ci sta già lavorando.

Dal 30/9/2026.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
45/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
pandas, python, scikit-learn
Ambito
data-engineering

Direzione di ricerca

Start by comparing philanthropy/ingest/_raisers_edge.py and philanthropy/ingest/_civicrm.py; verify Virtuous export labels and commitment/payment terms in its public help center and API docs before defining aliases or exclusions. Add philanthropy/ingest/_virtuous.py, tests in tests/test_virtuous.py, public exports and the stability-tier row, then update the changelog. Run the provided import check, make ci, and make riskcov; claim the issue first and check whether the in-flight preset registry PR has landed.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

enhancement good first issue roadmap
What's needed

Same pattern as the other CRM bridges in philanthropy.ingest (CiviCRM, Raiser's Edge, NPSP): a thin, CRM-specific header-alias map plus a commitment/payment exclusion filter, delegating the roll-up to the shared aggregator in philanthropy/ingest/_civicrm.py. This issue adds the bridge for Virtuous.

Where to look
File Purpose
philanthropy/ingest/_raisers_edge.py Closest existing example: header aliasing, a documented default exclusion set, delegation to the shared aggregator
philanthropy/ingest/_civicrm.py The shared aggregator (civicrm_contributions_to_features, read_civicrm_contributions) and its private helpers
tests/test_raisers_edge.py The test depth expected of your new tests/test_virtuous.py
philanthropy/cli.py _FEATURE_SOURCES and the features --source dispatch — wire your new source in the same shape, unless the read_gifts preset registry (a separate, in-flight PR) has already landed, in which case register there instead
What to build
  1. philanthropy/ingest/_virtuous.py: a header-alias map from Virtuous's real export labels (its gift export) and API field names onto the canonical contact_id / receive_date / total_amount / gift_type names; a documented default exclusion parameter for whatever its pledge-vs-payment split actually is (Virtuous models recurring gifts and pledges explicitly in its data model — find out exactly how from the docs, don't assume it matches Raiser's Edge or NPSP); a virtuous_gifts_to_features(...) function; and a read_virtuous_gifts(path) reader delegating to read_civicrm_contributions.
  2. Verify every field name and every commitment/payment vocabulary term against Virtuous's own public help center and API documentation before writing it down. Cite the doc URLs you actually used in your PR body, the way PR #233 does for NPSP. This issue does not assert any field name as fact — confirm everything yourself.
  3. Export the new names from philanthropy/ingest/__init__.py (__all__, alphabetical) and add a stability-tier row to docs/reference/index.md (Tier 2/Beta — a test enforces every public symbol has a row).
  4. tests/test_virtuous.py at the depth of tests/test_raisers_edge.py: header aliasing from every spelling the docs name, the commitment/payment double-count trap and its exclusion, the exclusion set being documented/overridable/disabled by None, currency parsing, schema/dtypes, empty input, missing required columns.
  5. CHANGELOG.md entry under ## [Unreleased], and add yourself to CONTRIBUTORS.md if you'd like.
Hard constraints (same as the rest of this ingest series)
  • Dependencies stay scikit-learn/pandas/numpy/joblib only — no new package, no API client, no network code anywhere in philanthropy/. File-export reader only, never a live API connector.
  • No new estimator class.
  • Build the exclusion logic from Virtuous's own public docs only — never from an institution's actual configuration or data.
  • Follow AGENTS.md's order: implement, export, verify with python -c "...", then write tests, then make ci.
Verifying
python -m pip install -e ".[dev]"
python -c "from philanthropy.ingest import virtuous_gifts_to_features, read_virtuous_gifts; print('OK')"
make ci
make riskcov

Claim this issue with a comment before starting; a maintainer assigns within 24 hours.

Lingua principale
Python
Stelle
11
Fork
23
Merge medio
1g 8h
PR unite (30g)
35

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di PhilanthroPy-Project/PhilanthroPy

Tutte le issue di PhilanthroPy-Project/PhilanthroPy

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.