feat: add a Neon One (Neon CRM) gift export reader (ingest preset)

Đang mở
  • Có gì không ổn?
#237 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@Utkarsh3725 đang làm issue này rồi.

Từ ngày 7/10/2026.

  • #314 của @Utkarsh3725 — đang mở

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
25/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
pandas, python, scikit-learn
Lĩnh vực
data-engineering

Hướng nghiên cứu

Read philanthropy/ingest/_raisers_edge.py for the existing bridge pattern and philanthropy/ingest/_civicrm.py for the shared aggregator. Verify Neon export labels and pledge/payment terminology against Neon One’s official help center and API docs; then check philanthropy/cli.py for source registration and follow tests/test_raisers_edge.py when adding tests/test_neon.py. Done means the documented aliases and exclusions are tested, exports and stability documentation are updated, and the verification commands pass; an open linked pull request already indicates work is underway.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

enhancement good first issue roadmap

Status (2026-11-04): PR #314 is open but conflicts with main, and its 2026-10-08 review has had no reply. A second contributor asked for this issue on 2026-10-28. Before starting a new PR, check with the #314 author on that PR.

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 Neon One / Neon CRM.

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_neon.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/_neon.py: a header-alias map from Neon's real export labels (its donation/transaction export) and its API field names onto the canonical contact_id / receive_date / total_amount / gift_type names; a documented default exclusion parameter for whatever Neon's pledge-vs-payment split actually is (find out exactly how from the docs — do not assume it matches Raiser's Edge or NPSP); a neon_donations_to_features(...) function (name it for what Neon actually calls the record once you've checked); and a read_neon_donations(path) reader delegating to read_civicrm_contributions.

  2. Verify every field name and every commitment/payment vocabulary term against Neon One'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_neon.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 Neon'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 neon_donations_to_features, read_neon_donations; print('OK')"
make ci
make riskcov

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

Ngôn ngữ chính
Python
Star
11
Fork
23
Merge trung bình
2 ngày 19 giờ
Pull request đã merge (30 ngày)
31

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của PhilanthroPy-Project/PhilanthroPy

Tất cả issue của PhilanthroPy-Project/PhilanthroPy

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.