rdce 0.1.0__tar.gz

rdce-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valerio 
+
+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.

rdce-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: rdce
+Version: 0.1.0
+Summary: Runtime Data Contract Enforcer
+License: MIT
+License-File: LICENSE
+Author: Valerio DAlessio
+Author-email: valdal14@gmail.com
+Requires-Python: >=3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Description-Content-Type: text/markdown
+
+# rdce
+
+[![CI Pipeline](https://github.com/valdal14/rdce/actions/workflows/ci.yml/badge.svg)](https://github.com/valdal14/rdce/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/Python-3.10%2B-blue?style=flat&logo=python)
+![License](https://img.shields.io/badge/License-MIT-green)
+
+**Runtime Data Contract Enforcer**: A lightweight Python 3 library for recursively validating and diffing nested JSON payloads against explicit Pydantic schemas.
+
+## Current Status
+🚀 **v0.1.0 Complete** 🚀
+The core recursive validation engine, Pydantic extractor, and public API are complete and fully tested with 100% coverage.
+
+## 🌟 Features
+* **Pydantic Native:** Define your data contracts using standard Pydantic `BaseModel` classes.
+* **Recursive Type Validation:** Deeply inspects nested dictionaries and payloads without flattening them.
+* **Path Tracking:** Returns exact dot-notation breadcrumbs for schema drift (e.g., `user.address.zip_code`).
+* **Zero Bloat:** Built to do one thing perfectly—diffing data schemas.
+
+---
+
+## 📦 Installation
+
+*(Note: Pending PyPI release)*
+```bash
+pip install rdce
+# Or using poetry
+poetry add rdce
+```
+
+---
+
+## 🚀 Quick Start
+`rdce` is designed to be a transparent bridge between your Pydantic models and incoming, untrusted dictionary payloads.
+
+### 1. Define your Contract
+Use standard Pydantic models. Nested models are fully supported.
+
+```python
+from pydantic import BaseModel
+
+class Address(BaseModel):
+    city: str
+    zip_code: int
+
+class UserContract(BaseModel):
+    username: str
+    is_active: bool
+    address: Address
+```
+
+### 2. Enforce the Payload
+Pass the model class and your raw dictionary payload into the `enforce_contract` engine.
+
+```python
+from rdce import enforce_contract
+
+# A payload with schema drift (wrong type for zip_code, missing is_active)
+incoming_payload = {
+    "username": "alice_data",
+    "address": {
+        "city": "London",
+        "zip_code": "E1 6AN" # Expected int, got string
+    }
+}
+
+errors = enforce_contract(UserContract, incoming_payload)
+
+for error in errors:
+    print(error)
+```
+
+Output:
+
+```json
+[
+  {"path": "is_active", "expected": "bool", "actual": "MISSING"},
+  {"path": "address.zip_code", "expected": "int", "actual": "str"}
+]
+```
+
+## 🤝 Contributing
+We welcome contributions! To set up the project locally:
+
+```bash
+1 Clone the repository.
+2 Initialize the environment: poetry install
+3 We strictly enforce formatting and linting via Ruff:
+4 Linter: 
+    poetry run python3 -m ruff check .
+5 Formatter: 
+    poetry run python3 -m ruff format .
+6 Run the test suite: 
+    poetry run pytest
+7 Ensure 100% test coverage before submitting a Pull Request.
+```
+
+

rdce-0.1.0/README.md

@@ -0,0 +1,96 @@
+# rdce
+
+[![CI Pipeline](https://github.com/valdal14/rdce/actions/workflows/ci.yml/badge.svg)](https://github.com/valdal14/rdce/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/Python-3.10%2B-blue?style=flat&logo=python)
+![License](https://img.shields.io/badge/License-MIT-green)
+
+**Runtime Data Contract Enforcer**: A lightweight Python 3 library for recursively validating and diffing nested JSON payloads against explicit Pydantic schemas.
+
+## Current Status
+🚀 **v0.1.0 Complete** 🚀
+The core recursive validation engine, Pydantic extractor, and public API are complete and fully tested with 100% coverage.
+
+## 🌟 Features
+* **Pydantic Native:** Define your data contracts using standard Pydantic `BaseModel` classes.
+* **Recursive Type Validation:** Deeply inspects nested dictionaries and payloads without flattening them.
+* **Path Tracking:** Returns exact dot-notation breadcrumbs for schema drift (e.g., `user.address.zip_code`).
+* **Zero Bloat:** Built to do one thing perfectly—diffing data schemas.
+
+---
+
+## 📦 Installation
+
+*(Note: Pending PyPI release)*
+```bash
+pip install rdce
+# Or using poetry
+poetry add rdce
+```
+
+---
+
+## 🚀 Quick Start
+`rdce` is designed to be a transparent bridge between your Pydantic models and incoming, untrusted dictionary payloads.
+
+### 1. Define your Contract
+Use standard Pydantic models. Nested models are fully supported.
+
+```python
+from pydantic import BaseModel
+
+class Address(BaseModel):
+    city: str
+    zip_code: int
+
+class UserContract(BaseModel):
+    username: str
+    is_active: bool
+    address: Address
+```
+
+### 2. Enforce the Payload
+Pass the model class and your raw dictionary payload into the `enforce_contract` engine.
+
+```python
+from rdce import enforce_contract
+
+# A payload with schema drift (wrong type for zip_code, missing is_active)
+incoming_payload = {
+    "username": "alice_data",
+    "address": {
+        "city": "London",
+        "zip_code": "E1 6AN" # Expected int, got string
+    }
+}
+
+errors = enforce_contract(UserContract, incoming_payload)
+
+for error in errors:
+    print(error)
+```
+
+Output:
+
+```json
+[
+  {"path": "is_active", "expected": "bool", "actual": "MISSING"},
+  {"path": "address.zip_code", "expected": "int", "actual": "str"}
+]
+```
+
+## 🤝 Contributing
+We welcome contributions! To set up the project locally:
+
+```bash
+1 Clone the repository.
+2 Initialize the environment: poetry install
+3 We strictly enforce formatting and linting via Ruff:
+4 Linter: 
+    poetry run python3 -m ruff check .
+5 Formatter: 
+    poetry run python3 -m ruff format .
+6 Run the test suite: 
+    poetry run pytest
+7 Ensure 100% test coverage before submitting a Pull Request.
+```
+

rdce-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "rdce"
+version = "0.1.0"
+description = "Runtime Data Contract Enforcer"
+authors = [
+    {name = "Valerio DAlessio",email = "valdal14@gmail.com"}
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic (>=2.12.5,<3.0.0)"
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "ruff (>=0.15.7,<0.16.0)",
+    "pytest (>=9.0.2,<10.0.0)",
+    "pytest-asyncio (>=1.3.0,<2.0.0)",
+    "pytest-cov (>=7.1.0,<8.0.0)"
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E501"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

rdce-0.1.0/rdce/__init__.py

@@ -0,0 +1,3 @@
+from .enforcer import enforce_contract
+
+__all__ = ["enforce_contract"]

rdce-0.1.0/rdce/enforcer.py

@@ -0,0 +1,11 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+from .engine import compare_payload
+from .extractor import extract_schema
+
+
+def enforce_contract(contract: type[BaseModel], payload: dict[str, Any]) -> list[dict[str, str]]:
+    schema = extract_schema(contract)
+    return compare_payload(schema, payload)

rdce-0.1.0/rdce/engine.py

@@ -0,0 +1,61 @@
+from typing import Any
+
+
+def compare_payload(
+    schema: dict[str, Any], payload: dict[str, Any], current_path: str = ""
+) -> list[dict[str, str]]:
+    """
+    Recursively compares a payload dictionary against an expected schema dictionary.
+
+    Args:
+        schema (dict[str, Any]): The expected data contract defining fields and types.
+        payload (dict[str, Any]): The actual incoming data payload.
+        current_path (str, optional): The current path traversal state. Defaults to "".
+
+    Returns:
+        list[dict[str, str]]: A list of validation errors. Returns an empty list if perfectly matched.
+    """
+    errors = []
+
+    for key, expected_type in schema.items():
+        if current_path == "":
+            path = key
+        else:
+            path = f"{current_path}.{key}"
+
+        if key not in payload:
+            # Log the missing key error
+            errors.append(_build_error(path, str(expected_type), "MISSING"))
+            # skip to the next key in the schema
+            continue
+
+        actual_value = payload[key]
+
+        # Check if this is a branch (The schema expects a dictionary)
+        if isinstance(expected_type, dict):
+            res = compare_payload(expected_type, actual_value, path)
+            errors.extend(res)
+        else:
+            # Get the actual type of the payload's value as a string
+            actual_type_string = type(actual_value).__name__
+
+            # Compare it to what the schema asked for
+            if actual_type_string != expected_type:
+                errors.append(_build_error(path, expected_type, actual_type_string))
+
+    return errors
+
+
+def _build_error(path: str, expected_type: str, actual: str) -> dict[str, str]:
+    """
+    Constructs a standardized validation error dictionary.
+
+    Args:
+        path (str): The dot-notation breadcrumb path of the failing field.
+        expected_type (str): The Python type expected by the schema.
+        actual (str): The actual type received, or "MISSING" if not found.
+
+    Returns:
+        dict[str, str]: The formatted error payload.
+    """
+    return {"path": path, "expected": expected_type, "actual": actual}

rdce-0.1.0/rdce/extractor.py

@@ -0,0 +1,27 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def extract_schema(model: type[BaseModel]) -> dict[str, Any]:
+    """
+    Translates a Pydantic model into a raw schema dictionary.
+
+    Args:
+        model (type[BaseModel]): The Pydantic class to inspect.
+
+    Returns:
+        dict[str, Any]: A nested dictionary representing the expected types.
+    """
+    schema = {}
+
+    for field_name, field_info in model.model_fields.items():
+        field_type = field_info.annotation
+
+        # Check if it is another Pydantic model
+        if isinstance(field_type, type) and issubclass(field_type, BaseModel):
+            schema[field_name] = extract_schema(field_type)
+        else:
+            schema[field_name] = field_type.__name__
+
+    return schema