CCM-12896: Initial version of python type generation

Author: gareth-allan

.gitignore

@@ -26,6 +26,18 @@ output
 /schemas
 .env
 
+# Python
+__pycache__/
+.Python
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
 # Coverage reports
 htmlcov/
 .coverage

Makefile

@@ -14,6 +14,7 @@ dependencies: # Install dependencies needed to build and test the project @Pipel
 
 generate: # Generate any autogenerated output @Pipeline
 	npm run generate-dependencies
+	$(MAKE) -C src/pydantic-model-generator generate
 
 build: # Build the project artefact @Pipeline
 	$(MAKE) -C docs build
@@ -32,6 +33,7 @@ clean:: # Clean-up project resources (main) @Operations
 	$(MAKE) -C src/cloudevents clean
 	$(MAKE) -C src/eventcatalogasyncapiimporter clean
 	$(MAKE) -C src/eventcatalogasyncapiimporter clean-output
+	$(MAKE) -C src/pydantic-model-generator clean
 	rm -f .version
 	npm run clean
 

scripts/config/vale/styles/config/vocabularies/words/accept.txt

@@ -69,6 +69,7 @@ Podman
 producedby
 projectRoot
 Protobuf
+Pydantic
 pylint
 Python
 quotingType

src/digital-letters-events-python/.gitignore

@@ -0,0 +1,2 @@
+# Models directory (auto-generated)
+models/

src/digital-letters-events-python/README.md

@@ -0,0 +1,66 @@
+<!-- vale Vale.Terms = NO -->
+<!-- vale Vale.Avoid = NO -->
+# digital-letters-events-python
+<!-- vale Vale.Terms = YES -->
+<!-- vale Vale.Avoid = YES -->
+
+<!-- vale Vale.Terms = NO -->
+This package contains the automatically-generated Pydantic v2 models that the [pydantic-model-generator](../pydantic-model-generator/) tool produces.
+<!-- vale Vale.Terms = YES -->
+
+The source files in this package should not be edited directly. If changes are required, update the schemas in the [schemas/digital-letters/2025-10-draft/events](../../schemas/digital-letters/2025-10-draft/events) directory and use the `pydantic-model-generator` tool to regenerate them.
+
+## Using this Package
+
+### Using Event Models
+
+The Pydantic models can be used by installing the `digital-letters-events-python` package and importing the desired model:
+
+```python
+from digital_letters_events_python import PDMResourceSubmitted
+
+try:
+    # Validate and parse an event
+    event_data = {
+        "type": "uk.nhs.notify.digital.letters.pdm.resource.submitted.v1",
+        "source": "/nhs/england/notify/staging/dev-647563337/data-plane/digitalletters/pdm",
+        "dataschema": "https://notify.nhs.uk/cloudevents/schemas/digital-letters/2025-10-draft/data/digital-letters-pdm-resource-submitted-data.schema.json",
+        "specversion": "1.0",
+        "id": "0249e529-f947-4012-819e-b634eb71be79",
+        "subject": "pdm-resource-123",
+        "time": "2025-12-11T10:00:00Z",
+        "data": {
+            "something": "example value"
+        }
+    }
+
+    # Create and validate the event
+    event = PDMResourceSubmitted(**event_data)
+
+    # Access validated fields
+    print(event.id)
+    print(event.type)
+    print(event.data.something)
+except Exception as e:
+    print(e)
+```
+
+### Type Safety and Validation
+
+All generated models include:
+
+- Type hints for all fields
+- Runtime validation via Pydantic
+- Automatic conversion of types where appropriate
+- Clear error messages for validation failures
+
+## Development
+
+This package is automatically generated. Do not edit the files in the [`models`](./models/) directory directly.
+
+To regenerate the models:
+
+```bash
+cd ../pydantic-model-generator
+make generate
+```

src/digital-letters-events-python/__init__.py

@@ -0,0 +1,13 @@
+"""Digital Letters Events package.
+
+This package contains automatically-generated Pydantic v2 models for NHS Notify
+Digital Letters events. These models are generated from JSON schemas by the
+pydantic-model-generator tool.
+
+DO NOT EDIT: Files in this package are auto-generated. Any manual changes will
+be overwritten when the models are regenerated.
+"""
+
+from .models import *
+
+__all__ = ["models"]

src/digital-letters-events-python/requirements.txt

@@ -0,0 +1 @@
+pydantic>=2.0.0,<3.0.0

src/pydantic-model-generator/Makefile

