| Name | common-grants-sdk JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | None |
| Summary | Python SDK for the CommonGrants protocol |
| upload_time | 2025-08-29 20:50:06 |
| maintainer | None |
| docs_url | None |
| author | Your Name |
| requires_python | <4.0,>=3.11 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# CommonGrants Python SDK
A Python SDK for interacting with the CommonGrants protocol, providing a type-safe interface for managing grant opportunities.
## Features
- **Type-Safe Models**: Built with Pydantic v2 for robust data validation and serialization
- **Comprehensive Schema Support**: Full implementation of the CommonGrants protocol schemas
- **Modern Python**: Requires Python 3.11+ for optimal performance and type safety
- **Extensible**: Easy to extend with custom fields and validation
## Installation
```bash
# Using pip
pip install common-grants-sdk
# Using Poetry
poetry add common-grants-sdk
```
## Quick Start
```python
from datetime import datetime, date, UTC
from uuid import uuid4
from common_grants_sdk.schemas.fields import Money, Event
from common_grants_sdk.schemas.models import (
OpportunityBase,
OppFunding,
OppStatus,
OppStatusOptions,
OppTimeline,
)
# Create a new opportunity
opportunity = OpportunityBase(
id=uuid4(),
title="Research Grant 2024",
description="Funding for innovative research projects",
status=OppStatus(
value=OppStatusOptions.OPEN,
description="This opportunity is currently accepting applications"
),
created_at=datetime.now(UTC),
last_modified_at=datetime.now(UTC),
funding=OppFunding(
total_amount_available=Money(amount="100000.00", currency="USD"),
min_award_amount=Money(amount="10000.00", currency="USD"),
max_award_amount=Money(amount="50000.00", currency="USD"),
estimated_award_count=5
),
key_dates=OppTimeline(
app_opens=Event(
name="Application Opens",
date=date(2024, 1, 1),
description="Applications open"
),
app_deadline=Event(
name="Application Deadline",
date=date(2024, 3, 31),
description="Applications close"
)
)
)
# Serialize to JSON
json_data = opportunity.dump_json()
# Deserialize from JSON
loaded_opportunity = OpportunityBase.from_json(json_data)
```
## Core Components
### Base Model
- `CommonGrantsBaseModel`: Base class for all models, provides common serialization and validation methods
- `SystemMetadata`: Tracks creation and modification timestamps for records
### Opportunity Models
- `OpportunityBase`: Core opportunity model
- `OppFunding`: Funding details and constraints
- `OppStatus` & `OppStatusOptions`: Opportunity status tracking
- `OppTimeline`: Key dates and milestones
### Field Types
- `Money`: Represents monetary amounts with currency
- `DecimalString`: Validated string representing a decimal number
- `Event`: Union of event types
- `EventType`: Enum for event type discrimination
- `SingleDateEvent`: Event with a single date
- `DateRangeEvent`: Event with a start and end date
- `OtherEvent`: Event with a custom description or recurrence
- `CustomField`: Flexible field type for custom data
- `CustomFieldType`: Enum for custom field value types
- `ISODate`: Alias for `datetime.date` (ISO 8601 date)
- `ISOTime`: Alias for `datetime.time` (ISO 8601 time)
- `UTCDateTime`: Alias for `datetime.datetime` (UTC timestamp)
### Transformation Utilities
The SDK includes a utility for transforming data according to a mapping specification:
- `transform_from_mapping()` supports extracting fields, switching on values, and reshaping data dictionaries
## Example: Data Transformation
```python
from common_grants_sdk.utils.transformation import transform_from_mapping
source_data = {
"opportunity_id": 12345,
"opportunity_title": "Research into ABC",
"opportunity_status": "posted",
"summary": {
"award_ceiling": 100000,
"award_floor": 10000,
"forecasted_close_date": "2025-07-15",
"forecasted_post_date": "2025-05-01",
},
}
mapping = {
"id": { "field": "opportunity_id" },
"title": { "field": "opportunity_title" },
"status": {
"switch": {
"field": "opportunity_status",
"case": {
"posted": "open",
"closed": "closed",
},
"default": "custom",
}
},
"funding": {
"minAwardAmount": {
"amount": { "field": "summary.award_floor" },
"currency": "USD",
},
"maxAwardAmount": {
"amount": { "field": "summary.award_ceiling" },
"currency": "USD",
},
},
"keyDates": {
"appOpens": { "field": "summary.forecasted_post_date" },
"appDeadline": { "field": "summary.forecasted_close_date" },
},
}
transformed_data = transform_from_mapping(source_data, mapping)
assert transformed_data == {
"id": uuid4(),
"title": "Research into ABC",
"status": "open",
"funding": {
"minAwardAmount": { "amount": 10000, "currency": "USD" },
"maxAwardAmount": { "amount": 100000, "currency": "USD" },
},
"keyDates": {
"appOpens": "2025-05-01",
"appDeadline": "2025-07-15",
},
}
```
## License
See [LICENSE](../../LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "common-grants-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Your Name",
"author_email": "you@example.com",
"download_url": "https://files.pythonhosted.org/packages/66/72/5211765801b231aaaca6756f3bcb787b863abbaad2aef727790543dcf858/common_grants_sdk-0.3.1.tar.gz",
"platform": null,
"description": "# CommonGrants Python SDK\n\nA Python SDK for interacting with the CommonGrants protocol, providing a type-safe interface for managing grant opportunities.\n\n## Features\n\n- **Type-Safe Models**: Built with Pydantic v2 for robust data validation and serialization\n- **Comprehensive Schema Support**: Full implementation of the CommonGrants protocol schemas\n- **Modern Python**: Requires Python 3.11+ for optimal performance and type safety\n- **Extensible**: Easy to extend with custom fields and validation\n\n## Installation\n\n```bash\n# Using pip\npip install common-grants-sdk\n\n# Using Poetry\npoetry add common-grants-sdk\n```\n\n## Quick Start\n\n```python\nfrom datetime import datetime, date, UTC\nfrom uuid import uuid4\n\nfrom common_grants_sdk.schemas.fields import Money, Event\nfrom common_grants_sdk.schemas.models import (\n OpportunityBase,\n OppFunding,\n OppStatus,\n OppStatusOptions,\n OppTimeline,\n)\n\n# Create a new opportunity\nopportunity = OpportunityBase(\n id=uuid4(),\n title=\"Research Grant 2024\",\n description=\"Funding for innovative research projects\",\n status=OppStatus(\n value=OppStatusOptions.OPEN,\n description=\"This opportunity is currently accepting applications\"\n ),\n created_at=datetime.now(UTC),\n last_modified_at=datetime.now(UTC),\n funding=OppFunding(\n total_amount_available=Money(amount=\"100000.00\", currency=\"USD\"),\n min_award_amount=Money(amount=\"10000.00\", currency=\"USD\"),\n max_award_amount=Money(amount=\"50000.00\", currency=\"USD\"),\n estimated_award_count=5\n ),\n key_dates=OppTimeline(\n app_opens=Event(\n name=\"Application Opens\",\n date=date(2024, 1, 1),\n description=\"Applications open\"\n ),\n app_deadline=Event(\n name=\"Application Deadline\",\n date=date(2024, 3, 31),\n description=\"Applications close\"\n )\n )\n)\n\n# Serialize to JSON\njson_data = opportunity.dump_json()\n\n# Deserialize from JSON\nloaded_opportunity = OpportunityBase.from_json(json_data)\n```\n\n## Core Components\n\n### Base Model\n\n- `CommonGrantsBaseModel`: Base class for all models, provides common serialization and validation methods\n- `SystemMetadata`: Tracks creation and modification timestamps for records\n\n### Opportunity Models\n\n- `OpportunityBase`: Core opportunity model\n- `OppFunding`: Funding details and constraints\n- `OppStatus` & `OppStatusOptions`: Opportunity status tracking\n- `OppTimeline`: Key dates and milestones\n\n### Field Types\n\n- `Money`: Represents monetary amounts with currency\n- `DecimalString`: Validated string representing a decimal number\n- `Event`: Union of event types\n- `EventType`: Enum for event type discrimination\n- `SingleDateEvent`: Event with a single date\n- `DateRangeEvent`: Event with a start and end date\n- `OtherEvent`: Event with a custom description or recurrence\n- `CustomField`: Flexible field type for custom data\n- `CustomFieldType`: Enum for custom field value types\n- `ISODate`: Alias for `datetime.date` (ISO 8601 date)\n- `ISOTime`: Alias for `datetime.time` (ISO 8601 time)\n- `UTCDateTime`: Alias for `datetime.datetime` (UTC timestamp)\n\n### Transformation Utilities\n\nThe SDK includes a utility for transforming data according to a mapping specification:\n\n- `transform_from_mapping()` supports extracting fields, switching on values, and reshaping data dictionaries\n\n## Example: Data Transformation\n\n```python\nfrom common_grants_sdk.utils.transformation import transform_from_mapping\n\nsource_data = {\n \"opportunity_id\": 12345,\n \"opportunity_title\": \"Research into ABC\",\n \"opportunity_status\": \"posted\",\n \"summary\": {\n \"award_ceiling\": 100000,\n \"award_floor\": 10000,\n \"forecasted_close_date\": \"2025-07-15\",\n \"forecasted_post_date\": \"2025-05-01\",\n },\n}\n\nmapping = {\n \"id\": { \"field\": \"opportunity_id\" },\n \"title\": { \"field\": \"opportunity_title\" },\n \"status\": { \n \"switch\": {\n \"field\": \"opportunity_status\",\n \"case\": {\n \"posted\": \"open\",\n \"closed\": \"closed\",\n },\n \"default\": \"custom\",\n }\n },\n \"funding\": {\n \"minAwardAmount\": {\n \"amount\": { \"field\": \"summary.award_floor\" },\n \"currency\": \"USD\",\n },\n \"maxAwardAmount\": {\n \"amount\": { \"field\": \"summary.award_ceiling\" },\n \"currency\": \"USD\",\n },\n },\n \"keyDates\": {\n \"appOpens\": { \"field\": \"summary.forecasted_post_date\" },\n \"appDeadline\": { \"field\": \"summary.forecasted_close_date\" },\n },\n}\n\ntransformed_data = transform_from_mapping(source_data, mapping)\n\nassert transformed_data == {\n \"id\": uuid4(),\n \"title\": \"Research into ABC\",\n \"status\": \"open\",\n \"funding\": {\n \"minAwardAmount\": { \"amount\": 10000, \"currency\": \"USD\" },\n \"maxAwardAmount\": { \"amount\": 100000, \"currency\": \"USD\" },\n },\n \"keyDates\": {\n \"appOpens\": \"2025-05-01\",\n \"appDeadline\": \"2025-07-15\",\n },\n}\n```\n\n## License\n\nSee [LICENSE](../../LICENSE) for details. \n",
"bugtrack_url": null,
"license": null,
"summary": "Python SDK for the CommonGrants protocol",
"version": "0.3.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2b51dcca637f4595da6d3e73e47bc0d55f7d3588bafe8cf1d7255ea18fd4e337",
"md5": "b9c831bf37194fddc8960af6df629a1e",
"sha256": "2cf3b807a5f72d2bbc0f4f902821c518dd680eb37f3ed0b15e335e4022ce5d1f"
},
"downloads": -1,
"filename": "common_grants_sdk-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b9c831bf37194fddc8960af6df629a1e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 29801,
"upload_time": "2025-08-29T20:50:05",
"upload_time_iso_8601": "2025-08-29T20:50:05.513443Z",
"url": "https://files.pythonhosted.org/packages/2b/51/dcca637f4595da6d3e73e47bc0d55f7d3588bafe8cf1d7255ea18fd4e337/common_grants_sdk-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "66725211765801b231aaaca6756f3bcb787b863abbaad2aef727790543dcf858",
"md5": "c4087eb19dd3533ad5160ed96abe59c7",
"sha256": "68c359de0304e20774d9cc48d6f5e9ccf46f27080b8fca707973d397ad231d01"
},
"downloads": -1,
"filename": "common_grants_sdk-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "c4087eb19dd3533ad5160ed96abe59c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 17745,
"upload_time": "2025-08-29T20:50:06",
"upload_time_iso_8601": "2025-08-29T20:50:06.367105Z",
"url": "https://files.pythonhosted.org/packages/66/72/5211765801b231aaaca6756f3bcb787b863abbaad2aef727790543dcf858/common_grants_sdk-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-29 20:50:06",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "common-grants-sdk"
}
