catalogkit-core 0.1.0__py3-none-any.whl

catalogkit/core/__init__.py

@@ -0,0 +1,49 @@
+"""Public package surface for catalogkit-core."""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .errors import CanonicalIdError, CatalogCoreError, MergeConflictError
+from .ids import (
+    asset_id,
+    column_id,
+    cte_id,
+    leaf_name,
+    model_id,
+    normalize_identifier,
+    normalize_identifier_part,
+    normalize_identifier_parts,
+    report_id,
+    schema_name,
+    split_qualified_identifier,
+    table_id,
+)
+from .merge import merge
+from .models import CatalogArtifact, Edge, Evidence, Node, Warning
+from .serialize import render_json
+
+__all__ = [
+    "__version__",
+    "asset_id",
+    "CatalogArtifact",
+    "CatalogCoreError",
+    "CanonicalIdError",
+    "column_id",
+    "cte_id",
+    "Edge",
+    "Evidence",
+    "leaf_name",
+    "merge",
+    "MergeConflictError",
+    "model_id",
+    "Node",
+    "normalize_identifier",
+    "normalize_identifier_part",
+    "normalize_identifier_parts",
+    "render_json",
+    "report_id",
+    "schema_name",
+    "split_qualified_identifier",
+    "table_id",
+    "Warning",
+]

catalogkit/core/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "0.1.0"

catalogkit/core/errors.py

@@ -0,0 +1,15 @@
+"""Shared errors for catalogkit-core."""
+
+from __future__ import annotations
+
+
+class CatalogCoreError(Exception):
+    """Base class for catalogkit-core failures."""
+
+
+class CanonicalIdError(CatalogCoreError):
+    """Raised when an identifier cannot be normalized into a canonical ID."""
+
+
+class MergeConflictError(CatalogCoreError):
+    """Raised when artifacts cannot be merged without losing information."""

catalogkit/core/ids.py

