API Reference

class pandera_catalog.CatalogViewReader(catalog)

Query generated SQL views from a catalog backend.

read_view(view_name)

Return a DataFrame for a named generated view.

Return type:

DataFrame

class pandera_catalog.PanderaCatalog(*, backend=None)

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': ...}, ...)>

property backend: SqlCatalogBackend | None

Return the configured SQL backend, if any.

export_projection(name)

Materialise and return the schema defined by projection name.

Return type:

DataFrameSchema

get(name)

Return the schema registered under name.

Parameters:

name (str) – Name of the schema to retrieve.

Return type:

pandera.DataFrameSchema

Raises:

KeyError – If name is not registered.

get_entry(name)

Return the full SchemaEntry for name.

Parameters:

name (str) – Name of the schema entry to retrieve.

Return type:

SchemaEntry

Raises:

KeyError – If name is not registered.

get_projection_entry(name)

Return the full projection entry registered under name.

Return type:

SchemaProjectionEntry

list()

Return a sorted list of all registered schema names.

Return type:

list[str]

list_projections()

Return a sorted list of all registered projection names.

Return type:

list[str]

register(name, schema, *, description=None, tags=None, overwrite=False)

Register a Pandera schema under name.

Parameters:

• name (str) – Unique identifier for the schema within this catalog.

• schema (DataFrameSchema) – A pandera.DataFrameSchema instance.

• description (str | None) – Optional human-readable description of the schema.

• tags (list[str] | None) – Optional list of string tags for categorisation.

• overwrite (bool) – When True, silently replace any existing entry with the same name. When False (default), raise KeyError if the name is already registered.

Raises:

KeyError – If name is already registered and overwrite is False.

Return type:

None

register_projection(name, steps, *, description=None, overwrite=False)

Register a named projection from ordered step definitions.

Parameters:

• name (str) – Unique projection name within this catalog.

• steps (list[SchemaProjectionStep | Mapping[str, object]]) – Ordered list of projection steps. Each step must include schema, kind, and names.

• description (str | None) – Optional human-readable description of the projection.

• overwrite (bool) – 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.

Return type:

None

remove(name)

Remove the schema registered under name.

Parameters:

name (str) – Name of the schema to remove.

Raises:

KeyError – If name is not registered.

Return type:

None

remove_projection(name)

Remove the projection registered under name.

Return type:

None

class pandera_catalog.SchemaEntry(name, schema, description=None, tags=<factory>)

A catalog entry wrapping a Pandera schema with metadata.

name

Unique name of the schema within the catalog.

schema

The Pandera DataFrameSchema instance.

description

Optional human-readable description.

tags

Optional list of string tags for categorisation or filtering.

class pandera_catalog.SchemaProjectionEntry(name, steps, description=None)

A named projection built from ordered schema selection steps.

class pandera_catalog.SchemaProjectionStep(schema, kind, names)

A single schema projection step.

class pandera_catalog.SqlCatalogBackend(engine=None, url=None)

Persist catalog schemas/projections and maintain tabular views.

initialize()

Create backend tables and tabular views.

Return type:

None

load_projections()

Return persisted projection entries.

Return type:

list[SchemaProjectionEntry]

load_schemas()

Return persisted schema entries.

Return type:

list[SchemaEntry]

remove_projection(projection_name)

Delete a persisted projection and materialized rows.

Return type:

None

remove_schema(schema_name)

Delete a persisted schema and its flattened rows.

Return type:

None

upsert_projection(entry, resolved_columns)

Insert or replace a projection and materialized projection rows.

Return type:

None

upsert_schema(entry)

Insert or replace a schema entry and its flattened rows.

Return type:

None

pandera_catalog.load_schema_from_yaml(path)

Load a Pandera DataFrameSchema from a YAML file.

The YAML file must follow the format produced by pandera.DataFrameSchema.to_yaml().

Parameters:

path (Union[str, Path]) – Path to the .yaml (or .yml) schema definition file.

Return type:

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"))

catalog	Core catalog abstraction for pandera-catalog.
schemas	Schema loading helpers for pandera-catalog.
types	Shared type aliases, dataclasses, and protocol helpers for pandera-catalog.
utils	Utility helpers for pandera-catalog.