civic-transparency-sdk 0.1.0__tar.gz

civic_transparency_sdk-0.1.0/.editorconfig

@@ -0,0 +1,13 @@
+# project .editorconfig file
+root = true
+
+[*]
+# Unix-style line endings
+end_of_line = lf
+# Add a newline at the end of the file
+insert_final_newline = true
+
+# Use 4-space indentation for Python files
+[*.py]
+indent_style = space
+indent_size = 4

civic_transparency_sdk-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# .gitattributes
+* text=auto eol=lf

civic_transparency_sdk-0.1.0/.github/scripts/coverage_summary.py

@@ -0,0 +1,59 @@
+# .github/scripts/coverage_summary.py
+import os
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Optional
+
+
+def get_coverage_summary() -> Optional[str]:
+    """
+    Parses a coverage.xml file and returns a formatted summary.
+    """
+    cov = Path("coverage.xml")
+    if not cov.exists():
+        print("coverage.xml not found; nothing to summarize.")
+        return None
+
+    try:
+        tree = ET.parse(cov)
+        root = tree.getroot()
+
+        lines_valid_str = root.get("lines-valid", "0")
+        lines_covered_str = root.get("lines-covered", "0")
+        branches_valid_str = root.get("branches-valid", "0")
+        branches_covered_str = root.get("branches-covered", "0")
+
+        lines_valid = int(lines_valid_str) if lines_valid_str else 0
+        lines_covered = int(lines_covered_str) if lines_covered_str else 0
+        branches_valid = int(branches_valid_str) if branches_valid_str else 0
+        branches_covered = int(branches_covered_str) if branches_covered_str else 0
+
+        pct = (100.0 * lines_covered / lines_valid) if lines_valid else 0.0
+        bpct = (100.0 * branches_covered / branches_valid) if branches_valid else 0.0
+
+        return f"""### Coverage Summary
+- Lines: **{lines_covered}/{lines_valid}** ({pct:.1f}%)
+- Branches: **{branches_covered}/{branches_valid}** ({bpct:.1f}%)
+"""
+    except (ET.ParseError, ValueError) as e:
+        print(f"Error parsing coverage.xml: {e}")
+        return None
+
+
+def main() -> None:
+    """
+    Main function to run the script.
+    """
+    summary = get_coverage_summary()
+
+    if summary:
+        out = os.environ.get("GITHUB_STEP_SUMMARY")
+        if out:
+            with open(out, "a", encoding="utf-8") as f:
+                f.write(summary)
+        else:
+            print(summary)
+
+
+if __name__ == "__main__":
+    main()

civic_transparency_sdk-0.1.0/.github/scripts/list_artifacts.py

@@ -0,0 +1,41 @@
+# .github/scripts/list_artifacts.py
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+DIST = Path("dist")
+
+
+def main() -> int:
+    """
+    List the distribution artifacts created by the build process.
+    """
+    if not DIST.exists():
+        print("ERROR: dist/ does not exist")
+        return 1
+
+    files = sorted(DIST.glob("*"))
+    if not files:
+        print("ERROR: dist/ is empty")
+        return 1
+
+    print("Dist files:")
+    for f in files:
+        print(" -", f)
+
+    wheels = sorted(DIST.glob("*.whl"))
+    sdists = sorted(DIST.glob("*.tar.gz"))
+
+    if not wheels:
+        print("ERROR: No wheel (*.whl) found in dist/")
+        return 1
+    if not sdists:
+        print("ERROR: No sdist (*.tar.gz) found in dist/")
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

