Catalog

databaas_utils.catalog

The Iceberg REST catalog, wired for Lakekeeper's remote signer.

The important part of this module is what rest_catalog does not set.

pyiceberg implements remote signing only in pyiceberg.io.fsspec, selected by s3.signer; PyArrowFileIO has no signer support at all and is tried first for s3:// (SCHEMA_TO_FILE_IO). So a catalog that does not pin py-io-impl silently resolves to PyArrow and reaches S3 with whatever ambient credentials the process happens to carry — or fails. s3.remote-signing-enabled is a Java-Iceberg property name and does nothing here.

py-io-impl points at catalog_io.SigningFileIO, an FsspecFileIO that gives each table its own S3 client; pyiceberg's own shares one client between tables and threads and swaps the signer on it. Lakekeeper names the stock FsspecFileIO in every loadTable response, so py-catalog-impl selects catalog_io.LakekeeperCatalog to swap it back. See catalog_io.

s3.signer.uri and s3.signer.endpoint are deliberately left unset: the loadTable response supplies both and pyiceberg concatenates them. Setting a hand-built URI that already ends in /v1/aws/s3/sign yields .../v1/aws/s3/sign/v1/aws/s3/sign.

CatalogClient

CatalogClient(
    settings: LakehouseSettings,
    *,
    session: Session | None = None,
    timeout: float = REQUEST_TIMEOUT,
)

The slice of Lakekeeper's REST API that pyiceberg does not cover.

Usable as a context manager, which closes its HTTP session.

Parameters:

Name	Type	Description	Default
settings	LakehouseSettings	Which warehouse, as which identity.	required
session	Session | None	A requests.Session to use; one is created if omitted.	None
timeout	float	Per-request timeout in seconds.	REQUEST_TIMEOUT

Example

with CatalogClient(settings) as client: ... client.ensure_namespace("open_meteo")

settings property

settings: LakehouseSettings

The settings this client was built with.

warehouse_id

warehouse_id() -> str

The warehouse UUID, from /v1/config. Cached per client.

Raises:

Type	Description
LakehouseError	If Lakekeeper does not know the warehouse name.
HTTPError	On a non-2xx response, e.g. 401 or 403.

ensure_namespace

ensure_namespace(namespace: str | None = None) -> None

Create the namespace if absent. A 409 means someone else won the race.

Parameters:

Name	Type	Description	Default
namespace	str | None	Dotted namespace; settings.namespace if omitted.	None

close

close() -> None

Close the underlying HTTP session.

__enter__

__enter__() -> Self

Return self; the session closes on exit.

__exit__

__exit__(*exc: object) -> None

Close the session.

rest_catalog

rest_catalog(
    settings: LakehouseSettings, **overrides: str
) -> Catalog

A pyiceberg REST catalog bound to settings, signing through Lakekeeper.

No S3 credentials are ever placed in the properties; object storage is reached by asking Lakekeeper to sign each request. Needs the iceberg extra.

Parameters:

Name	Type	Description	Default
settings	LakehouseSettings	Which warehouse, as which identity.	required
**overrides	str	pyiceberg catalog properties that replace the defaults.	{}

Returns:

Type	Description
Catalog	A pyiceberg Catalog. Use fully qualified namespace.table
Catalog	identifiers with it.

Example

catalog = rest_catalog(settings) catalog.load_table("open_meteo.daily_summary").scan(limit=10).to_arrow()

catalog_properties

catalog_properties(
    settings: LakehouseSettings,
) -> dict[str, Any]

The properties handed to load_catalog. Separated out so it is testable.

Parameters:

Name	Type	Description	Default
settings	LakehouseSettings	Which warehouse, as which identity.	required

Returns:

Type	Description
dict[str, Any]	pyiceberg catalog properties with remote signing enabled and no S3 keys.