schemawatch-core 0.1.0__tar.gz

schemawatch_core-0.1.0/.gitignore

@@ -0,0 +1,62 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Testing & Coverage
+.coverage
+.coverage.*
+coverage/
+htmlcov/
+.pytest_cache/
+.hypothesis/
+
+# Type checking & Linters
+.mypy_cache/
+.ruff_cache/
+
+# Environment & Secrets
+.env*
+!.env.example
+
+# Databases & Runtime state
+*.db
+*.sqlite
+*.sqlite3
+
+# Frontend & Dependencies
+node_modules/
+dist/
+
+# OS / IDE
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+.vscode/
+.idea/
+

schemawatch_core-0.1.0/LICENSE

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

schemawatch_core-0.1.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.5
+Name: schemawatch-core
+Version: 0.1.0
+Summary: Pure Python engine for schema inference, diffing, PII redaction, drift severity classification, and sampling watchdog
+Project-URL: Homepage, https://github.com/Mohd-obaidullah/schemawatch
+Project-URL: Source, https://github.com/Mohd-obaidullah/schemawatch
+Project-URL: Issues, https://github.com/Mohd-obaidullah/schemawatch/issues
+Project-URL: Changelog, https://github.com/Mohd-obaidullah/schemawatch/blob/main/CHANGELOG.md
+Author: Mohd Obaidullah
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,contract-testing,drift,monitoring,schema
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.27.0; extra == 'httpx'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# schemawatch core
+
+Pure Python engine for schema inference, diffing, PII redaction, drift severity classification, and sampling watchdog.
+
+## Installation
+
+```bash
+pip install schemawatch
+```
+
+Optional extras:
+```bash
+pip install "schemawatch[redis]"  # Redis-backed baseline and dedupe store
+pip install "schemawatch[httpx]"  # httpx integration hook
+```

schemawatch_core-0.1.0/README.md

@@ -0,0 +1,15 @@
+# schemawatch core
+
+Pure Python engine for schema inference, diffing, PII redaction, drift severity classification, and sampling watchdog.
+
+## Installation
+
+```bash
+pip install schemawatch
+```
+
+Optional extras:
+```bash
+pip install "schemawatch[redis]"  # Redis-backed baseline and dedupe store
+pip install "schemawatch[httpx]"  # httpx integration hook
+```

