crosscontract 0.2.2__tar.gz

crosscontract-0.2.2/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @jabrell

crosscontract-0.2.2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Report a software bug or issue
+title: "\U0001F41E Bug: [describe the issue]"
+labels: bug
+assignees: ''
+
+---
+
+### Describe the Bug
+A clear and concise description of what the bug is.
+
+### Steps to Reproduce
+1. Go to '...'
+2. Click on '...'
+3. Scroll down to '...'
+4. See error
+
+### Expected Behavior
+What you expected to happen instead.
+
+### Screenshots or Logs
+If applicable, add screenshots or logs to help explain the issue.
+
+### Environment
+- Device: [eg. Laptop 13", iPhone 15, iPad Air]
+- OS: [e.g. Windows 11, macOS 14]
+- Browser/app version: [e.g. Chrome 115, v2.3.1]
+
+### Additional context
+Add any other context about the problem here.

crosscontract-0.2.2/.github/ISSUE_TEMPLATE/discussion---design-proposal.md

@@ -0,0 +1,24 @@
+---
+name: Discussion / Design Proposal
+about: Share an idea or proposal for feedback
+title: "\U0001F4AD Discussion: [topic or idea]"
+labels: question
+assignees: ''
+
+---
+
+### Topic
+Briefly describe the concept, idea, or challenge.
+
+### Problem Statement
+What problem are we trying to solve or avoid?
+
+### Proposed Direction
+Outline your suggested approach or solution.
+
+### Alternatives Considered
+Any other directions you thought of or rejected?
+
+### Open Questions
+- [ ] What are the trade-offs?
+- [ ] What do we need to learn or test?

crosscontract-0.2.2/.github/ISSUE_TEMPLATE/documentation-request.md

@@ -0,0 +1,20 @@
+---
+name: Documentation Request
+about: Request updates or additions to documentation
+title: "\U0001F4DA Docs: [topic or file name]"
+labels: documentation
+assignees: ''
+
+---
+
+### Topic or Page
+Which doc or section needs an update?
+
+### Problem or Gap
+What’s currently unclear, outdated, or missing?
+
+### Suggested Changes
+List specific edits, new sections, or examples to add.
+
+### Supporting Links or Content
+If relevant, include screenshots, code, or references.

crosscontract-0.2.2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,31 @@
+---
+name: Feature request
+about: Suggest an new feature or capability
+title: "\U0001F31F Feature: [suggested feature name]"
+labels: feature
+assignees: ''
+
+---
+
+### User Story
+**As a [role],**
+**I want [an action or feature],**
+**So that [a reason or benefit].**
+
+### Description
+A detailed explanation of the feature you'd like to see.
+
+### Acceptance Criteria
+- [ ] Criteria 1: Describe the first acceptance criterion here.
+- [ ] Criteria 2: Describe the second acceptance criterion here.
+- [ ] Criteria 3: Describe additional criteria as needed.
+
+### Definition of Done
+- [ ] All acceptance criteria are met.
+- [ ] Code is reviewed and approved.
+- [ ] Necessary tests are written and pass.
+- [ ] Documentation is updated, if applicable.
+- [ ] Feature is deployed to the [environment name].
+
+### Additional Context
+Add any related links, screenshots, or prior discussions.

crosscontract-0.2.2/.github/ISSUE_TEMPLATE/improvement.md

@@ -0,0 +1,20 @@
+---
+name: Improvement
+about: Propose improvements to existing features
+title: "\U0001F501 Improve: [feature/component name]"
+labels: ''
+assignees: ''
+
+---
+
+### Current Behavior
+Briefly describe what the current functionality is and any issues with it.
+
+### Suggested Improvement
+Describe how this feature could be improved, optimized, or simplified.
+
+### Why This Matters
+Explain the impact or benefit of this change to users or maintainers.
+
+### Related Issues or Feedback
+List any related discussions, issues, or user requests.

crosscontract-0.2.2/.github/ISSUE_TEMPLATE/maintenance---chore.md

@@ -0,0 +1,21 @@
+---
+name: Maintenance / Chore
+about: Internal development or maintenance task
+title: "\U0001F6E0️ Chore: [task name]"
+labels: ''
+assignees: ''
+
+---
+
+### Task Description
+Explain what needs to be done and why.
+
+### Context
+Is this related to refactoring, tech debt, infra updates, etc.?
+
+### Dependencies
+Does this task block or depend on other issues?
+
+### Definition of Done
+- [ ] Clear outcome or artifact produced
+- [ ] No user-visible changes unless noted

crosscontract-0.2.2/.github/ISSUE_TEMPLATE/qa---test-case.md

@@ -0,0 +1,22 @@
+---
+name: QA / Test Case
+about: Add or request test scenarios or QA validation
+title: "\U0001F9EA Test Case: [area or component]"
+labels: ''
+assignees: ''
+
+---
+
+### What to Test
+Describe the functionality or area that needs testing.
+
+###Test Scenarios
+- [ ] Scenario 1: ...
+- [ ] Scenario 2: ...
+- [ ] Scenario 3: ...
+
+### Expected Results
+Describe what each test should confirm or validate.
+
+### Environment / Test Notes
+Mention browsers, platforms, or edge cases to consider.

crosscontract-0.2.2/.github/copilot-instructions.md

@@ -0,0 +1,76 @@
+# GitHub Copilot Instructions
+
+You are an expert **Senior Python Software Engineer** specializing in distributed systems, data modeling, and API design. You are responsible for maintaining a Python Package that provides high-integrity data contracts and SDKs.
+
+## 1. Interaction Protocol (CRITICAL)
+
+- **Plan First:** For logic changes, refactoring, or new features, **do not write code immediately**. Outline a step-by-step plan.
+- **Confirm:** Explicitly ask: _"Does this plan align with your intent, or should we adjust?"_ Wait for approval.
+- **Clarify:** If requirements are vague, ask clarifying questions immediately.
+
+## 2. Project Structure (The Map)
+
+The project is a Monorepo managed by `uv`. Always check relative paths against this map:
+
+- **Root Configs:** `pyproject.toml`, `uv.lock`, `mkdocs.yml` (Documentation).
+- **Libraries & Packages:**
+  - `src/crosscontract/contracts/`: Data Contracts, Schema definitions, and Pydantic models.
+  - `src/crosscontract/crossclient/`: Synchronous HTTP client SDK.
+- **Data & Scripts:**
+  - `notebooks/`: Notebooks for illustration and experimentation.
+- **Documentation:**
+  - `docs/`: MkDocs documentation source files.
+
+## 3. Tech Stack & Standards
+
+- **Language:** Python 3.12+ (Use modern type hinting: PEP 604 union types `int | str`, `Generic` types, and `TypedDict`).
+- **Data Contracts (Pydantic v2):**
+  - **Models:** Use `ConfigDict(extra='forbid', str_strip_whitespace=True)` for strict validation.
+  - **Polymorphism:** Use `Annotated[Union[...], Field(discriminator="type")]` for polymorphic list fields (e.g., `FieldUnion`).
+  - **Frictionless Compat:** `TableSchema` models may use camelCase fields (e.g., `primaryKey`) to match JSON schema standards directly.
+  - **Validation:** Use `model_validator(mode='after')` for cross-field validation.
+- **Data Validation:**
+  - Use **Pandera** (`pandera.pandas`) for DataFrame-level validation.
+- **API Client:**
+  - Use `httpx.Client` for **synchronous** operations.
+  - **Error Handling:** Raise `CrossClientError` base exception. Map 422 responses to `ValidationError` containing detailed structure.
+  - **Context Manager:** The client is designed to be used as a context manager (`with CrossClient(...) as client:`).
+- **Package Manager:** **uv**.
+  - Use `uv sync` or `uv add`. Do not suggest `pip`.
+
+## 4. Code Style & Linting
+
+- **Linting:** Strictly follow `ruff` rules. Configured in `pyproject.toml`.
+- **Imports:** Grouping: 1. Stdlib, 2. Third-party (include `pydantic`, `pandas`, `httpx`), 3. Workspace packages (`crosscontract`), 4. Local modules.
+- **Typing:** **Strict typing is required.** Use `Any` only as a last resort. Use `Self` for method return types where applicable.
+- **Naming:** Follow PEP8. Exceptions allowed for specific Schema fields (camelCase) where mapping to external JSON standards is required.
+
+## 5. Documentation (MkDocs)
+
+- **Google Style:** All public APIs must have Google-style docstrings.
+- **Admonitions:** Use MkDocs Material syntax (e.g., `!!! note "Title"`) in docstrings and `.md` files.
+- **Root Config:** `mkdocs.yml` in the root directory controls the docs site.
+- **Documentation:** When adding features, identify which file in `docs/` needs an update.
+
+## 6. Testing
+
+- **Pattern:** Use **Arrange-Act-Assert (AAA)**.
+- **Tooling:** Use `pytest` for all tests. Use `respx` for mocking HTTP requests.
+- **Contract Testing:** Ensure every Pydantic model has a test case for:
+  1. Valid data (Happy path).
+  2. Invalid data (Edge cases/Validation errors).
+  3. Serialization to/from JSON.
+- **Isolation:** Mock external API calls using `respx` to test the client without hitting real endpoints.
+- **Organization:** Mirror source structure under `tests/`. Group related cases in classes.
+
+## 7. Frictionless Mapping Reference (Internal)
+
+When implementing Frictionless schemas in Pydantic:
+
+- `name` -> Field name
+- `type` -> Python type hint (mapped via `FieldUnion` discriminators)
+- `title` -> `Field(title=...)`
+- `constraints.required` -> Non-optional type hint
+- `description` -> `Field(description=...)`
+- `constraints.enum` -> `Literal` or `Enum`
+- `primaryKey` -> `primaryKey` field in `TableSchema`

crosscontract-0.2.2/.github/workflows/check_pr_title.yml

@@ -0,0 +1,26 @@
+name: Lint PR Title
+
+on:
+  workflow_call:
+
+jobs:
+  validate_title:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # The complete recommended list
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            ci
+            chore
+            revert
+          requireScope: false

crosscontract-0.2.2/.github/workflows/check_pr_to_main.yml

@@ -0,0 +1,18 @@
+# Orchestrator workflow for the main branch.
+# Runs tests on every PR to the main branch.
+name: Check PR Main Branch
+
+on:
+    pull_request:
+        branches:
+            - main
+        types:
+            - opened
+            - edited
+            - synchronize
+
+jobs:
+    lint_pr_title:
+        uses: ./.github/workflows/check_pr_title.yml
+    test_and_coverage:
+        uses: ./.github/workflows/test_and_coverage.yml

crosscontract-0.2.2/.github/workflows/deploy_docs.yml

@@ -0,0 +1,53 @@
+# Reusable workflow that builds the MkDocs documentation site and deploys
+# it to GitHub Pages. Requires 'workflow_call' or 'workflow_dispatch'.
+name: Build and Deploy Docs
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: "The git ref to check out (tag, branch, or SHA)"
+        required: false
+        type: string
+        default: ""
+  workflow_dispatch:
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Build Docs
+        # Change 'gh-deploy' to 'build'. This creates the 'site' folder.
+        run: uv run mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # MkDocs builds to the 'site' directory by default
+          path: "./site"
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

crosscontract-0.2.2/.github/workflows/publish_pypi.yml

@@ -0,0 +1,59 @@
+# Standalone workflow to publish the package to PyPI.
+# Triggered manually. Defaults to the latest release tag.
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version tag to publish (e.g. v0.2.1). Defaults to latest release."
+        required: false
+        type: string
+        default: ""
+
+jobs:
+  resolve_version:
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.resolve.outputs.tag }}
+    steps:
+      - name: Get latest release tag
+        id: resolve
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if [ -n "${{ inputs.version }}" ]; then
+            echo "tag=${{ inputs.version }}" >> $GITHUB_OUTPUT
+          else
+            LATEST=$(gh release view --repo ${{ github.repository }} --json tagName -q .tagName)
+            echo "tag=$LATEST" >> $GITHUB_OUTPUT
+          fi
+      - name: Validate tag exists
+        if: inputs.version != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if ! gh release view ${{ inputs.version }} --repo ${{ github.repository }} > /dev/null 2>&1; then
+            echo "Error: version '${{ inputs.version }}' not found in releases"
+            exit 1
+          fi
+
+  publish:
+    needs: resolve_version
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi-test
+      url: https://test.pypi.org/p/crosscontract
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.resolve_version.outputs.tag }}
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - name: Inspect wheel contents
+        run: unzip -l dist/*.whl
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

crosscontract-0.2.2/.github/workflows/release_main_branch.yml

@@ -0,0 +1,31 @@
+# Orchestrator workflow to deploy a new release when changes are pushed to the
+# main branch. It runs tests, creates a release if needed, and deploys docs if
+#the release was successful.
+name: Release Main Branch
+
+on:
+    workflow_dispatch:
+    push:
+        branches:
+            - main
+
+jobs:
+    test_and_coverage:
+        uses: ./.github/workflows/test_and_coverage.yml
+
+    release:
+        needs: test_and_coverage
+        if: success()
+        uses: ./.github/workflows/versioning.yml
+        permissions:
+            contents: write
+        secrets: inherit
+
+    deploy_docs:
+        needs: release
+        if: >-
+            success() &&
+            (needs.release.outputs.released == 'true' || needs.release.result == 'success')
+        uses: ./.github/workflows/deploy_docs.yml
+        with:
+            ref: ${{ needs.release.outputs.released == 'true' && needs.release.outputs.tag || github.ref }}

crosscontract-0.2.2/.github/workflows/test_and_coverage.yml

@@ -0,0 +1,75 @@
+# Reusable workflow that runs the test suite and generates coverage reports
+# for Python 3.12 and 3.13. It includes pre-commit checks.
+name: Test and Coverage
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  pre-commit:
+    name: Check Pre-commit Hooks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run pre-commit
+        run: uv run pre-commit run --all-files
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests with coverage
+        run: |
+          set -o pipefail
+          uv run coverage run -m pytest | tee pytest.log
+
+      - name: Generate Reports
+        if: success() || failure()
+        run: |
+          echo "## Test Summary (Python ${{ matrix.python-version }})" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          cat pytest.log >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+
+          echo "## Coverage Summary (Python ${{ matrix.python-version }})" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          uv run coverage report >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY

crosscontract-0.2.2/.github/workflows/versioning.yml

@@ -0,0 +1,37 @@
+name: Versioning
+
+on:
+  workflow_call:
+    outputs:
+      released:
+        description: "True if a release was created"
+        value: ${{ jobs.versioning.outputs.released }}
+      tag:
+        description: "The tag created (e.g. v1.0.1)"
+        value: ${{ jobs.versioning.outputs.tag }}
+
+jobs:
+  versioning:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # Required to push the new version commit and tag
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+      tag: ${{ steps.release.outputs.tag }}
+
+    steps:
+      - name: Generate token
+        id: generate-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+      - uses: actions/checkout@v6.0.2
+        with:
+          fetch-depth: 0
+          token: ${{ steps.generate-token.outputs.token }}
+      - name: Python Semantic Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v10.5.3
+        with:
+          github_token: ${{ steps.generate-token.outputs.token }}