From 85457c0d718661594f6f8fe9b27d958d312c67d2 Mon Sep 17 00:00:00 2001 From: Chris Kucharczyk <23062974+chrisjkuch@users.noreply.github.com> Date: Wed, 18 Nov 2026 06:45:11 +0000 Subject: [PATCH 1/3] Fix type errors and run type checks in CI Annotate the hand-written modules so mypy, strict mypy on src, pyrefly, and ty all pass on Python 3.12 and 3.14. Generated models already passed. Add typecheck to `just check` and a CI job for both Python versions. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 15 ++ AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- .../test_pdc_group_membership.py | 1 + integration_tests/test_permission_grants.py | 1 + integration_tests/test_seed.py | 2 + justfile | 4 +- src/pdc_api_client/_base.py | 7 + src/pdc_api_client/client.py | 22 ++- src/pdc_api_client/errors.py | 5 +- src/pdc_api_client/models.py | 14 +- src/pdc_api_client/permission_grants.py | 19 +-- src/pdc_api_client/seeding/keycloak_admin.py | 22 +-- src/pdc_api_client/seeding/pdc_entities.py | 40 +++--- src/pdc_api_client/testing.py | 128 ++++++++++++------ src/pdc_api_client/token.py | 9 +- src/pdc_api_client/transport.py | 24 ++-- tests/test_client_operations.py | 5 +- tests/test_permission_grants.py | 3 +- tests/test_token.py | 4 +- 20 files changed, 211 insertions(+), 118 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0995fda..71f812b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -43,6 +43,21 @@ jobs: just codegen git diff --exit-code src/pdc_api_client/_generated.py + typecheck: + name: Type check (Python ${{ matrix.python }}) + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + python: ["3.12", "3.14"] + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4 + - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0 + - run: just typecheck --python=${{ matrix.python }} + test: name: Unit tests (Python ${{ matrix.python }}${{ matrix.lowest_direct && ', lowest direct dependencies' || '' }}) runs-on: ubuntu-latest diff --git a/AGENTS.md b/AGENTS.md index e87d721..e20ec74 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,7 +26,7 @@ A framework-free Python client for the Philanthropy Data Commons (PDC) API. The - `just test [--python VERSION] [--lowest-direct] [--upgrade] [-- ARGS]` runs the unit tests, which mock all HTTP with `responses`. `just integration` takes the same options. Both run against the installed package in an isolated environment, with the versions in `uv.lock` unless `--lowest-direct` or `--upgrade` resolves them fresh. Arguments after `--` go to pytest. - `just pdc up` starts PDC's CI stack in Docker; `just integration` runs the live suite against it. - `just typecheck` runs mypy (with the pydantic plugin) over `src` and both test suites, mypy in strict mode over `src`, then pyrefly and ty over `src` and both test suites, and fails at the end if any of them failed. `just typecheck-mypy`, `just typecheck-pyrefly`, and `just typecheck-ty` run one checker each. All take `--python` to check against a Python version other than `.python-version`. -- Verify with `just check` (lint plus both suites). The unit tests can't catch a change in PDC's behavior; if the stack isn't available, run `just test` and `just lint` and say that integration verification is pending. +- Verify with `just check` (lint, type checks, and both suites). The unit tests can't catch a change in PDC's behavior; if the stack isn't available, run `just lint`, `just typecheck`, and `just test` and say that integration verification is pending. ## Standards diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 52926cc..3d36050 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ just test # unit tests, no network just typecheck # mypy, pyrefly, and ty just pdc up # start PDC's CI stack in Docker just integration # integration tests against that stack -just check # lint, unit tests, and integration tests +just check # lint, type checks, unit tests, and integration tests ``` `just test` and `just integration` install the package into an isolated environment and run the tests against it, using the Python version in `.python-version` and the versions in `uv.lock`. Both take the same options, and pass arguments after `--` to pytest: diff --git a/integration_tests/test_pdc_group_membership.py b/integration_tests/test_pdc_group_membership.py index 5854760..1aa9135 100644 --- a/integration_tests/test_pdc_group_membership.py +++ b/integration_tests/test_pdc_group_membership.py @@ -54,6 +54,7 @@ def create(org_id: str) -> int: scope=[PermissionGrantEntityType.ANY], ), ) + assert grant.id is not None grant_ids.append(grant.id) return changemaker.id diff --git a/integration_tests/test_permission_grants.py b/integration_tests/test_permission_grants.py index 24544f5..237bcb5 100644 --- a/integration_tests/test_permission_grants.py +++ b/integration_tests/test_permission_grants.py @@ -142,6 +142,7 @@ def test_authenticated_users_changemaker_grant_roundtrips(self, api_session, see ) created = create_permission_grant(api_session, spec=spec) + assert created.id is not None created_grant_ids.append(created.id) assert isinstance(created, ChangemakerPermissionGrant) diff --git a/integration_tests/test_seed.py b/integration_tests/test_seed.py index 138e4bb..652d1f7 100644 --- a/integration_tests/test_seed.py +++ b/integration_tests/test_seed.py @@ -71,6 +71,7 @@ class TestSeedProposalBundle: def test_creates_complete_bundle(self, api_session): bundle = seed_proposal_bundle(api_session) assert isinstance(bundle, SeededProposalBundle) + assert bundle.changemaker is not None assert bundle.changemaker.id > 0 assert bundle.funder.short_code assert bundle.opportunity.id > 0 @@ -91,6 +92,7 @@ def test_bundle_seeds_standard_proposal_fields(self, api_session): def test_bundle_is_retrievable(self, api_session): bundle = seed_proposal_bundle(api_session) + assert bundle.changemaker is not None results = list( get_changemaker_proposals( api_session, diff --git a/justfile b/justfile index 009337c..6bde099 100644 --- a/justfile +++ b/justfile @@ -82,9 +82,9 @@ integration python=python lowest_direct="false" upgrade="false" *args: --isolated --no-editable --no-dev --group tests --reinstall -- \ python -I -m pytest -c integration_tests/pytest.ini integration_tests/ {{args}} -# Run lint, unit tests, and integration tests (run `just pdc up` first) +# Run lint, type checks, unit tests, and integration tests (run `just pdc up` first) [group('test')] -check: lint test integration +check: lint typecheck test integration # Download the current PDC OpenAPI spec [group('codegen')] diff --git a/src/pdc_api_client/_base.py b/src/pdc_api_client/_base.py index b8c795e..1118344 100644 --- a/src/pdc_api_client/_base.py +++ b/src/pdc_api_client/_base.py @@ -1,6 +1,13 @@ +from typing import ClassVar + from pydantic import BaseModel, ConfigDict class BaseSchema(BaseModel): # Ignore undeclared fields so a field PDC adds to a response doesn't break parsing. model_config = ConfigDict(populate_by_name=True, extra="ignore") + + +class PageableBundle(BaseSchema): + pdc_endpoint: ClassVar[str] + default_page_size: ClassVar[int] diff --git a/src/pdc_api_client/client.py b/src/pdc_api_client/client.py index 6d25b32..3168003 100644 --- a/src/pdc_api_client/client.py +++ b/src/pdc_api_client/client.py @@ -1,11 +1,12 @@ import json from collections.abc import Generator from datetime import datetime -from typing import ClassVar, Protocol +from typing import Any import requests from pdc_api_client import errors +from pdc_api_client._base import PageableBundle from pdc_api_client.models import ( BaseField, Changemaker, @@ -32,11 +33,11 @@ def _iterate_pages( session: APISession, *, endpoint: str, - params: dict | None = None, + params: dict[str, Any] | None = None, count_per_page: int = 50, max_requests: int | None = None, - **kwargs, -) -> Generator[dict, None, None]: + **kwargs: Any, +) -> Generator[dict[str, Any], None, None]: params = params or {} page = 1 n_pages = None @@ -180,7 +181,7 @@ def get_application_form_by_name(session: APISession, *, name: str) -> Changemak raise errors.ApplicationFormNotFoundError(detail=f"No application form named {name!r}") -def create_changemaker_proposal(session: APISession, *, data: dict) -> Proposal: +def create_changemaker_proposal(session: APISession, *, data: dict[str, Any]) -> Proposal: response = session.post("proposals", json=data) return Proposal.model_validate(response.json()) @@ -287,11 +288,6 @@ def get_funder(session: APISession, *, short_code: str) -> Funder: return Funder.model_validate(response.json()) -class PageableBundle(Protocol): - pdc_endpoint: ClassVar[str] - default_page_size: ClassVar[int] - - def get_bundle_page[BundleT: PageableBundle]( session: APISession, bundle_type: type[BundleT], @@ -299,10 +295,10 @@ def get_bundle_page[BundleT: PageableBundle]( page: int = 1, count_per_page: int | None = None, content: str | None = None, - extra_params: dict | None = None, - path_params: dict | None = None, + extra_params: dict[str, Any] | None = None, + path_params: dict[str, Any] | None = None, ) -> BundleT: - params: dict = {"_page": page, "_count": count_per_page or bundle_type.default_page_size} + params: dict[str, Any] = {"_page": page, "_count": count_per_page or bundle_type.default_page_size} if content: params["_content"] = content if extra_params: diff --git a/src/pdc_api_client/errors.py b/src/pdc_api_client/errors.py index 7fe80fb..fd11607 100644 --- a/src/pdc_api_client/errors.py +++ b/src/pdc_api_client/errors.py @@ -1,5 +1,8 @@ +from typing import Any + + class PDCException(Exception): - def __init__(self, *, detail, code=None): + def __init__(self, *, detail: Any, code: int | None = None) -> None: super().__init__(str(detail)) self.detail = detail self.code = code diff --git a/src/pdc_api_client/models.py b/src/pdc_api_client/models.py index f2fe4d8..1f96209 100644 --- a/src/pdc_api_client/models.py +++ b/src/pdc_api_client/models.py @@ -4,7 +4,7 @@ from pydantic import Field from pdc_api_client import _generated -from pdc_api_client._base import BaseSchema +from pdc_api_client._base import BaseSchema, PageableBundle from pdc_api_client._generated import ( ApplicationForm as ChangemakerApplicationForm, ) @@ -88,32 +88,32 @@ ] -class ChangemakerBundle(_generated.ChangemakerBundle): +class ChangemakerBundle(_generated.ChangemakerBundle, PageableBundle): pdc_endpoint: ClassVar[str] = "changemakers" default_page_size: ClassVar[int] = 10 -class FunderBundle(_generated.FunderBundle): +class FunderBundle(_generated.FunderBundle, PageableBundle): pdc_endpoint: ClassVar[str] = "funders" default_page_size: ClassVar[int] = 10 -class FunderCollaborativeMemberBundle(_generated.FunderCollaborativeMemberBundle): +class FunderCollaborativeMemberBundle(_generated.FunderCollaborativeMemberBundle, PageableBundle): pdc_endpoint: ClassVar[str] = "funders/{funder_collaborative_short_code}/members" default_page_size: ClassVar[int] = 50 -class ProposalBundle(_generated.ProposalBundle): +class ProposalBundle(_generated.ProposalBundle, PageableBundle): pdc_endpoint: ClassVar[str] = "proposals" default_page_size: ClassVar[int] = 10 -class InitiativeBundle(_generated.InitiativeBundle): +class InitiativeBundle(_generated.InitiativeBundle, PageableBundle): pdc_endpoint: ClassVar[str] = "initiatives" default_page_size: ClassVar[int] = 10 -class OpportunityBundle(_generated.OpportunityBundle): +class OpportunityBundle(_generated.OpportunityBundle, PageableBundle): pdc_endpoint: ClassVar[str] = "opportunities" default_page_size: ClassVar[int] = 10 diff --git a/src/pdc_api_client/permission_grants.py b/src/pdc_api_client/permission_grants.py index 4c1c9fb..65f3cf1 100644 --- a/src/pdc_api_client/permission_grants.py +++ b/src/pdc_api_client/permission_grants.py @@ -1,9 +1,10 @@ from datetime import datetime -from typing import Annotated, ClassVar, Literal +from typing import Annotated, Any, ClassVar, Literal, Self from uuid import UUID from pydantic import Field, TypeAdapter, field_validator, model_validator +from pdc_api_client._base import PageableBundle from pdc_api_client.client import get_bundle_page from pdc_api_client.models import ( BaseFieldCategory, @@ -43,7 +44,7 @@ class _PermissionGrantBase(BaseSchema): created_at: datetime | None = Field(default=None, alias="createdAt") @model_validator(mode="after") - def _check_grantee_keys_match_type(self): + def _check_grantee_keys_match_type(self) -> Self: if self.grantee_type == PermissionGrantGranteeType.USER: if self.grantee_user_keycloak_user_id is None: raise ValueError("grantee_user_keycloak_user_id is required when grantee_type is 'user'") @@ -195,10 +196,10 @@ class InitiativeFieldValuePermissionGrant(_PermissionGrantBase): _PERMISSION_GRANT_ADAPTER: TypeAdapter[PermissionGrant] = TypeAdapter(PermissionGrant) # PDC rejects write bodies that include server-managed fields. -_READONLY_FIELDS = frozenset({"id", "created_by", "created_at"}) +_READONLY_FIELDS = {"id", "created_by", "created_at"} -class PermissionGrantBundle(BaseSchema): +class PermissionGrantBundle(PageableBundle): pdc_endpoint: ClassVar[str] = _ENDPOINT default_page_size: ClassVar[int] = _DEFAULT_PAGE_SIZE entries: list[PermissionGrant] @@ -210,25 +211,25 @@ class DefaultPermissionGrant(_PermissionGrantBase): @field_validator("context_entity_type") @classmethod - def _reject_any_context(cls, value): + def _reject_any_context(cls, value: PermissionGrantEntityType) -> PermissionGrantEntityType: # PDC accepts "any" in scope but not as a default's context. if value == PermissionGrantEntityType.ANY: raise ValueError("context_entity_type cannot be 'any'") return value -class DefaultPermissionGrantBundle(BaseSchema): +class DefaultPermissionGrantBundle(PageableBundle): pdc_endpoint: ClassVar[str] = _DEFAULT_ENDPOINT default_page_size: ClassVar[int] = _DEFAULT_PAGE_SIZE entries: list[DefaultPermissionGrant] total: int -def _validate_grant(payload: dict) -> PermissionGrant: +def _validate_grant(payload: dict[str, Any]) -> PermissionGrant: return _PERMISSION_GRANT_ADAPTER.validate_python(payload) -def _grant_to_payload(spec: PermissionGrant | DefaultPermissionGrant) -> dict: +def _grant_to_payload(spec: PermissionGrant | DefaultPermissionGrant) -> dict[str, Any]: # PDC rejects the unset grantee key, so drop None values. return spec.model_dump(mode="json", by_alias=True, exclude=_READONLY_FIELDS, exclude_none=True) @@ -244,7 +245,7 @@ def list_permission_grants( grantee_type: PermissionGrantGranteeType | None = None, verb: PermissionGrantVerb | None = None, ) -> PermissionGrantBundle: - extra_params: dict = {} + extra_params: dict[str, Any] = {} if changemaker is not None: extra_params["changemaker"] = changemaker if funder is not None: diff --git a/src/pdc_api_client/seeding/keycloak_admin.py b/src/pdc_api_client/seeding/keycloak_admin.py index 4db2e84..16e6967 100644 --- a/src/pdc_api_client/seeding/keycloak_admin.py +++ b/src/pdc_api_client/seeding/keycloak_admin.py @@ -46,6 +46,8 @@ def ensure_organization(self, *, name: str, alias: str, domain: str) -> Keycloak org_id = self._admin.create_organization( {"name": name, "alias": alias, "domains": [{"name": domain, "verified": False}]} ) + if org_id is None: + raise LookupError(f"Keycloak did not return an id for new organization {alias!r}") return KeycloakOrganization(id=org_id, alias=alias, name=name) def get_organization(self, *, alias: str) -> KeycloakOrganization | None: @@ -54,9 +56,10 @@ def get_organization(self, *, alias: str) -> KeycloakOrganization | None: return None return KeycloakOrganization(id=existing["id"], alias=existing["alias"], name=existing["name"]) - def _find_org_by_alias(self, alias: str) -> dict | None: + def _find_org_by_alias(self, alias: str) -> dict[str, Any] | None: # Keycloak's org search matches names, not aliases, so filter the full listing. - for org in self._admin.get_organizations(): + organizations: list[dict[str, Any]] = self._admin.get_organizations() + for org in organizations: if org.get("alias") == alias: return org return None @@ -93,14 +96,16 @@ def ensure_user( ) return KeycloakUser(id=user_id, username=username, email=email) - def _find_user_by_username(self, username: str) -> dict | None: - for user in self._admin.get_users({"username": username, "exact": True}): + def _find_user_by_username(self, username: str) -> dict[str, Any] | None: + users: list[dict[str, Any]] = self._admin.get_users({"username": username, "exact": True}) + for user in users: if user.get("username") == username: return user return None - def _find_user_by_email(self, email: str) -> dict | None: - for user in self._admin.get_users({"email": email, "exact": True}): + def _find_user_by_email(self, email: str) -> dict[str, Any] | None: + users: list[dict[str, Any]] = self._admin.get_users({"email": email, "exact": True}) + for user in users: if (user.get("email") or "").lower() == email.lower(): return user return None @@ -166,8 +171,9 @@ def set_direct_grants_enabled(self, *, client_id: str, enabled: bool) -> None: target = self._find_client(client_id) self._admin.update_client(target["id"], {"directAccessGrantsEnabled": enabled}) - def _find_client(self, client_id: str) -> dict: - for client in self._admin.get_clients(): + def _find_client(self, client_id: str) -> dict[str, Any]: + clients: list[dict[str, Any]] = self._admin.get_clients() + for client in clients: if client.get("clientId") == client_id: return client raise LookupError(f"Keycloak client {client_id!r} not found in realm {self.realm!r}") diff --git a/src/pdc_api_client/seeding/pdc_entities.py b/src/pdc_api_client/seeding/pdc_entities.py index 71f97fd..7beb74f 100644 --- a/src/pdc_api_client/seeding/pdc_entities.py +++ b/src/pdc_api_client/seeding/pdc_entities.py @@ -1,5 +1,6 @@ import uuid from dataclasses import dataclass, field +from typing import Any from faker import Faker @@ -39,7 +40,7 @@ class SeededApplicationForm: id: int opportunity_id: int - fields: list[dict] = field(default_factory=list) + fields: list[dict[str, Any]] = field(default_factory=list) @dataclass @@ -158,7 +159,7 @@ def seed_funder( ) -> Funder: short_code = short_code or _token("funder") name = name or make_funder_name(is_collaborative=is_collaborative) - body: dict = {"name": name, "isCollaborative": is_collaborative} + body: dict[str, Any] = {"name": name, "isCollaborative": is_collaborative} if keycloak_organization_id is not None: body["keycloakOrganizationId"] = keycloak_organization_id response = session.put(f"/funders/{short_code}", json=body) @@ -170,11 +171,12 @@ def seed_funder_collaborative_member( *, collaborative: Funder, member: Funder, -) -> dict: +) -> dict[str, Any]: response = session.post( f"/funders/{collaborative.short_code}/members/{member.short_code}", ) - return response.json() + payload: dict[str, Any] = response.json() + return payload @dataclass @@ -228,7 +230,7 @@ def seed_changemaker( return existing else: tax_id = f"XX-{uuid.uuid4().hex[:7]}" - body: dict = {"name": name, "taxId": tax_id} + body: dict[str, Any] = {"name": name, "taxId": tax_id} if keycloak_organization_id is not None: body["keycloakOrganizationId"] = keycloak_organization_id response = session.post("/changemakers", json=body) @@ -274,7 +276,7 @@ def seed_data_provider( ) -> DataProvider: short_code = short_code or _token("dp") name = name or f"{fake.company()} Data" - body: dict = {"name": name} + body: dict[str, Any] = {"name": name} if keycloak_organization_id is not None: body["keycloakOrganizationId"] = keycloak_organization_id response = session.put(f"/dataProviders/{short_code}", json=body) @@ -349,15 +351,16 @@ def seed_fiscal_sponsorship( sponsee: ShallowChangemaker, sponsor: ShallowChangemaker, not_after: str | None = None, -) -> dict: - body: dict = {} +) -> dict[str, Any]: + body: dict[str, Any] = {} if not_after is not None: body["notAfter"] = not_after response = session.put( f"/changemakers/{sponsee.id}/fiscalSponsors/{sponsor.id}", json=body, ) - return response.json() + payload: dict[str, Any] = response.json() + return payload def seed_funder_collaborative_invitation( @@ -365,13 +368,14 @@ def seed_funder_collaborative_invitation( *, collaborative: Funder, invited: Funder, -) -> dict: +) -> dict[str, Any]: response = session.post( f"/funders/{collaborative.short_code}/invitations/sent/{invited.short_code}", # PDC rejects a missing body even though no fields are required. json={}, ) - return response.json() + payload: dict[str, Any] = response.json() + return payload def respond_to_funder_collaborative_invitation( @@ -380,12 +384,13 @@ def respond_to_funder_collaborative_invitation( collaborative: Funder, invited: Funder, status: str, -) -> dict: +) -> dict[str, Any]: response = session.patch( f"/funders/{invited.short_code}/invitations/received/{collaborative.short_code}", json={"invitationStatus": status}, ) - return response.json() + payload: dict[str, Any] = response.json() + return payload def seed_source( @@ -399,7 +404,7 @@ def seed_source( label = label or f"{fake.catch_phrase()} Source" if changemaker_id is not None: return create_changemaker_source(session, changemaker_id=changemaker_id, label=label) - payload: dict = {"label": label} + payload: dict[str, Any] = {"label": label} if data_provider_short_code: payload["dataProviderShortCode"] = data_provider_short_code elif funder_short_code: @@ -494,7 +499,7 @@ def seed_proposal_version( proposal: Proposal, source: Source, application_form: SeededApplicationForm, - field_values: list[dict] | None = None, + field_values: list[dict[str, Any]] | None = None, ) -> ProposalVersion: response = session.post( "/proposalVersions", @@ -513,7 +518,7 @@ def link_changemaker_to_proposal( *, changemaker: ShallowChangemaker, proposal: Proposal, -) -> dict: +) -> dict[str, Any]: response = session.post( "/changemakerProposals", json={ @@ -521,7 +526,8 @@ def link_changemaker_to_proposal( "proposalId": proposal.id, }, ) - return response.json() + payload: dict[str, Any] = response.json() + return payload _CHANGEMAKER_PROFILE_FIELDS: tuple[tuple[str, str, str], ...] = ( diff --git a/src/pdc_api_client/testing.py b/src/pdc_api_client/testing.py index ca7239c..0ed0be2 100644 --- a/src/pdc_api_client/testing.py +++ b/src/pdc_api_client/testing.py @@ -1,10 +1,16 @@ +from typing import Any + import responses +from pdc_api_client._base import PageableBundle + CREATED_AT = "2026-01-01T00:00:00Z" CREATED_BY = "00000000-0000-0000-0000-000000000009" -def changemaker_payload(*, id=1, name="Acme", keycloak_org_id=None, tax_id="12-3456789"): +def changemaker_payload( + *, id: int = 1, name: str = "Acme", keycloak_org_id: str | None = None, tax_id: str = "12-3456789" +) -> dict[str, Any]: return { "id": id, "taxId": tax_id, @@ -18,7 +24,13 @@ def changemaker_payload(*, id=1, name="Acme", keycloak_org_id=None, tax_id="12-3 } -def funder_payload(*, short_code="acme", name="Acme Foundation", keycloak_org_id=None, is_collaborative=False): +def funder_payload( + *, + short_code: str = "acme", + name: str = "Acme Foundation", + keycloak_org_id: str | None = None, + is_collaborative: bool = False, +) -> dict[str, Any]: return { "shortCode": short_code, "name": name, @@ -30,7 +42,9 @@ def funder_payload(*, short_code="acme", name="Acme Foundation", keycloak_org_id } -def data_provider_payload(*, short_code="pdw", name="Philanthropy Data Warehouse", keycloak_org_id=None): +def data_provider_payload( + *, short_code: str = "pdw", name: str = "Philanthropy Data Warehouse", keycloak_org_id: str | None = None +) -> dict[str, Any]: return { "shortCode": short_code, "name": name, @@ -40,7 +54,9 @@ def data_provider_payload(*, short_code="pdw", name="Philanthropy Data Warehouse } -def base_field_payload(short_code="field", *, data_type="string", category="uncategorized"): +def base_field_payload( + short_code: str = "field", *, data_type: str = "string", category: str = "uncategorized" +) -> dict[str, Any]: return { "shortCode": short_code, "label": short_code, @@ -54,7 +70,7 @@ def base_field_payload(short_code="field", *, data_type="string", category="unca } -def proposal_payload(*, id=100, opportunity_id=5, external_id="ext-1"): +def proposal_payload(*, id: int = 100, opportunity_id: int = 5, external_id: str = "ext-1") -> dict[str, Any]: return { "id": id, "opportunityId": opportunity_id, @@ -66,7 +82,7 @@ def proposal_payload(*, id=100, opportunity_id=5, external_id="ext-1"): } -def initiative_payload(*, id=1, changemaker_id=10, title="Summer meals"): +def initiative_payload(*, id: int = 1, changemaker_id: int = 10, title: str = "Summer meals") -> dict[str, Any]: return { "id": id, "changemakerId": changemaker_id, @@ -77,8 +93,14 @@ def initiative_payload(*, id=1, changemaker_id=10, title="Summer meals"): def initiative_field_value_payload( - *, id=1, initiative_id=1, short_code="field", value="", created_at=CREATED_AT, data_type="string" -): + *, + id: int = 1, + initiative_id: int = 1, + short_code: str = "field", + value: str = "", + created_at: str = CREATED_AT, + data_type: str = "string", +) -> dict[str, Any]: return { "id": id, "initiativeId": initiative_id, @@ -95,7 +117,7 @@ def initiative_field_value_payload( } -def changemaker_proposal_payload(*, id=1, changemaker_id=10, proposal_id=100): +def changemaker_proposal_payload(*, id: int = 1, changemaker_id: int = 10, proposal_id: int = 100) -> dict[str, Any]: return { "id": id, "changemakerId": changemaker_id, @@ -106,11 +128,16 @@ def changemaker_proposal_payload(*, id=1, changemaker_id=10, proposal_id=100): } -def organization_payload(*, changemaker=None, funder=None, data_provider=None): +def organization_payload( + *, + changemaker: dict[str, Any] | None = None, + funder: dict[str, Any] | None = None, + data_provider: dict[str, Any] | None = None, +) -> dict[str, Any]: return {"changemaker": changemaker, "funder": funder, "dataProvider": data_provider} -def application_form_payload(*, id=7, version=1, opportunity_id=5): +def application_form_payload(*, id: int = 7, version: int = 1, opportunity_id: int = 5) -> dict[str, Any]: return { "id": id, "version": version, @@ -121,11 +148,11 @@ def application_form_payload(*, id=7, version=1, opportunity_id=5): } -def source_payload(*, id=1, label="src"): +def source_payload(*, id: int = 1, label: str = "src") -> dict[str, Any]: return {"id": id, "label": label, "createdAt": CREATED_AT} -def proposal_version_payload(*, id=1, proposal_id=100, version=1): +def proposal_version_payload(*, id: int = 1, proposal_id: int = 100, version: int = 1) -> dict[str, Any]: return { "id": id, "proposalId": proposal_id, @@ -139,7 +166,9 @@ def proposal_version_payload(*, id=1, proposal_id=100, version=1): } -def changemaker_field_value_batch_payload(*, id=1, source_id=1, notes="Routine annual import"): +def changemaker_field_value_batch_payload( + *, id: int = 1, source_id: int = 1, notes: str | None = "Routine annual import" +) -> dict[str, Any]: return { "id": id, "sourceId": source_id, @@ -152,14 +181,14 @@ def changemaker_field_value_batch_payload(*, id=1, source_id=1, notes="Routine a def changemaker_field_value_payload( *, - id=1, - changemaker_id=10, - batch_id=1, - short_code="organization_name", - value="Acme", - is_valid=True, - batch=None, -): + id: int = 1, + changemaker_id: int = 10, + batch_id: int = 1, + short_code: str = "organization_name", + value: str = "Acme", + is_valid: bool | None = True, + batch: dict[str, Any] | None = None, +) -> dict[str, Any]: return { "id": id, "changemakerId": changemaker_id, @@ -175,12 +204,19 @@ def changemaker_field_value_payload( } -def bundle(entries, *, total=None): +def bundle(entries: list[dict[str, Any]], *, total: int | None = None) -> dict[str, Any]: return {"entries": entries, "total": total if total is not None else len(entries)} -def add_json_response(*, base_url, path, payload, status=200, query_params=None): - add_kwargs = { +def add_json_response( + *, + base_url: str, + path: str, + payload: Any, + status: int = 200, + query_params: dict[str, Any] | None = None, +) -> None: + add_kwargs: dict[str, Any] = { "method": responses.GET, "url": f"{base_url.rstrip('/')}/{path.lstrip('/')}", "json": payload, @@ -191,7 +227,9 @@ def add_json_response(*, base_url, path, payload, status=200, query_params=None) responses.add(**add_kwargs) -def add_changemaker_response(*, base_url, id=1, status=200, payload=None, **payload_kwargs): +def add_changemaker_response( + *, base_url: str, id: int = 1, status: int = 200, payload: Any = None, **payload_kwargs: Any +) -> None: add_json_response( base_url=base_url, path=f"changemakers/{id}", @@ -200,7 +238,9 @@ def add_changemaker_response(*, base_url, id=1, status=200, payload=None, **payl ) -def add_funder_response(*, base_url, short_code="acme", status=200, payload=None, **payload_kwargs): +def add_funder_response( + *, base_url: str, short_code: str = "acme", status: int = 200, payload: Any = None, **payload_kwargs: Any +) -> None: add_json_response( base_url=base_url, path=f"funders/{short_code}", @@ -209,7 +249,9 @@ def add_funder_response(*, base_url, short_code="acme", status=200, payload=None ) -def add_proposal_response(*, base_url, id=100, status=200, payload=None, **payload_kwargs): +def add_proposal_response( + *, base_url: str, id: int = 100, status: int = 200, payload: Any = None, **payload_kwargs: Any +) -> None: add_json_response( base_url=base_url, path=f"proposals/{id}", @@ -218,7 +260,9 @@ def add_proposal_response(*, base_url, id=100, status=200, payload=None, **paylo ) -def add_application_form_response(*, base_url, id=7, status=200, payload=None, **payload_kwargs): +def add_application_form_response( + *, base_url: str, id: int = 7, status: int = 200, payload: Any = None, **payload_kwargs: Any +) -> None: add_json_response( base_url=base_url, path=f"applicationForms/{id}", @@ -227,7 +271,9 @@ def add_application_form_response(*, base_url, id=7, status=200, payload=None, * ) -def add_organization_response(*, base_url, keycloak_id, status=200, payload=None, **payload_kwargs): +def add_organization_response( + *, base_url: str, keycloak_id: str, status: int = 200, payload: Any = None, **payload_kwargs: Any +) -> None: add_json_response( base_url=base_url, path=f"organizations/{keycloak_id}", @@ -237,18 +283,18 @@ def add_organization_response(*, base_url, keycloak_id, status=200, payload=None def add_page_response( - bundle_type, + bundle_type: type[PageableBundle], *, - base_url, - payload, - page=1, - count_per_page=None, - content=None, - status=200, - extra_params=None, - path_params=None, -): - query_params = {"_page": page, "_count": count_per_page or bundle_type.default_page_size} + base_url: str, + payload: Any, + page: int = 1, + count_per_page: int | None = None, + content: str | None = None, + status: int = 200, + extra_params: dict[str, Any] | None = None, + path_params: dict[str, Any] | None = None, +) -> None: + query_params: dict[str, Any] = {"_page": page, "_count": count_per_page or bundle_type.default_page_size} if content: query_params["_content"] = content if extra_params: diff --git a/src/pdc_api_client/token.py b/src/pdc_api_client/token.py index 24251fb..23751e2 100644 --- a/src/pdc_api_client/token.py +++ b/src/pdc_api_client/token.py @@ -23,7 +23,7 @@ def __init__( client_secret: str, timeout: float, expiry_leeway_seconds: float = 30.0, - ): + ) -> None: self._token_url = f"{server_url.rstrip('/')}/realms/{realm}/protocol/openid-connect/token" self._client_id = client_id self._client_secret = client_secret @@ -34,13 +34,13 @@ def __init__( def get_token(self) -> str: if self._token is None or time.monotonic() >= self._expires_at - self._leeway: - self._request_token() + self._token, self._expires_at = self._request_token() return self._token def refresh_if_necessary(self) -> None: pass - def _request_token(self) -> None: + def _request_token(self) -> tuple[str, float]: try: response = requests.post( self._token_url, @@ -64,8 +64,7 @@ def _request_token(self) -> None: # A fronting proxy can return 200 with a body that isn't a token. try: payload = response.json() - self._token = payload["access_token"] - self._expires_at = time.monotonic() + payload["expires_in"] + return payload["access_token"], time.monotonic() + payload["expires_in"] except (ValueError, KeyError) as exc: raise TokenRequestError( detail="Malformed token response from auth server", code=response.status_code diff --git a/src/pdc_api_client/transport.py b/src/pdc_api_client/transport.py index eefa08b..48cf0c3 100644 --- a/src/pdc_api_client/transport.py +++ b/src/pdc_api_client/transport.py @@ -1,3 +1,4 @@ +from typing import Any from urllib.parse import urljoin import requests @@ -23,10 +24,10 @@ def __init__( *, base_url: str, token_provider: TokenProvider, - timeout: int = 15, - request_kwargs: dict | None = None, + timeout: float = 15, + request_kwargs: dict[str, Any] | None = None, keep_alive: bool = True, - ): + ) -> None: # Without the trailing slash, urljoin drops the last path segment of a base like "https://host/api". self._base_url = base_url if base_url.endswith("/") else base_url + "/" self.auth = token_provider @@ -48,10 +49,12 @@ def __init__( if not keep_alive: self._session.headers["Connection"] = "close" - def _make_api_url(self, path): + def _make_api_url(self, path: str) -> str: return urljoin(self._base_url, path.lstrip("/")) - def _make_api_request(self, method, url, data=None, params=None, **kwargs): + def _make_api_request( + self, method: str, url: str, data: Any = None, params: Any = None, **kwargs: Any + ) -> requests.Response: if not url.startswith("http"): url = self._make_api_url(url) timeout = kwargs.pop("timeout", self._timeout) @@ -73,6 +76,7 @@ def _make_api_request(self, method, url, data=None, params=None, **kwargs): detail = response.json() except ValueError: detail = response.text or f"HTTP {response.status_code}" + error_class: type[errors.PDCException] if response.status_code >= 500: error_class = errors.PDCServiceError else: @@ -80,17 +84,17 @@ def _make_api_request(self, method, url, data=None, params=None, **kwargs): raise error_class(detail=detail, code=response.status_code) return response - def get(self, path, **kwargs): + def get(self, path: str, **kwargs: Any) -> requests.Response: return self._make_api_request("GET", path, **kwargs) - def put(self, path, **kwargs): + def put(self, path: str, **kwargs: Any) -> requests.Response: return self._make_api_request("PUT", path, **kwargs) - def post(self, path, **kwargs): + def post(self, path: str, **kwargs: Any) -> requests.Response: return self._make_api_request("POST", path, **kwargs) - def patch(self, path, **kwargs): + def patch(self, path: str, **kwargs: Any) -> requests.Response: return self._make_api_request("PATCH", path, **kwargs) - def delete(self, path, **kwargs): + def delete(self, path: str, **kwargs: Any) -> requests.Response: return self._make_api_request("DELETE", path, **kwargs) diff --git a/tests/test_client_operations.py b/tests/test_client_operations.py index b8b906c..19995ee 100644 --- a/tests/test_client_operations.py +++ b/tests/test_client_operations.py @@ -60,7 +60,9 @@ def _post(path, payload): def _sent_json(): - return json.loads(responses.calls[-1].request.body) + body = responses.calls[-1].request.body + assert isinstance(body, str | bytes) + return json.loads(body) class TestGetProposal: @@ -114,6 +116,7 @@ def test_parses_organization_with_funder_facet(self, session, add_organization_r result = get_organization_by_keycloak_id(session, keycloak_id="kc-uuid") assert isinstance(result, Organization) + assert result.funder is not None assert result.funder.short_code == "acme" assert result.changemaker is None diff --git a/tests/test_permission_grants.py b/tests/test_permission_grants.py index 3bbc0eb..ff2edd9 100644 --- a/tests/test_permission_grants.py +++ b/tests/test_permission_grants.py @@ -1,3 +1,4 @@ +from typing import Any from uuid import UUID import pytest @@ -21,7 +22,7 @@ USER_UUID = UUID("00000000-0000-0000-0000-000000000002") -def _changemaker_grant_payload(*, grant_id, changemaker_id, grantee_org_id): +def _changemaker_grant_payload(*, grant_id: int, changemaker_id: int, grantee_org_id: UUID) -> dict[str, Any]: return { "id": grant_id, "contextEntityType": "changemaker", diff --git a/tests/test_token.py b/tests/test_token.py index 89160e3..386daf5 100644 --- a/tests/test_token.py +++ b/tests/test_token.py @@ -1,3 +1,5 @@ +from typing import Any + import pytest import responses @@ -21,7 +23,7 @@ def _provider(**kwargs): def _add_token(*, access_token="abc", expires_in=300, status=200): - add_kwargs = { + add_kwargs: dict[str, Any] = { "method": responses.POST, "url": TOKEN_URL, "status": status, From 1c0862298c0e2a9a18a9df91bb9f6e3cb3f2def5 Mon Sep 17 00:00:00 2001 From: Chris Kucharczyk <23062974+chrisjkuch@users.noreply.github.com> Date: Wed, 18 Nov 2026 07:05:09 +0000 Subject: [PATCH 2/3] Address review: type check lowest versions, keep PageableBundle a Protocol - Raise floors to requests>=2.34, urllib3>=2, and faker>=26, the first releases with type information, and type check them in CI with `just typecheck --lowest-direct` on Python 3.12 - Match the typecheck CI job to main's conventions and notify on failure - Keep PageableBundle a Protocol, adding model_validate, so structurally matching bundles still type check - Accept list payloads and UUID keycloak ids in the testing helpers - Test ensure_organization's missing-id error, share one JSON helper in seeding, inline the read-only field set, and add a changelog entry Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 18 ++++++++++---- AGENTS.md | 2 +- CHANGELOG.md | 7 ++++++ CONTRIBUTING.md | 2 ++ justfile | 21 +++++++++------- pyproject.toml | 6 ++--- src/pdc_api_client/_base.py | 7 ------ src/pdc_api_client/client.py | 11 +++++++-- src/pdc_api_client/models.py | 14 +++++------ src/pdc_api_client/permission_grants.py | 12 ++++------ src/pdc_api_client/seeding/pdc_entities.py | 23 +++++++++--------- src/pdc_api_client/testing.py | 28 +++++++++++++--------- tests/test_keycloak_admin.py | 20 ++++++++++++++++ uv.lock | 6 ++--- 14 files changed, 112 insertions(+), 65 deletions(-) create mode 100644 tests/test_keycloak_admin.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 71f812b..c3ee759 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -44,19 +44,29 @@ jobs: git diff --exit-code src/pdc_api_client/_generated.py typecheck: - name: Type check (Python ${{ matrix.python }}) + name: Type check (Python ${{ matrix.python }}${{ matrix.lowest_direct && ', lowest direct dependencies' || '' }}) runs-on: ubuntu-latest strategy: fail-fast: false matrix: - python: ["3.12", "3.14"] + include: + - python: "3.12" + lowest_direct: true + - python: "3.14" steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4 + with: + just-version: "1.55.0" # Keep in sync with minimum-version in justfile - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0 - - run: just typecheck --python=${{ matrix.python }} + with: + cache-suffix: typecheck-py${{ matrix.python }}${{ matrix.lowest_direct && '-lowest-direct' || '' }} + - run: just typecheck --python="$PYTHON" ${LOWEST_DIRECT:+--lowest-direct} + env: + PYTHON: ${{ matrix.python }} + LOWEST_DIRECT: ${{ matrix.lowest_direct && 'true' || '' }} test: name: Unit tests (Python ${{ matrix.python }}${{ matrix.lowest_direct && ', lowest direct dependencies' || '' }}) @@ -115,7 +125,7 @@ jobs: notify: name: Notify failed build - needs: [lint, test, integration] + needs: [lint, typecheck, test, integration] if: failure() && (github.event_name == 'push' || github.event_name == 'schedule') runs-on: ubuntu-latest permissions: diff --git a/AGENTS.md b/AGENTS.md index e20ec74..6814a39 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,7 +25,7 @@ A framework-free Python client for the Philanthropy Data Commons (PDC) API. The - `just test [--python VERSION] [--lowest-direct] [--upgrade] [-- ARGS]` runs the unit tests, which mock all HTTP with `responses`. `just integration` takes the same options. Both run against the installed package in an isolated environment, with the versions in `uv.lock` unless `--lowest-direct` or `--upgrade` resolves them fresh. Arguments after `--` go to pytest. - `just pdc up` starts PDC's CI stack in Docker; `just integration` runs the live suite against it. -- `just typecheck` runs mypy (with the pydantic plugin) over `src` and both test suites, mypy in strict mode over `src`, then pyrefly and ty over `src` and both test suites, and fails at the end if any of them failed. `just typecheck-mypy`, `just typecheck-pyrefly`, and `just typecheck-ty` run one checker each. All take `--python` to check against a Python version other than `.python-version`. +- `just typecheck` runs mypy (with the pydantic plugin) over `src` and both test suites, mypy in strict mode over `src`, then pyrefly and ty over `src` and both test suites, and fails at the end if any of them failed. `just typecheck-mypy`, `just typecheck-pyrefly`, and `just typecheck-ty` run one checker each. All take `--python` and `--lowest-direct`, which work as they do for `just test`. - Verify with `just check` (lint, type checks, and both suites). The unit tests can't catch a change in PDC's behavior; if the stack isn't available, run `just lint`, `just typecheck`, and `just test` and say that integration verification is pending. ## Standards diff --git a/CHANGELOG.md b/CHANGELOG.md index d5615ef..1ad6de2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,13 @@ This project follows [Semantic Versioning](https://semver.org). Until 1.0, a min PDC does not bump its spec version for every API change, so each entry names the spec version and the date the spec was downloaded. +## Unreleased + +- The package is now type checked with mypy (including strict mode), pyrefly, and ty, so its `py.typed` marker is accurate. The testing helpers and seeding modules are fully annotated. +- The minimum versions are now `requests>=2.34`, `urllib3>=2`, and, for the `seeding` extra, `faker>=26`, the first releases that ship type information. +- `APISession(timeout=...)` accepts a float. +- `KeycloakAdmin.ensure_organization` raises `LookupError` if Keycloak creates an organization without returning its id. + ## 0.2.1 (2026-11-12) - `create_initiative` and `create_initiative_field_value` create an initiative and add a field value to it. `seed_initiative` and `seed_initiative_field_value` now call them. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d36050..4512a21 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,6 +21,8 @@ just check # lint, type checks, unit tests, and integration tests just test --python 3.12 --lowest-direct -- -k token ``` +`just typecheck` takes `--python` and `--lowest-direct` too. CI type checks Python 3.12 with the lowest versions and Python 3.14 with `uv.lock`. + `uv.lock` pins the versions used for development and CI. Update it with `uv lock --upgrade`. CI also runs both suites weekly with `--upgrade`, and opens an issue when that run fails. `just pdc up` downloads PDC's [`compose-ci.yml`](https://github.com/PhilanthropyDataCommons/service/blob/main/compose-ci.yml) and Keycloak realm from the service repo's main branch and starts the stack: the PDC API, Keycloak, Postgres, and S3. The integration tests reach Keycloak at `pdc-auth`, so add this line to `/etc/hosts`: diff --git a/justfile b/justfile index 6bde099..0e98837 100644 --- a/justfile +++ b/justfile @@ -23,21 +23,24 @@ format: # Run all three type checkers, failing at the end if any failed [group('dev')] [arg("python", long)] -typecheck python=python: +[arg("lowest_direct", long="lowest-direct", value="true")] +typecheck python=python lowest_direct="false": #!/usr/bin/env bash status=0 for checker in mypy pyrefly ty; do - {{just_executable()}} typecheck-$checker --python={{python}} || status=1 + {{just_executable()}} typecheck-$checker --python={{python}} \ + {{ if lowest_direct == "true" { "--lowest-direct" } else { "" } }} || status=1 done exit $status # Type check the package and tests with mypy, then the package in strict mode [group('dev')] [arg("python", long)] -typecheck-mypy python=python: +[arg("lowest_direct", long="lowest-direct", value="true")] +typecheck-mypy python=python lowest_direct="false": #!/usr/bin/env bash status=0 - run="uv run --python={{python}} --isolated --no-dev --group tests --group typecheck --" + run="uv run --python={{python}} {{ if lowest_direct == "true" { "--resolution=lowest-direct" } else { "" } }} --isolated --no-dev --group tests --group typecheck --" $run mypy --python-version={{python}} || status=1 $run mypy --python-version={{python}} --strict src || status=1 exit $status @@ -45,15 +48,17 @@ typecheck-mypy python=python: # Type check the package and tests with pyrefly (passes through args) [group('dev')] [arg("python", long)] -typecheck-pyrefly python=python *args: - uv run --python={{python}} --isolated --no-dev --group tests --group typecheck -- \ +[arg("lowest_direct", long="lowest-direct", value="true")] +typecheck-pyrefly python=python lowest_direct="false" *args: + uv run --python={{python}} {{ if lowest_direct == "true" { "--resolution=lowest-direct" } else { "" } }} --isolated --no-dev --group tests --group typecheck -- \ pyrefly check --python-version={{python}} {{args}} # Type check the package and tests with ty (passes through args) [group('dev')] [arg("python", long)] -typecheck-ty python=python *args: - uv run --python={{python}} --isolated --no-dev --group tests --group typecheck -- \ +[arg("lowest_direct", long="lowest-direct", value="true")] +typecheck-ty python=python lowest_direct="false" *args: + uv run --python={{python}} {{ if lowest_direct == "true" { "--resolution=lowest-direct" } else { "" } }} --isolated --no-dev --group tests --group typecheck -- \ ty check --python-version={{python}} {{args}} # Run the unit tests against the installed package diff --git a/pyproject.toml b/pyproject.toml index c5e0af6..d80ec3e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,13 +21,13 @@ classifiers = [ ] dependencies = [ "pydantic>=2.7", - "requests>=2.30", - "urllib3>=1.26.5", + "requests>=2.34", + "urllib3>=2", ] [project.optional-dependencies] testing = ["responses>=0.23"] -seeding = ["faker>=20", "python-keycloak>=6"] +seeding = ["faker>=26", "python-keycloak>=6"] [project.urls] Repository = "https://github.com/PhilanthropyDataCommons/pdc-python-client" diff --git a/src/pdc_api_client/_base.py b/src/pdc_api_client/_base.py index 1118344..b8c795e 100644 --- a/src/pdc_api_client/_base.py +++ b/src/pdc_api_client/_base.py @@ -1,13 +1,6 @@ -from typing import ClassVar - from pydantic import BaseModel, ConfigDict class BaseSchema(BaseModel): # Ignore undeclared fields so a field PDC adds to a response doesn't break parsing. model_config = ConfigDict(populate_by_name=True, extra="ignore") - - -class PageableBundle(BaseSchema): - pdc_endpoint: ClassVar[str] - default_page_size: ClassVar[int] diff --git a/src/pdc_api_client/client.py b/src/pdc_api_client/client.py index 3168003..d251532 100644 --- a/src/pdc_api_client/client.py +++ b/src/pdc_api_client/client.py @@ -1,12 +1,11 @@ import json from collections.abc import Generator from datetime import datetime -from typing import Any +from typing import Any, ClassVar, Protocol, Self import requests from pdc_api_client import errors -from pdc_api_client._base import PageableBundle from pdc_api_client.models import ( BaseField, Changemaker, @@ -288,6 +287,14 @@ def get_funder(session: APISession, *, short_code: str) -> Funder: return Funder.model_validate(response.json()) +class PageableBundle(Protocol): + pdc_endpoint: ClassVar[str] + default_page_size: ClassVar[int] + + @classmethod + def model_validate(cls, obj: Any) -> Self: ... + + def get_bundle_page[BundleT: PageableBundle]( session: APISession, bundle_type: type[BundleT], diff --git a/src/pdc_api_client/models.py b/src/pdc_api_client/models.py index 1f96209..f2fe4d8 100644 --- a/src/pdc_api_client/models.py +++ b/src/pdc_api_client/models.py @@ -4,7 +4,7 @@ from pydantic import Field from pdc_api_client import _generated -from pdc_api_client._base import BaseSchema, PageableBundle +from pdc_api_client._base import BaseSchema from pdc_api_client._generated import ( ApplicationForm as ChangemakerApplicationForm, ) @@ -88,32 +88,32 @@ ] -class ChangemakerBundle(_generated.ChangemakerBundle, PageableBundle): +class ChangemakerBundle(_generated.ChangemakerBundle): pdc_endpoint: ClassVar[str] = "changemakers" default_page_size: ClassVar[int] = 10 -class FunderBundle(_generated.FunderBundle, PageableBundle): +class FunderBundle(_generated.FunderBundle): pdc_endpoint: ClassVar[str] = "funders" default_page_size: ClassVar[int] = 10 -class FunderCollaborativeMemberBundle(_generated.FunderCollaborativeMemberBundle, PageableBundle): +class FunderCollaborativeMemberBundle(_generated.FunderCollaborativeMemberBundle): pdc_endpoint: ClassVar[str] = "funders/{funder_collaborative_short_code}/members" default_page_size: ClassVar[int] = 50 -class ProposalBundle(_generated.ProposalBundle, PageableBundle): +class ProposalBundle(_generated.ProposalBundle): pdc_endpoint: ClassVar[str] = "proposals" default_page_size: ClassVar[int] = 10 -class InitiativeBundle(_generated.InitiativeBundle, PageableBundle): +class InitiativeBundle(_generated.InitiativeBundle): pdc_endpoint: ClassVar[str] = "initiatives" default_page_size: ClassVar[int] = 10 -class OpportunityBundle(_generated.OpportunityBundle, PageableBundle): +class OpportunityBundle(_generated.OpportunityBundle): pdc_endpoint: ClassVar[str] = "opportunities" default_page_size: ClassVar[int] = 10 diff --git a/src/pdc_api_client/permission_grants.py b/src/pdc_api_client/permission_grants.py index 65f3cf1..00d4f05 100644 --- a/src/pdc_api_client/permission_grants.py +++ b/src/pdc_api_client/permission_grants.py @@ -4,7 +4,6 @@ from pydantic import Field, TypeAdapter, field_validator, model_validator -from pdc_api_client._base import PageableBundle from pdc_api_client.client import get_bundle_page from pdc_api_client.models import ( BaseFieldCategory, @@ -195,11 +194,8 @@ class InitiativeFieldValuePermissionGrant(_PermissionGrantBase): _PERMISSION_GRANT_ADAPTER: TypeAdapter[PermissionGrant] = TypeAdapter(PermissionGrant) -# PDC rejects write bodies that include server-managed fields. -_READONLY_FIELDS = {"id", "created_by", "created_at"} - -class PermissionGrantBundle(PageableBundle): +class PermissionGrantBundle(BaseSchema): pdc_endpoint: ClassVar[str] = _ENDPOINT default_page_size: ClassVar[int] = _DEFAULT_PAGE_SIZE entries: list[PermissionGrant] @@ -218,7 +214,7 @@ def _reject_any_context(cls, value: PermissionGrantEntityType) -> PermissionGran return value -class DefaultPermissionGrantBundle(PageableBundle): +class DefaultPermissionGrantBundle(BaseSchema): pdc_endpoint: ClassVar[str] = _DEFAULT_ENDPOINT default_page_size: ClassVar[int] = _DEFAULT_PAGE_SIZE entries: list[DefaultPermissionGrant] @@ -230,8 +226,8 @@ def _validate_grant(payload: dict[str, Any]) -> PermissionGrant: def _grant_to_payload(spec: PermissionGrant | DefaultPermissionGrant) -> dict[str, Any]: - # PDC rejects the unset grantee key, so drop None values. - return spec.model_dump(mode="json", by_alias=True, exclude=_READONLY_FIELDS, exclude_none=True) + # PDC rejects server-managed fields and the unset grantee key in write bodies. + return spec.model_dump(mode="json", by_alias=True, exclude={"id", "created_by", "created_at"}, exclude_none=True) def list_permission_grants( diff --git a/src/pdc_api_client/seeding/pdc_entities.py b/src/pdc_api_client/seeding/pdc_entities.py index 7beb74f..6ab9d71 100644 --- a/src/pdc_api_client/seeding/pdc_entities.py +++ b/src/pdc_api_client/seeding/pdc_entities.py @@ -2,6 +2,7 @@ from dataclasses import dataclass, field from typing import Any +import requests from faker import Faker from pdc_api_client.client import ( @@ -94,11 +95,16 @@ def make_proposal_field_seeds(*, include_numbers: bool = False) -> list[tuple[st def make_changemaker_name(*, include_numbers: bool = False) -> str: if include_numbers: - suffix = fake.random_element(("Foundation", "Initiative", "Collective", "Project", "Alliance")) + suffix: str = fake.random_element(("Foundation", "Initiative", "Collective", "Project", "Alliance")) return f"{fake.last_name()} {fake.random_int(min=100, max=9999)} {suffix}" return fake.company() +def _json_object(response: requests.Response) -> dict[str, Any]: + payload: dict[str, Any] = response.json() + return payload + + def _token(label: str) -> str: return f"{_PREFIX}_{label}_{uuid.uuid4().hex[:8]}" @@ -175,8 +181,7 @@ def seed_funder_collaborative_member( response = session.post( f"/funders/{collaborative.short_code}/members/{member.short_code}", ) - payload: dict[str, Any] = response.json() - return payload + return _json_object(response) @dataclass @@ -359,8 +364,7 @@ def seed_fiscal_sponsorship( f"/changemakers/{sponsee.id}/fiscalSponsors/{sponsor.id}", json=body, ) - payload: dict[str, Any] = response.json() - return payload + return _json_object(response) def seed_funder_collaborative_invitation( @@ -374,8 +378,7 @@ def seed_funder_collaborative_invitation( # PDC rejects a missing body even though no fields are required. json={}, ) - payload: dict[str, Any] = response.json() - return payload + return _json_object(response) def respond_to_funder_collaborative_invitation( @@ -389,8 +392,7 @@ def respond_to_funder_collaborative_invitation( f"/funders/{invited.short_code}/invitations/received/{collaborative.short_code}", json={"invitationStatus": status}, ) - payload: dict[str, Any] = response.json() - return payload + return _json_object(response) def seed_source( @@ -526,8 +528,7 @@ def link_changemaker_to_proposal( "proposalId": proposal.id, }, ) - payload: dict[str, Any] = response.json() - return payload + return _json_object(response) _CHANGEMAKER_PROFILE_FIELDS: tuple[tuple[str, str, str], ...] = ( diff --git a/src/pdc_api_client/testing.py b/src/pdc_api_client/testing.py index 0ed0be2..c00bc55 100644 --- a/src/pdc_api_client/testing.py +++ b/src/pdc_api_client/testing.py @@ -1,15 +1,16 @@ from typing import Any +from uuid import UUID import responses -from pdc_api_client._base import PageableBundle +from pdc_api_client.client import PageableBundle CREATED_AT = "2026-01-01T00:00:00Z" CREATED_BY = "00000000-0000-0000-0000-000000000009" def changemaker_payload( - *, id: int = 1, name: str = "Acme", keycloak_org_id: str | None = None, tax_id: str = "12-3456789" + *, id: int = 1, name: str = "Acme", keycloak_org_id: str | UUID | None = None, tax_id: str = "12-3456789" ) -> dict[str, Any]: return { "id": id, @@ -28,7 +29,7 @@ def funder_payload( *, short_code: str = "acme", name: str = "Acme Foundation", - keycloak_org_id: str | None = None, + keycloak_org_id: str | UUID | None = None, is_collaborative: bool = False, ) -> dict[str, Any]: return { @@ -43,7 +44,7 @@ def funder_payload( def data_provider_payload( - *, short_code: str = "pdw", name: str = "Philanthropy Data Warehouse", keycloak_org_id: str | None = None + *, short_code: str = "pdw", name: str = "Philanthropy Data Warehouse", keycloak_org_id: str | UUID | None = None ) -> dict[str, Any]: return { "shortCode": short_code, @@ -212,7 +213,7 @@ def add_json_response( *, base_url: str, path: str, - payload: Any, + payload: dict[str, Any] | list[Any], status: int = 200, query_params: dict[str, Any] | None = None, ) -> None: @@ -228,7 +229,7 @@ def add_json_response( def add_changemaker_response( - *, base_url: str, id: int = 1, status: int = 200, payload: Any = None, **payload_kwargs: Any + *, base_url: str, id: int = 1, status: int = 200, payload: dict[str, Any] | None = None, **payload_kwargs: Any ) -> None: add_json_response( base_url=base_url, @@ -239,7 +240,12 @@ def add_changemaker_response( def add_funder_response( - *, base_url: str, short_code: str = "acme", status: int = 200, payload: Any = None, **payload_kwargs: Any + *, + base_url: str, + short_code: str = "acme", + status: int = 200, + payload: dict[str, Any] | None = None, + **payload_kwargs: Any, ) -> None: add_json_response( base_url=base_url, @@ -250,7 +256,7 @@ def add_funder_response( def add_proposal_response( - *, base_url: str, id: int = 100, status: int = 200, payload: Any = None, **payload_kwargs: Any + *, base_url: str, id: int = 100, status: int = 200, payload: dict[str, Any] | None = None, **payload_kwargs: Any ) -> None: add_json_response( base_url=base_url, @@ -261,7 +267,7 @@ def add_proposal_response( def add_application_form_response( - *, base_url: str, id: int = 7, status: int = 200, payload: Any = None, **payload_kwargs: Any + *, base_url: str, id: int = 7, status: int = 200, payload: dict[str, Any] | None = None, **payload_kwargs: Any ) -> None: add_json_response( base_url=base_url, @@ -272,7 +278,7 @@ def add_application_form_response( def add_organization_response( - *, base_url: str, keycloak_id: str, status: int = 200, payload: Any = None, **payload_kwargs: Any + *, base_url: str, keycloak_id: str, status: int = 200, payload: dict[str, Any] | None = None, **payload_kwargs: Any ) -> None: add_json_response( base_url=base_url, @@ -286,7 +292,7 @@ def add_page_response( bundle_type: type[PageableBundle], *, base_url: str, - payload: Any, + payload: dict[str, Any], page: int = 1, count_per_page: int | None = None, content: str | None = None, diff --git a/tests/test_keycloak_admin.py b/tests/test_keycloak_admin.py new file mode 100644 index 0000000..e9d45b7 --- /dev/null +++ b/tests/test_keycloak_admin.py @@ -0,0 +1,20 @@ +import pytest +import responses + +from pdc_api_client.seeding.keycloak_admin import KeycloakAdmin + +KEYCLOAK_URL = "https://keycloak.test" +ORGANIZATIONS_URL = f"{KEYCLOAK_URL}/admin/realms/pdc/organizations" + + +def test_ensure_organization_raises_when_keycloak_returns_no_id(): + responses.post( + f"{KEYCLOAK_URL}/realms/master/protocol/openid-connect/token", + json={"access_token": "token", "expires_in": 300, "refresh_token": "refresh", "refresh_expires_in": 1800}, + ) + responses.get(ORGANIZATIONS_URL, json=[]) + responses.post(ORGANIZATIONS_URL, status=201) + admin = KeycloakAdmin(keycloak_url=KEYCLOAK_URL, realm="pdc", admin_username="admin", admin_password="secret") + + with pytest.raises(LookupError, match="acme"): + admin.ensure_organization(name="Acme", alias="acme", domain="acme.test") diff --git a/uv.lock b/uv.lock index 2a60ba3..f666b03 100644 --- a/uv.lock +++ b/uv.lock @@ -1087,12 +1087,12 @@ typecheck = [ [package.metadata] requires-dist = [ - { name = "faker", marker = "extra == 'seeding'", specifier = ">=20" }, + { name = "faker", marker = "extra == 'seeding'", specifier = ">=26" }, { name = "pydantic", specifier = ">=2.7" }, { name = "python-keycloak", marker = "extra == 'seeding'", specifier = ">=6" }, - { name = "requests", specifier = ">=2.30" }, + { name = "requests", specifier = ">=2.34" }, { name = "responses", marker = "extra == 'testing'", specifier = ">=0.23" }, - { name = "urllib3", specifier = ">=1.26.5" }, + { name = "urllib3", specifier = ">=2" }, ] provides-extras = ["testing", "seeding"] From 8686d1ca893cb8236364f012a6f1af48dcb2508e Mon Sep 17 00:00:00 2001 From: Chris Kucharczyk <23062974+chrisjkuch@users.noreply.github.com> Date: Wed, 18 Nov 2026 14:31:22 +0000 Subject: [PATCH 3/3] Run type checks in the unit test job Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 34 +++++++--------------------------- 1 file changed, 7 insertions(+), 27 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c3ee759..58c3797 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -43,33 +43,8 @@ jobs: just codegen git diff --exit-code src/pdc_api_client/_generated.py - typecheck: - name: Type check (Python ${{ matrix.python }}${{ matrix.lowest_direct && ', lowest direct dependencies' || '' }}) - runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: - include: - - python: "3.12" - lowest_direct: true - - python: "3.14" - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4 - with: - just-version: "1.55.0" # Keep in sync with minimum-version in justfile - - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0 - with: - cache-suffix: typecheck-py${{ matrix.python }}${{ matrix.lowest_direct && '-lowest-direct' || '' }} - - run: just typecheck --python="$PYTHON" ${LOWEST_DIRECT:+--lowest-direct} - env: - PYTHON: ${{ matrix.python }} - LOWEST_DIRECT: ${{ matrix.lowest_direct && 'true' || '' }} - test: - name: Unit tests (Python ${{ matrix.python }}${{ matrix.lowest_direct && ', lowest direct dependencies' || '' }}) + name: Unit tests and type checks (Python ${{ matrix.python }}${{ matrix.lowest_direct && ', lowest direct dependencies' || '' }}) runs-on: ubuntu-latest strategy: fail-fast: false @@ -93,6 +68,11 @@ jobs: PYTHON: ${{ matrix.python }} LOWEST_DIRECT: ${{ matrix.lowest_direct && 'true' || '' }} UPGRADE: ${{ (github.event_name == 'schedule' || inputs.upgrade) && 'true' || '' }} + - run: just typecheck --python="$PYTHON" ${LOWEST_DIRECT:+--lowest-direct} + if: ${{ !cancelled() }} + env: + PYTHON: ${{ matrix.python }} + LOWEST_DIRECT: ${{ matrix.lowest_direct && 'true' || '' }} integration: name: Integration tests @@ -125,7 +105,7 @@ jobs: notify: name: Notify failed build - needs: [lint, typecheck, test, integration] + needs: [lint, test, integration] if: failure() && (github.event_name == 'push' || github.event_name == 'schedule') runs-on: ubuntu-latest permissions: