artifact-parser 1.0.0__py3-none-any.whl

artifact_parser/__init__.py

@@ -0,0 +1,53 @@
+"""artifact-parser — a pluggable framework for parsing data tool artifacts.
+
+The framework is source-agnostic: each plugin owns one family of artifacts and
+registers itself with the shared :data:`~artifact_parser.core.registry.registry`.
+The first (and currently only) plugin parses dbt-core artifacts.
+
+The headline entry point is :func:`parse`, which sniffs any supported artifact
+and routes it to the right plugin::
+
+    from artifact_parser import parse
+    model = parse(json.loads(manifest_path.read_text()))
+
+For dbt-specific, version-pinned parsing, import from
+:mod:`artifact_parser.dbt` directly.
+
+The dbt plugin's generated code lives under ``artifact_parser/dbt/generated/``
+and may be deleted and rebuilt with ``codegen dbt``. While it is absent the dbt
+plugin simply does not register — the framework (and the codegen CLI it needs to
+rebuild itself) still imports cleanly.
+"""
+
+import importlib
+import warnings
+
+from artifact_parser.core import ArtifactParser
+from artifact_parser.core import ArtifactParserError
+from artifact_parser.core import BaseArtifactModel
+from artifact_parser.core import ParserRegistrationError
+from artifact_parser.core import ParserRegistry
+from artifact_parser.core import UnknownArtifactError
+from artifact_parser.core import registry
+
+try:
+    importlib.import_module("artifact_parser.dbt")  # registers the dbt plugin
+except ImportError:  # pragma: no cover - only when dbt/generated/ is dropped
+    warnings.warn(
+        "artifact_parser.dbt is unavailable (generated code missing). "
+        "Run `codegen dbt` to rebuild it.",
+        stacklevel=2,
+    )
+
+parse = registry.parse
+
+__all__ = [
+    "ArtifactParser",
+    "ArtifactParserError",
+    "BaseArtifactModel",
+    "ParserRegistrationError",
+    "ParserRegistry",
+    "UnknownArtifactError",
+    "parse",
+    "registry",
+]

artifact_parser/core/__init__.py

@@ -0,0 +1,19 @@
+"""Core parser framework: base model, plugin protocol, and the registry."""
+
+from artifact_parser.core.base import BaseArtifactModel
+from artifact_parser.core.exceptions import ArtifactParserError
+from artifact_parser.core.exceptions import ParserRegistrationError
+from artifact_parser.core.exceptions import UnknownArtifactError
+from artifact_parser.core.parser import ArtifactParser
+from artifact_parser.core.registry import ParserRegistry
+from artifact_parser.core.registry import registry
+
+__all__ = [
+    "ArtifactParser",
+    "ArtifactParserError",
+    "BaseArtifactModel",
+    "ParserRegistrationError",
+    "ParserRegistry",
+    "UnknownArtifactError",
+    "registry",
+]

artifact_parser/core/base.py

@@ -0,0 +1,13 @@
+"""Shared base model for every parsed artifact, regardless of source."""
+
+from pydantic import BaseModel
+
+
+class BaseArtifactModel(BaseModel):
+    """Base class for all artifact models across every parser plugin.
+
+    Each plugin (dbt-core today, others tomorrow) builds its typed models on
+    top of this so the framework has a single, predictable root type to reason
+    about. It is intentionally empty — it exists to be an anchor, not a place to
+    smuggle behaviour into.
+    """

artifact_parser/core/exceptions.py

@@ -0,0 +1,13 @@
+"""Exception types raised by the parser framework."""
+
+
+class ArtifactParserError(Exception):
+    """Base class for every error this package raises."""
+
+
+class UnknownArtifactError(ArtifactParserError):
+    """Raised when no registered parser recognises the given artifact."""
+
+
+class ParserRegistrationError(ArtifactParserError):
+    """Raised when a parser is registered under a name that is already taken."""

artifact_parser/core/parser.py