civic_transparency_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+# .github/workflows/ci.yml
+name: Civic Transparency SDK CI (Build, Lint, Test, Coverage)
+# Runs on every push to the main branch and on pull requests.
+# First line of defense, catches issues before they reach release.
+# Designed to fail fast, run all tests, and generate coverage reports.
+# It does not fix issues, only checks them.
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout (full history for tags) 
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python and cache ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Assemble. Install all dev dependencies (non-editable)
+        run: |
+          pip install ".[dev]"
+
+      - name: Baseline. Ruff lint (fail fast, check only, no format or auto-fix in CI)
+        run: ruff check .
+
+      - name: Baseline. Run tests (include any validation and coverage)
+        run: pytest -q
+
+      - name: Coverage. Generate summary
+        run: python .github/scripts/coverage_summary.py
+
+      - name: Coverage. Build HTML
+        run: coverage html
+
+      - name: Coverage. Combine and Upload Reports
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-reports-${{ matrix.python-version }}
+          path: |
+            coverage.xml
+            htmlcov/
+          overwrite: true
+
+      - name: Deploy. Build package (sanity check)
+        run: python -m build
+
+      - name: Deploy. Build docs (sanity check)
+        run: mkdocs build

civic_transparency_sdk-0.1.0/.github/workflows/deploy-docs.yml

@@ -0,0 +1,44 @@
+# .github/workflows/deploy-docs.yml
+name: Deploy CT SDK Docs (always latest main)
+# Designed to run on every push to the main branch.
+# It builds and deploys the latest version of the documentation to GitHub Pages.
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    
+    permissions:
+      contents: write # gh-pages in docs job
+    
+    steps:
+      - name: Checkout (full history) # so setuptools_scm can see tags
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python and cache
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+      
+      - name: Assemble. Install all dev dependencies (non-editable)
+        run: |
+          pip install ".[dev]"
+
+      - name: Deploy. Build docs
+        run: mkdocs build
+
+      - name: Deploy. Deploy docs with Mike and set latest
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          mike deploy --push --update-aliases latest main
+          mike set-default --push latest
+
+
+

civic_transparency_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,70 @@
+# .github/workflows/release.yml
+name: CT SDK Release (GH Release + PyPI + versioned docs)
+# Designed to run only on version tags (e.g., v0.1.4).
+# Final step before distribution.
+# It builds distribution files, runs tests, prepares release, and publishes.
+
+on:
+  push:
+    tags:
+      - "v*.*.*"  # trigger only on version tags like v0.1.4
+
+permissions:
+  contents: write   # create the GitHub Release
+  id-token: write   # PyPI Trusted Publishing (OIDC)
+
+jobs:
+  build-and-release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout (full history) # so setuptools_scm can see tags
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python and cache
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Versioning. Extract plain version from tag (no leading `v`)
+        id: ver
+        shell: bash
+        run: echo "plain=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Versioning. Print build version for logs
+        run: echo "Building version ${{ steps.ver.outputs.plain }}"
+
+      - name: Assemble. Install all dev dependencies (non-editable)
+        run: |
+          pip install ".[dev]"
+
+      - name: Baseline. Run tests (include any validation and coverage)
+        run: pytest -q
+
+      - name: Deploy. Build sdist + wheel (exact version)
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ steps.ver.outputs.plain }}
+        run: python -m build
+
+      - name: Deploy. List artifacts
+        run: python .github/scripts/list_artifacts.py
+
+      - name: Deploy. Create GitHub Release, upload artifacts and set as latest
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}  # e.g., v0.1.4
+          name: ${{ github.ref_name }}
+          generate_release_notes: true
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+          draft: false
+          prerelease: false
+          make_latest: true
+
+      - name: Deploy. Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+

civic_transparency_sdk-0.1.0/.gitignore

