odsbox-diff 1.0.0__py3-none-any.whl

odsbox_diff/__init__.py

@@ -0,0 +1,32 @@
+"""odsbox-diff: compare two ASAM ODS hierarchy instances."""
+
+__version__ = "1.0.0"
+
+from .api import (
+    collect_to_file,
+    diff_file_to_file,
+    diff_file_to_server,
+    diff_server_to_server,
+)
+from .diff import collect_ods_test, diff_ods_tests
+from .ods_diff_hierarchy import (
+    collect,
+    diff_dictionaries,
+    dump_diff_as_json,
+    load_collect_results,
+    save_collect_results,
+)
+
+__all__ = [
+    "collect_ods_test",
+    "collect_to_file",
+    "diff_file_to_file",
+    "diff_file_to_server",
+    "diff_ods_tests",
+    "diff_server_to_server",
+    "collect",
+    "diff_dictionaries",
+    "dump_diff_as_json",
+    "load_collect_results",
+    "save_collect_results",
+]

odsbox_diff/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running the package with ``python -m odsbox_diff``."""
+
+from .diff import cli
+
+cli()

odsbox_diff/api.py

@@ -0,0 +1,245 @@
+"""High-level API for programmatic use in test frameworks and scripts.
+
+All functions return :class:`~deepdiff.DeepDiff` objects (falsy when no
+differences are found) and raise exceptions on errors — no ``sys.exit()``
+calls.  This makes them suitable for direct use in ``assert`` statements::
+
+    from odsbox_diff import diff_file_to_file
+    assert not diff_file_to_file("baseline.json", "current.json")
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from deepdiff import DeepDiff
+
+from .connection import AppConfig, ServerConfig, create_connection, load_config
+from .ods_diff_hierarchy.collect import collect, load_collect_results, save_collect_results
+from .ods_diff_hierarchy.diff import diff_dictionaries
+
+_log = logging.getLogger(__name__)
+
+
+def _resolve_config(config: str | Path | AppConfig) -> AppConfig:
+    """Return an :class:`AppConfig`, loading from disk when needed."""
+    if isinstance(config, AppConfig):
+        return config
+    return load_config(str(config))
+
+
+def _resolve_server_and_id(
+    config: AppConfig,
+    inst_id: int | str,
+) -> tuple[ServerConfig, int | str | dict[str, Any]]:
+    """Resolve a server config and instance condition from *inst_id*.
+
+    *inst_id* may be a plain ``int``, a string integer (``"42"``),
+    a JSON condition string, a named query, or ``"server:42"`` for
+    multi-server configs.
+    """
+    from .diff import _parse_server_id
+
+    servers = config.servers
+    multi_server = len(servers) > 1
+    return _parse_server_id(str(inst_id), servers, config.queries, multi_server)
+
+
+def _collect_from_server(
+    server_cfg: ServerConfig,
+    entity_name: str,
+    inst_id: int | str | dict[str, Any],
+    *,
+    no_bulk: bool = False,
+    bulk_progress_bar: bool = False,
+    cached_related: list[str] | None = None,
+) -> dict[Any, Any]:
+    """Connect to an ODS server and collect a hierarchy."""
+    log = _log
+    log.info("Connecting to %s", server_cfg.url)
+    with create_connection(server_cfg) as con_i:
+        result, _ = collect(
+            con_i,
+            entity_name,
+            inst_id,
+            calculate_bulk_hash=not no_bulk,
+            show_progress=bulk_progress_bar,
+            cached_related_entities=cached_related,
+        )
+    log.info("Connection closed")
+    return result
+
+
+# ── Public API ───────────────────────────────────────────────────────────
+
+
+def diff_file_to_file(
+    file1: str | Path,
+    file2: str | Path,
+    *,
+    exclude_regex_paths: list[str] | None = None,
+    exclude_paths: list[str] | None = None,
+) -> DeepDiff:
+    """Compare two previously saved hierarchy files.
+
+    No server connection or config file is required.
+
+    Args:
+        file1: Path to the first hierarchy JSON or ZIP file.
+        file2: Path to the second hierarchy JSON or ZIP file.
+        exclude_regex_paths: Extra regex exclusions appended to the defaults.
+        exclude_paths: Extra explicit path exclusions.
+
+    Returns:
+        A :class:`~deepdiff.DeepDiff` object.  Falsy when no differences exist.
+    """
+    d1 = load_collect_results(str(file1))
+    d2 = load_collect_results(str(file2))
+    return diff_dictionaries(
+        d1,
+        d2,
+        exclude_regex_paths or [],
+        exclude_paths or [],
+    )
+
+
+def diff_server_to_server(
+    config: str | Path | AppConfig,
+    entity_name: str,
+    inst1_id: int | str,
+    inst2_id: int | str,
+    *,
+    exclude_regex_paths: list[str] | None = None,
+    exclude_paths: list[str] | None = None,
+    no_bulk: bool = False,
+    cached_related: list[str] | None = None,
+) -> DeepDiff:
+    """Collect two hierarchies from ODS server(s) and diff them.
+
+    Args:
+        config: Path to a TOML/JSON config file **or** an :class:`AppConfig`
+            built in code.
+        entity_name: ODS entity name (e.g. ``"TestStep"``).
+        inst1_id: Instance ID or ``"server:id"`` string for the first side.
+        inst2_id: Instance ID or ``"server:id"`` string for the second side.
+        exclude_regex_paths: Extra regex exclusions appended to the defaults.
+        exclude_paths: Extra explicit path exclusions.
+        no_bulk: Skip hashing of bulk LocalColumn data.
+        cached_related: Entity names whose IDs are resolved to names.
+
+    Returns:
+        A :class:`~deepdiff.DeepDiff` object.  Falsy when no differences exist.
+    """
+    app = _resolve_config(config)
+    cfg1, id1 = _resolve_server_and_id(app, inst1_id)
+    cfg2, id2 = _resolve_server_and_id(app, inst2_id)
+
+    d1 = _collect_from_server(cfg1, entity_name, id1, no_bulk=no_bulk, cached_related=cached_related)
+    d2 = _collect_from_server(cfg2, entity_name, id2, no_bulk=no_bulk, cached_related=cached_related)
+
+    return diff_dictionaries(
+        d1,
+        d2,
+        exclude_regex_paths or [],
+        exclude_paths or [],
+    )
+
+
+def diff_file_to_server(
+    config: str | Path | AppConfig,
+    entity_name: str,
+    server_id: int | str,
+    baseline_file: str | Path,
+    *,
+    exclude_regex_paths: list[str] | None = None,
+    exclude_paths: list[str] | None = None,
+    no_bulk: bool = False,
+    cached_related: list[str] | None = None,
+) -> DeepDiff:
+    """Compare a saved baseline file against a live server hierarchy.
+
+    Typical use case: regression testing — verify that a server instance still
+    matches a known-good baseline.
+
+    Args:
+        config: Path to a TOML/JSON config file **or** an :class:`AppConfig`.
+        entity_name: ODS entity name (e.g. ``"TestStep"``).
+        server_id: Instance ID or ``"server:id"`` for the live side.
+        baseline_file: Path to the baseline hierarchy JSON or ZIP file.
+        exclude_regex_paths: Extra regex exclusions appended to the defaults.
+        exclude_paths: Extra explicit path exclusions.
+        no_bulk: Skip hashing of bulk LocalColumn data.
+        cached_related: Entity names whose IDs are resolved to names.
+
+    Returns:
+        A :class:`~deepdiff.DeepDiff` object.  Falsy when no differences exist.
+    """
+    app = _resolve_config(config)
+    cfg, iid = _resolve_server_and_id(app, server_id)
+
+    baseline = load_collect_results(str(baseline_file))
+    live = _collect_from_server(cfg, entity_name, iid, no_bulk=no_bulk, cached_related=cached_related)
+
+    return diff_dictionaries(
+        baseline,
+        live,
+        exclude_regex_paths or [],
+        exclude_paths or [],
+    )
+
+
+def collect_to_file(
+    config: str | Path | AppConfig,
+    entity_name: str,
+    inst_id: int | str,
+    output_file: str | Path,
+    *,
+    no_bulk: bool = False,
+    bulk_progress_bar: bool = False,
+    cached_related: list[str] | None = None,
+    validate: bool = False,
+) -> DeepDiff | None:
+    """Collect an ODS hierarchy and save it to a JSON or ZIP file.
+
+    When *validate* is ``True`` the file is reloaded immediately and compared
+    against the in-memory data to verify round-trip fidelity.
+
+    Args:
+        config: Path to a TOML/JSON config file **or** an :class:`AppConfig`.
+        entity_name: ODS entity name (e.g. ``"TestStep"``).
+        inst_id: Instance ID or ``"server:id"`` string.
+        output_file: Destination path (``.json`` or ``.zip``).
+        no_bulk: Skip hashing of bulk LocalColumn data.
+        bulk_progress_bar: Show a progress bar during bulk hashing.
+        cached_related: Entity names whose IDs are resolved to names.
+        validate: Perform a round-trip self-diff after saving.
+
+    Returns:
+        ``None`` when *validate* is ``False``.
+        A :class:`~deepdiff.DeepDiff` object when *validate* is ``True``
+        (falsy if round-trip is clean).
+    """
+    app = _resolve_config(config)
+    cfg, iid = _resolve_server_and_id(app, inst_id)
+
+    result = _collect_from_server(
+        cfg,
+        entity_name,
+        iid,
+        no_bulk=no_bulk,
+        bulk_progress_bar=bulk_progress_bar,
+        cached_related=cached_related,
+    )
+
+    out = str(output_file)
+    save_collect_results(out, result)
+    _log.info("Saved collected hierarchy to: %s", out)
+
+    if not validate:
+        return None
+
+    _log.info("Validating round-trip fidelity ...")
+    reloaded = load_collect_results(out)
+    return diff_dictionaries(reloaded, result, [], [])

