Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ jobs:
- name: Check generated models match the spec
run: |
just codegen
git diff --exit-code src/pdc_api_client/_generated.py
git diff --exit-code src/pdc_api/_generated.py

zizmor:
name: Zizmor audit
Expand Down
10 changes: 5 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,24 @@
This file guides AI agents (Claude, Codex, and others) working in this repository.

# pdc-python-client
# pdc-api-python

A framework-free Python client for the Philanthropy Data Commons (PDC) API. The distribution is `pdc-python-client`; the import name is `pdc_api_client`. `README.md` is the user-facing documentation and `CONTRIBUTING.md` the developer documentation; keep both accurate when you change behavior.
A framework-free Python client for the Philanthropy Data Commons (PDC) API. The distribution is `pdc-api`; the import name is `pdc_api`. `README.md` is the user-facing documentation and `CONTRIBUTING.md` the developer documentation; keep both accurate when you change behavior.

## Boundaries

- No framework dependency, and no reference to any particular consumer in code, comments, or tests. Configuration arrives as arguments (`base_url`, `timeout`, a `TokenProvider`), never from settings or the environment. The integration tests are the one place that reads environment variables.
- Optional features live in extras: `pdc_api_client.testing` needs `[testing]`, `pdc_api_client.seeding` needs `[seeding]`. The core imports neither.
- Optional features live in extras: `pdc_api.testing` needs `[testing]`, `pdc_api.seeding` needs `[seeding]`. The core imports neither.

## Models and codegen

- `src/pdc_api_client/_generated.py` is generated from `src/pdc_api_client/openapi.json` by `just codegen`. Never edit it by hand, and import models from `pdc_api_client.models`.
- `src/pdc_api/_generated.py` is generated from `src/pdc_api/openapi.json` by `just codegen`. Never edit it by hand, and import models from `pdc_api.models`.
- Generated code owns field shapes. `models.py` owns client concerns: bundle `pdc_endpoint` and `default_page_size` ClassVars, aliases, and write-only request models. `permission_grants.py` models the grant union by hand.
- After `just update-api-spec`, record the spec's `info.version` and the download date in `CHANGELOG.md`; PDC changes the spec without bumping that version.
- When the spec disagrees with what PDC returns, add a rule to `codegen/preprocess.py` with a one-line comment naming the mismatch, then regenerate. Delete a rule once PDC fixes the cause. CI fails if `_generated.py` drifts from the spec.

## API conventions

- `session` is the first positional argument; every other argument is keyword-only. The exception is the bundle type in `get_bundle_page` and `pdc_api_client.testing.add_page_response`, which names the endpoint.
- `session` is the first positional argument; every other argument is keyword-only. The exception is the bundle type in `get_bundle_page` and `pdc_api.testing.add_page_response`, which names the endpoint.
- Errors end in `Error`, except the base class `PDCException`. A lookup's not-found error subclasses `PDCNotFoundError`.

## Commands
Expand Down
3 changes: 2 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ PDC does not bump its spec version for every API change, so each entry names the

Breaking changes that make names consistent before a wider release:

- The distribution is now `pdc-api` (was `pdc-python-client`), the import name is `pdc_api` (was `pdc_api_client`), and the repository is `PhilanthropyDataCommons/pdc-api-python`.
- `get_basefields` is now `get_base_fields`, `create_changemaker_proposal` is `create_proposal`, `create_changemaker_proposal_version` is `create_proposal_version`, and `register_file_upload` is `create_file`.
- `get_application_form` takes `application_form_id` instead of `form_id`.
- `list_permission_grants` filters by `changemaker_id`, `funder_short_code`, and `proposal_id` instead of `changemaker`, `funder`, and `proposal`.
Expand All @@ -18,7 +19,7 @@ Breaking changes that make names consistent before a wider release:

Other changes:

- `ChangemakerFieldValueBatchNotFoundError` and `TokenRequestError` can be imported from `pdc_api_client`.
- `ChangemakerFieldValueBatchNotFoundError` and `TokenRequestError` can be imported from `pdc_api`.

