datacontract-cli 0.10.23__py3-none-any.whl → 0.10.37__py3-none-any.whl

datacontract/__init__.py

@@ -0,0 +1,13 @@
+# Configuration so that yaml.safe_dump dumps strings with line breaks with yaml literal |
+import yaml
+
+yaml.SafeDumper.org_represent_str = yaml.SafeDumper.represent_str
+
+
+def repr_str(dumper, data):
+    if "\n" in data:
+        return dumper.represent_scalar("tag:yaml.org,2002:str", data, style="|")
+    return dumper.org_represent_str(data)
+
+
+yaml.add_representer(str, repr_str, Dumper=yaml.SafeDumper)

datacontract/api.py

@@ -10,7 +10,7 @@ from fastapi.security.api_key import APIKeyHeader
 from datacontract.data_contract import DataContract, ExportFormat
 from datacontract.model.run import Run
 
-DATA_CONTRACT_EXAMPLE_PAYLOAD = """dataContractSpecification: 1.1.0
+DATA_CONTRACT_EXAMPLE_PAYLOAD = """dataContractSpecification: 1.2.1
 id: urn:datacontract:checkout:orders-latest
 info:
   title: Orders Latest
@@ -162,15 +162,22 @@ async def test(
     server: Annotated[
         str | None,
         Query(
-            example="production",
             description="The server name to test. Optional, if there is only one server.",
+            examples=["production"],
+        ),
+    ] = None,
+    publish_url: Annotated[
+        str | None,
+        Query(
+            description="URL to publish test results. Optional, if you want to publish the test results to a Data Mesh Manager or Data Contract Manager. Example: https://api.datamesh-manager.com/api/test-results",
+            examples=["https://api.datamesh-manager.com/api/test-results"],
         ),
     ] = None,
 ) -> Run:
     check_api_key(api_key)
     logging.info("Testing data contract...")
     logging.info(body)
