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

datacontract/export/jsonschema_converter.py

@@ -1,8 +1,14 @@
 import json
 from typing import Dict
 
-from datacontract.model.data_contract_specification import \
-    DataContractSpecification, Model, Field
+from datacontract.export.exporter import Exporter, _check_models_for_export
+from datacontract.model.data_contract_specification import DataContractSpecification, Field, Model
+
+
+class JsonSchemaExporter(Exporter):
+    def export(self, data_contract, model, server, sql_server_type, export_args) -> dict:
+        model_name, model_value = _check_models_for_export(data_contract, model, self.export_format)
+        return to_jsonschema_json(model_name, model_value)
 
 
 def to_jsonschemas(data_contract_spec: DataContractSpecification):
@@ -18,15 +24,6 @@ def to_jsonschema_json(model_key, model_value: Model) -> str:
     return json.dumps(jsonschema, indent=2)
 
 
-def to_jsonschema(model_key, model_value: Model) -> dict:
-    return {
-        "$schema": "http://json-schema.org/draft-07/schema#",
-        "type": "object",
-        "properties": to_properties(model_value.fields),
-        "required": to_required(model_value.fields),
-    }
-
-
 def to_properties(fields: Dict[str, Field]) -> dict:
     properties = {}
     for field_name, field in fields.items():
@@ -38,17 +35,60 @@ def to_property(field: Field) -> dict:
     property = {}
     json_type, json_format = convert_type_format(field.type, field.format)
     if json_type is not None:
-        if field.required:
-            property["type"] = json_type
-        else:
+        if not field.required:
+            """
+            From: https://json-schema.org/understanding-json-schema/reference/type
+            The type keyword may either be a string or an array:
+
+            If it's a string, it is the name of one of the basic types above.
+            If it is an array, it must be an array of strings, where each string 
+            is the name of one of the basic types, and each element is unique.
+            In this case, the JSON snippet is valid if it matches any of the given types.
+            """
             property["type"] = [json_type, "null"]
+        else:
+            property["type"] = json_type
     if json_format is not None:
         property["format"] = json_format
+    if field.primaryKey:
+        property["primaryKey"] = field.primaryKey
     if field.unique:
         property["unique"] = True
     if json_type == "object":
-        property["properties"] = to_properties(field.fields)
+        # TODO: any better idea to distinguish between properties and patternProperties?
+        if field.fields.keys() and next(iter(field.fields.keys())).startswith("^"):
+            property["patternProperties"] = to_properties(field.fields)
+        else:
+            property["properties"] = to_properties(field.fields)
         property["required"] = to_required(field.fields)
+    if json_type == "array":
+        property["items"] = to_property(field.items)
+    if field.pattern:
+        property["pattern"] = field.pattern
+    if field.enum:
+        property["enum"] = field.enum
+    if field.minLength is not None:
+        property["minLength"] = field.minLength
+    if field.maxLength is not None:
+        property["maxLength"] = field.maxLength
+    if field.title:
+        property["title"] = field.title
+    if field.description:
+        property["description"] = field.description
+    if field.exclusiveMinimum is not None:
+        property["exclusiveMinimum"] = field.exclusiveMinimum
+    if field.exclusiveMaximum is not None:
+        property["exclusiveMaximum"] = field.exclusiveMaximum
+    if field.minimum is not None:
+        property["minimum"] = field.minimum
+    if field.maximum is not None:
+        property["maximum"] = field.maximum
+    if field.tags:
+        property["tags"] = field.tags
+    if field.pii:
+        property["pii"] = field.pii
+    if field.classification is not None:
+        property["classification"] = field.classification
 
     # TODO: all constraints
     return property
@@ -88,7 +128,7 @@ def convert_type_format(type, format) -> (str, str):
     return None, None
 
 
-def convert_format(format):
+def convert_format(self, format):
     if format is None:
         return None
     if format.lower() in ["uri"]:
@@ -100,3 +140,18 @@ def convert_format(format):
     if format.lower() in ["boolean"]:
         return "boolean"
     return None
+
+
+def to_jsonschema(model_key, model_value: Model) -> dict:
+    model = {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "properties": to_properties(model_value.fields),
+        "required": to_required(model_value.fields),
+    }
+    if model_value.title:
+        model["title"] = model_value.title
+    if model_value.description:
+        model["description"] = model_value.description
+
+    return model

datacontract/export/markdown_converter.py

