pandera-catalog 0.2.0__py3-none-any.whl

pandera_catalog/__init__.py

@@ -0,0 +1,19 @@
+from importlib import metadata
+
+from .catalog import PanderaCatalog
+from .schemas import load_schema_from_yaml
+from .types import SchemaEntry, SchemaProjectionEntry, SchemaProjectionStep
+
+try:
+    __version__ = metadata.version("pandera_catalog")
+except metadata.PackageNotFoundError:
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "PanderaCatalog",
+    "load_schema_from_yaml",
+    "SchemaEntry",
+    "SchemaProjectionEntry",
+    "SchemaProjectionStep",
+    "__version__",
+]

pandera_catalog/catalog.py

@@ -0,0 +1,324 @@
+"""Core catalog abstraction for pandera-catalog.
+
+The :class:`PanderaCatalog` class is the primary entry-point for registering,
+looking up, listing, and removing Pandera schema entries.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import pandera.pandas as pa
+
+from .types import SchemaEntry, SchemaProjectionEntry, SchemaProjectionStep
+
+
+class PanderaCatalog:
+    """A registry for Pandera schemas.
+
+    Schemas are stored in memory by name.  A future version will persist
+    entries to a SQLAlchemy-backed database (SQLite by default).
+
+    Examples
+    --------
+    >>> from pandera_catalog import PanderaCatalog
+    >>> import pandera.pandas as pa
+    >>> catalog = PanderaCatalog()
+    >>> schema = pa.DataFrameSchema({"value": pa.Column(float)})
+    >>> catalog.register("my_schema", schema)
+    >>> catalog.get("my_schema")
+    <Schema DataFrameSchema(columns={'value': ...}, ...)>
+    """
+
+    def __init__(self) -> None:
+        self._store: dict[str, SchemaEntry] = {}
+        self._projections: dict[str, SchemaProjectionEntry] = {}
+
+    # ------------------------------------------------------------------
+    # Mutating operations
+    # ------------------------------------------------------------------
+
+    def register(
+        self,
+        name: str,
+        schema: pa.DataFrameSchema,
+        *,
+        description: str | None = None,
+        tags: list[str] | None = None,
+        overwrite: bool = False,
+    ) -> None:
+        """Register a Pandera schema under *name*.
+
+        Parameters
+        ----------
+        name:
+            Unique identifier for the schema within this catalog.
+        schema:
+            A :class:`pandera.DataFrameSchema` instance.
+        description:
+            Optional human-readable description of the schema.
+        tags:
+            Optional list of string tags for categorisation.
+        overwrite:
+            When ``True``, silently replace any existing entry with the same
+            name.  When ``False`` (default), raise :class:`KeyError` if the
+            name is already registered.
+
+        Raises
+        ------
+        KeyError
+            If *name* is already registered and *overwrite* is ``False``.
+        """
+        if name in self._store and not overwrite:
+            raise KeyError(
+                f"Schema '{name}' is already registered.  "
+                "Pass overwrite=True to replace it."
+            )
+        self._store[name] = SchemaEntry(
+            name=name,
+            schema=schema,
+            description=description,
+            tags=list(tags or []),
+        )
+
+    def register_projection(
+        self,
+        name: str,
+        steps: list[SchemaProjectionStep | Mapping[str, object]],
+        *,
+        description: str | None = None,
+        overwrite: bool = False,
+    ) -> None:
+        """Register a named projection from ordered step definitions.
+
+        Parameters
+        ----------
+        name:
+            Unique projection name within this catalog.
+        steps:
+            Ordered list of projection steps. Each step must include
+            ``schema``, ``kind``, and ``names``.
+        description:
+            Optional human-readable description of the projection.
+        overwrite:
+            When ``True``, replace any existing projection with the same name.
+
+        Raises
+        ------
+        KeyError
+            If any step schema is not registered, or if *name* already exists
+            and *overwrite* is ``False``.
+        ValueError
+            If *steps* are invalid, include duplicates, include unknown columns,
+            or include an unknown step kind.
+        NotImplementedError
+            If a ``kind: group`` step is provided.
+        """
+        if name in self._projections and not overwrite:
+            raise KeyError(
+                f"Projection '{name}' is already registered.  "
+                "Pass overwrite=True to replace it."
+            )
+
+        resolved_steps = self._normalise_projection_steps(steps)
+        resolved_columns = self._resolve_projection_columns(resolved_steps)
+        duplicate_columns = self._find_duplicate_columns(
+            [column for _, column in resolved_columns]
+        )
+        if duplicate_columns:
+            raise ValueError(
+                f"Projection columns contain duplicates across steps: "
+                f"{duplicate_columns!r}."
+            )
+
+        self._projections[name] = SchemaProjectionEntry(
+            name=name,
+            steps=resolved_steps,
+            description=description,
+        )
+
+    def remove(self, name: str) -> None:
+        """Remove the schema registered under *name*.
+
+        Parameters
+        ----------
+        name:
+            Name of the schema to remove.
+
+        Raises
+        ------
+        KeyError
+            If *name* is not registered.
+        """
+        if name not in self._store:
+            raise KeyError(f"Schema '{name}' is not registered.")
+        del self._store[name]
+
+    def remove_projection(self, name: str) -> None:
+        """Remove the projection registered under *name*."""
+        if name not in self._projections:
+            raise KeyError(f"Projection '{name}' is not registered.")
+        del self._projections[name]
+
+    # ------------------------------------------------------------------
+    # Read operations
+    # ------------------------------------------------------------------
+
+    def get(self, name: str) -> pa.DataFrameSchema:
+        """Return the schema registered under *name*.
+
+        Parameters
+        ----------
+        name:
+            Name of the schema to retrieve.
+
+        Returns
+        -------
+        pandera.DataFrameSchema
+
+        Raises
+        ------
+        KeyError
+            If *name* is not registered.
+        """
+        if name not in self._store:
+            raise KeyError(f"Schema '{name}' is not registered.")
+        return self._store[name].schema
+
+    def get_entry(self, name: str) -> SchemaEntry:
+        """Return the full :class:`~pandera_catalog.types.SchemaEntry` for *name*.
+
+        Parameters
+        ----------
+        name:
+            Name of the schema entry to retrieve.
+
+        Returns
+        -------
+        SchemaEntry
+
+        Raises
+        ------
+        KeyError
+            If *name* is not registered.
+        """
+        if name not in self._store:
+            raise KeyError(f"Schema '{name}' is not registered.")
+        return self._store[name]
+
+    def get_projection_entry(self, name: str) -> SchemaProjectionEntry:
+        """Return the full projection entry registered under *name*."""
+        if name not in self._projections:
+            raise KeyError(f"Projection '{name}' is not registered.")
+        return self._projections[name]
+
+    def export_projection(self, name: str) -> pa.DataFrameSchema:
+        """Materialise and return the schema defined by projection *name*."""
+        projection = self.get_projection_entry(name)
+        resolved_columns = self._resolve_projection_columns(projection.steps)
+        columns: dict[str, pa.Column] = {}
+        for schema_name, column_name in resolved_columns:
+            source_schema = self.get(schema_name)
+            columns[column_name] = source_schema.columns[column_name]
+        return pa.DataFrameSchema(columns=columns, name=projection.name)
+
+    def list(self) -> list[str]:
+        """Return a sorted list of all registered schema names.
+
+        Returns
+        -------
+        list[str]
+        """
+        return sorted(self._store.keys())
+
+    def list_projections(self) -> list[str]:
+        """Return a sorted list of all registered projection names."""
+        return sorted(self._projections.keys())
+
+    def __len__(self) -> int:
+        return len(self._store)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._store
+
+    def __repr__(self) -> str:
+        names = self.list()
+        projections = self.list_projections()
+        return f"PanderaCatalog(schemas={names!r}, projections={projections!r})"
+
+    @staticmethod
+    def _find_duplicate_columns(columns: list[str]) -> list[str]:
+        seen: set[str] = set()
+        duplicates: list[str] = []
+        for column in columns:
+            if column in seen and column not in duplicates:
+                duplicates.append(column)
+            seen.add(column)
+        return duplicates
+
+    def _normalise_projection_steps(
+        self, steps: list[SchemaProjectionStep | Mapping[str, object]]
+    ) -> list[SchemaProjectionStep]:
+        if not steps:
+            raise ValueError("Projection steps cannot be empty.")
+
+        normalised_steps: list[SchemaProjectionStep] = []
+        for step in steps:
+            if isinstance(step, SchemaProjectionStep):
+                normalised = step
+            elif isinstance(step, Mapping):
+                normalised = SchemaProjectionStep(
+                    schema=self._require_string(step, "schema"),
+                    kind=self._require_string(step, "kind"),
+                    names=self._require_string_list(step, "names"),
+                )
+            else:
+                raise ValueError("Projection steps must be mappings or SchemaProjectionStep.")
+
+            if normalised.kind not in {"columns", "group"}:
+                raise ValueError(f"Unknown projection step kind: {normalised.kind!r}.")
+
+            if normalised.kind == "group":
+                raise NotImplementedError("Projection step kind 'group' is not implemented.")
+
+            if normalised.schema not in self._store:
+                raise KeyError(f"Schema '{normalised.schema}' is not registered.")
+
+            if not normalised.names:
+                raise ValueError("Projection step names cannot be empty.")
+
+            normalised_steps.append(normalised)
+
+        return normalised_steps
+
+    def _resolve_projection_columns(
+        self, steps: list[SchemaProjectionStep]
+    ) -> list[tuple[str, str]]:
+        resolved: list[tuple[str, str]] = []
+        for step in steps:
+            source_columns = set(self._store[step.schema].schema.columns.keys())
+            unknown_columns = [name for name in step.names if name not in source_columns]
+            if unknown_columns:
+                raise ValueError(
+                    f"Projection columns not found in source schema '{step.schema}': "
+                    f"{unknown_columns!r}."
+                )
+            resolved.extend((step.schema, name) for name in step.names)
+        return resolved
+
+    @staticmethod
+    def _require_string(step: Mapping[str, object], key: str) -> str:
+        value = step.get(key)
+        if not isinstance(value, str) or not value:
+            raise ValueError(f"Projection step '{key}' must be a non-empty string.")
+        return value
+
+    @staticmethod
+    def _require_string_list(step: Mapping[str, object], key: str) -> list[str]:
+        value = step.get(key)
+        if not isinstance(value, list) or not all(
+            isinstance(item, str) and item for item in value
+        ):
+            raise ValueError(
+                f"Projection step '{key}' must be a list of non-empty strings."
+            )
+        return list(value)

pandera_catalog/schemas.py

@@ -0,0 +1,77 @@
+"""Schema loading helpers for pandera-catalog.
+
+This module provides utilities for loading Pandera schemas from YAML files
+and from plain Python dictionaries.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Union
+
+import pandera.pandas as pa
+import yaml
+
+
+def load_schema_from_yaml(path: Union[str, Path]) -> pa.DataFrameSchema:
+    """Load a Pandera :class:`~pandera.DataFrameSchema` from a YAML file.
+
+    The YAML file must follow the format produced by
+    :meth:`pandera.DataFrameSchema.to_yaml`.
+
+    Parameters
+    ----------
+    path:
+        Path to the ``.yaml`` (or ``.yml``) schema definition file.
+
+    Returns
+    -------
+    pandera.DataFrameSchema
+
+    Raises
+    ------
+    FileNotFoundError
+        If the file does not exist.
+    ValueError
+        If the file cannot be parsed as a Pandera schema.
+
+    Examples
+    --------
+    >>> from pathlib import Path
+    >>> from pandera_catalog.schemas import load_schema_from_yaml
+    >>> schema = load_schema_from_yaml(Path("schemas/my_schema.yaml"))
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Schema file not found: {path}")
+    return pa.DataFrameSchema.from_yaml(path)
+
+
+def load_schema_from_dict(definition: dict) -> pa.DataFrameSchema:
+    """Build a Pandera :class:`~pandera.DataFrameSchema` from a dictionary.
+
+    The dictionary must follow the same structure as Pandera's YAML
+    serialisation format.
+
+    Parameters
+    ----------
+    definition:
+        Mapping that describes the schema (columns, checks, etc.).
+
+    Returns
+    -------
+    pandera.DataFrameSchema
+
+    Examples
+    --------
+    >>> from pandera_catalog.schemas import load_schema_from_dict
+    >>> defn = {"columns": {"value": {"dtype": "float64"}}}
+    >>> schema = load_schema_from_dict(defn)
+    """
+    yaml_str = yaml.dump(definition)
+    return pa.DataFrameSchema.from_yaml(yaml_str)
+
+
+__all__ = [
+    "load_schema_from_yaml",
+    "load_schema_from_dict",
+]

pandera_catalog/types.py

@@ -0,0 +1,59 @@
+"""Shared type aliases, dataclasses, and protocol helpers for pandera-catalog."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import pandera.pandas as pa
+
+
+@dataclass
+class SchemaEntry:
+    """A catalog entry wrapping a Pandera schema with metadata.
+
+    Attributes
+    ----------
+    name:
+        Unique name of the schema within the catalog.
+    schema:
+        The Pandera :class:`~pandera.DataFrameSchema` instance.
+    description:
+        Optional human-readable description.
+    tags:
+        Optional list of string tags for categorisation or filtering.
+    """
+
+    name: str
+    schema: pa.DataFrameSchema
+    description: str | None = None
+    tags: list[str] = field(default_factory=list)
+
+    def __repr__(self) -> str:
+        tag_str = f", tags={self.tags!r}" if self.tags else ""
+        desc_str = f", description={self.description!r}" if self.description else ""
+        return f"SchemaEntry(name={self.name!r}{desc_str}{tag_str})"
+
+
+@dataclass
+class SchemaProjectionEntry:
+    """A named projection built from ordered schema selection steps."""
+
+    name: str
+    steps: list["SchemaProjectionStep"]
+    description: str | None = None
+
+    def __repr__(self) -> str:
+        desc_str = f", description={self.description!r}" if self.description else ""
+        return (
+            f"SchemaProjectionEntry(name={self.name!r}, steps={self.steps!r}{desc_str})"
+        )
+
+
+@dataclass
+class SchemaProjectionStep:
+    """A single schema projection step."""
+
+    schema: str
+    kind: str
+    names: list[str]
+
+
+__all__ = ["SchemaEntry", "SchemaProjectionEntry", "SchemaProjectionStep"]