-    return DataContract(data_contract_str=body, server=server).test()
+    return DataContract(data_contract_str=body, server=server, publish_url=publish_url).test()
 
 
 @app.post(
@@ -191,7 +198,7 @@ async def lint(
     schema: Annotated[
         str | None,
         Query(
-            example="https://datacontract.com/datacontract.schema.json",
+            examples=["https://datacontract.com/datacontract.schema.json"],
             description="The schema to use for validation. This must be a URL.",
         ),
     ] = None,
@@ -220,7 +227,7 @@ def export(
     server: Annotated[
         str | None,
         Query(
-            example="production",
+            examples=["production"],
             description="The server name to export. Optional, if there is only one server.",
         ),
     ] = None,

datacontract/catalog/catalog.py

@@ -1,3 +1,4 @@
+import logging
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
@@ -6,11 +7,12 @@ import pytz
 from jinja2 import Environment, PackageLoader, select_autoescape
 
 from datacontract.data_contract import DataContract
-from datacontract.export.html_export import get_version
+from datacontract.export.html_exporter import get_version
 from datacontract.model.data_contract_specification import DataContractSpecification
 
 
 def create_data_contract_html(contracts, file: Path, path: Path, schema: str):
+    logging.debug(f"Creating data contract html for file {file} and schema {schema}")
     data_contract = DataContract(
         data_contract_file=f"{file.absolute()}", inline_definitions=True, inline_quality=True, schema_location=schema
     )
@@ -19,7 +21,7 @@ def create_data_contract_html(contracts, file: Path, path: Path, schema: str):
     file_without_suffix = file.with_suffix(".html")
     html_filepath = path / file_without_suffix
     html_filepath.parent.mkdir(parents=True, exist_ok=True)
-    with open(html_filepath, "w") as f:
+    with open(html_filepath, "w", encoding="utf-8") as f:
         f.write(html)
     contracts.append(
         DataContractView(
@@ -42,7 +44,7 @@ class DataContractView:
 
 def create_index_html(contracts, path):
     index_filepath = path / "index.html"
-    with open(index_filepath, "w") as f:
+    with open(index_filepath, "w", encoding="utf-8") as f:
         # Load templates from templates folder
         package_loader = PackageLoader("datacontract", "templates")
         env = Environment(

datacontract/cli.py

@@ -1,4 +1,6 @@
+import logging
 import os
+import sys
 from importlib import metadata
 from pathlib import Path
 from typing import Iterable, List, Optional
@@ -11,17 +13,20 @@ from typing_extensions import Annotated
 
 from datacontract.catalog.catalog import create_data_contract_html, create_index_html
 from datacontract.data_contract import DataContract, ExportFormat
-from datacontract.imports.importer import ImportFormat
+from datacontract.imports.importer import ImportFormat, Spec
 from datacontract.init.init_template import get_init_template
 from datacontract.integration.datamesh_manager import (
     publish_data_contract_to_datamesh_manager,
 )
 from datacontract.lint.resolve import resolve_data_contract_dict
+from datacontract.model.exceptions import DataContractException
 from datacontract.output.output_format import OutputFormat
 from datacontract.output.test_results_writer import write_test_result
 
 console = Console()
 
+debug_option = Annotated[bool, typer.Option(help="Enable debug logging")]
+
 
 class OrderedCommands(TyperGroup):
     def list_commands(self, ctx: Context) -> Iterable[str]:
@@ -69,10 +74,13 @@ def init(
     ] = "datacontract.yaml",
     template: Annotated[str, typer.Option(help="URL of a template or data contract")] = None,
     overwrite: Annotated[bool, typer.Option(help="Replace the existing datacontract.yaml")] = False,
+    debug: debug_option = None,
 ):
     """
     Create an empty data contract.
     """
+    enable_debug_logging(debug)
+
     if not overwrite and os.path.exists(location):
         console.print("File already exists, use --overwrite to overwrite")
         raise typer.Exit(code=1)
@@ -99,14 +107,24 @@ def lint(
         ),
     ] = None,
     output_format: Annotated[OutputFormat, typer.Option(help="The target format for the test results.")] = None,
+    debug: debug_option = None,
 ):
     """
     Validate that the datacontract.yaml is correctly formatted.
     """
+    enable_debug_logging(debug)
+
     run = DataContract(data_contract_file=location, schema_location=schema).lint()
     write_test_result(run, console, output_format, output)
 
 
+def enable_debug_logging(debug: bool):
+    if debug:
+        logging.basicConfig(
+            level=logging.DEBUG, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", stream=sys.stderr
+        )
+
+
 @app.command()
 def test(
     location: Annotated[
@@ -126,7 +144,10 @@ def test(
             "servers (default)."
         ),
     ] = "all",
-    publish: Annotated[str, typer.Option(help="The url to publish the results after the test")] = None,
+    publish_test_results: Annotated[
+        bool, typer.Option(help="Deprecated. Use publish parameter. Publish the results after the test")
+    ] = False,
+    publish: Annotated[str, typer.Option(help="The url to publish the results after the test.")] = None,
     output: Annotated[
         Path,
         typer.Option(
@@ -139,16 +160,20 @@ def test(
         bool,
         typer.Option(help="SSL verification when publishing the data contract."),
     ] = True,
+    debug: debug_option = None,
 ):
     """
     Run schema and quality tests on configured servers.
     """
+    enable_debug_logging(debug)
+
     console.print(f"Testing {location}")
     if server == "all":
         server = None
     run = DataContract(
         data_contract_file=location,
         schema_location=schema,
+        publish_test_results=publish_test_results,
         publish_url=publish,
         server=server,
         ssl_verification=ssl_verification,
@@ -208,12 +233,24 @@ def export(
     # TODO: this should be a subcommand
     template: Annotated[
         Optional[Path],
-        typer.Option(help="[custom] The file path of Jinja template."),
+        typer.Option(
+            help="The file path or URL of a template. For Excel format: path/URL to custom Excel template. For custom format: path to Jinja template."
+        ),
     ] = None,
+    debug: debug_option = None,
 ):
     """
     Convert data contract to a specific format. Saves to file specified by `output` option if present, otherwise prints to stdout.
     """
+    enable_debug_logging(debug)
+
+    # Validate that Excel format requires an output file path
+    if format == ExportFormat.excel and output is None:
+        console.print("❌ Error: Excel export requires an output file path.")
+        console.print("💡 Hint: Use --output to specify where to save the Excel file, e.g.:")
+        console.print("   datacontract export --format excel --output datacontract.xlsx")
+        raise typer.Exit(code=1)
+
     # TODO exception handling
     result = DataContract(data_contract_file=location, schema_location=schema, server=server).export(
         export_format=format,
@@ -228,8 +265,13 @@ def export(
     if output is None:
         console.print(result, markup=False, soft_wrap=True)
     else:
-        with output.open(mode="w", encoding="utf-8") as f:
-            f.write(result)
+        if isinstance(result, bytes):
+            # If the result is bytes, we assume it's a binary file (e.g., Excel, PDF)
+            with output.open(mode="wb") as f:
+                f.write(result)
+        else:
+            with output.open(mode="w", encoding="utf-8") as f:
+                f.write(result)
         console.print(f"Written result to {output}")
 
 
@@ -244,8 +286,12 @@ def import_(
     ] = None,
     source: Annotated[
         Optional[str],
-        typer.Option(help="The path to the file or Glue Database that should be imported."),
+        typer.Option(help="The path to the file that should be imported."),
     ] = None,
+    spec: Annotated[
+        Spec,
+        typer.Option(help="The format of the data contract to import. "),
+    ] = Spec.datacontract_specification,
     dialect: Annotated[
         Optional[str],
         typer.Option(help="The SQL dialect to use when importing SQL files, e.g., postgres, tsql, bigquery."),
@@ -265,7 +311,7 @@ def import_(
         ),
     ] = None,
     unity_table_full_name: Annotated[
-        Optional[str], typer.Option(help="Full name of a table in the unity catalog")
+        Optional[List[str]], typer.Option(help="Full name of a table in the unity catalog")
     ] = None,
     dbt_model: Annotated[
         Optional[List[str]],
@@ -297,13 +343,25 @@ def import_(
         str,
         typer.Option(help="The location (url or path) of the Data Contract Specification JSON Schema"),
     ] = None,
+    owner: Annotated[
+        Optional[str],
+        typer.Option(help="The owner or team responsible for managing the data contract."),
+    ] = None,
+    id: Annotated[
+        Optional[str],
+        typer.Option(help="The identifier for the the data contract."),
+    ] = None,
+    debug: debug_option = None,
 ):
     """
     Create a data contract from the given source location. Saves to file specified by `output` option if present, otherwise prints to stdout.
     """
-    result = DataContract().import_from_source(
+    enable_debug_logging(debug)
+
+    result = DataContract.import_from_source(
         format=format,
         source=source,
+        spec=spec,
         template=template,
         schema=schema,
         dialect=dialect,
@@ -316,6 +374,8 @@ def import_(
         dbml_schema=dbml_schema,
         dbml_table=dbml_table,
         iceberg_table=iceberg_table,
+        owner=owner,
+        id=id,
     )
     if output is None:
         console.print(result.to_yaml(), markup=False, soft_wrap=True)
@@ -339,10 +399,13 @@ def publish(
         bool,
         typer.Option(help="SSL verification when publishing the data contract."),
     ] = True,
+    debug: debug_option = None,
 ):
     """
     Publish the data contract to the Data Mesh Manager.
     """
+    enable_debug_logging(debug)
+
     publish_data_contract_to_datamesh_manager(
         data_contract_dict=resolve_data_contract_dict(location),
         ssl_verification=ssl_verification,
@@ -362,10 +425,13 @@ def catalog(
         str,
         typer.Option(help="The location (url or path) of the Data Contract Specification JSON Schema"),
     ] = None,
+    debug: debug_option = None,
 ):
     """
     Create a html catalog of data contracts.
     """
+    enable_debug_logging(debug)
+
     path = Path(output)
     path.mkdir(parents=True, exist_ok=True)
     console.print(f"Created {output}")
@@ -374,6 +440,11 @@ def catalog(
     for file in Path().rglob(files):
         try:
             create_data_contract_html(contracts, file, path, schema)
+        except DataContractException as e:
+            if e.reason == "Cannot parse ODPS product":
+                console.print(f"Skipped {file} due to error: {e.reason}")
+            else:
+                console.print(f"Skipped {file} due to error: {e}")
         except Exception as e:
             console.print(f"Skipped {file} due to error: {e}")
 
@@ -390,10 +461,12 @@ def breaking(
         str,
         typer.Argument(help="The location (url or path) of the new data contract yaml."),
     ],
+    debug: debug_option = None,
 ):
     """
     Identifies breaking changes between data contracts. Prints to stdout.
     """
+    enable_debug_logging(debug)
 
     # TODO exception handling
     result = DataContract(data_contract_file=location_old, inline_definitions=True).breaking(
@@ -416,10 +489,12 @@ def changelog(
         str,
         typer.Argument(help="The location (url or path) of the new data contract yaml."),
     ],
+    debug: debug_option = None,
 ):
     """
     Generate a changelog between data contracts. Prints to stdout.
     """
+    enable_debug_logging(debug)
 
     # TODO exception handling
     result = DataContract(data_contract_file=location_old, inline_definitions=True).changelog(
@@ -439,10 +514,12 @@ def diff(
         str,
         typer.Argument(help="The location (url or path) of the new data contract yaml."),
     ],
+    debug: debug_option = None,
 ):
     """
     PLACEHOLDER. Currently works as 'changelog' does.
     """
+    enable_debug_logging(debug)
 
     # TODO change to diff output, not the changelog entries
     result = DataContract(data_contract_file=location_old, inline_definitions=True).changelog(
@@ -452,12 +529,32 @@ def diff(
     console.print(result.changelog_str())
 
 
-@app.command()
+def _get_uvicorn_arguments(port: int, host: str, context: typer.Context) -> dict:
+    """
+    Take the default datacontract uvicorn arguments and merge them with the
+    extra arguments passed to the command to start the API.
+    """
+    default_args = {
+        "app": "datacontract.api:app",
+        "port": port,
+        "host": host,
+        "reload": True,
+    }
+
+    # Create a list of the extra arguments, remove the leading -- from the cli arguments
+    trimmed_keys = list(map(lambda x: str(x).replace("--", ""), context.args[::2]))
+    # Merge the two dicts and return them as one dict
+    return default_args | dict(zip(trimmed_keys, context.args[1::2]))
+
+
+@app.command(context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
 def api(
+    ctx: Annotated[typer.Context, typer.Option(help="Extra arguments to pass to uvicorn.run().")],
     port: Annotated[int, typer.Option(help="Bind socket to this port.")] = 4242,
     host: Annotated[
         str, typer.Option(help="Bind socket to this host. Hint: For running in docker, set it to 0.0.0.0")
     ] = "127.0.0.1",
+    debug: debug_option = None,
 ):
     """
     Start the datacontract CLI as server application with REST API.
@@ -471,14 +568,23 @@ def api(
 
     To connect to servers (such as a Snowflake data source), set the credentials as environment variables as documented in
     https://cli.datacontract.com/#test
+
+    It is possible to run the API with extra arguments for `uvicorn.run()` as keyword arguments, e.g.:
+    `datacontract api --port 1234 --root_path /datacontract`.
     """
+    enable_debug_logging(debug)
+
     import uvicorn
     from uvicorn.config import LOGGING_CONFIG
 
     log_config = LOGGING_CONFIG
     log_config["root"] = {"level": "INFO"}
 
-    uvicorn.run(app="datacontract.api:app", port=port, host=host, reload=True, log_config=LOGGING_CONFIG)
+    uvicorn_args = _get_uvicorn_arguments(port, host, ctx)
+    # Add the log config
+    uvicorn_args["log_config"] = log_config
+    # Run uvicorn
+    uvicorn.run(**uvicorn_args)
 
 
 def _print_logs(run):