@@ -0,0 +1,337 @@
+from typing import Dict, List
+
+from pydantic import BaseModel
+
+from datacontract.export.exporter import Exporter
+from datacontract.model.data_contract_specification import (
+    DataContractSpecification,
+    Definition,
+    Field,
+    Model,
+    Server,
+    ServiceLevel,
+)
+
+TAB = " "
+ARROW = "↳"
+
+
+class MarkdownExporter(Exporter):
+    """Exporter implementation for converting data contracts to Markdown."""
+
+    def export(
+        self,
+        data_contract: DataContractSpecification,
+        model: Model,
+        server: str,
+        sql_server_type: str,
+        export_args: dict,
+    ) -> str:
+        """Exports a data contract to Markdown format."""
+        return to_markdown(data_contract)
+
+
+def to_markdown(data_contract: DataContractSpecification) -> str:
+    """
+    Convert a data contract to its Markdown representation.
+
+    Args:
+        data_contract (DataContractSpecification): The data contract to convert.
+
+    Returns:
+        str: The Markdown representation of the data contract.
+    """
+    markdown_parts = [
+        f"# {data_contract.id}",
+        "## Info",
+        obj_attributes_to_markdown(data_contract.info),
+        "",
+        "## Servers",
+        servers_to_markdown(data_contract.servers),
+        "",
+        "## Terms",
+        obj_attributes_to_markdown(data_contract.terms),
+        "",
+        "## Models",
+        models_to_markdown(data_contract.models),
+        "",
+        "## Definitions",
+        definitions_to_markdown(data_contract.definitions),
+        "",
+        "## Service levels",
+        service_level_to_markdown(data_contract.servicelevels),
+    ]
+    return "\n".join(markdown_parts)
+
+
+def obj_attributes_to_markdown(obj: BaseModel, excluded_fields: set = set(), is_in_table_cell: bool = False) -> str:
+    if not obj:
+        return ""
+    if is_in_table_cell:
+        bullet_char = "•"
+        newline_char = "<br>"
+    else:
+        bullet_char = "-"
+        newline_char = "\n"
+    model_attributes_to_include = set(obj.__class__.model_fields.keys())
+    obj_model = obj.model_dump(exclude_unset=True, include=model_attributes_to_include, exclude=excluded_fields)
+    description_value = obj_model.pop("description", None)
+    attributes = [
+        (f"{bullet_char} `{attr}`" if value is True else f"{bullet_char} **{attr}:** {value}")
+        for attr, value in obj_model.items()
+        if value
+    ]
+    description = f"*{description_to_markdown(description_value)}*"
+    extra = [extra_to_markdown(obj, is_in_table_cell)] if obj.model_extra else []
+    return newline_char.join([description] + attributes + extra)
+
+
+def servers_to_markdown(servers: Dict[str, Server]) -> str:
+    if not servers:
+        return ""
+    markdown_parts = [
+        "| Name | Type | Attributes |",
+        "| ---- | ---- | ---------- |",
+    ]
+    for server_name, server in servers.items():
+        markdown_parts.append(
+            f"| {server_name} | {server.type or ''} | {obj_attributes_to_markdown(server, {'type'}, True)} |"
+        )
+    return "\n".join(markdown_parts)
+
+
+def models_to_markdown(models: Dict[str, Model]) -> str:
+    return "\n".join(model_to_markdown(model_name, model) for model_name, model in models.items())
+
+
+def model_to_markdown(model_name: str, model: Model) -> str:
+    """
+    Generate Markdown representation for a specific model.
+
+    Args:
+        model_name (str): The name of the model.
+        model (Model): The model object.
+
+    Returns:
+        str: The Markdown representation of the model.
+    """
+    parts = [
+        f"### {model_name}",
+        f"*{description_to_markdown(model.description)}*",
+        "",
+        "| Field | Type | Attributes |",
+        "| ----- | ---- | ---------- |",
+    ]
+
+    # Append generated field rows
+    parts.append(fields_to_markdown(model.fields))
+    return "\n".join(parts)
+
+
+def fields_to_markdown(
+    fields: Dict[str, Field],
+    level: int = 0,
+) -> str:
+    """
+    Generate Markdown table rows for all fields in a model.
+
+    Args:
+        fields (Dict[str, Field]): The fields to process.
+        level (int): The level of nesting for indentation.
+
+    Returns:
+        str: A Markdown table rows for the fields.
+    """
+
+    return "\n".join(field_to_markdown(field_name, field, level) for field_name, field in fields.items())
+
+
+def field_to_markdown(field_name: str, field: Field, level: int = 0) -> str:
+    """
+    Generate Markdown table rows for a single field, including nested structures.
+
+    Args:
+        field_name (str): The name of the field.
+        field (Field): The field object.
+        level (int): The level of nesting for indentation.
+
+    Returns:
+        str: A Markdown table rows for the field.
+    """
+    tabs = TAB * level
+    arrow = ARROW if level > 0 else ""
+    column_name = f"{tabs}{arrow} {field_name}"
+
+    attributes = obj_attributes_to_markdown(field, {"type", "fields", "items", "keys", "values"}, True)
+
+    rows = [f"| {column_name} | {field.type} | {attributes} |"]
+
+    # Recursively handle nested fields, array, map
+    if field.fields:
+        rows.append(fields_to_markdown(field.fields, level + 1))
+    if field.items:
+        rows.append(field_to_markdown("items", field.items, level + 1))
+    if field.keys:
+        rows.append(field_to_markdown("keys", field.keys, level + 1))
+    if field.values:
+        rows.append(field_to_markdown("values", field.values, level + 1))
+
+    return "\n".join(rows)
+
+
+def definitions_to_markdown(definitions: Dict[str, Definition]) -> str:
+    if not definitions:
+        return ""
+    markdown_parts = [
+        "| Name | Type | Domain | Attributes |",
+        "| ---- | ---- | ------ | ---------- |",
+    ]
+    for definition_name, definition in definitions.items():
+        markdown_parts.append(
+            f"| {definition_name} | {definition.type or ''} | {definition.domain or ''} | {obj_attributes_to_markdown(definition, {'name', 'type', 'domain'}, True)} |",
+        )
+    return "\n".join(markdown_parts)
+
+
+def service_level_to_markdown(service_level: ServiceLevel | None) -> str:
+    if not service_level:
+        return ""
+    sections = {
+        "Availability": service_level.availability,
+        "Retention": service_level.retention,
+        "Latency": service_level.latency,
+        "Freshness": service_level.freshness,
+        "Frequency": service_level.frequency,
+        "Support": service_level.support,
+        "Backup": service_level.backup,
+    }
+    result = [f"### {name}\n{obj_attributes_to_markdown(attr)}\n" for name, attr in sections.items() if attr]
+    return "\n".join(result)
+
+
+def description_to_markdown(description: str | None) -> str:
+    return (description or "No description.").replace("\n", "<br>")
+
+
+def array_of_dict_to_markdown(array: List[Dict[str, str]]) -> str:
+    """
+    Convert a list of dictionaries to a Markdown table.
+
+    Args:
+        array (List[Dict[str, str]]): A list of dictionaries where each dictionary represents a row in the table.
+
+    Returns:
+        str: A Markdown formatted table.
+    """
+    if not array:
+        return ""
+
+    headers = []
+
+    for item in array:
+        headers += item.keys()
+    headers = list(dict.fromkeys(headers))  # Preserve order and remove duplicates
+
+    markdown_parts = [
+        "| " + " | ".join(headers) + " |",
+        "| " + " | ".join(["---"] * len(headers)) + " |",
+    ]
+
+    for row in array:
+        element = row
+        markdown_parts.append(
+            "| "
+            + " | ".join(
+                f"{str(element.get(header, ''))}".replace("\n", "<br>").replace("\t", TAB) for header in headers
+            )
+            + " |"
+        )
+
+    return "\n".join(markdown_parts) + "\n"
+
+
+def array_to_markdown(array: List[str]) -> str:
+    """
+    Convert a list of strings to a Markdown formatted list.
+
+    Args:
+        array (List[str]): A list of strings to convert.
+
+    Returns:
+        str: A Markdown formatted list.
+    """
+    if not array:
+        return ""
+    return "\n".join(f"- {item}" for item in array) + "\n"
+
+
+def dict_to_markdown(dictionary: Dict[str, str]) -> str:
+    """
+    Convert a dictionary to a Markdown formatted list.
+
+    Args:
+        dictionary (Dict[str, str]): A dictionary where keys are item names and values are item descriptions.
+
+    Returns:
+        str: A Markdown formatted list of items.
+    """
+    if not dictionary:
+        return ""
+
+    markdown_parts = []
+    for key, value in dictionary.items():
+        if isinstance(value, dict):
+            markdown_parts.append(f"- {key}")
+            nested_markdown = dict_to_markdown(value)
+            if nested_markdown:
+                nested_lines = nested_markdown.split("\n")
+                for line in nested_lines:
+                    if line.strip():
+                        markdown_parts.append(f"  {line}")
+        else:
+            markdown_parts.append(f"- {key}: {value}")
+    return "\n".join(markdown_parts) + "\n"
+
+
+def extra_to_markdown(obj: BaseModel, is_in_table_cell: bool = False) -> str:
+    """
+    Convert the extra attributes of a data contract to Markdown format.
+    Args:
+        obj (BaseModel): The data contract object containing extra attributes.
+        is_in_table_cell (bool): Whether the extra attributes are in a table cell.
+    Returns:
+        str: A Markdown formatted string representing the extra attributes of the data contract.
+    """
+    extra = obj.model_extra
+
+    if not extra:
+        return ""
+
+    bullet_char = "•"
+    value_line_ending = "" if is_in_table_cell else "\n"
+    row_suffix = "<br>" if is_in_table_cell else ""
+
+    def render_header(key: str) -> str:
+        return f"{bullet_char} **{key}:** " if is_in_table_cell else f"\n### {key.capitalize()}\n"
+
+    parts: list[str] = []
+    for key_extra, value_extra in extra.items():
+        if not value_extra:
+            continue
+
+        parts.append(render_header(key_extra))
+
+        if isinstance(value_extra, list) and len(value_extra):
+            if isinstance(value_extra[0], dict):
+                parts.append(array_of_dict_to_markdown(value_extra))
+            elif isinstance(value_extra[0], str):
+                parts.append(array_to_markdown(value_extra))
+        elif isinstance(value_extra, dict):
+            parts.append(dict_to_markdown(value_extra))
+        else:
+            parts.append(f"{str(value_extra)}{value_line_ending}")
+
+        if row_suffix:
+            parts.append(row_suffix)
+
+    return "".join(parts)

