A Python SDK for interacting with the CommonGrants protocol, providing a type-safe interface for managing grant opportunities.
# Using pip
pip install common-grants-sdk
# Using Poetry
poetry add common-grants-sdkfrom common_grants_sdk.client import Client, Auth
from common_grants_sdk.client.config import Config
# 1. Create a client
config = Config(base_url="https://api.example.org", api_key="YOUR_API_KEY")
client = Client(config=config, auth=Auth.api_key("YOUR_API_KEY"))
# 2. List opportunities
response = client.opportunities.list()
for opp in response.items:
print(f"{opp.title} ({opp.status.value})")This example shows how the SDK's modules work together: fetching data with the client, validating it with schemas, and accessing typed custom fields via extensions.
from common_grants_sdk.client import Client, Auth
from common_grants_sdk.client.config import Config
from common_grants_sdk.schemas.pydantic import (
OpportunityBase,
OppStatusOptions,
CustomFieldType,
)
from common_grants_sdk.extensions.specs import CustomFieldSpec
# Extend the base schema with custom fields
CustomOpportunity = OpportunityBase.with_custom_fields(
custom_fields={
"programArea": CustomFieldSpec(
field_type=CustomFieldType.STRING,
description="Grant program area",
),
"legacyId": CustomFieldSpec(
field_type=CustomFieldType.INTEGER,
description="Legacy system ID",
),
},
model_name="CustomOpportunity",
)
# Create a client
config = Config(base_url="https://api.example.org", api_key="YOUR_API_KEY")
client = Client(config=config, auth=Auth.api_key("YOUR_API_KEY"))
# Fetch opportunities using the extended schema
response = client.opportunities.list(schema=CustomOpportunity)
for opp in response.items:
print(f"{opp.title} ({opp.status.value})")
# Access typed custom fields
if opp.status.value == OppStatusOptions.OPEN:
program = opp.get_custom_field_value("programArea", str)
print(f" Program area: {program}")
# Validate standalone data directly against the schema
raw = {
"id": "ac201443-5480-4e36-9799-a39765225153",
"title": "Community Health Grant",
"description": "A grant supporting community health initiatives.",
"status": {"value": "open"},
"createdAt": "2025-01-01T00:00:00Z",
"lastModifiedAt": "2025-01-01T00:00:00Z",
}
validated_opp = OpportunityBase.model_validate(raw)
print(validated_opp.title)The SDK is organized into modules, each with its own documentation:
| Module | Description |
|---|---|
| Client | HTTP client with auth, pagination, and low-level HTTP methods |
| Schemas | Pydantic models, validation, and generic response schemas |
| Extensions | Custom fields and plugin framework |
HTTP client with built-in authentication, auto-pagination, and environment variable configuration. See the Client guide for setup, authentication, and usage examples.
Pydantic v2 models for validating and parsing CommonGrants data, along with type-safe enum constants. See the Schemas guide for validation examples, type safety patterns, and the full API reference.
Extension framework for adding typed custom fields to CommonGrants schemas, either ad hoc or as reusable plugins. See the Extensions guide for the full guide.
See LICENSE