pdc-api-python
A Python client for the Philanthropy Data Commons (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 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-api and import it as pdc_api.
Status: alpha. The API may change between minor versions until 1.0.
Installation
Install it from PyPI:
pip install pdc-api
or with uv:
uv add pdc-api
Two optional extras add test and seeding helpers:
testing: helpers for mocking PDC responses in your own tests, built onresponses.seeding: helpers for creating PDC and Keycloak test data, built onpython-keycloakand Faker.
Add them to the requirement, as in pdc-api[testing,seeding].
Python 3.12 or later is required.
Quickstart
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/",
token_provider=KeycloakClientCredentialsProvider(
server_url="https://auth.philanthropydatacommons.org",
realm="pdc",
client_id="your-client-id",
client_secret="your-client-secret",
timeout=15,
),
)
for changemaker in get_changemakers(session):
print(changemaker.name, changemaker.tax_id)
proposal = get_proposal(session, proposal_id=42)
Every response is parsed into a model from pdc_api.models, with snake_case attributes over PDC's camelCase fields.
Authentication
APISession asks a token provider for a bearer token before each request. A token provider is any object with these two methods:
class TokenProvider(Protocol):
def get_token(self) -> str: ...
def refresh_if_necessary(self) -> None: ...
The package ships one: KeycloakClientCredentialsProvider runs the OAuth2 client-credentials grant against PDC's Keycloak and caches the token until 30 seconds before it expires. Use it for a service account.
To call PDC as a signed-in user, write your own provider that returns the user's access token and refreshes it as your app requires. The protocol is structural, so your class doesn't need to import or subclass anything from this package.
PDC applies the caller's permissions to every request. The same call can return different records for different tokens, and a record the caller may not view comes back as a 404, not a 403.
Reading data
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:
from pdc_api.client import get_changemaker_proposals
for link in get_changemaker_proposals(session, changemaker_id=7):
print(link.proposal_id)
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:
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])
Bundles for nested endpoints take path parameters, such as get_bundle_page(session, FunderCollaborativeMemberBundle, path_params={"funder_collaborative_short_code": "acme"}). Query parameters that get_bundle_page doesn't name go in extra_params.
Writing data
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.
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(
session,
proposal_version=NewProposalVersion(
proposal_id=proposal.id,
source_id=3,
application_form_id=12,
field_values=[NewProposalFieldValue(application_form_field_id=88, position=1, value="Summer meals")],
),
)
A changemaker can also write its own profile values. create_changemaker_source creates a source the changemaker owns, create_changemaker_field_value_batch opens a batch under it, and create_changemaker_field_value adds one value to the batch. PDC ranks changemaker-sourced values above funder and data-provider values.
create_initiative creates an initiative led by a changemaker, and create_initiative_field_value adds a value to it from a given source.
Uploading a file takes two steps. create_file creates the file record and returns a presigned S3 POST, and upload_file_to_s3_presigned_url sends the bytes to it.
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.permission_grants models each context as its own class, so a grant parses into, say, ChangemakerPermissionGrant with a typed changemaker_id:
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,
grant=ChangemakerPermissionGrant(
changemaker_id=7,
grantee_type=PermissionGrantGranteeType.USER_GROUP,
grantee_keycloak_organization_id="1f0c6e2a-7d4b-4c55-9a51-0d8c2f0b6a11",
verbs=[PermissionGrantVerb.VIEW],
scope=[PermissionGrantEntityType.CHANGEMAKER, PermissionGrantEntityType.PROPOSAL],
),
)
page = list_permission_grants(session, changemaker_id=7, verb=PermissionGrantVerb.VIEW)
The models check that the grantee fields match grantee_type before anything is sent. Create, get, update, and delete functions exist for grants and for default permission grants. A default permission grant has no context entity; PDC copies it into a real grant on each new entity of its type as that entity is created.
Errors
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 |
|---|---|
| 400 | PDCBadRequestError |
| 401 | PDCUnauthorizedError |
| 403 | PDCForbiddenError |
| 404 | PDCNotFoundError |
| 409 | PDCConflictError |
| 422 | PDCUnprocessableEntityError |
| 5xx, timeout, or connection failure | PDCServiceError |
| Any other non-2xx | PDCException |
A few lookups raise a subclass of PDCNotFoundError named for the resource:
get_proposalandget_changemaker_proposalraiseProposalNotFoundError.get_changemakerraisesChangemakerNotFoundError.get_funderraisesFunderNotFoundError.get_changemaker_field_value_batchraisesChangemakerFieldValueBatchNotFoundError.get_application_form_by_nameraisesApplicationFormNotFoundErrorwhen no form has that name.
KeycloakClientCredentialsProvider raises TokenRequestError when Keycloak rejects the grant.
Models
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.
The spec doesn't always match what PDC returns. Some fields it marks required are missing or null in real responses, and a few shapes don't generate usable models. codegen/preprocess.py patches each mismatch before generation, one function per problem. Each rule names the mismatch it patches, and should be deleted once PDC's spec matches its responses. We reported the first batch in PhilanthropyDataCommons/service#2451.
What's not covered yet
The client covers most of the API but not all of it:
- No client functions:
/applicationFormFields,/sources(apart fromcreate_changemaker_source),/tasks(bulk uploads and base field copies),/terminologySets, and/users. Their models are generated, andsession.get/session.postreach 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.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.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:
import responses
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/"
class StaticToken:
def get_token(self) -> str:
return "test-token"
def refresh_if_necessary(self) -> None:
pass
@responses.activate
def test_lists_changemakers():
testing.add_page_response(
ChangemakerBundle,
base_url=BASE_URL,
payload=testing.bundle([testing.changemaker_payload(id=1, name="Acme")]),
)
session = APISession(base_url=BASE_URL, token_provider=StaticToken())
page = get_bundle_page(session, ChangemakerBundle)
assert page.entries[0].name == "Acme"
Seeding a PDC stack
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.seeding.pdc_entities:seed_*functions for funders, collaboratives, changemakers, fiscal sponsorships, data providers, opportunities, application forms, proposals, initiatives, and field values.seed_proposal_bundlecreates a full proposal and everything it depends on in one call.pdc_api.seeding.keycloak_admin:KeycloakAdmin, whoseensure_*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
See CONTRIBUTING.md for development setup, tests, and regenerating the models.
License
AGPL-3.0. Maintained by DrivenData.
Metadata
Release files for pdc-api 0.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pdc_api-0.4.1.tar.gz | 88.2 kB | With provenance | Details for pdc_api-0.4.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pdc_api-0.4.1-py3-none-any.whl | Python 3 | none | any | Details for pdc_api-0.4.1-py3-none-any.whl |
Total release size: 132.7 kB
Release files / pdc_api-0.4.1.tar.gz
| Download URL | pdc_api-0.4.1.tar.gz |
|---|---|
| Size | 88.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2a6fd57851ebd54a2ba8debb406a36b7eb0fd2fe82599dd57138317d83a9ec27
|
|
BLAKE2b-256 checksum How to use checksums |
6e4fb06013d4267dc690877779f786b0be94820d91df686233d09c87506bf341
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / pdc_api-0.4.1-py3-none-any.whl
| Download URL | pdc_api-0.4.1-py3-none-any.whl |
|---|---|
| Size | 44.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
76092cfb646606cb2e1d45a500a96cf2baa9bb5f10fa78b24581ded90962c389
|
|
BLAKE2b-256 checksum How to use checksums |
fe5dd5a4d44fae291682270e7b926a527e718c34e4a6ff2db9a31ddd8ed68f53
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for pdc-api 0.4.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pdc_api-0.4.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.