@@ -0,0 +1,70 @@
+# Variables
+SCHEMA_SRC_DIR := ../../schemas/digital-letters/2025-10-draft/events
+OUTPUT_DIR := ../digital-letters-events-python/models
+SCRIPTS_DIR := scripts
+
+# Python settings
+VENV_DIR := ../../.venv
+VENV_PYTHON := $(VENV_DIR)/bin/python
+VENV_PIP := $(VENV_DIR)/bin/pip
+
+# Default target
+.PHONY: all clean generate install install-dev test coverage help
+
+all: generate
+
+# Install production dependencies (uses repo-level venv)
+install:
+	@echo "Installing production dependencies..."
+	@$(VENV_PIP) install -r requirements.txt
+	@echo "Production dependencies installed!"
+
+# Install development dependencies (uses repo-level venv)
+install-dev:
+	@echo "Installing development dependencies..."
+	@$(VENV_PIP) install -r requirements-dev.txt
+	@echo "Development dependencies installed!"
+
+# Generate Pydantic models from JSON schemas
+generate: install
+	@echo "Generating Pydantic models from JSON schemas..."
+	@mkdir -p $(OUTPUT_DIR)
+	@$(VENV_PYTHON) $(SCRIPTS_DIR)/generate_models.py \
+		--input-dir $(SCHEMA_SRC_DIR) \
+		--output-dir $(OUTPUT_DIR)
+	@echo "Pydantic models generated in $(OUTPUT_DIR)/"
+
+# Run tests
+test: install-dev
+	@echo "Running tests..."
+	@cd ../.. && pytest src/pydantic-model-generator/tests/
+
+# Generate coverage report
+coverage: install-dev
+	@echo "Generating coverage report..."
+	@cd ../.. && pytest src/pydantic-model-generator/tests/ \
+		--cov=src/pydantic-model-generator \
+		--cov-config=src/pydantic-model-generator/pytest.ini \
+		--cov-report=html:src/pydantic-model-generator/htmlcov \
+		--cov-report=term-missing \
+		--cov-report=xml:src/pydantic-model-generator/coverage.xml \
+		--cov-branch
+	@echo "Coverage report generated in htmlcov/"
+
+# Clean output directory and generated files
+clean:
+	@echo "Cleaning generated models..."
+	@rm -rf $(OUTPUT_DIR) htmlcov .pytest_cache coverage.xml
+	@echo "Clean complete!"
+
+# Show help
+help:
+	@echo "Available targets:"
+	@echo "  all          - Generate Pydantic models (default)"
+	@echo "  install      - Install production dependencies"
+	@echo "  install-dev  - Install development dependencies"
+	@echo "  generate     - Generate Pydantic models from JSON schemas"
+	@echo "  test         - Run tests"
+	@echo "  coverage     - Generate coverage report"
+	@echo "  clean        - Clean output directories"
+	@echo "  help         - Show this help message"

src/pydantic-model-generator/README.md

@@ -0,0 +1,108 @@
+<!-- vale Vale.Terms = NO -->
+# pydantic-model-generator
+<!-- vale Vale.Terms = YES -->
+
+This package provides a tool that generates Pydantic v2 models for the events
+that are defined in the JSON schemas that are built as part of this repository.
+The generated Pydantic models can be used to validate and parse NHS Notify
+Digital Letters events.
+
+## Setup
+
+Use `make install-dev` to install the necessary dependencies for this application.
+
+## Generating Models
+
+In order for this tool to function, you must first build the JSON schemas for
+the Digital Letters events. The simplest way to build these schemas is to run
+the `npm run generate-dependencies` command from the root of this repository.
+
+### Using the Generator
+
+Once the JSON schemas have been built, Pydantic models can be generated by running:
+
+```bash
+make generate
+```
+
+This will:
+
+- Read all JSON event schemas from `schemas/digital-letters/2025-10-draft/events/`
+- Generate Pydantic v2 models using `datamodel-code-generator`
+- Output the models to `../digital-letters-events-python/models/`
+
+### Configuration
+
+The generator can be configured through:
+
+- Command-line arguments
+- Environment variables
+- Configuration file (if needed)
+
+### Output Structure
+
+<!-- vale Vale.Terms = NO -->
+<!-- vale Vale.Avoid = NO -->
+Generated models are placed in the
+[digital-letters-events-python](../digital-letters-events-python/) package:
+<!-- vale Vale.Terms = YES -->
+<!-- vale Vale.Avoid = YES -->
+
+- `../digital-letters-events-python/models/` - Individual Pydantic model files
+- `../digital-letters-events-python/models/__init__.py` - Combined index for easy imports
+
+## Testing
+
+Run tests using:
+
+```bash
+make test
+```
+
+For coverage reporting:
+
+```bash
+make coverage
+```
+
+## Development
+
+### Prerequisites
+
+- Python 3.11+
+- pip or poetry for dependency management
+
+### Installing Development Dependencies
+
+```bash
+make install-dev
+```
+
+### Running Tests
+
+```bash
+make test
+```
+
+## Usage
+
+Once generated, the models can be used in your code as follows:
+
+```python
+from digital_letters_event_python import PrintLetterAvailable, CloudEventEnvelope
+
+# Validate incoming event
+event_data = CloudEventEnvelope(**raw_event)
+if event_data.type == "uk.nhs.notify.digital.letters.letter.available.v1":
+    letter_available = PrintLetterAvailable(**raw_event)
+    # Process the validated event
+```
+
+## Architecture
+
+The generator consists of:
+
+- `scripts/generate_models.py` - Main CLI script
+- `scripts/schema_processor.py` - Schema loading and processing
+- `scripts/model_generator.py` - Pydantic model generation logic
+- `scripts/file_utils.py` - File system utilities

src/pydantic-model-generator/pytest.ini

@@ -0,0 +1,21 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+addopts =
+    -v
+    --tb=short
+
+[coverage:run]
+relative_files = True
+omit =
+    */tests/*
+    */test_*.py
+    test_*.py
+    */venv/*
+    */.venv/*
+    */__pycache__/*
+
+[coverage:xml]
+output = coverage.xml