@@ -0,0 +1,28 @@
+"""The :class:`ArtifactParser` protocol every plugin implements."""
+
+from abc import ABC
+from abc import abstractmethod
+
+from artifact_parser.core.base import BaseArtifactModel
+
+
+class ArtifactParser(ABC):
+    """Contract for a parser plugin (e.g. the dbt-core artifacts plugin).
+
+    A plugin owns one *family* of artifacts. It answers two questions: "is this
+    blob mine?" (:meth:`can_parse`) and "turn it into a typed model"
+    (:meth:`parse`). The :data:`~artifact_parser.core.registry.registry`
+    dispatches to the first plugin that claims the blob, so plugins should keep
+    :meth:`can_parse` cheap and specific.
+    """
+
+    #: Stable, unique identifier for the plugin (e.g. ``"dbt"``).
+    name: str
+
+    @abstractmethod
+    def can_parse(self, artifact: dict) -> bool:
+        """Return ``True`` if this plugin recognises ``artifact``."""
+
+    @abstractmethod
+    def parse(self, artifact: dict) -> BaseArtifactModel:
+        """Parse ``artifact`` into a typed model, or raise on a mismatch."""

artifact_parser/core/registry.py

@@ -0,0 +1,72 @@
+"""A small registry that routes an artifact to the plugin that owns it."""
+
+from artifact_parser.core.base import BaseArtifactModel
+from artifact_parser.core.exceptions import ParserRegistrationError
+from artifact_parser.core.exceptions import UnknownArtifactError
+from artifact_parser.core.parser import ArtifactParser
+
+
+class ParserRegistry:
+    """Holds the known parser plugins and dispatches artifacts to them.
+
+    Registration order is preserved, so :meth:`parse` tries plugins in the
+    order they were added and returns the first match. There is one module-level
+    instance (:data:`registry`); most callers never build their own.
+    """
+
+    def __init__(self) -> None:
+        self._parsers: dict[str, ArtifactParser] = {}
+
+    def register(self, parser: ArtifactParser) -> None:
+        """Add ``parser`` to the registry, keyed by its ``name``.
+
+        Raises:
+            ParserRegistrationError: if the name is already taken.
+        """
+        if parser.name in self._parsers:
+            raise ParserRegistrationError(
+                f"A parser named {parser.name!r} is already registered."
+            )
+        self._parsers[parser.name] = parser
+
+    def unregister(self, name: str) -> None:
+        """Remove the parser registered under ``name``.
+
+        Raises:
+            UnknownArtifactError: if no parser is registered under ``name``.
+        """
+        if name not in self._parsers:
+            raise UnknownArtifactError(f"No parser named {name!r} is registered.")
+        del self._parsers[name]
+
+    def get(self, name: str) -> ArtifactParser:
+        """Return the parser registered under ``name``.
+
+        Raises:
+            UnknownArtifactError: if no parser is registered under ``name``.
+        """
+        if name not in self._parsers:
+            raise UnknownArtifactError(f"No parser named {name!r} is registered.")
+        return self._parsers[name]
+
+    def names(self) -> list[str]:
+        """Return the registered plugin names, in registration order."""
+        return list(self._parsers)
+
+    def parse(self, artifact: dict) -> BaseArtifactModel:
+        """Parse ``artifact`` with the first plugin that claims it.
+
+        Raises:
+            UnknownArtifactError: if no registered plugin recognises it.
+        """
+        for parser in self._parsers.values():
+            if parser.can_parse(artifact):
+                return parser.parse(artifact)
+        raise UnknownArtifactError(
+            "No registered parser recognises this artifact. "
+            f"Tried: {', '.join(self._parsers) or '(none registered)'}."
+        )
+
+
+#: The process-wide registry. Plugins register themselves against this.
+registry = ParserRegistry()

artifact_parser/dbt/__init__.py

