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

Abierto
  • ¿Algo no está bien?
#239 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@Atharvatonape ya está trabajando en esto.

Desde el 30/9/2026.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
45/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
pandas, python, scikit-learn
Área
data-engineering

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

enhancement good first issue roadmap

Status (2026-11-04): claimed on 2026-09-30, no PR yet. If you are the claimant and have stopped, say so here so it goes back up for grabs.

What's needed

Same pattern as the seven CRM bridges already in philanthropy.ingest (CiviCRM, Raiser's Edge, NPSP, Nonprofit Cloud, Bloomerang, DonorPerfect, Blackbaud CRM): 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/ingest/_read_gifts.py GIFT_SOURCES and _REGISTRY: the preset registry has landed, so register the new source here. Once #338 merges, philanthropy features --source reads GIFT_SOURCES directly, so there is no CLI dispatch to edit for features
philanthropy/cli.py _read_raw_gifts, used by check and train --task leadership. Once #341 merges, every GIFT_SOURCES name needs an entry there too, and a test fails if one is missing (see step 3)
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).

    Then register the source, which the bridges merged since this issue was written all needed:

    • Add the name to GIFT_SOURCES and _REGISTRY in philanthropy/ingest/_read_gifts.py, and update the hardcoded set in tests/test_read_gifts.py (assert set(GIFT_SOURCES) == {...}).
    • Split the row filter out of your *_to_features function into a private _<crm>_received_rows(rows, <filter>=DEFAULT_...) helper and call it from *_to_features, the way _raisers_edge_received_rows and _npsp_received_rows do (#337). The CLI's check and train --task leadership read raw gift rows through that helper, so they drop the same pledges and non-gift rows features drops.
    • If #341 has merged (PR #359), add your source to the CLI's raw-gift reader table in philanthropy/cli.py; its coverage test fails otherwise. If it has not merged yet, say so in your PR body so whichever lands second adds the other's entry.

  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.

Lenguaje dominante
Python
Estrellas
11
Forks
23
Merge medio
1 d 11 h
PR fusionados (30 d)
30

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de PhilanthroPy-Project/PhilanthroPy

Todos los issues de PhilanthroPy-Project/PhilanthroPy

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.