datacontract/export/mermaid_exporter.py

@@ -0,0 +1,110 @@
+from open_data_contract_standard.model import OpenDataContractStandard
+
+from datacontract.export.exporter import Exporter
+from datacontract.model.data_contract_specification import DataContractSpecification
+
+
+class MermaidExporter(Exporter):
+    def export(self, data_contract, model, server, sql_server_type, export_args) -> dict:
+        return to_mermaid(data_contract)
+
+
+def to_mermaid(data_contract_spec: DataContractSpecification | OpenDataContractStandard) -> str | None:
+    if isinstance(data_contract_spec, DataContractSpecification):
+        return dcs_to_mermaid(data_contract_spec)
+    elif isinstance(data_contract_spec, OpenDataContractStandard):
+        return odcs_to_mermaid(data_contract_spec)
+    else:
+        return None
+
+
+def dcs_to_mermaid(data_contract_spec: DataContractSpecification) -> str | None:
+    try:
+        if not data_contract_spec.models:
+            return None
+
+        mmd_entity = "erDiagram\n"
+        mmd_references = []
+
+        for model_name, model in data_contract_spec.models.items():
+            clean_model = _sanitize_name(model_name)
+            entity_block = ""
+
+            for field_name, field in model.fields.items():
+                clean_name = _sanitize_name(field_name)
+                field_type = field.type or "unknown"
+
+                is_pk = bool(field.primaryKey or (field.unique and field.required))
+                is_fk = bool(field.references)
+
+                entity_block += _field_line(clean_name, field_type, pk=is_pk, uk=bool(field.unique), fk=is_fk)
+
+                if field.references:
+                    references = field.references.replace(".", "·")
+                    parts = references.split("·")
+                    referenced_model = _sanitize_name(parts[0]) if len(parts) > 0 else ""
+                    referenced_field = _sanitize_name(parts[1]) if len(parts) > 1 else ""
+                    if referenced_model:
+                        label = referenced_field or clean_name
+                        mmd_references.append(f'"**{referenced_model}**" ||--o{{ "**{clean_model}**" : {label}')
+
+            mmd_entity += f'\t"**{clean_model}**" {{\n{entity_block}}}\n'
+
+        if mmd_references:
+            mmd_entity += "\n" + "\n".join(mmd_references)
+
+        return mmd_entity + "\n"
+
+    except Exception as e:
+        print(f"Error generating DCS mermaid diagram: {e}")
+        return None
+
+
+def odcs_to_mermaid(data_contract_spec: OpenDataContractStandard) -> str | None:
+    try:
+        if not data_contract_spec.schema_:
+            return None
+
+        mmd_entity = "erDiagram\n"
+
+        for schema in data_contract_spec.schema_:
+            schema_name = schema.name or schema.physicalName
+            entity_block = ""
+
+            if schema.properties:
+                for prop in schema.properties:
+                    clean_name = _sanitize_name(prop.name)
+                    indicators = ""
+
+                    if prop.primaryKey:
+                        indicators += "🔑"
+                    if getattr(prop, "partitioned", False):
+                        indicators += "🔀"
+                    if getattr(prop, "criticalDataElement", False):
+                        indicators += "⚠️"
+
+                    prop_type = prop.logicalType or prop.physicalType or "unknown"
+                    entity_block += f"\t{clean_name}{indicators} {prop_type}\n"
+
+            mmd_entity += f'\t"**{schema_name}**"' + "{\n" + entity_block + "}\n"
+
+        return f"{mmd_entity}\n"
+
+    except Exception as e:
+        print(f"Error generating ODCS mermaid diagram: {e}")
+        return None
+
+
+def _sanitize_name(name: str) -> str:
+    return name.replace("#", "Nb").replace(" ", "_").replace("/", "by")
+
+
+def _field_line(name: str, field_type: str, pk: bool = False, uk: bool = False, fk: bool = False) -> str:
+    indicators = ""
+    if pk:
+        indicators += "🔑"
+    if uk:
+        indicators += "🔒"
+    if fk:
+        indicators += "⌘"
+    return f"\t{name}{indicators} {field_type}\n"