odsbox_diff/connection/__init__.py

@@ -0,0 +1,14 @@
+"""Connection subsystem: config models, config loading, and connection factory."""
+
+from .config import AppConfig, AuthMethod, DiffDefaults, ServerConfig
+from .factory import create_connection
+from .manager import load_config
+
+__all__ = [
+    "AppConfig",
+    "AuthMethod",
+    "DiffDefaults",
+    "ServerConfig",
+    "create_connection",
+    "load_config",
+]

odsbox_diff/connection/config.py

@@ -0,0 +1,96 @@
+"""Configuration models for ODS server connections."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class AuthMethod(Enum):
+    BASIC = "basic"
+    M2M = "m2m"
+    OIDC = "oidc"
+
+
+@dataclass
+class ServerConfig:
+    """Connection and authentication settings for a single ODS server."""
+
+    url: str
+    auth_method: AuthMethod = AuthMethod.BASIC
+    verify_certificate: bool = True
+
+    # basic auth
+    username: str | None = None
+    password: str | None = None
+
+    # m2m / oidc shared
+    client_id: str | None = None
+    client_secret: str | None = None
+    token_endpoint: str | None = None
+    scope: list[str] | None = None
+
+    # oidc specific
+    redirect_uri: str | None = None
+    redirect_url_allow_insecure: bool = False
+    authorization_endpoint: str | None = None
+    login_timeout: int = 60
+    webfinger_path_prefix: str = ""
+
+    def validate(self) -> None:
+        """Raise ValueError if required fields for the chosen auth method are missing."""
+        if not self.url:
+            raise ValueError("Server URL is required.")
+
+        if self.auth_method == AuthMethod.BASIC:
+            if not self.username:
+                raise ValueError("Username is required for basic auth.")
+            if not self.password:
+                raise ValueError(
+                    f"Password is required for basic auth. "
+                    f"Store it in keyring service 'odsbox-diff' with key '{self.url}:{self.username}' "
+                    f"or provide it in the config file."
+                )
+
+        elif self.auth_method == AuthMethod.M2M:
+            if not self.client_id:
+                raise ValueError("client_id is required for m2m auth.")
+            if not self.token_endpoint:
+                raise ValueError("token_endpoint is required for m2m auth.")
+            if not self.client_secret:
+                raise ValueError(
+                    f"client_secret is required for m2m auth. "
+                    f"Store it in keyring service 'odsbox-diff' with key '{self.token_endpoint}:{self.client_id}' "
+                    f"or provide it in the config file."
+                )
+
+        elif self.auth_method == AuthMethod.OIDC:
+            if not self.client_id:
+                raise ValueError("client_id is required for oidc auth.")
+            if not self.redirect_uri:
+                raise ValueError("redirect_uri is required for oidc auth.")
+
+
+@dataclass
+class DiffDefaults:
+    """Default diff behavior settings loadable from config."""
+
+    exclude_regex_paths: list[str] = field(default_factory=list[str])
+    exclude_paths: list[str] = field(default_factory=list[str])
+    bulk_progress_bar: bool = False
+    no_bulk: bool = False
+    dump_dictionaries: bool = False
+    result_file: str = "diff_ods_tests_result.json"
+    verbose: bool = False
+    quiet: bool = False
+    cached_related: list[str] = field(default_factory=list[str])
+
+
+@dataclass
+class AppConfig:
+    """Top-level application config combining named server(s) and diff settings."""
+
+    servers: dict[str, ServerConfig]
+    defaults: DiffDefaults = field(default_factory=DiffDefaults)
+    queries: list[dict[str, Any]] = field(default_factory=list[dict[str, Any]])

odsbox_diff/connection/factory.py

@@ -0,0 +1,52 @@
+"""Create ConI connections from ServerConfig using odsbox ConIFactory."""
+
+from __future__ import annotations
+
+import logging
+
+from odsbox import ConI
+from odsbox import ConIFactory
+
+from .config import AuthMethod, ServerConfig
+
+log = logging.getLogger(__name__)
+
+
+def create_connection(cfg: ServerConfig) -> ConI:
+    """Return an opened ConI for the given server configuration."""
+    log.debug("Creating %s connection to %s", cfg.auth_method.value, cfg.url)
+
+    if cfg.auth_method == AuthMethod.BASIC:
+        return ConIFactory.basic(
+            url=cfg.url,
+            username=cfg.username,  # type: ignore[arg-type]
+            password=cfg.password,  # type: ignore[arg-type]
+            verify_certificate=cfg.verify_certificate,
+        )
+
+    if cfg.auth_method == AuthMethod.M2M:
+        return ConIFactory.m2m(
+            url=cfg.url,
+            token_endpoint=cfg.token_endpoint,  # type: ignore[arg-type]
+            client_id=cfg.client_id,  # type: ignore[arg-type]
+            client_secret=cfg.client_secret,  # type: ignore[arg-type]
+            scope=cfg.scope,
+            verify_certificate=cfg.verify_certificate,
+        )
+
+    if cfg.auth_method == AuthMethod.OIDC:
+        return ConIFactory.oidc(
+            url=cfg.url,
+            client_id=cfg.client_id,  # type: ignore[arg-type]
+            redirect_uri=cfg.redirect_uri,  # type: ignore[arg-type]
+            redirect_url_allow_insecure=cfg.redirect_url_allow_insecure,
+            client_secret=cfg.client_secret,
+            scope=cfg.scope,
+            authorization_endpoint=cfg.authorization_endpoint,
+            token_endpoint=cfg.token_endpoint,
+            login_timeout=cfg.login_timeout,
+            verify_certificate=cfg.verify_certificate,
+            webfinger_path_prefix=cfg.webfinger_path_prefix,
+        )
+
+    raise ValueError(f"Unsupported auth method: {cfg.auth_method}")

odsbox_diff/connection/manager.py

@@ -0,0 +1,150 @@
+"""Config file loading, validation, and keyring-backed secret resolution."""
+
+from __future__ import annotations
+
+import json
+import logging
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import keyring
+
+from .config import AppConfig, AuthMethod, DiffDefaults, ServerConfig
+
+_KEYRING_SERVICE = "odsbox-diff"
+
+log = logging.getLogger(__name__)
+
+
+def _keyring_key_for_basic(url: str, username: str) -> str:
+    return f"{url}:{username}"
+
+
+def _keyring_key_for_client(token_endpoint: str, client_id: str) -> str:
+    return f"{token_endpoint}:{client_id}"
+
+
+def _resolve_secret(cfg: ServerConfig) -> None:
+    """Fill in missing secrets from keyring. Mutates *cfg* in place."""
+    if cfg.auth_method == AuthMethod.BASIC and not cfg.password:
+        if cfg.username:
+            key = _keyring_key_for_basic(cfg.url, cfg.username)
+            secret = keyring.get_password(_KEYRING_SERVICE, key)
+            if secret:
+                log.debug("Resolved password from keyring for key '%s'.", key)
+                cfg.password = secret
+
+    elif cfg.auth_method in (AuthMethod.M2M, AuthMethod.OIDC) and not cfg.client_secret:
+        if cfg.client_id and cfg.token_endpoint:
+            key = _keyring_key_for_client(cfg.token_endpoint, cfg.client_id)
+            secret = keyring.get_password(_KEYRING_SERVICE, key)
+            if secret:
+                log.debug("Resolved client_secret from keyring for key '%s'.", key)
+                cfg.client_secret = secret
+
+
+def _parse_server(raw: dict[str, Any]) -> ServerConfig:
+    """Build a ServerConfig from a merged server/auth section dict."""
+    auth_method_str = raw.get("method", "basic")
+    try:
+        auth_method = AuthMethod(auth_method_str)
+    except ValueError:
+        raise ValueError(f"Unknown auth method '{auth_method_str}'. Use one of: basic, m2m, oidc.")
+
+    scope_raw = raw.get("scope")
+    scope = scope_raw if isinstance(scope_raw, list) else None
+
+    return ServerConfig(
+        url=raw.get("url", ""),
+        auth_method=auth_method,
+        verify_certificate=raw.get("verify_certificate", True),
+        username=raw.get("username"),
+        password=raw.get("password"),
+        client_id=raw.get("client_id"),
+        client_secret=raw.get("client_secret"),
+        token_endpoint=raw.get("token_endpoint"),
+        scope=scope,
+        redirect_uri=raw.get("redirect_uri"),
+        redirect_url_allow_insecure=raw.get("redirect_url_allow_insecure", False),
+        authorization_endpoint=raw.get("authorization_endpoint"),
+        login_timeout=raw.get("login_timeout", 60),
+        webfinger_path_prefix=raw.get("webfinger_path_prefix", ""),
+    )
+
+
+def _parse_config(raw: dict[str, Any]) -> AppConfig:
+    """Build an AppConfig from a parsed TOML/JSON dictionary."""
+    servers: dict[str, ServerConfig] = {}
+
+    if "servers" in raw:
+        # New format: one [servers.<name>] section per server
+        for name, srv_raw in raw["servers"].items():
+            if isinstance(srv_raw, dict):
+                servers[name] = _parse_server(srv_raw)
+    elif "server" in raw:
+        # New format: single unnamed [server] section
+        servers["default"] = _parse_server(raw["server"])
+    elif "connection" in raw or "authentication" in raw:
+        # Backward-compat: old separate [connection] + [authentication] sections
+        conn = raw.get("connection", {})
+        auth = raw.get("authentication", {})
+        servers["default"] = _parse_server({**conn, **auth})
+    # else: no server section — allowed when both diff sides are file sources
+    # and only [defaults] is needed from the config.
+
+    defaults_raw = raw.get("defaults", {})
+    erp = defaults_raw.get("exclude_regex_paths", [])
+    ep = defaults_raw.get("exclude_paths", [])
+    cr = defaults_raw.get("cached_related", [])
+    defaults = DiffDefaults(
+        exclude_regex_paths=erp if isinstance(erp, list) else [],
+        exclude_paths=ep if isinstance(ep, list) else [],
+        bulk_progress_bar=defaults_raw.get("bulk_progress_bar", False),
+        no_bulk=defaults_raw.get("no_bulk", False),
+        dump_dictionaries=defaults_raw.get("dump_dictionaries", False),
+        result_file=defaults_raw.get("result_file", "diff_ods_tests_result.json"),
+        verbose=defaults_raw.get("verbose", False),
+        quiet=defaults_raw.get("quiet", False),
+        cached_related=cr if isinstance(cr, list) else [],
+    )
+
+    queries: list[dict[str, Any]] = []
+    for query_name, query_raw in raw.get("queries", {}).items():
+        if isinstance(query_raw, dict) and "condition" in query_raw:
+            condition_raw = query_raw["condition"]
+            condition = json.loads(condition_raw) if isinstance(condition_raw, str) else condition_raw
+            queries.append({"name": query_name, "condition": condition})
+
+    return AppConfig(servers=servers, defaults=defaults, queries=queries)
+
+
+def load_config(path: str | Path) -> AppConfig:
+    """Load, validate, and return an AppConfig from a TOML or JSON file.
+
+    Secrets missing from the file are resolved from the OS keyring before
+    validation so that the returned config is ready for connection creation.
+    """
+    p = Path(path)
+    if not p.is_file():
+        raise FileNotFoundError(f"Config file not found: {p}")
+
+    text = p.read_text(encoding="utf-8")
+
+    if p.suffix in (".toml",):
+        raw = tomllib.loads(text)
+    elif p.suffix in (".json",):
+        raw = json.loads(text)
+    else:
+        # Try TOML first, fall back to JSON
+        try:
+            raw = tomllib.loads(text)
+        except Exception:
+            raw = json.loads(text)
+
+    app_config = _parse_config(raw)
+    for cfg in app_config.servers.values():
+        _resolve_secret(cfg)
+        cfg.validate()
+
+    return app_config