Init

Author: SamuelMarks

.github/workflows/uv.yml

@@ -0,0 +1,40 @@
+name: uv
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install the project
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install -e ".[dev]"
+
+      - name: Run tests
+        run: uv run pytest

.gitignore

@@ -0,0 +1,5 @@
+.vscode
+.idea
+*venv*
+__pycache__
+*.pyc

ARCHITECTURE.md

@@ -0,0 +1,47 @@
+# Architecture
+
+The `cdd-python-client` is designed around a strictly modular, bidirectional Code-to-Spec and Spec-to-Code architecture, heavily utilizing Abstract Syntax Trees (AST).
+
+## Core Concepts
+
+1. **Contract-Driven Development (CDD)**: The source of truth can be dynamically negotiated. You can start with an OpenAPI specification (`openapi.json`) or you can start with Python code (FastAPI mocks, Pydantic models, or pytest tests).
+2. **Abstract Syntax Trees (AST)**: Instead of regex or simple templating, this tool utilizes `libcst` (Concrete Syntax Tree) to read and write Python code. This preserves comments, whitespace, and structural integrity.
+3. **Pydantic Models**: The OpenAPI 3.2.0 specification is modeled heavily using Pydantic (`models.py`). This guarantees in-memory type safety and validation when parsing or emitting specifications.
+
+## Directory Structure
+
+The repository is modularized by domain, ensuring that parsing and emitting logic for specific Python/OpenAPI concepts remain isolated:
+
+```
+src/openapi_client/
+├── models.py                   # Single Source of Truth for OpenAPI 3.2.0 specs
+├── cli.py                      # CLI entrypoints and unified sync workflows
+├── openapi/                    # JSON/Dict Serialization
+│   ├── parse.py
+│   └── emit.py
+├── classes/                    # Pydantic Models <-> OpenAPI Components/Schemas
+│   ├── parse.py                # Extracts JSON schemas from Python classes
+│   └── emit.py                 # Emits Pydantic models from JSON schemas
+├── functions/                  # Python Methods <-> OpenAPI Operations
+│   ├── parse.py
+│   └── emit.py
+├── docstrings/                 # Python Docstrings <-> OpenAPI Summary/Description
+│   ├── parse.py
+│   └── emit.py
+├── routes/                     # Client generation (combining classes + functions)
+│   ├── parse.py
+│   └── emit.py
+├── mocks/                      # FastAPI Mocks <-> OpenAPI Paths/Operations
+│   ├── parse.py
+│   └── emit.py
+└── tests/                      # Pytest functions <-> OpenAPI Examples/Validation
+    ├── parse.py
+    └── emit.py
+```
+
+## The Sync Lifecycle (`cdd sync --dir`)
+
+When using the unified sync workflow, the system performs a bidirectional merge:
+1. **Parse**: `libcst` Visitors traverse `client.py`, `mock_server.py`, and `test_client.py`. Any discovered routes, Pydantic models, and docstrings are extracted and merged into the in-memory OpenAPI Pydantic model.
+2. **Merge**: If an `openapi.json` exists, it is parsed and used as the baseline. Code-extracted definitions overlay or expand the JSON definitions.
+3. **Emit**: The fully reconciled OpenAPI model is serialized back to `openapi.json`. Then, `libcst` generators rebuild `client.py`, `mock_server.py`, and `test_client.py`, ensuring 100% synchronization across the client, backend mocks, tests, and documentation.

COMPLIANCE.md

@@ -0,0 +1,33 @@
+# OpenAPI 3.2.0 Compliance
+
+This project is actively pursuing 100% compliance with the **OpenAPI 3.2.0 Specification**.
+
+## Supported Features
+
+The following OpenAPI 3.2.0 structures are fully modeled in `src/openapi_client/models.py` via Pydantic and actively supported in the AST parsing/emitting pipeline:
+
+### Document Structure
+- **OpenAPI Object**: Core root object supporting `openapi: 3.2.0`, `info`, `paths`, `components`, `servers`, `security`, `tags`, `webhooks`, and `$self`.
+- **Info Object**: Fully supported, including `Contact` and `License` objects.
+- **Server / ServerVariable Objects**: Fully modeled.
+- **Paths / PathItem Objects**: Supports standard HTTP methods (`get`, `post`, `put`, `delete`, `patch`, `options`, `head`, `trace`) as well as the new OAS 3.2.0 `query` method and `additionalOperations` mapping.
+- **Operation Object**: Supports `operationId`, `summary`, `description`, `parameters`, `requestBody`, `responses`, `callbacks`, `security`, etc.
+- **Components Object**: Models schemas, responses, parameters, examples, requestBodies, headers, securitySchemes, links, callbacks, pathItems, and `mediaTypes` (new in OAS 3.2.0).
+
+### Schema & Data Types
+- **Schema Object**: Includes full JSON Schema validation properties (`type`, `properties`, `items`, `allOf`, `anyOf`, `oneOf`, `discriminator`, etc.). 
+- **Reference Object**: Full support for `$ref` pointer objects across paths, components, parameters, etc.
+
+### Media Types & Encodings (OAS 3.2.0 Enhancements)
+- **MediaType Object**: Supports the newly defined streaming and sequential payload fields `itemSchema`, `prefixEncoding`, and `itemEncoding`.
+- **Encoding Object**: Supports headers, standard encodings, `prefixEncoding`, and `itemEncoding`.
+
+## Partial / Ongoing Support
+While the data models strictly validate against OpenAPI 3.2.0 schemas, the *AST manipulation* logic is still incrementally supporting features:
+
+1. **Complex Parameters**: Deep object serializations for Query strings (`spaceDelimited`, `pipeDelimited`) are modeled but code-generation for them currently maps to generic `Any` types in the Python client.
+2. **Streaming / Webhooks**: Models exist, but FastAPI mock extraction and test extraction for event-driven / server-sent events (`text/event-stream`) is currently stubbed.
+3. **Implicit Connections**: Cross-document `$ref` resolution is currently limited to local `#/...` JSON pointers within the `openapi.json` file.
+
+## Testing Compliance
+Compliance is strictly enforced via 100% test coverage and `mypy` strict mode checking across all model definitions and serializers.