@@ -0,0 +1,78 @@
+# This .gitignore file lists content that does NOT need to be tracked in the project history
+
+# ----------------------------------------
+# macOS system files (always ignore)
+# ----------------------------------------
+.DS_Store
+
+# ----------------------------------------
+# Visual Studio Code (always ignore)
+# ----------------------------------------
+.vscode/
+
+# ----------------------------------------
+# Environment variables and secrets (always ignore)
+# ----------------------------------------
+.env
+.env.*
+
+# ----------------------------------------
+# Python (ignore for all Python projects)
+# ----------------------------------------
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+dist/
+build/
+
+# ----------------------------------------
+# Testing & coverage
+# ----------------------------------------
+.coveragerc # Put info in pyproject.toml
+coveragerc # Put info in pyproject.toml
+pytest.ini # Put info in pyproject.toml
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.tox/
+.nox/
+
+# ----------------------------------------
+# Packaging tools
+# ----------------------------------------
+*.manifest
+*.spec
+
+# ----------------------------------------
+# Jupyter Notebook checkpoints
+# ----------------------------------------
+.ipynb_checkpoints/
+
+# ----------------------------------------
+# Local tools & cache
+# ----------------------------------------
+.mypy_cache/
+.ruff_cache/
+.cache/
+
+# ----------------------------------------
+# Generated version files
+# ----------------------------------------
+src/ci/transparency/types/_version.py
+
+# ----------------------------------------
+# Generated data files 
+# ----------------------------------------
+data/
+*.duckdb
+*.jsonl
+
+# ----------------------------------------
+# setuptools-scm recreates _version.py from Git tags 
+# on every build or install, so ignore it here.
+# ----------------------------------------
+*_version.py

civic_transparency_sdk-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+# .pre-commit-config.yaml
+# Only format or fix in pre-commit, not in CI.
+# CI should only check for issues, not fix them.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.8
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [--fix]
+