@@ -0,0 +1,149 @@
+"""Canonical identifier normalization and ID builders."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from .errors import CanonicalIdError
+
+_QUOTE_PAIRS = {
+    '"': '"',
+    "`": "`",
+    "[": "]",
+}
+
+
+def _strip_matching_quotes(value: str) -> str:
+    if len(value) < 2:
+        return value
+
+    first = value[0]
+    last = value[-1]
+    expected_last = _QUOTE_PAIRS.get(first)
+    if expected_last == last:
+        return value[1:-1]
+    return value
+
+
+def normalize_identifier(value: str) -> str:
+    """Normalize a possibly qualified identifier into canonical dotted form."""
+    parts = split_qualified_identifier(value)
+    return normalize_identifier_parts(parts)
+
+
+def normalize_identifier_parts(parts: Iterable[str]) -> str:
+    """Normalize already separated identifier parts into canonical dotted form."""
+    normalized_parts = [normalize_identifier_part(part) for part in parts if str(part).strip()]
+    if not normalized_parts:
+        raise CanonicalIdError("Identifier must contain at least one non-empty part.")
+    return ".".join(normalized_parts)
+
+
+def normalize_identifier_part(part: str) -> str:
+    """Normalize one identifier segment."""
+    value = str(part).strip()
+    if not value:
+        raise CanonicalIdError("Identifier part cannot be empty.")
+    if value == "*":
+        raise CanonicalIdError("Wildcard identifiers cannot be canonicalized.")
+    unquoted = _strip_matching_quotes(value).strip()
+    if not unquoted:
+        raise CanonicalIdError("Identifier part cannot be empty after unquoting.")
+    return unquoted.lower()
+
+
+def split_qualified_identifier(value: str) -> list[str]:
+    """Split a qualified identifier on dots while respecting quoted segments."""
+    text = str(value).strip()
+    if not text:
+        raise CanonicalIdError("Identifier cannot be empty.")
+
+    parts: list[str] = []
+    current: list[str] = []
+    quote_stack: list[str] = []
+
+    for char in text:
+        if quote_stack:
+            current.append(char)
+            if char == quote_stack[-1]:
+                quote_stack.pop()
+            continue
+
+        if char in _QUOTE_PAIRS:
+            quote_stack.append(_QUOTE_PAIRS[char])
+            current.append(char)
+            continue
+
+        if char == ".":
+            part = "".join(current).strip()
+            if not part:
+                raise CanonicalIdError(f"Invalid qualified identifier {value!r}.")
+            parts.append(part)
+            current = []
+            continue
+
+        current.append(char)
+
+    if quote_stack:
+        raise CanonicalIdError(f"Unclosed quote in identifier {value!r}.")
+
+    final_part = "".join(current).strip()
+    if not final_part:
+        raise CanonicalIdError(f"Invalid qualified identifier {value!r}.")
+    parts.append(final_part)
+    return parts
+
+
+def table_id(qualified_name: str) -> str:
+    return f"table:{normalize_identifier(qualified_name)}"
+
+
+def cte_id(name: str) -> str:
+    return f"cte:{normalize_identifier_part(name)}"
+
+
+def column_id(parent_qualified_name: str, column_name: str) -> str:
+    parent = normalize_identifier(parent_qualified_name)
+    column = normalize_identifier_part(column_name)
+    return f"column:{parent}.{column}"
+
+
+def model_id(qualified_name: str) -> str:
+    return f"model:{normalize_identifier(qualified_name)}"
+
+
+def report_id(qualified_name: str) -> str:
+    return f"report:{normalize_identifier(qualified_name)}"
+
+
+def asset_id(qualified_name: str) -> str:
+    return f"asset:{normalize_identifier(qualified_name)}"
+
+
+def schema_name(qualified_name: str) -> str | None:
+    normalized = normalize_identifier(qualified_name)
+    parts = normalized.split(".")
+    if len(parts) <= 1:
+        return None
+    return ".".join(parts[:-1])
+
+
+def leaf_name(qualified_name: str) -> str:
+    normalized = normalize_identifier(qualified_name)
+    return normalized.split(".")[-1]
+
+
+__all__ = [
+    "asset_id",
+    "column_id",
+    "cte_id",
+    "leaf_name",
+    "model_id",
+    "normalize_identifier",
+    "normalize_identifier_part",
+    "normalize_identifier_parts",
+    "report_id",
+    "schema_name",
+    "split_qualified_identifier",
+    "table_id",
+]

catalogkit/core/merge.py

@@ -0,0 +1,123 @@
+"""Artifact merge utilities."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .errors import MergeConflictError
+from .models import CatalogArtifact, Edge, Evidence, Node, Warning
+
+
+def merge(*artifacts: CatalogArtifact) -> CatalogArtifact:
+    """Merge multiple artifacts under the shared catalogkit-core rules."""
+    merged_nodes: dict[str, Node] = {}
+    merged_edges: dict[tuple[str, str, str], Edge] = {}
+    merged_warnings: dict[tuple[str, str, str | None], Warning] = {}
+
+    for artifact in artifacts:
+        for node in artifact.nodes:
+            existing = merged_nodes.get(node.id)
+            merged_nodes[node.id] = node if existing is None else _merge_node(existing, node)
+
+        for edge in artifact.edges:
+            key = (edge.kind, edge.source_id, edge.target_id)
+            existing = merged_edges.get(key)
+            merged_edges[key] = edge if existing is None else _merge_edge(existing, edge)
+
+        for warning in artifact.warnings:
+            merged_warnings[(warning.code, warning.message, warning.location)] = warning
+
+    return CatalogArtifact(
+        version=_merge_versions([artifact.version for artifact in artifacts]),
+        nodes=sorted(merged_nodes.values(), key=lambda node: node.id),
+        edges=sorted(
+            merged_edges.values(),
+            key=lambda edge: (edge.kind, edge.source_id, edge.target_id),
+        ),
+        warnings=sorted(
+            merged_warnings.values(),
+            key=lambda warning: (warning.code, warning.message, warning.location or ""),
+        ),
+    )
+
+
+def _merge_versions(versions: list[str]) -> str:
+    unique_versions = {version for version in versions if version}
+    if not unique_versions:
+        return "1"
+    if len(unique_versions) != 1:
+        raise MergeConflictError(
+            f"Cannot merge artifacts with different schema versions: {sorted(unique_versions)}"
+        )
+    return unique_versions.pop()
+
+
+def _merge_node(left: Node, right: Node) -> Node:
+    return Node(
+        id=left.id,
+        kind=_merge_scalar("node.kind", left.kind, right.kind, left.id),
+        name=_merge_scalar("node.name", left.name, right.name, left.id),
+        qualified_name=_merge_optional(
+            "node.qualified_name",
+            left.qualified_name,
+            right.qualified_name,
+            left.id,
+        ),
+        schema=_merge_optional("node.schema", left.schema_name, right.schema_name, left.id),
+        evidence=_merge_evidence(left.evidence, right.evidence),
+    )
+
+
+def _merge_edge(left: Edge, right: Edge) -> Edge:
+    return Edge(
+        kind=left.kind,
+        source_id=left.source_id,
+        target_id=left.target_id,
+        label=_merge_optional("edge.label", left.label, right.label, left.source_id),
+        confidence=_merge_scalar(
+            "edge.confidence",
+            left.confidence,
+            right.confidence,
+            f"{left.kind}:{left.source_id}->{left.target_id}",
+        ),
+        evidence=_merge_evidence(left.evidence, right.evidence),
+    )
+
+
+def _merge_scalar(field_name: str, left: Any, right: Any, owner: str) -> Any:
+    if left != right:
+        raise MergeConflictError(
+            f"Conflicting {field_name} values for {owner!r}: {left!r} != {right!r}"
+        )
+    return left
+
+
+def _merge_optional(field_name: str, left: Any, right: Any, owner: str) -> Any:
+    if left in (None, ""):
+        return right
+    if right in (None, ""):
+        return left
+    if left != right:
+        raise MergeConflictError(
+            f"Conflicting {field_name} values for {owner!r}: {left!r} != {right!r}"
+        )
+    return left
+
+
+def _merge_evidence(left: list[Evidence], right: list[Evidence]) -> list[Evidence]:
+    seen: set[tuple[str | None, str | None, str | None, str]] = set()
+    merged: list[Evidence] = []
+
+    for evidence in [*left, *right]:
+        key = (
+            evidence.file,
+            evidence.location,
+            evidence.expression,
+            evidence.confidence,
+        )
+        if key in seen:
+            continue
+        seen.add(key)
+        merged.append(evidence)
+
+    return merged

