hmp.open#

Open a project catalog backed by .hmp/index.duckdb. The argument is a project directory, the one holding project.toml and .hmp/index.duckdb, not the workspace root above it. With the default create=False it raises FileNotFoundError when no index exists; pass create=True to initialise an empty catalog. The default open is read-only; pass read_only=False for a writable handle.

Signature#

hmp.open(workspace, *, create=False, read_only=True) -> Catalog

Reference#

hydromodpy.open(workspace, *, create=False, read_only=True)[source]

Open a HydroModPy project catalog.

The single door to a workspace catalog: returns a hydromodpy.results.catalog.Catalog backed by <project>/.hmp/index.duckdb. It exposes object access (latest, best, find, cat[ref]), tabular access (frame, sql, list_simulations), schema discovery (describe, tables, columns, variables, metrics, stations), and per-id reads (read).

The default open is read-only: inspecting a catalog never migrates it, never rewrites a view, and never touches its mtime, so an archived project can be browsed without leaving a trace and a reader never contends with a running solve. Pass read_only=False (or create=True) for the writable handle used to initialise or annotate a catalog.

Return type:

Catalog

Parameters:

workspace (Any)
create (bool)
read_only (bool)

Parameters#

workspace: Project directory holding .hmp/index.duckdb (or a direct path to the .duckdb file).
create: False (default) raises FileNotFoundError when no catalog exists yet (no phantom catalog is created). True opens a writable handle and initialises an empty catalog.
read_only: True (default) opens the catalog read-only. Ignored when create=True (initialisation requires a writable handle).

Returns#

hydromodpy.results.catalog.Catalog: Catalog handle for the project.

Raises#

FileNotFoundError: If no index database is found and create is False.
hydromodpy.core.exceptions.CatalogError: If the DuckDB catalog file is locked, corrupted, or unreadable.

Examples#

>>> import hydromodpy as hmp
>>> cat = hmp.open("~/ws/projects/naizin")  
>>> cat.latest()  

Example#

import hydromodpy as hmp

catalog = hmp.open("~/hmp_workspace/projects/naizin")
latest = catalog.latest()