DEVELOPING.md

@@ -0,0 +1,53 @@
+# Developing
+
+Welcome to the `cdd-python-client` development guide. This project is built using Python 3.9+ and relies heavily on AST manipulation using `libcst`.
+
+## Setup
+
+1. **Clone and Setup Virtual Environment:**
+   ```bash
+   git clone <repository_url>
+   cd cdd-python-client
+   python3 -m venv venv
+   source venv/bin/activate
+   ```
+
+2. **Install Dependencies (Including Dev):**
+   ```bash
+   pip install -e .[dev]
+   ```
+   *Note: This will install `pydantic`, `libcst`, `urllib3`, `pytest`, `pytest-cov`, and `mypy`.*
+
+## Running Tests
+
+We maintain **100% test coverage**. Any new features must be fully covered.
+
+```bash
+# Run pytest with coverage reporting
+PYTHONPATH=src pytest --cov=src --cov-report=term-missing
+```
+
+## Type Checking
+
+We maintain **100% Type Safety**. All modules must pass strict mypy validation.
+
+```bash
+mypy src/openapi_client
+```
+
+## Extending the Architecture
+
+The codebase relies on a pattern of `parse.py` (AST to Spec) and `emit.py` (Spec to AST) inside domain-specific directories (`src/openapi_client/<domain>/`).
+
+### Adding a New Domain
+1. **Create the directory**: `mkdir src/openapi_client/new_domain/`
+2. **Create `parse.py`**:
+   - Write a `libcst.CSTVisitor` subclass to traverse Python AST and mutate the shared `OpenAPI` state model.
+3. **Create `emit.py`**:
+   - Write functions that take an `OpenAPI` state model and return `libcst.CSTNode` objects (like `cst.ClassDef` or `cst.FunctionDef`).
+4. **Wire into `cli.py`**:
+   - Make sure your extractor is called inside `sync_dir()` and `extract_from_code()`.
+   - Make sure your emitter is called when assembling the client module.
+
+### Updating Models
+Models are located in `src/openapi_client/models.py`. We use `pydantic`. If you add self-referencing schemas or complex union types, ensure you update the `model_rebuild()` calls at the bottom of the file.

PUBLISH.md