@@ -0,0 +1,31 @@
+"""dbt-core artifact parser — the first plugin of the framework.
+
+Importing this package registers :class:`DbtArtifactParser` with the shared
+:data:`~artifact_parser.core.registry.registry`, so ``registry.parse(blob)``
+works as soon as ``artifact_parser`` is imported.
+
+The version-dependent code (the typed models, the schema-version lookup table,
+and the ``parse_*`` dispatch) is generated and lives under
+:mod:`artifact_parser.dbt.generated` — a directory you can delete and rebuild
+with ``codegen dbt``. The public ``parse_*`` names are re-exported here so that
+import path never changes.
+"""
+
+from artifact_parser.core.registry import registry
+from artifact_parser.dbt.generated.parser import parse_catalog
+from artifact_parser.dbt.generated.parser import parse_manifest
+from artifact_parser.dbt.generated.parser import parse_run_results
+from artifact_parser.dbt.generated.parser import parse_sources
+from artifact_parser.dbt.plugin import DbtArtifactParser
+
+dbt_parser = DbtArtifactParser()
+registry.register(dbt_parser)
+
+__all__ = [
+    "DbtArtifactParser",
+    "dbt_parser",
+    "parse_catalog",
+    "parse_manifest",
+    "parse_run_results",
+    "parse_sources",
+]

artifact_parser/dbt/generated/__init__.py

@@ -0,0 +1,9 @@
+"""Generated dbt code — DO NOT EDIT BY HAND.
+
+Everything in this package (the typed models, ``version_map.py``, and
+``parser.py``) is produced by ``codegen dbt`` from dbt-core's JSON schemas. The
+whole directory is safe to delete and rebuild::
+
+    rm -rf src/artifact_parser/dbt/generated
+    codegen dbt --skip-download   # or drop the flag to pull fresh schemas
+"""

artifact_parser/dbt/generated/models/__init__.py

@@ -0,0 +1 @@
+"""Typed pydantic models for every supported dbt artifact schema version."""

artifact_parser/dbt/generated/models/catalog/__init__.py

@@ -0,0 +1 @@
+"""Generated dbt artifact models."""

artifact_parser/dbt/generated/models/catalog/catalog_v1.py

@@ -0,0 +1,86 @@
+# generated by datamodel-codegen:
+#   filename:  catalog_v1.json
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import ConfigDict, Field
+
+from artifact_parser.core.base import BaseArtifactModel
+
+
+class Metadata(BaseArtifactModel):
+    model_config = ConfigDict(
+        extra="ignore",
+    )
+    dbt_schema_version: str | None = None
+    dbt_version: str | None = "1.11.6"
+    generated_at: str | None = None
+    invocation_id: str | None = None
+    invocation_started_at: str | None = None
+    env: dict[str, str] | None = None
+
+
+class Metadata1(BaseArtifactModel):
+    model_config = ConfigDict(
+        extra="ignore",
+    )
+    type: str
+    schema_: str = Field(..., alias="schema")
+    name: str
+    database: str | None = None
+    comment: str | None = None
+    owner: str | None = None
+
+
+class Columns(BaseArtifactModel):
+    model_config = ConfigDict(
+        extra="ignore",
+    )
+    type: str
+    index: int
+    name: str
+    comment: str | None = None
+
+
+class Stats(BaseArtifactModel):
+    model_config = ConfigDict(
+        extra="ignore",
+    )
+    id: str
+    label: str
+    value: bool | str | float | None
+    include: bool
+    description: str | None = None
+
+
+class Nodes(BaseArtifactModel):
+    model_config = ConfigDict(
+        extra="ignore",
+    )
+    metadata: Metadata1 = Field(..., title="TableMetadata")
+    columns: dict[str, Columns]
+    stats: dict[str, Stats]
+    unique_id: str | None = None
+
+
+class Sources(BaseArtifactModel):
+    model_config = ConfigDict(
+        extra="ignore",
+    )
+    metadata: Metadata1 = Field(..., title="TableMetadata")
+    columns: dict[str, Columns]
+    stats: dict[str, Stats]
+    unique_id: str | None = None
+
+
+class CatalogV1(BaseArtifactModel):
+    model_config = ConfigDict(
+        extra="ignore",
+    )
+    metadata: Metadata = Field(..., title="CatalogMetadata")
+    nodes: dict[str, Nodes]
+    sources: dict[str, Sources]
+    errors: list[str] | None = None
+    field_compile_results: Any = Field(None, alias="_compile_results")

artifact_parser/dbt/generated/models/manifest/__init__.py

@@ -0,0 +1 @@
+"""Generated dbt artifact models."""