pandera_catalog/utils/__init__.py

@@ -0,0 +1,3 @@
+"""Utility helpers for pandera-catalog."""
+
+__all__: list[str] = []

pandera_catalog-0.2.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: pandera-catalog
+Version: 0.2.0
+Summary: A database-backed catalog for defining and managing Pandera schemas.
+Author-email: Greg Elphick <11791585+elphick@users.noreply.github.com>
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.11
+Requires-Dist: pandas>=2.0
+Requires-Dist: pandera>=0.19
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: plotly<7,>=6.0; extra == 'all'
+Requires-Dist: pydantic>=2.0; extra == 'all'
+Provides-Extra: schema
+Requires-Dist: pydantic>=2.0; extra == 'schema'
+Provides-Extra: viz
+Requires-Dist: plotly<7,>=6.0; extra == 'viz'
+Description-Content-Type: text/markdown
+
+<h1 style="display: inline-flex; align-items: center; gap: 0.4rem; margin: 0;">
+  <img src="https://raw.githubusercontent.com/elphick/pandera-catalog/main/docs/_static/branding/pandera-catalog.svg" alt="pandera-catalog logo" width="72" style="display: block; margin-top: 20px;" />
+  <span>pandera-catalog</span>
+</h1>
+
+[![Run Tests](https://github.com/elphick/pandera-catalog/actions/workflows/build_and_test.yml/badge.svg?branch=main)](https://github.com/elphick/pandera-catalog/actions/workflows/build_and_test.yml)
+[![PyPI](https://img.shields.io/pypi/v/pandera-catalog?logo=python&logoColor=white)](https://pypi.org/project/pandera-catalog/)
+![Coverage](https://raw.githubusercontent.com/elphick/pandera-catalog/main/docs/_static/badges/coverage.svg)
+[![Python Versions](https://img.shields.io/pypi/pyversions/pandera-catalog)](https://pypi.org/project/pandera-catalog/)
+[![License](https://img.shields.io/github/license/elphick/pandera-catalog?cacheSeconds=86400)](https://pypi.org/project/pandera-catalog/)
+[![Open Issues](https://img.shields.io/github/issues/elphick/pandera-catalog?cacheSeconds=86400)](https://github.com/elphick/pandera-catalog/issues)
+
+## Overview
+
+`pandera-catalog` is a Python package that provides a database-backed catalog for registering, looking up, and
+managing [Pandera](https://pandera.readthedocs.io/) schemas. It is designed to grow into a SQLAlchemy-connected
+(SQLite initially) registry of schema entries, validation rules, and schema metadata — keeping schemas
+organized, discoverable, and version-aware.
+
+## Installation
+
+Install the base package:
+
+```bash
+pip install pandera-catalog
+```
+
+Or with `uv`:
+
+```bash
+uv add pandera-catalog
+```
+
+Install optional extras for schema validation helpers using Pydantic:
+
+```bash
+pip install "pandera-catalog[schema]"
+```
+
+## Quick Usage
+
+```python
+import pandera.pandas as pa
+from pandera_catalog import PanderaCatalog
+
+# Create a catalog
+catalog = PanderaCatalog()
+
+# Define a schema
+schema = pa.DataFrameSchema(
+    columns={
+        "id": pa.Column(int),
+        "value": pa.Column(float, pa.Check.greater_than(0)),
+    }
+)
+
+# Register the schema
+catalog.register("my_schema", schema)
+
+# Look up the schema
+retrieved = catalog.get("my_schema")
+print(retrieved)
+
+# List all registered schemas
+print(catalog.list())
+```
+
+## Loading schemas from YAML
+
+```python
+from pathlib import Path
+from pandera_catalog import PanderaCatalog
+from pandera_catalog.schemas import load_schema_from_yaml
+
+catalog = PanderaCatalog()
+schema = load_schema_from_yaml(Path("schemas/my_schema.yaml"))
+catalog.register("my_schema", schema)
+```
+
+See the [documentation](https://elphick.github.io/pandera-catalog/) and
+[examples](examples/) for more detail.

pandera_catalog-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pandera_catalog/__init__.py,sha256=5h7UHUqUFlNtA5CyNye4cYtUmBZSAJMEggyABN64uT4,477
+pandera_catalog/catalog.py,sha256=if6C6V-KTUiLW3INduWSgpp8mdjs8AA3pyYaRA30iw4,11165
+pandera_catalog/schemas.py,sha256=of4S_pUT_0BcWs00kdl4XIDHTqzInkrIWwqVp11LrYQ,1993
+pandera_catalog/types.py,sha256=BEyZhg9nJ51pLlizP6rfYplIqw0gKwX3aMVEe-NUI1w,1634
+pandera_catalog/utils/__init__.py,sha256=duRo6yjdtevOp8nneLMHqRA3OEah2FXyePeLZ1xx68U,68
+pandera_catalog-0.2.0.dist-info/METADATA,sha256=fjPHrCsOp-pjN1Vod1MqWssDlYcAa2EL10SujxLG1I0,3551
+pandera_catalog-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pandera_catalog-0.2.0.dist-info/licenses/LICENSE,sha256=WUlvMlvb1bMwFWopOL0z-7OO-JlkC5nYuzJj8e5Db5Y,1069
+pandera_catalog-0.2.0.dist-info/RECORD,,

pandera_catalog-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pandera_catalog-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Greg Elphick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.