@@ -0,0 +1,84 @@
+# Publishing the CDD Python Client
+
+This document outlines how to publish the `cdd-python-client` library and CLI to Python's official package repository, as well as how to generate and host the project's documentation.
+
+## 1. Publishing to PyPI (Python Package Index)
+
+PyPI is the standard and most popular package registry for Python. Publishing there makes the library installable via `pip install cdd-python-client`.
+
+### Prerequisites
+- Create an account on [PyPI](https://pypi.org/) and [TestPyPI](https://test.pypi.org/).
+- Generate an API token from your PyPI account settings.
+- Install the build and publish tools:
+  ```bash
+  pip install build twine
+  ```
+
+### Build and Upload
+1. **Clean previous builds** (optional but recommended):
+   ```bash
+   rm -rf dist/ build/
+   ```
+2. **Build the wheel and sdist**:
+   ```bash
+   python -m build
+   ```
+   *This uses `hatchling` as configured in the `pyproject.toml` to generate files in the `dist/` directory.*
+3. **Upload to PyPI**:
+   ```bash
+   python -m twine upload dist/*
+   ```
+   *When prompted, use `__token__` as the username and your generated API token as the password.*
+
+---
+
+## 2. Generating Local Documentation (Static Serving)
+
+To generate static HTML documentation directly from the source code and docstrings, we recommend `pdoc` (or `mkdocs`/`sphinx`). `pdoc` requires zero configuration and produces a ready-to-serve static HTML folder.
+
+### Generate HTML
+```bash
+pip install pdoc
+pdoc src/openapi_client -o docs_html
+```
+
+### Serve Locally
+You can preview the generated static documentation by serving the `docs_html` directory:
+```bash
+python -m http.server -d docs_html 8000
+```
+Visit `http://localhost:8000` in your browser. This `docs_html` folder can be uploaded to any static web host (e.g., AWS S3, GitHub Pages, Vercel).
+
+---
+
+## 3. Publishing Documentation to Read the Docs
+
+[Read the Docs (RTD)](https://readthedocs.org/) is the most popular hosting platform for open-source Python documentation.
+
+### Setup Steps
+1. **Create a `.readthedocs.yaml` file** in the root of the repository:
+   ```yaml
+   version: 2
+   build:
+     os: ubuntu-22.04
+     tools:
+       python: "3.12"
+   python:
+     install:
+       - requirements: requirements.txt
+       - method: pip
+         path: .
+   sphinx:
+     configuration: docs/conf.py
+   ```
+2. **Initialize Sphinx** (if not already done):
+   ```bash
+   pip install sphinx sphinx-rtd-theme
+   mkdir docs && cd docs
+   sphinx-quickstart
+   ```
+   *Update `docs/conf.py` to use `html_theme = 'sphinx_rtd_theme'` and configure the `sys.path` to point to `../src`.*
+3. **Connect to Read the Docs**:
+   - Log in to [readthedocs.org](https://readthedocs.org/).
+   - Click **Import a Project**.
+   - Connect your GitHub repository. RTD will automatically hook into your git pushes and build/host the documentation whenever the `main` branch is updated.

PUBLISH_OUTPUT.md

@@ -0,0 +1,129 @@
+# Publishing & Automating the Generated Client
+
+This document outlines how to publish the **generated API client** (the output of the `cdd sync` command) and how to keep it automatically synchronized with your upstream server's OpenAPI specification.
+
+## 1. Packaging the Generated Client
+
+When `cdd sync` produces a `client.py` and related models, you need to wrap them in a package before distributing. A standard minimal Python package structure looks like this:
+
+```
+my-api-client/
+├── pyproject.toml
+├── README.md
+└── src/
+    └── my_api_client/
+        ├── __init__.py
+        └── client.py      <-- Generated by CDD
+```
+
+### Example `pyproject.toml`
+Create a `pyproject.toml` in your client repository:
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "my-api-client"
+version = "1.0.0"
+description = "Auto-generated OpenAPI client"
+dependencies = [
+    "pydantic>=2.0",
+    "urllib3"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/my_api_client"]
+```
+
+## 2. Publishing the Client to PyPI
+
+To manually publish the generated client to the Python Package Index:
+
+```bash
+cd my-api-client
+pip install build twine
+python -m build
+python -m twine upload dist/*
+```
+
+---
+
+## 3. Automating Updates via GitHub Actions
+
+The power of CDD is ensuring your client SDK is never out of sync with your API server. You can use a GitHub Actions Cron Job to routinely check your upstream OpenAPI server, sync the models, and publish a new version.
+
+### Setup the GitHub Action Workflow
+
+Create a file in your client repository at `.github/workflows/sync-and-publish.yml`:
+
+```yaml
+name: Sync OpenAPI Client
+
+on:
+  schedule:
+    # Run every day at midnight UTC
+    - cron: '0 0 * * *'
+  workflow_dispatch: # Allow manual trigger via GitHub UI
+
+jobs:
+  sync_and_publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Client Repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install cdd-python-client build twine bumpver
+
+      - name: Fetch Latest OpenAPI Spec
+        # Replace the URL with your server's live openapi.json endpoint
+        run: curl -s https://api.my-service.com/openapi.json > openapi.json
+
+      - name: Sync Client Code
+        # This updates the `src/my_api_client` files based on the fetched JSON
+        run: cdd sync --from-openapi openapi.json --to-python src/my_api_client/
+
+      - name: Check for changes
+        id: git-check
+        run: |
+          git diff --exit-code || echo "changes=true" >> $GITHUB_OUTPUT
+
+      - name: Bump Version and Commit
+        if: steps.git-check.outputs.changes == 'true'
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          
+          # Automatically bump the patch version in pyproject.toml
+          bumpver update --patch
+          
+          git add src/my_api_client/ openapi.json pyproject.toml
+          git commit -m "chore(openapi): auto-sync client with upstream spec"
+          git push
+
+      - name: Build and Publish to PyPI
+        if: steps.git-check.outputs.changes == 'true'
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          python -m build
+          twine upload dist/*
+```
+
+### How it Works:
+1. **Cron Schedule**: The action runs daily at midnight (or manually).
+2. **Fetch**: It pulls the absolute latest `openapi.json` from the upstream server.
+3. **CDD Sync**: It runs the `cdd sync` CLI tool to regenerate the client, mock, and test files using the new spec.
+4. **Diff Check**: It uses `git diff` to see if the generated AST code differs from what is currently checked in.
+5. **Bump & Commit**: If the spec changed, it bumps the version in `pyproject.toml` and commits the code.
+6. **Publish**: It builds the new wheel and uploads it to PyPI automatically (requires a `PYPI_API_TOKEN` secret to be set in your GitHub repository settings).