datacontract-cli 1.2.6__tar.gz → 1.2.7__tar.gz

{datacontract_cli-1.2.6/datacontract_cli.egg-info → datacontract_cli-1.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datacontract-cli
-Version: 1.2.6
+Version: 1.2.7
 Summary: The datacontract CLI is an open source command-line tool for working with Data Contracts. It uses data contract YAML files to lint the data contract, connect to data sources and execute schema and quality tests, detect breaking changes, and export to different formats. The tool is written in Python. It can be used as a standalone CLI tool, in a CI/CD pipeline, or directly as a Python library.
 Author-email: Jochen Christ <jochen.christ@entropy-data.com>, Stefan Negele <stefan.negele@innoq.com>, Simon Harrer <simon.harrer@entropy-data.com>
 License-Expression: MIT
@@ -195,7 +195,7 @@ It can be used as a standalone CLI tool, in a CI/CD pipeline, or directly as a P
 >
 > Quick links: [Quickstart](https://docs.datacontract.com/quickstart) · [Commands](https://docs.datacontract.com/commands) · [Best Practices](https://docs.datacontract.com/best-practices) · [Custom Export and Import](https://docs.datacontract.com/extending) · [Release Notes](https://docs.datacontract.com/release-notes) · [Development Setup](#development-setup)
 >
-> For LLMs: [docs.datacontract.com/llms.txt](https://docs.datacontract.com/llms.txt) · [docs.datacontract.com/llms-full.txt](https://docs.datacontract.com/llms-full.txt)
+> For LLMs: [docs.datacontract.com/llms.txt](https://docs.datacontract.com/llms.txt) · [docs.datacontract.com/llms-full.txt](https://docs.datacontract.com/llms-full.txt) · [Data Contract Skills](https://github.com/datacontract/datacontract-skills) for coding agents
 
 ## Getting started
 
@@ -318,7 +318,7 @@ $ datacontract lint odcs.yaml
 # show a changelog between two data contracts
 $ datacontract changelog v1.odcs.yaml v2.odcs.yaml
 
-# fail when a contract change is backward-incompatible
+# fail when a contract change breaks a guarantee consumers rely on
 $ datacontract breaking v1.odcs.yaml v2.odcs.yaml
 
 # execute schema and quality checks (define credentials as environment variables)
@@ -356,6 +356,7 @@ if not run.has_passed():
 ## How to
 
 - [How to integrate Data Contract CLI in your CI/CD pipeline as a GitHub Action](https://github.com/datacontract/datacontract-action/)
+- [How to let your coding agent (Claude Code, Codex, GitHub Copilot) create and test data contracts with the Data Contract Skills](https://github.com/datacontract/datacontract-skills)
 - [How to run the Data Contract CLI API to test data contracts with POST requests](https://docs.datacontract.com/api)
 - [How to run Data Contract CLI in a Databricks pipeline](https://www.datamesh-architecture.com/howto/build-a-dataproduct-with-databricks#test-the-data-product)
 

{datacontract_cli-1.2.6 → datacontract_cli-1.2.7}/README.md

@@ -24,7 +24,7 @@ It can be used as a standalone CLI tool, in a CI/CD pipeline, or directly as a P
 >
 > Quick links: [Quickstart](https://docs.datacontract.com/quickstart) · [Commands](https://docs.datacontract.com/commands) · [Best Practices](https://docs.datacontract.com/best-practices) · [Custom Export and Import](https://docs.datacontract.com/extending) · [Release Notes](https://docs.datacontract.com/release-notes) · [Development Setup](#development-setup)
 >
-> For LLMs: [docs.datacontract.com/llms.txt](https://docs.datacontract.com/llms.txt) · [docs.datacontract.com/llms-full.txt](https://docs.datacontract.com/llms-full.txt)
+> For LLMs: [docs.datacontract.com/llms.txt](https://docs.datacontract.com/llms.txt) · [docs.datacontract.com/llms-full.txt](https://docs.datacontract.com/llms-full.txt) · [Data Contract Skills](https://github.com/datacontract/datacontract-skills) for coding agents
 
 ## Getting started
 
@@ -147,7 +147,7 @@ $ datacontract lint odcs.yaml
 # show a changelog between two data contracts
 $ datacontract changelog v1.odcs.yaml v2.odcs.yaml
 
-# fail when a contract change is backward-incompatible
+# fail when a contract change breaks a guarantee consumers rely on
 $ datacontract breaking v1.odcs.yaml v2.odcs.yaml
 
 # execute schema and quality checks (define credentials as environment variables)
@@ -185,6 +185,7 @@ if not run.has_passed():
 ## How to
 
 - [How to integrate Data Contract CLI in your CI/CD pipeline as a GitHub Action](https://github.com/datacontract/datacontract-action/)
+- [How to let your coding agent (Claude Code, Codex, GitHub Copilot) create and test data contracts with the Data Contract Skills](https://github.com/datacontract/datacontract-skills)
 - [How to run the Data Contract CLI API to test data contracts with POST requests](https://docs.datacontract.com/api)
 - [How to run Data Contract CLI in a Databricks pipeline](https://www.datamesh-architecture.com/howto/build-a-dataproduct-with-databricks#test-the-data-product)
 

{datacontract_cli-1.2.6 → datacontract_cli-1.2.7}/datacontract/api.py

@@ -14,7 +14,7 @@ from pydantic import BaseModel, Field, ValidationError
 from datacontract.config import Config, known_env_names
 from datacontract.config.variables import CONTRACT_VARIABLES_ENV, allowed_environment, resolve_variables
 from datacontract.data_contract import DataContract, ExportFormat
-from datacontract.model.breaking import BreakingChangeEntry
+from datacontract.model.breaking import BreakingChangeEntry, Perspective
 from datacontract.model.changelog import ChangelogEntry
 from datacontract.model.exceptions import DataContractException, DefinitionResolutionError
 from datacontract.model.run import Check, ResultEnum, Run
@@ -259,9 +259,10 @@ A posted contract carries SQL and names the hosts to connect to, so the server t
 untrusted input: a `quality.type: sql` rule must be a read-only query, a credential held in the
 server's environment is never sent to a host the contract names, a `publish_url` may only point at
 the Entropy Data platform or the host configured via `ENTROPY_DATA_HOST`, and `servers[].type: local`
-is refused so a caller cannot read the server's own files. Set
-`DATACONTRACT_CLI_API_ALLOW_LOCAL_FILES=true` if the deployment serves its own files on purpose;
-the contract is then still confined to the paths it declares.
+is refused so a caller cannot read the server's own files, and an `api` server's requests may not
+reach a private network address. Set `DATACONTRACT_CLI_API_ALLOW_LOCAL_FILES=true` if the deployment
+serves its own files on purpose; the contract is then still confined to the paths it declares. Set
+`DATACONTRACT_CLI_API_ALLOW_PRIVATE_NETWORK=true` to test APIs in the server's own network.
 
 ## Connecting to data sources
 
@@ -525,6 +526,8 @@ _ENVIRONMENT_CREDENTIAL_TARGETS: dict[str, tuple[str, str | None, tuple[str, ...
     # option pins it), so an environment-held SASL password can never be paired
     # with a posted contract safely -- host_field is None, so it is always rejected.
     "kafka": ("broker host", None, ("kafka_sasl_password",)),
+    # Nothing pins an API server's location either.
+    "api": ("location", None, ("api_header_authorization", "api_header_x_api_key")),
 }
 
 
@@ -552,6 +555,7 @@ def _selected_server(body: str, server_name: str | None, config):
 _LOCAL_SERVER_TYPES = frozenset({"local", "duckdb"})
 
 ALLOW_LOCAL_FILES_ENV = "DATACONTRACT_CLI_API_ALLOW_LOCAL_FILES"
+ALLOW_PRIVATE_NETWORK_ENV = "DATACONTRACT_CLI_API_ALLOW_PRIVATE_NETWORK"
 _TRUTHY = frozenset({"1", "true", "yes", "on"})
 
 
@@ -570,6 +574,11 @@ def _local_files_allowed() -> bool:
     return (os.getenv(ALLOW_LOCAL_FILES_ENV) or "").strip().lower() in _TRUTHY
 
 
+def _private_network_allowed() -> bool:
+    """Whether the operator lets a posted contract's API requests reach private network addresses."""
+    return (os.getenv(ALLOW_PRIVATE_NETWORK_ENV) or "").strip().lower() in _TRUTHY
+
+
 def _reject_local_server_type(body: str, server_name: str | None, config) -> None:
     """Keep a posted contract from reading the server's own disk.
 
@@ -623,20 +632,23 @@ def _reject_environment_credentials_to_untrusted_host(body: str, server_name: st
         return  # no environment-held secret for this server type; nothing to protect
     if host_field is not None and resolved.option_source(host_field) == "env":
         return  # the operator pinned the target host; the contract's host is ignored
+    held = [
+        env_name(field, Config.model_fields[field]) for field in secret_fields if resolved.option_source(field) == "env"
+    ]
     if host_field is not None:
         env_var = env_name(host_field, Config.model_fields[host_field])
         detail = (
-            f"This server holds a {server.type} credential in its environment, so the connection "
-            f"{target_attr} must also come from the server's environment ({env_var}); it will not be "
-            f"taken from the posted data contract. Set {env_var}, or send the full set of credentials "
-            f"with the request instead of relying on the server's environment."
+            f"This server holds a credential for {server.type} servers in its environment ({', '.join(held)}), so the "
+            f"connection {target_attr} must also come from the server's environment ({env_var}); it will not "
+            f"be taken from the posted data contract. Set {env_var}, or send the full set of credentials with "
+            f"the request instead of relying on the server's environment."
         )
     else:
         detail = (
-            f"This server holds a {server.type} credential in its environment, but its {target_attr} "
-            f"can only come from the posted data contract, so the credential cannot be pinned to a "
-            f"trusted target. Send the credentials with the request instead of relying on the server's "
-            f"environment."
+            f"This server holds a credential for {server.type} servers in its environment ({', '.join(held)}), but "
+            f"their {target_attr} can only come from the posted data contract, so the credential cannot be pinned to "
+            f"a trusted target. Send the credentials as request headers instead "
+            f"({', '.join(name.lower().replace('_', '-') for name in held)})."
         )
     raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=detail)
 
@@ -835,6 +847,7 @@ def test(
         filters=parsed_filters,
         untrusted_contract=untrusted_contract,
         allowed_variables=_allowed_contract_variables(),
+        allow_private_network=_private_network_allowed(),
     ).test()
 
 
@@ -943,6 +956,9 @@ class BreakingChangesResponse(BaseModel):
     entries: list[BreakingChangeEntry] = Field(
         description="Every single change with its grade and the old and new value.",
     )
+    perspective: Perspective = Field(
+        description="Whose expectations the changes were graded against: `consumer` or `producer`.",
+    )
     is_breaking: bool = Field(
         description="Whether any detected change is classified as an error-level breaking change.",
     )
@@ -1006,13 +1022,21 @@ parsed is answered with `422`.
 def breaking_endpoint(
     body: ChangelogRequest,
     api_key: Annotated[str | None, Depends(api_key_header)] = None,
+    perspective: Annotated[
+        Perspective,
+        Query(
+            description="`consumer` flags changes that lead to unexpected data for consumers, `producer` flags changes that can make data contract tests fail.",
+        ),
+    ] = Perspective.CONSUMER,
 ) -> BreakingChangesResponse:
     check_api_key(api_key)
 
     result = DataContract(data_contract_str=body.v1, untrusted_contract=True).breaking(
-        DataContract(data_contract_str=body.v2, untrusted_contract=True)
+        DataContract(data_contract_str=body.v2, untrusted_contract=True), perspective=perspective
+    )
+    return BreakingChangesResponse(
+        summary=result.summary, entries=result.entries, perspective=result.perspective, is_breaking=result.is_breaking
     )
-    return BreakingChangesResponse(summary=result.summary, entries=result.entries, is_breaking=result.is_breaking)
 
 
 @app.post(

{datacontract_cli-1.2.6 → datacontract_cli-1.2.7}/datacontract/breaking/detector.py

@@ -1,8 +1,14 @@
 from collections import defaultdict
 from collections.abc import Iterable
 
-from datacontract.breaking.rules import DEFAULT_RULES, BreakingChangeRule
-from datacontract.model.breaking import BreakingChangeEntry, BreakingChangeLevel, BreakingChangeResult
+from datacontract.breaking.rules import DEFAULT_RULES, BreakingChangeRule, MetadataFallbackRule
+from datacontract.model.breaking import (
+    BreakingChangeEntry,
+    BreakingChangeLevel,
+    BreakingChangeResult,
+    Direction,
+    Perspective,
+)
 from datacontract.model.changelog import ChangelogEntry, ChangelogResult, ChangelogType
 
 _LEVEL_ORDER = {
@@ -20,43 +26,22 @@ class BreakingChangeDetector:
         if not self._rules:
             raise ValueError("At least one breaking-change rule is required")
 
-    def detect(self, changelog: ChangelogResult) -> BreakingChangeResult:
-        entries = [self._classify(entry) for entry in changelog.entries]
-        # Nothing inside an added element can break a consumer: it did not exist before.
-        # Inside a removed one, the element's own entry carries the grade; its former
-        # constraints are gone, which is a relaxation.
-        added_or_removed = {
+    def detect(
+        self, changelog: ChangelogResult, perspective: Perspective, before: dict, after: dict
+    ) -> BreakingChangeResult:
+        """Grade ``changelog``, built from the normalized contracts ``before`` and ``after``, for ``perspective``."""
+        entries = [self._classify(entry, perspective, before, after) for entry in changelog.entries]
+        # An added or removed element carries the grade for everything inside it.
+        elements = {
             entry.path
             for entry in entries
             if entry.change_type in (ChangelogType.added, ChangelogType.removed)
-            and (
-                entry.path.startswith("schema.")
-                and (len(entry.path.split(".")) == 2 or entry.path.split(".")[-2] in ("properties", "quality"))
-            )
-        }
-        removed_enums = {
-            entry.path
-            for entry in entries
-            if entry.change_type == ChangelogType.removed and entry.path.endswith(".enum")
+            and entry.rule_id != MetadataFallbackRule.rule_id
         }
-        # Stable IDs may change or swap without changing the set of allowed
-        # values. Match removed/updated values against additions in the same enum.
-        added_values = defaultdict(set)
         for entry in entries:
-            if entry.rule_id == "enum-constraint-changed" and entry.path.endswith(".value"):
-                if entry.change_type in (ChangelogType.added, ChangelogType.updated):
-                    added_values[entry.path.rsplit(".enum.", 1)[0]].add(entry.new_value)
-        for entry in entries:
-            segments = entry.path.split(".")
-            if any(".".join(segments[:i]) in added_or_removed for i in range(1, len(segments))):
+            if any(entry.path.startswith(f"{path}.") for path in elements):
+                entry.direction = None
                 entry.level = BreakingChangeLevel.INFO
-            if entry.rule_id == "enum-constraint-changed":
-                if any(entry.path.startswith(path + ".") for path in removed_enums):
-                    entry.level = BreakingChangeLevel.INFO
-                elif entry.path.endswith(".value") and entry.old_value in added_values.get(
-                    entry.path.rsplit(".enum.", 1)[0], set()
-                ):
-                    entry.level = BreakingChangeLevel.INFO
         entries_by_prefix = defaultdict(list)
         for entry in entries:
             prefix = ""
@@ -64,16 +49,33 @@ class BreakingChangeDetector:
                 prefix = f"{prefix}.{segment}" if prefix else segment
                 entries_by_prefix[prefix].append(entry)
         summary = [self._summarize(entry, entries_by_prefix.get(entry.path, [])) for entry in changelog.summary]
-        return BreakingChangeResult(v1=changelog.v1, v2=changelog.v2, summary=summary, entries=entries)
+        return BreakingChangeResult(
+            v1=changelog.v1, v2=changelog.v2, perspective=perspective, summary=summary, entries=entries
+        )
 
-    def _classify(self, entry: ChangelogEntry) -> BreakingChangeEntry:
+    def _classify(
+        self, entry: ChangelogEntry, perspective: Perspective, before: dict, after: dict
+    ) -> BreakingChangeEntry:
         for rule in self._rules:
-            evaluation = rule.evaluate(entry)
+            evaluation = rule.evaluate(entry, before, after)
             if evaluation is not None:
+                direction = evaluation.direction
+                if direction == Direction.BOTH:
+                    level = BreakingChangeLevel.ERROR
+                elif direction == Direction.UNDETERMINED:
+                    level = BreakingChangeLevel.WARNING
+                elif (direction, perspective) in (
+                    (Direction.TIGHTENS, Perspective.PRODUCER),
+                    (Direction.LOOSENS, Perspective.CONSUMER),
+                ):
+                    level = BreakingChangeLevel.ERROR
+                else:
+                    level = BreakingChangeLevel.INFO
                 return BreakingChangeEntry(
                     path=entry.path,
                     change_type=entry.type,
-                    level=evaluation.level,
+                    level=level,
+                    direction=direction,
                     message=evaluation.message,
                     rule_id=evaluation.rule_id,
                     old_value=entry.old_value,