## 0.3.0 (2026-11-18)

Expand Down
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,8 @@ gh run download <run-id> -n coverage-json
## Updating to a new PDC spec

```bash
just update-api-spec # download the current spec into src/pdc_api_client/openapi.json
just codegen # regenerate src/pdc_api_client/_generated.py
just update-api-spec # download the current spec into src/pdc_api/openapi.json
just codegen # regenerate src/pdc_api/_generated.py
just check
```

Expand Down
54 changes: 27 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# pdc-python-client
# pdc-api-python

A Python client for the [Philanthropy Data Commons](https://philanthropydatacommons.org) (PDC) API.

PDC is an access-controlled service where changemakers and funders share funding proposals and organization data. A changemaker can submit a proposal once and share it with any funder it chooses, and the data owner decides who sees what. This package wraps the [PDC API](https://api.philanthropydatacommons.org/) in typed Pydantic models, handles pagination, and raises one exception class per HTTP error. It doesn't depend on any web framework.

Install it as `pdc-python-client` and import it as `pdc_api_client`.
Install it as `pdc-api` and import it as `pdc_api`.

> **Status:** alpha. The API may change between minor versions until 1.0.

Expand All @@ -13,30 +13,30 @@ Install it as `pdc-python-client` and import it as `pdc_api_client`.
The package is not on PyPI yet. Install it from a tagged release on GitHub:

```bash
pip install "pdc-python-client @ git+https://github.com/PhilanthropyDataCommons/pdc-python-client@v0.3.0"
pip install "pdc-api @ git+https://github.com/PhilanthropyDataCommons/pdc-api-python@v0.3.0"
```

or with uv:

```bash
uv add git+https://github.com/PhilanthropyDataCommons/pdc-python-client --tag v0.3.0
uv add git+https://github.com/PhilanthropyDataCommons/pdc-api-python --tag v0.3.0
```

Two optional extras add test and seeding helpers:

- **`testing`:** helpers for mocking PDC responses in your own tests, built on [`responses`](https://github.com/getsentry/responses).
- **`seeding`:** helpers for creating PDC and Keycloak test data, built on [`python-keycloak`](https://github.com/marcospereirampj/python-keycloak) and [Faker](https://github.com/joke2k/faker).

Add them to the requirement, as in `"pdc-python-client[testing,seeding] @ git+https://github.com/PhilanthropyDataCommons/pdc-python-client@v0.3.0"`.
Add them to the requirement, as in `"pdc-api[testing,seeding] @ git+https://github.com/PhilanthropyDataCommons/pdc-api-python@v0.3.0"`.

Python 3.12 or later is required.

## Quickstart

```python
from pdc_api_client import APISession
from pdc_api_client.client import get_changemakers, get_proposal
from pdc_api_client.token import KeycloakClientCredentialsProvider
from pdc_api import APISession
from pdc_api.client import get_changemakers, get_proposal
from pdc_api.token import KeycloakClientCredentialsProvider

session = APISession(
base_url="https://api.philanthropydatacommons.org/",
Expand All @@ -55,7 +55,7 @@ for changemaker in get_changemakers(session):
proposal = get_proposal(session, proposal_id=42)
```

Every response is parsed into a model from `pdc_api_client.models`, with snake_case attributes over PDC's camelCase fields.
Every response is parsed into a model from `pdc_api.models`, with snake_case attributes over PDC's camelCase fields.

## Authentication

Expand All @@ -80,7 +80,7 @@ There are two ways to read a list.
**Iterate everything.** `get_changemakers`, `get_funders`, `get_proposals`, `get_initiatives`, and the other plural `get_*` functions are generators that walk every page for you. The exception is `get_base_fields`, which returns a list:

```python
from pdc_api_client.client import get_changemaker_proposals
from pdc_api.client import get_changemaker_proposals

for link in get_changemaker_proposals(session, changemaker_id=7):
print(link.proposal_id)
Expand All @@ -89,8 +89,8 @@ for link in get_changemaker_proposals(session, changemaker_id=7):
**Fetch one page.** `get_bundle_page` returns a single page as a bundle, which is what a paginated UI needs. It takes the bundle type, a page number, an optional page size, and an optional search string:

```python
from pdc_api_client.client import get_bundle_page
from pdc_api_client.models import FunderBundle
from pdc_api.client import get_bundle_page
from pdc_api.models import FunderBundle

page = get_bundle_page(session, FunderBundle, page=2, count_per_page=25, content="climate")
print(page.total, [funder.name for funder in page.entries])
Expand All @@ -103,8 +103,8 @@ Bundles for nested endpoints take path parameters, such as `get_bundle_page(sess
The client covers the writes a proposal workflow needs: creating a proposal, adding a version with field values, linking a changemaker to it, and uploading files.

```python
from pdc_api_client.client import create_proposal, create_proposal_version
from pdc_api_client.models import NewProposalFieldValue, NewProposalVersion
from pdc_api.client import create_proposal, create_proposal_version
from pdc_api.models import NewProposalFieldValue, NewProposalVersion

proposal = create_proposal(session, data={"opportunityId": 5, "externalId": "app-2026-001"})
version = create_proposal_version(
Expand All @@ -126,11 +126,11 @@ Uploading a file takes two steps. `create_file` creates the file record and retu

## Permission grants

PDC controls access with permission grants. Each grant gives a grantee (a user, a Keycloak organization, or every authenticated user) a set of verbs (such as `view` or `edit`) over a set of scopes, in the context of one entity such as a changemaker or a proposal. `pdc_api_client.permission_grants` models each context as its own class, so a grant parses into, say, `ChangemakerPermissionGrant` with a typed `changemaker_id`:
PDC controls access with permission grants. Each grant gives a grantee (a user, a Keycloak organization, or every authenticated user) a set of verbs (such as `view` or `edit`) over a set of scopes, in the context of one entity such as a changemaker or a proposal. `pdc_api.permission_grants` models each context as its own class, so a grant parses into, say, `ChangemakerPermissionGrant` with a typed `changemaker_id`:

```python
from pdc_api_client.models import PermissionGrantEntityType, PermissionGrantGranteeType, PermissionGrantVerb
from pdc_api_client.permission_grants import ChangemakerPermissionGrant, create_permission_grant, list_permission_grants
from pdc_api.models import PermissionGrantEntityType, PermissionGrantGranteeType, PermissionGrantVerb
from pdc_api.permission_grants import ChangemakerPermissionGrant, create_permission_grant, list_permission_grants

grant = create_permission_grant(
session,
Expand All @@ -150,7 +150,7 @@ The models check that the grantee fields match `grantee_type` before anything is

## Errors

`APISession` raises a subclass of `pdc_api_client.PDCException` for every failed request. Each exception has `.code` (the HTTP status) and `.detail` (the parsed JSON body, or the raw text when the body isn't JSON). Before raising, it retries a GET or HEAD up to three times on a 502, 503, or 504 or a dropped connection.
`APISession` raises a subclass of `pdc_api.PDCException` for every failed request. Each exception has `.code` (the HTTP status) and `.detail` (the parsed JSON body, or the raw text when the body isn't JSON). Before raising, it retries a GET or HEAD up to three times on a 502, 503, or 504 or a dropped connection.

| Status | Exception |
| ------------- | ----------------------------- |
Expand All @@ -175,7 +175,7 @@ A few lookups raise a subclass of `PDCNotFoundError` named for the resource:

## Models

Most models are generated from PDC's OpenAPI spec, which is pinned in `src/pdc_api_client/openapi.json`. Import them from `pdc_api_client.models`; `pdc_api_client._generated` is an implementation detail.
Most models are generated from PDC's OpenAPI spec, which is pinned in `src/pdc_api/openapi.json`. Import them from `pdc_api.models`; `pdc_api._generated` is an implementation detail.

The models ignore fields they don't declare. When PDC adds a field to a response, parsing keeps working, and the new field appears once the models are regenerated.

Expand All @@ -186,21 +186,21 @@ The spec doesn't always match what PDC returns. Some fields it marks required ar
The client covers most of the API but not all of it:

- **No client functions:** `/applicationFormFields`, `/sources` (apart from `create_changemaker_source`), `/tasks` (bulk uploads and base field copies), `/terminologySets`, and `/users`. Their models are generated, and `session.get`/`session.post` reach any endpoint directly.
- **Other writes:** creating funders, changemakers, opportunities, and funder or data-provider sources is possible only through the seeding helpers in `pdc_api_client.seeding`, which aren't meant for production data.
- **Other writes:** creating funders, changemakers, opportunities, and funder or data-provider sources is possible only through the seeding helpers in `pdc_api.seeding`, which aren't meant for production data.
- **Async:** the client is synchronous and built on `requests`.

Issues and pull requests that fill these gaps are welcome.

## Testing your code

`pdc_api_client.testing` (extra: `testing`) registers mocked PDC responses with `responses`. It has payload builders that return valid response bodies, and `add_*_response` functions that register them for a base URL:
`pdc_api.testing` (extra: `testing`) registers mocked PDC responses with `responses`. It has payload builders that return valid response bodies, and `add_*_response` functions that register them for a base URL:

```python
import responses

from pdc_api_client import APISession, testing
from pdc_api_client.client import get_bundle_page
from pdc_api_client.models import ChangemakerBundle
from pdc_api import APISession, testing
from pdc_api.client import get_bundle_page
from pdc_api.models import ChangemakerBundle

BASE_URL = "https://pdc.test/"

Expand Down Expand Up @@ -229,10 +229,10 @@ def test_lists_changemakers():

## Seeding a PDC stack

`pdc_api_client.seeding` (extra: `seeding`) creates realistic data on a PDC stack through the public PDC API and the Keycloak admin API. It is for local development and integration tests, not production:
`pdc_api.seeding` (extra: `seeding`) creates realistic data on a PDC stack through the public PDC API and the Keycloak admin API. It is for local development and integration tests, not production:

- **`pdc_api_client.seeding.pdc_entities`:** `seed_*` functions for funders, collaboratives, changemakers, fiscal sponsorships, data providers, opportunities, application forms, proposals, initiatives, and field values. `seed_proposal_bundle` creates a full proposal and everything it depends on in one call.
- **`pdc_api_client.seeding.keycloak_admin`:** `KeycloakAdmin`, whose `ensure_*` methods create Keycloak organizations, users, memberships, and realm roles only if they don't already exist, so re-running a seed script is safe.
- **`pdc_api.seeding.pdc_entities`:** `seed_*` functions for funders, collaboratives, changemakers, fiscal sponsorships, data providers, opportunities, application forms, proposals, initiatives, and field values. `seed_proposal_bundle` creates a full proposal and everything it depends on in one call.
- **`pdc_api.seeding.keycloak_admin`:** `KeycloakAdmin`, whose `ensure_*` methods create Keycloak organizations, users, memberships, and realm roles only if they don't already exist, so re-running a seed script is safe.

## Contributing

Expand Down
2 changes: 1 addition & 1 deletion codegen/postprocess.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import sys
from pathlib import Path

BANNER = "# Generated by `just codegen` from src/pdc_api_client/openapi.json. Do not edit.\n"
BANNER = "# Generated by `just codegen` from src/pdc_api/openapi.json. Do not edit.\n"


def postprocess(source: str) -> str:
Expand Down
10 changes: 5 additions & 5 deletions integration_tests/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,17 @@
import pytest
import requests

from pdc_api_client.models import FunderCollaborativeMemberBundle
from pdc_api_client.seeding.keycloak_admin import KeycloakAdmin
from pdc_api_client.seeding.pdc_entities import (
from pdc_api.models import FunderCollaborativeMemberBundle
from pdc_api.seeding.keycloak_admin import KeycloakAdmin
from pdc_api.seeding.pdc_entities import (
SeededFunderCollaborative,
SeededProposalBundle,
seed_funder_collaborative_with_members,
seed_proposal_bundle,
seed_proposal_corpus,
)
from pdc_api_client.token import KeycloakClientCredentialsProvider
from pdc_api_client.transport import APISession
from pdc_api.token import KeycloakClientCredentialsProvider
from pdc_api.transport import APISession

PDC_API_URL = os.environ.get("PDC_API_URL", "http://localhost:3030")
KEYCLOAK_SERVER_URL = os.environ.get("KEYCLOAK_SERVER_URL", "http://pdc-auth:8780")
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@

import pytest

from pdc_api_client.client import get_application_form
from pdc_api_client.errors import PDCBadRequestError
from pdc_api_client.models import ChangemakerApplicationForm
from pdc_api_client.seeding.pdc_entities import seed_application_form, seed_base_field, seed_opportunity
from pdc_api.client import get_application_form
from pdc_api.errors import PDCBadRequestError
from pdc_api.models import ChangemakerApplicationForm
from pdc_api.seeding.pdc_entities import seed_application_form, seed_base_field, seed_opportunity

SPEC_ENUM_VALUES = ["shortText", "longText", "radio", "dropdown", "multiselect", "hidden"]

Expand Down
4 changes: 2 additions & 2 deletions integration_tests/test_default_permission_grants.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

import pytest

from pdc_api_client.errors import PDCNotFoundError
from pdc_api_client.permission_grants import (
from pdc_api.errors import PDCNotFoundError
from pdc_api.permission_grants import (
DefaultPermissionGrant,
PermissionGrantEntityType,
PermissionGrantGranteeType,
Expand Down
2 changes: 1 addition & 1 deletion integration_tests/test_ensure_for_keycloak_org.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
from pdc_api_client.seeding.pdc_entities import (
from pdc_api.seeding.pdc_entities import (
ensure_changemaker_for_keycloak_org,
ensure_data_provider_for_keycloak_org,
ensure_funder_for_keycloak_org,
Expand Down
10 changes: 5 additions & 5 deletions integration_tests/test_group_membership.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@

import pytest

from pdc_api_client.client import get_changemaker
from pdc_api_client.models import PermissionGrantEntityType, PermissionGrantVerb
from pdc_api_client.permission_grants import (
from pdc_api.client import get_changemaker
from pdc_api.models import PermissionGrantEntityType, PermissionGrantVerb
from pdc_api.permission_grants import (
ChangemakerPermissionGrant,
PermissionGrantGranteeType,
create_permission_grant,
delete_permission_grant,
)
from pdc_api_client.seeding.pdc_entities import seed_changemaker
from pdc_api_client.transport import APISession
from pdc_api.seeding.pdc_entities import seed_changemaker
from pdc_api.transport import APISession


def _can_manage(session: APISession, changemaker_id: int) -> bool:
Expand Down
2 changes: 1 addition & 1 deletion integration_tests/test_keycloak_admin.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
from pdc_api_client.seeding.keycloak_admin import KeycloakOrganization, KeycloakUser
from pdc_api.seeding.keycloak_admin import KeycloakOrganization, KeycloakUser


class TestEnsureOrganization:
Expand Down
8 changes: 4 additions & 4 deletions integration_tests/test_operations.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
import pytest
import requests

from pdc_api_client.client import (
from pdc_api.client import (
create_changemaker_field_value,
create_changemaker_field_value_batch,
create_changemaker_source,
Expand All @@ -32,8 +32,8 @@
get_proposals,
link_changemaker_to_proposal,
)
from pdc_api_client.errors import PDCNotFoundError, ProposalNotFoundError
from pdc_api_client.models import (
from pdc_api.errors import PDCNotFoundError, ProposalNotFoundError
from pdc_api.models import (
BaseField,
Changemaker,
ChangemakerApplicationForm,
Expand All @@ -53,7 +53,7 @@
Proposal,
ProposalBundle,
)
from pdc_api_client.seeding.pdc_entities import (
from pdc_api.seeding.pdc_entities import (
seed_application_form,
seed_base_field,
seed_changemaker,
Expand Down
Loading