civic-transparency-types

Name	civic-transparency-types JSON
Version	0.2.1 JSON
	download
home_page	None
Summary	Typed Python models (Pydantic v2) for the Civic Transparency specification
upload_time	2025-08-20 03:45:37
maintainer	None
docs_url	None
author	Civic Interconnect
requires_python	>=3.11
license	None
keywords	civic transparency jsonschema specification types
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Civic Transparency – Types

[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://civic-interconnect.github.io/civic-transparency-types/)
[![PyPI](https://img.shields.io/pypi/v/civic-transparency-types.svg)](https://pypi.org/project/civic-transparency-types/)
[![Python 3.11](https://img.shields.io/badge/python-3.11-blue?logo=python)](#)
[![CI Status](https://github.com/civic-interconnect/civic-transparency-types/actions/workflows/ci.yml/badge.svg)](https://github.com/civic-interconnect/civic-transparency-types/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

> **Typed Python models (Pydantic v2) for the Civic Transparency schema.**

> Maintained by [**Civic Interconnect**](https://github.com/civic-interconnect).

- **Documentation:** https://civic-interconnect.github.io/civic-transparency-types/
- **Schema Specification:** https://civic-interconnect.github.io/civic-transparency-spec/
- **Contributing:** [CONTRIBUTING.md](./CONTRIBUTING.md)

---

## Overview

This package provides strongly-typed Python models that correspond to the [Civic Transparency specification](https://civic-interconnect.github.io/civic-transparency-spec/).
The types are automatically generated from canonical JSON Schema definitions, ensuring consistency and validation at runtime.

**Key Features:**
- **Type Safety:** Full Pydantic v2 validation with IDE support
- **Schema Compliance:** Generated directly from official JSON schemas
- **Privacy-First:** Designed for aggregated, non-PII data exchange
- **Interoperability:** JSON serialization/deserialization with validation

---

## Installation

```bash
pip install civic-transparency-types
```

For development or schema validation:
```bash
pip install "civic-transparency-types[dev]"
```

> **Note:** This package automatically includes the compatible `civic-transparency-spec` version as a dependency.

---

## Quick Start

### Basic Usage

```python
from ci.transparency.types import Series, ProvenanceTag

# Create a time series for civic data
series = Series(
    topic="#LocalElection",
    generated_at="2025-01-15T12:00:00Z",
    interval="minute",
    points=[]  # Add your aggregated data points here
)

# Validate and serialize
data = series.model_dump()  # JSON-compatible dict
json_str = series.model_dump_json(indent=2)  # Pretty JSON string
```

### Loading and Validation

```python
from ci.transparency.types import Series

# Load from existing data with validation
series = Series.model_validate(data_dict)
series = Series.model_validate_json(json_string)

# Handle validation errors
from pydantic import ValidationError
try:
    invalid_series = Series.model_validate(bad_data)
except ValidationError as e:
    print(f"Validation failed: {e}")
```

### Working with Provenance Tags

```python
from ci.transparency.types import ProvenanceTag

tag = ProvenanceTag(
    acct_age_bucket="1-6m",
    acct_type="person", 
    automation_flag="manual",
    post_kind="original",
    client_family="mobile",
    media_provenance="hash_only",
    dedup_hash="a1b2c3d4"
)
```

---

## Available Types

| Type | Description | Schema Source |
|------|-------------|---------------|
| `Series` | Privacy-preserving time series data for civic topics | `series.schema.json` |
| `ProvenanceTag` | Per-post metadata tags (bucketed, no PII) | `provenance_tag.schema.json` |

See the [API documentation](https://civic-interconnect.github.io/civic-transparency-types/api/) for complete field definitions and examples.

---

## Validation and Schemas

### Pydantic Validation
All models use Pydantic v2 for runtime validation:
- **Strict typing:** Unknown fields are rejected
- **Format validation:** ISO 8601 dates, patterns, enums
- **Range checking:** Min/max values, string lengths
- **Nested validation:** Complex object hierarchies

### JSON Schema Validation (Optional)
For additional validation against the canonical schemas:

```python
import json
from importlib.resources import files
from jsonschema import Draft202012Validator

# Get the official schema
schema_text = files("ci.transparency.spec.schemas").joinpath("series.schema.json").read_text()
schema = json.loads(schema_text)

# Validate your data
validator = Draft202012Validator(schema)
validator.validate(series.model_dump())
```

---

## Versioning Strategy

This package follows the underlying specification versions:
- **Major versions:** Breaking schema changes
- **Minor versions:** Backward-compatible additions  
- **Patch versions:** Documentation, tooling, bug fixes

**Best Practice:** Pin to compatible major versions:
```bash
pip install "civic-transparency-types>=0.2.1,<1.0"
```

The package automatically manages compatibility with the corresponding `civic-transparency-spec` version.

---

## Integration Examples

### FastAPI Integration
```python
from fastapi import FastAPI
from ci.transparency.types import Series

app = FastAPI()

@app.post("/civic-data")
async def receive_series(series: Series) -> dict:
    # Automatic validation and parsing
    return {"received": series.topic, "points": len(series.points)}
```

### File I/O
```python
from pathlib import Path
from ci.transparency.types import Series

# Save to file
series_file = Path("data.json")
series_file.write_text(series.model_dump_json(indent=2))

# Load from file
loaded_series = Series.model_validate_json(series_file.read_text())
```

---

## Development and Contributing

This is a **generated types package** - the source of truth is the [civic-transparency-spec](https://github.com/civic-interconnect/civic-transparency-spec) repository.

### For Type Users
- Report type-related issues here
- Request documentation improvements
- Share integration examples

### For Schema Changes
- Schema modifications should be made in the [spec repository](https://github.com/civic-interconnect/civic-transparency-spec)
- Types are automatically regenerated when the spec changes

### Local Development
```bash
git clone https://github.com/civic-interconnect/civic-transparency-types
cd civic-transparency-types
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"
```

See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.

---

## Support and Community

- **Documentation:** https://civic-interconnect.github.io/civic-transparency-types/
- **Issues:** [GitHub Issues](https://github.com/civic-interconnect/civic-transparency-types/issues)
- **Discussions:** [GitHub Discussions](https://github.com/civic-interconnect/civic-transparency-types/discussions)  
- **Email:** info@civicinterconnect.org

---

## About Civic Transparency

Civic Transparency is an open standard for privacy-preserving, non-partisan analysis of how information spreads in civic contexts. The specification enables researchers, platforms, and civic organizations to share insights while protecting individual privacy.

**Core Principles:**
- **Privacy by Design:** No personally identifiable information
- **Aggregation First:** Time-bucketed, statistical summaries
- **Open Standard:** Collaborative, transparent development
- **Practical Implementation:** Real-world deployment focus

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "civic-transparency-types",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.11",
    "maintainer_email": null,
    "keywords": "civic, transparency, jsonschema, specification, types",
    "author": "Civic Interconnect",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/42/4b/74371318b61d4090a9d7a1c1b8d163d5ddb558144d7dc5cb113ae915a5a1/civic_transparency_types-0.2.1.tar.gz",
    "platform": null,
    "description": "# Civic Transparency \u2013 Types\n\n[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://civic-interconnect.github.io/civic-transparency-types/)\n[![PyPI](https://img.shields.io/pypi/v/civic-transparency-types.svg)](https://pypi.org/project/civic-transparency-types/)\n[![Python 3.11](https://img.shields.io/badge/python-3.11-blue?logo=python)](#)\n[![CI Status](https://github.com/civic-interconnect/civic-transparency-types/actions/workflows/ci.yml/badge.svg)](https://github.com/civic-interconnect/civic-transparency-types/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n\n> **Typed Python models (Pydantic v2) for the Civic Transparency schema.**\n\n> Maintained by [**Civic Interconnect**](https://github.com/civic-interconnect).\n\n- **Documentation:** https://civic-interconnect.github.io/civic-transparency-types/\n- **Schema Specification:** https://civic-interconnect.github.io/civic-transparency-spec/\n- **Contributing:** [CONTRIBUTING.md](./CONTRIBUTING.md)\n\n---\n\n## Overview\n\nThis package provides strongly-typed Python models that correspond to the [Civic Transparency specification](https://civic-interconnect.github.io/civic-transparency-spec/).\nThe types are automatically generated from canonical JSON Schema definitions, ensuring consistency and validation at runtime.\n\n**Key Features:**\n- **Type Safety:** Full Pydantic v2 validation with IDE support\n- **Schema Compliance:** Generated directly from official JSON schemas\n- **Privacy-First:** Designed for aggregated, non-PII data exchange\n- **Interoperability:** JSON serialization/deserialization with validation\n\n---\n\n## Installation\n\n```bash\npip install civic-transparency-types\n```\n\nFor development or schema validation:\n```bash\npip install \"civic-transparency-types[dev]\"\n```\n\n> **Note:** This package automatically includes the compatible `civic-transparency-spec` version as a dependency.\n\n---\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom ci.transparency.types import Series, ProvenanceTag\n\n# Create a time series for civic data\nseries = Series(\n    topic=\"#LocalElection\",\n    generated_at=\"2025-01-15T12:00:00Z\",\n    interval=\"minute\",\n    points=[]  # Add your aggregated data points here\n)\n\n# Validate and serialize\ndata = series.model_dump()  # JSON-compatible dict\njson_str = series.model_dump_json(indent=2)  # Pretty JSON string\n```\n\n### Loading and Validation\n\n```python\nfrom ci.transparency.types import Series\n\n# Load from existing data with validation\nseries = Series.model_validate(data_dict)\nseries = Series.model_validate_json(json_string)\n\n# Handle validation errors\nfrom pydantic import ValidationError\ntry:\n    invalid_series = Series.model_validate(bad_data)\nexcept ValidationError as e:\n    print(f\"Validation failed: {e}\")\n```\n\n### Working with Provenance Tags\n\n```python\nfrom ci.transparency.types import ProvenanceTag\n\ntag = ProvenanceTag(\n    acct_age_bucket=\"1-6m\",\n    acct_type=\"person\", \n    automation_flag=\"manual\",\n    post_kind=\"original\",\n    client_family=\"mobile\",\n    media_provenance=\"hash_only\",\n    dedup_hash=\"a1b2c3d4\"\n)\n```\n\n---\n\n## Available Types\n\n| Type | Description | Schema Source |\n|------|-------------|---------------|\n| `Series` | Privacy-preserving time series data for civic topics | `series.schema.json` |\n| `ProvenanceTag` | Per-post metadata tags (bucketed, no PII) | `provenance_tag.schema.json` |\n\nSee the [API documentation](https://civic-interconnect.github.io/civic-transparency-types/api/) for complete field definitions and examples.\n\n---\n\n## Validation and Schemas\n\n### Pydantic Validation\nAll models use Pydantic v2 for runtime validation:\n- **Strict typing:** Unknown fields are rejected\n- **Format validation:** ISO 8601 dates, patterns, enums\n- **Range checking:** Min/max values, string lengths\n- **Nested validation:** Complex object hierarchies\n\n### JSON Schema Validation (Optional)\nFor additional validation against the canonical schemas:\n\n```python\nimport json\nfrom importlib.resources import files\nfrom jsonschema import Draft202012Validator\n\n# Get the official schema\nschema_text = files(\"ci.transparency.spec.schemas\").joinpath(\"series.schema.json\").read_text()\nschema = json.loads(schema_text)\n\n# Validate your data\nvalidator = Draft202012Validator(schema)\nvalidator.validate(series.model_dump())\n```\n\n---\n\n## Versioning Strategy\n\nThis package follows the underlying specification versions:\n- **Major versions:** Breaking schema changes\n- **Minor versions:** Backward-compatible additions  \n- **Patch versions:** Documentation, tooling, bug fixes\n\n**Best Practice:** Pin to compatible major versions:\n```bash\npip install \"civic-transparency-types>=0.2.1,<1.0\"\n```\n\nThe package automatically manages compatibility with the corresponding `civic-transparency-spec` version.\n\n---\n\n## Integration Examples\n\n### FastAPI Integration\n```python\nfrom fastapi import FastAPI\nfrom ci.transparency.types import Series\n\napp = FastAPI()\n\n@app.post(\"/civic-data\")\nasync def receive_series(series: Series) -> dict:\n    # Automatic validation and parsing\n    return {\"received\": series.topic, \"points\": len(series.points)}\n```\n\n### File I/O\n```python\nfrom pathlib import Path\nfrom ci.transparency.types import Series\n\n# Save to file\nseries_file = Path(\"data.json\")\nseries_file.write_text(series.model_dump_json(indent=2))\n\n# Load from file\nloaded_series = Series.model_validate_json(series_file.read_text())\n```\n\n---\n\n## Development and Contributing\n\nThis is a **generated types package** - the source of truth is the [civic-transparency-spec](https://github.com/civic-interconnect/civic-transparency-spec) repository.\n\n### For Type Users\n- Report type-related issues here\n- Request documentation improvements\n- Share integration examples\n\n### For Schema Changes\n- Schema modifications should be made in the [spec repository](https://github.com/civic-interconnect/civic-transparency-spec)\n- Types are automatically regenerated when the spec changes\n\n### Local Development\n```bash\ngit clone https://github.com/civic-interconnect/civic-transparency-types\ncd civic-transparency-types\npython -m venv .venv\nsource .venv/bin/activate  # or .venv\\Scripts\\activate on Windows\npip install -e \".[dev]\"\n```\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.\n\n---\n\n## Support and Community\n\n- **Documentation:** https://civic-interconnect.github.io/civic-transparency-types/\n- **Issues:** [GitHub Issues](https://github.com/civic-interconnect/civic-transparency-types/issues)\n- **Discussions:** [GitHub Discussions](https://github.com/civic-interconnect/civic-transparency-types/discussions)  \n- **Email:** info@civicinterconnect.org\n\n---\n\n## About Civic Transparency\n\nCivic Transparency is an open standard for privacy-preserving, non-partisan analysis of how information spreads in civic contexts. The specification enables researchers, platforms, and civic organizations to share insights while protecting individual privacy.\n\n**Core Principles:**\n- **Privacy by Design:** No personally identifiable information\n- **Aggregation First:** Time-bucketed, statistical summaries\n- **Open Standard:** Collaborative, transparent development\n- **Practical Implementation:** Real-world deployment focus\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Typed Python models (Pydantic v2) for the Civic Transparency specification",
    "version": "0.2.1",
    "project_urls": {
        "Documentation": "https://civic-interconnect.github.io/civic-transparency-types/latest/",
        "Homepage": "https://github.com/civic-interconnect/civic-transparency-types",
        "Repository": "https://github.com/civic-interconnect/civic-transparency-types"
    },
    "split_keywords": [
        "civic",
        " transparency",
        " jsonschema",
        " specification",
        " types"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "fa335034d46774739d36610b0514df6a2658e18537315fb5895078676370ba3b",
                "md5": "314db8e0b2e9b67a60cec9f66bf4fdec",
                "sha256": "5c1a63afb2d8b7bc88ad151d562f5a32b6154a68bef0d6195a1e4233a2fd1a04"
            },
            "downloads": -1,
            "filename": "civic_transparency_types-0.2.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "314db8e0b2e9b67a60cec9f66bf4fdec",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.11",
            "size": 15368,
            "upload_time": "2025-08-20T03:45:36",
            "upload_time_iso_8601": "2025-08-20T03:45:36.231516Z",
            "url": "https://files.pythonhosted.org/packages/fa/33/5034d46774739d36610b0514df6a2658e18537315fb5895078676370ba3b/civic_transparency_types-0.2.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "424b74371318b61d4090a9d7a1c1b8d163d5ddb558144d7dc5cb113ae915a5a1",
                "md5": "b1617fc181ae9a8d3b8494e9a757cea6",
                "sha256": "cebb77883e9372fa9258951da968973c1b7b54d75a59b8a10f1f840e2fe2925a"
            },
            "downloads": -1,
            "filename": "civic_transparency_types-0.2.1.tar.gz",
            "has_sig": false,
            "md5_digest": "b1617fc181ae9a8d3b8494e9a757cea6",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.11",
            "size": 55825,
            "upload_time": "2025-08-20T03:45:37",
            "upload_time_iso_8601": "2025-08-20T03:45:37.802610Z",
            "url": "https://files.pythonhosted.org/packages/42/4b/74371318b61d4090a9d7a1c1b8d163d5ddb558144d7dc5cb113ae915a5a1/civic_transparency_types-0.2.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-20 03:45:37",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "civic-interconnect",
    "github_project": "civic-transparency-types",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "civic-transparency-types"
}