catalogkit/core/models.py

@@ -0,0 +1,55 @@
+"""Shared artifact models for CatalogKit."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+Confidence = Literal["high", "medium", "low"]
+NodeKind = Literal["table", "cte", "column", "model", "report", "asset"]
+EdgeKind = Literal["depends_on", "feeds", "derives_from", "references", "joins"]
+
+
+class Evidence(BaseModel):
+    file: str | None = None
+    location: str | None = None
+    expression: str | None = None
+    confidence: Confidence = "medium"
+
+
+class Warning(BaseModel):
+    code: str
+    message: str
+    location: str | None = None
+
+
+class Node(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str
+    kind: NodeKind
+    name: str
+    qualified_name: str | None = None
+    schema_name: str | None = Field(
+        default=None,
+        alias="schema",
+        serialization_alias="schema",
+    )
+    evidence: list[Evidence] = Field(default_factory=list)
+
+
+class Edge(BaseModel):
+    kind: EdgeKind
+    source_id: str
+    target_id: str
+    label: str | None = None
+    confidence: Confidence = "high"
+    evidence: list[Evidence] = Field(default_factory=list)
+
+
+class CatalogArtifact(BaseModel):
+    version: str = "1"
+    nodes: list[Node] = Field(default_factory=list)
+    edges: list[Edge] = Field(default_factory=list)
+    warnings: list[Warning] = Field(default_factory=list)

catalogkit/core/serialize.py

@@ -0,0 +1,10 @@
+"""Serialization helpers for CatalogKit artifacts."""
+
+from __future__ import annotations
+
+from .models import CatalogArtifact
+
+
+def render_json(artifact: CatalogArtifact) -> dict:
+    """Return the canonical JSON-serializable artifact."""
+    return artifact.model_dump(mode="json", by_alias=True)

catalogkit_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: catalogkit-core
+Version: 0.1.0
+Summary: Shared artifact models, canonical IDs, and merge semantics for CatalogKit.
+Author: ClearMetric Labs
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Clearmetric-Labs/CatalogKit
+Project-URL: Source, https://github.com/Clearmetric-Labs/CatalogKit
+Project-URL: Issues, https://github.com/Clearmetric-Labs/CatalogKit/issues
+Keywords: catalog,lineage,metadata,graph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.10.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Provides-Extra: release
+Requires-Dist: build>=1.2.2; extra == "release"
+Requires-Dist: twine>=5.1.1; extra == "release"
+
+# catalogkit-core
+
+`catalogkit-core` is the shared consistency layer for every CatalogKit module.
+
+It owns:
+
+- artifact schema versioning
+- canonical ID normalization
+- shared graph models
+- deterministic JSON serialization
+- merge semantics
+
+It does **not** perform extraction by itself. Tool packages such as `catalogkit-query`
+depend on `catalogkit-core` and emit artifacts that follow its contract.
+
+## Install
+
+```bash
+python -m pip install catalogkit-core
+```
+
+## Imports
+
+```python
+from catalogkit.core import CatalogArtifact, Edge, Evidence, Node, Warning, merge
+```
+
+For local development:
+
+```bash
+python -m pip install -e ".[dev,release]"
+```
+
+## Contract
+
+The source of truth for the shared artifact contract is
+[`docs/contract.md`](docs/contract.md).

catalogkit_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+catalogkit/core/__init__.py,sha256=BA2M718ODcIomKTxn-Wq23xQW4b2Seyb-kahbrPI_PA,1060
+catalogkit/core/_version.py,sha256=VDsBswzfU7gNsBkIaxxV6tsi0ixlms3WjN7HYgZJZ2g,46
+catalogkit/core/errors.py,sha256=Rtv4GhUQjETARUdBkwhhQUSovBKd5MHMrhtfMc23lfw,410
+catalogkit/core/ids.py,sha256=FATrzpvFTi0qsXS377QnA-tiyDUg9uD-763nVgza2zs,4160
+catalogkit/core/merge.py,sha256=1BJOi9-LUIakIP2L1iK1jqVfmgDNr6O9KmDw60DNLDM,4111
+catalogkit/core/models.py,sha256=49kJBeA0F7j4DFEsW5sPXeZGOVZbAWv1p11fF56f4Iw,1388
+catalogkit/core/serialize.py,sha256=tm6X2pVoWfLfpCYZw8-IRMhaqL2vcvG-uftYYU2y8MY,299
+catalogkit_core-0.1.0.dist-info/METADATA,sha256=NUBqss2fwTYB5ixDn8_VYkbFlUOxLWpv499TKHu7Vho,1968
+catalogkit_core-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+catalogkit_core-0.1.0.dist-info/top_level.txt,sha256=RsnUdiXrSqkJn7elbvcSi3dAxxLtc6rLuzPGHGR_44I,11
+catalogkit_core-0.1.0.dist-info/RECORD,,

catalogkit_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

catalogkit_core-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+catalogkit