schemawatch_core-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "schemawatch-core"
+version = "0.1.0"
+description = "Pure Python engine for schema inference, diffing, PII redaction, drift severity classification, and sampling watchdog"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mohd Obaidullah" }]
+keywords = ["api", "schema", "drift", "contract-testing", "monitoring"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Mohd-obaidullah/schemawatch"
+Source = "https://github.com/Mohd-obaidullah/schemawatch"
+Issues = "https://github.com/Mohd-obaidullah/schemawatch/issues"
+Changelog = "https://github.com/Mohd-obaidullah/schemawatch/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+redis = ["redis>=5.0.0"]
+httpx = ["httpx>=0.27.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["schemawatch"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true

schemawatch_core-0.1.0/schemawatch/__init__.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from schemawatch.diff import Change, DriftEvent, diff
+from schemawatch.infer import SchemaNode, infer_schema, merge
+from schemawatch.redact import DYNAMIC_KEY_WILDCARD, DynamicKeyWildcard, redact
+from schemawatch.severity import (
+    KIND_BECAME_NULLABLE,
+    KIND_ENUM_CHANGED,
+    KIND_FIELD_ADDED,
+    KIND_FIELD_MISSING,
+    KIND_TYPE_CHANGED,
+    SEVERITY_BREAKING,
+    SEVERITY_INFO,
+    SEVERITY_WARNING,
+    calculate_severity,
+)
+from schemawatch.store import MemoryStore, RedisStore, Store
+from schemawatch.watchdog import Watchdog
+
+if TYPE_CHECKING:
+    from schemawatch.alerts import SlackAlert, WebhookAlert, fan_out
+    from schemawatch.integrations.httpx_hook import SchemawatchHTTPXHook, create_httpx_hook
+
+__all__ = [
+    "Change",
+    "DYNAMIC_KEY_WILDCARD",
+    "DriftEvent",
+    "DynamicKeyWildcard",
+    "KIND_BECAME_NULLABLE",
+    "KIND_ENUM_CHANGED",
+    "KIND_FIELD_ADDED",
+    "KIND_FIELD_MISSING",
+    "KIND_TYPE_CHANGED",
+    "MemoryStore",
+    "RedisStore",
+    "SEVERITY_BREAKING",
+    "SEVERITY_INFO",
+    "SEVERITY_WARNING",
+    "SchemaNode",
+    "SchemawatchHTTPXHook",
+    "SlackAlert",
+    "Store",
+    "Watchdog",
+    "WebhookAlert",
+    "calculate_severity",
+    "create_httpx_hook",
+    "diff",
+    "fan_out",
+    "infer_schema",
+    "merge",
+    "redact",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy module exports so 'import schemawatch' works without httpx installed."""
+    if name in ("SlackAlert", "WebhookAlert", "fan_out"):
+        import schemawatch.alerts as alerts
+
+        return getattr(alerts, name)
+    if name in ("SchemawatchHTTPXHook", "create_httpx_hook"):
+        import schemawatch.integrations.httpx_hook as httpx_hook
+
+        return getattr(httpx_hook, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(list(globals().keys()) + __all__)

schemawatch_core-0.1.0/schemawatch/alerts/__init__.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+from schemawatch.alerts.slack import SlackAlert
+from schemawatch.alerts.webhook import WebhookAlert
+from schemawatch.diff import Change, DriftEvent
+
+logger = logging.getLogger(__name__)
+
+
+def fan_out(
+    *dispatchers: Callable[[DriftEvent], None],
+) -> Callable[[DriftEvent | Change], None]:
+    """Combine multiple alert dispatchers into a single fail-open callback.
+
+    Dispatches sequentially to each handler. If one handler raises an exception,
+    the exception is logged and swallowed so subsequent handlers still execute.
+    """
+
+    def _composite(event: DriftEvent | Change) -> None:
+        drift_event = (
+            event
+            if isinstance(event, DriftEvent)
+            else DriftEvent(vendor="unknown", endpoint="unknown", changes=(event,))
+        )
+        for dispatcher in dispatchers:
+            try:
+                dispatcher(drift_event)
+            except Exception as exc:
+                logger.exception("schemawatch fan_out: dispatcher failed: %s", exc)
+
+    return _composite
+
+
+__all__ = [
+    "SlackAlert",
+    "WebhookAlert",
+    "fan_out",
+]

schemawatch_core-0.1.0/schemawatch/alerts/retry.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import logging
+import urllib.error
+from typing import Final
+
+logger = logging.getLogger(__name__)
+
+RETRYABLE_STATUS_CODES: Final[frozenset[int]] = frozenset({408, 425, 429})
+MAX_RETRY_AFTER_SECONDS: Final[float] = 30.0
+
+
+def should_retry_error(exc: Exception) -> tuple[bool, float | None]:
+    """Determine whether an HTTP/network exception should be retried.
+
+    Rules:
+    - Network errors (URLError, OSError, TimeoutError) are retried.
+    - HTTP status codes 408, 425, 429, and 5xx are retried.
+    - Other 4xx status codes (400, 401, 403, 404, etc.) are NOT retried.
+    - If a Retry-After header is present on a retryable HTTP response, its value
+      is honoured as seconds and capped at 30 seconds.
+
+    Returns:
+        (should_retry, retry_after_delay_in_seconds)
+    """
+    if isinstance(exc, urllib.error.HTTPError):
+        code = exc.code
+        if code in RETRYABLE_STATUS_CODES or code >= 500:
+            retry_after: float | None = None
+            if exc.headers:
+                raw_ra = exc.headers.get("Retry-After")
+                if raw_ra:
+                    try:
+                        retry_after = min(max(0.0, float(raw_ra)), MAX_RETRY_AFTER_SECONDS)
+                    except ValueError:
+                        retry_after = None
+            return True, retry_after
+        # Other 4xx are client errors and should NOT be retried
+        if 400 <= code < 500:
+            return False, None
+        return False, None
+
+    if isinstance(exc, (urllib.error.URLError, OSError, TimeoutError)):
+        return True, None
+
+    return False, None

schemawatch_core-0.1.0/schemawatch/alerts/slack.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import json
+import logging
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from typing import Any
+
+from schemawatch.alerts.retry import should_retry_error
+from schemawatch.diff import Change, DriftEvent
+from schemawatch.severity import SEVERITY_BREAKING, SEVERITY_INFO, SEVERITY_WARNING
+
+logger = logging.getLogger(__name__)
+
+SLACK_COLOR_MAP: dict[str, str] = {
+    SEVERITY_BREAKING: "#E01E5A",  # Red / Danger
+    SEVERITY_WARNING: "#ECB22E",  # Yellow / Warning
+    SEVERITY_INFO: "#2F80ED",  # Blue / Info
+}
+SLACK_COLOR_DEFAULT = "#2F80ED"  # Blue / Info
+
+
+class SlackAlert:
+    """Fail-open Slack incoming webhook dispatcher with rich formatting.
+
+    Maps schema drift changes to colored Slack attachments.
+    Never raises exceptions into host application and never logs raw webhook URLs.
+    """
+
+    def __init__(
+        self,
+        webhook_url: str,
+        *,
+        channel: str | None = None,
+        timeout: float = 5.0,
+        max_retries: int = 2,
+        backoff_seconds: float = 0.5,
+        sleep_fn: Callable[[float], None] = time.sleep,
+    ) -> None:
+        parsed = urllib.parse.urlparse(webhook_url)
+        if parsed.scheme not in ("http", "https"):
+            raise ValueError(
+                f"Invalid alert webhook URL scheme: {parsed.scheme!r}. Must be http or https."
+            )
+        self._url = webhook_url
+        self._channel = channel
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._backoff = backoff_seconds
+        self._sleep_fn = sleep_fn
+        self.last_status_code: int | None = None
+        self.last_response_body: str | None = None
+        self.last_attempts: int = 0
+
+    def __repr__(self) -> str:
+        return f"SlackAlert(webhook_url='***redacted***', channel={self._channel!r})"
+
+    def __call__(self, event: DriftEvent | Change) -> None:
+        """Dispatch drift event alert to Slack."""
+        self.send(event)
+
+    def _build_payload(self, event: DriftEvent) -> dict[str, Any]:
+        header_text = f":warning: API Contract Drift Detected: *{event.vendor}* `{event.endpoint}`"
+
+        # Group changes by severity in priority order
+        severity_order = [SEVERITY_BREAKING, SEVERITY_WARNING, SEVERITY_INFO]
+        changes_by_sev: dict[str, list[Change]] = {sev: [] for sev in severity_order}
+
+        for ch in event.changes:
+            if ch.severity in changes_by_sev:
+                changes_by_sev[ch.severity].append(ch)
+            else:
+                changes_by_sev[SEVERITY_INFO].append(ch)
+
+        attachments: list[dict[str, Any]] = []
+        for sev in severity_order:
+            sev_changes = changes_by_sev[sev]
+            if not sev_changes:
+                continue
+
+            color = SLACK_COLOR_MAP.get(sev, SLACK_COLOR_DEFAULT)
+            fields: list[dict[str, Any]] = []
+            for ch in sev_changes:
+                desc = ch.detail or (f"`{ch.was}` -> `{ch.now}`" if ch.was or ch.now else ch.kind)
+                fields.append(
+                    {
+                        "title": f"`{ch.field}`",
+                        "value": f"*{ch.kind}*: {desc}",
+                        "short": len(ch.field) <= 24,
+                    }
+                )
+
+            count_str = f" ({len(sev_changes)})" if len(sev_changes) > 1 else ""
+            attachments.append(
+                {
+                    "color": color,
+                    "title": f"[{sev.upper()}]{count_str}",
+                    "fields": fields,
+                    "ts": int(event.detected_at),
+                }
+            )
+
+        payload: dict[str, Any] = {
+            "text": header_text,
+            "attachments": attachments,
+        }
+        if self._channel:
+            payload["channel"] = self._channel
+        return payload
+
+    def send(self, event: DriftEvent | Change) -> bool:
+        """Send formatted Slack message with retries.
+
+        Returns True if successful, False otherwise. Never raises exceptions.
+        """
+        # Normalize Change to DriftEvent if passed directly
+        if isinstance(event, Change):
+            drift_event = DriftEvent(
+                vendor="unknown",
+                endpoint="unknown",
+                changes=(event,),
+            )
+        else:
+            drift_event = event
+
+        payload = self._build_payload(drift_event)
+        data = json.dumps(payload).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "schemawatch-slack-alert/0.1.0",
+        }
+
+        self.last_status_code = None
+        self.last_response_body = None
+        self.last_attempts = 0
+
+        for attempt in range(1, self._max_retries + 2):
+            self.last_attempts = attempt
+            try:
+                req = urllib.request.Request(
+                    self._url,
+                    data=data,
+                    headers=headers,
+                    method="POST",
+                )
+                with urllib.request.urlopen(req, timeout=self._timeout) as resp:  # nosec B310
+                    self.last_status_code = resp.status
+                    self.last_response_body = resp.read().decode("utf-8", errors="replace")
+                    if 200 <= resp.status < 300:
+                        return True
+            except urllib.error.HTTPError as http_exc:
+                self.last_status_code = http_exc.code
+                try:
+                    self.last_response_body = http_exc.read().decode("utf-8", errors="replace")
+                except Exception:
+                    self.last_response_body = None
+                should_retry, retry_after = should_retry_error(http_exc)
+                logger.warning(
+                    "schemawatch: slack alert delivery failed (attempt %d/%d): HTTP %d",
+                    attempt,
+                    self._max_retries + 1,
+                    http_exc.code,
+                )
+                if not should_retry:
+                    return False
+
+                if attempt <= self._max_retries:
+                    delay = (
+                        retry_after
+                        if retry_after is not None
+                        else self._backoff * (2 ** (attempt - 1))
+                    )
+                    self._sleep_fn(delay)
+            except Exception as exc:
+                should_retry, retry_after = should_retry_error(exc)
+                # Privacy rule: NEVER log the webhook URL
+                logger.warning(
+                    "schemawatch: slack alert delivery failed (attempt %d/%d): %s",
+                    attempt,
+                    self._max_retries + 1,
+                    type(exc).__name__,
+                )
+                if not should_retry:
+                    return False
+
+                if attempt <= self._max_retries:
+                    delay = (
+                        retry_after
+                        if retry_after is not None
+                        else self._backoff * (2 ** (attempt - 1))
+                    )
+                    self._sleep_fn(delay)
+
+        logger.error(
+            "schemawatch: slack alert delivery exhausted all retries for %s %s",
+            drift_event.vendor,
+            drift_event.endpoint,
+        )
+        return False