civic_transparency_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/)**  
+and this project adheres to **[Semantic Versioning](https://semver.org/spec/v2.0.0.html)**.
+
+---
+
+## [Unreleased]
+
+### Added
+- (placeholder) Notes for the next release.
+
+---
+
+## [0.1.0] - 2025-09-11
+
+### Added
+- **Initial release** of the **Civic Transparency SDK**.
+- Generators for simple civic transparency worlds producing JSONL windows.
+- Utilities to convert JSONL worlds into DuckDB (`jsonl_to_duckdb`).
+- Initial README with reproducible commands and seed values.
+- Packaged schemas and OpenAPI reference (mirrors `civic-transparency-spec`) for downstream private verification work.
+
+---
+
+## Notes on versioning and releases
+
+- **SemVer policy**
+  - **MAJOR** – breaking API/schema or CLI changes.
+  - **MINOR** – backward-compatible additions and enhancements.
+  - **PATCH** – documentation, tooling, or non-breaking fixes.
+- Versions are driven by git tags via `setuptools_scm`.  
+  Tag the repository with `vX.Y.Z` to publish a release.
+- Documentation and badges are updated per tag and aliased to **latest**.
+
+[Unreleased]: https://github.com/civic-interconnect/civic-transparency-sdk/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/civic-interconnect/civic-transparency-sdk/releases/tag/v0.1.0

civic_transparency_sdk-0.1.0/CITATION.cff

@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+title: Civic Transparency SDK
+message: If you use this software, please cite it as below.
+type: software
+authors:
+  - name: Civic Interconnect
+repository-code: https://github.com/civic-interconnect/civic-transparency-sdk
+license: MIT
+

civic_transparency_sdk-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,48 @@
+# Civic Transparency Code of Conduct
+
+## Our Commitment
+
+We are committed to a respectful, inclusive, and collaborative environment for everyone, regardless of:
+age, culture, ethnicity, gender identity or expression, language, national origin, neurotype, physical or mental ability, political beliefs, profession, race, religion, sexual orientation, socioeconomic status, or technical background.
+
+We welcome global participation. While we may not be able to meet every request, we will always work to treat each other well.
+
+## Expected Behavior
+
+- **Be respectful and kind.** Treat others as you would wish to be treated.
+- **Be collaborative.** Share knowledge freely, give credit, and help others succeed.
+- **Be constructive.** Focus on ideas and solutions, not personal attacks.
+- **Be concise and clear.** Communicate in ways that make participation easier for everyone, especially across languages.
+- **Use public channels** for project-related communication whenever possible, so everyone can benefit from shared knowledge.
+- **Respect privacy** and avoid sharing personal information without consent.
+
+## Unacceptable Behavior
+
+Harassment, discrimination, or abusive conduct of any kind is not acceptable. Examples include:
+
+- Threats or violent language
+- Sexist, racist, or discriminatory jokes or comments
+- Posting sexual or violent material
+- Sharing private communications without permission
+- Personal insults or name-calling
+- Unwelcome sexual attention
+- Persistent disruption or hostility after being asked to stop
+
+## Scope
+
+This Code applies to all project spaces, both online and offline, and in all interactions where you represent the project.
+
+## Reporting
+
+If you experience or witness behavior that violates this Code:
+
+- You may report it privately to the maintainers at: **info@civicinterconnect.org**
+- Reports will be handled respectfully and confidentially.
+- The project team is committed to fair review and, when necessary, taking appropriate action.
+
+## Attribution
+
+This Code of Conduct is adapted from:
+
+- [Apache Software Foundation Code of Conduct](https://www.apache.org/foundation/policies/conduct.html)
+- [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html)

civic_transparency_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# CONTRIBUTING.md
+
+## Ground Rules
+
+- **Code of Conduct**: Be respectful and constructive. Reports: `info@civicinterconnect.org`.
+- **License**: All contributions are accepted under the repo's **MIT License**.
+
+---
+
+## DEV 1. Start Locally
+
+Setup development environment (commands are for cross-platform PowerShell. Install on macOS/Linux as needed):
+
+```pwsh
+uv venv
+.\.venv\Scripts\activate
+uv pip install --upgrade pip setuptools wheel
+uv pip install --only-binary=:all: -e ".[dev]"
+pre-commit install
+pytest -q
+```
+
+## DEV 2. Validate Changes
+
+Run all checks and build verification:
+
+```pwsh
+ruff format .
+ruff check --fix
+ruff check
+mkdocs build
+pre-commit run --all-files
+pytest -q
+```
+
+## DEV 3. Build and Inspect Package
+
+```pwsh
+py -m build
+
+$TMP = New-Item -ItemType Directory -Path ([System.IO.Path]::GetTempPath()) -Name ("wheel_" + [System.Guid]::NewGuid())
+Expand-Archive dist\*.whl -DestinationPath $TMP.FullName
+Get-ChildItem -Recurse $TMP.FullName | ForEach-Object { $_.FullName.Replace($TMP.FullName + '\','') }
+Remove-Item -Recurse -Force $TMP
+```
+
+## DEV 4. Preview Docs
+
+```pwsh
+mkdocs serve
+```
+
+Open: <http://127.0.0.1:8000/>
+
+## DEV 5. Clean Artifacts
+
+```pwsh
+Get-ChildItem -Path . -Recurse -Directory -Filter "*__pycache__*" | Remove-Item -Recurse -Force
+Get-ChildItem -Path . -Recurse -Directory -Filter ".*_cache"  | Remove-Item -Recurse -Force
+Get-ChildItem -Path "src" -Recurse -Directory -Name "*.egg-info" | Remove-Item -Recurse -Force
+Remove-Item -Path "build", "dist", "site" -Recurse -Force
+```
+
+## DEV 6. Update Docs & Verify
+
+Update `CHANGELOG.md` and `pyproject`.toml dependencies.
+Ensure CI passes:
+
+```shell
+pre-commit run --all-files
+pytest -q
+```
+
+## DEV 7. Git add-commit-push Changes
+
+```shell
+git add .
+git commit -m "Prep vx.y.z"
+git push origin main
+```
+
+## DEV 8. Git tag and Push tag
+
+```shell
+git tag vx.y.z -m "x.y.z"
+git push origin vx.y.z
+```
+
+> A GitHub Action will **build**, **publish to PyPI** (Trusted Publishing), **create a GitHub Release** with artifacts, and **deploy versioned docs** with `mike`.
+
+> You do **not** need to run `gh release create` or upload files manually.

civic_transparency_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Civic Interconnect
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.