API reference

The dscat Python package. The command-line interface is described in the CLI guide; this page documents the importable API that backs it. Each entry links to a page generated from the source docstrings.

Data model

The dataclasses that flow from the adapters into the index, and the configuration that drives them.

model.FeatureRow	One dictionary variable, normalised for the index.
model.TableRow	One physical CSV file in a dataset version.
config.DatasetConfig	One dataset's adapter configuration, loaded from a JSON file.
config.Version	One discovered version of a dataset: a vendor ship folder.

Catalogue index

The SQLite catalogue and its typed read and write helpers. The tables it builds are described in Catalogue schema.

index.Catalogue

A connection to the SQLite catalogue index.

Ingestion

Discovering versions, parsing dictionaries, and building the index.

ingest.run_ingest	Build or refresh the catalogue index from data/.
ingest.IngestSummary	What one dataset contributed to the index during ingestion.
adapters.parse	Parse a version's dictionary into feature rows using the configured layout.
config.discover_versions	Return versions for one dataset, newest first.
config.load_configs	Built-in adapters, with optional project overrides from <root>/datasets.
config.version_sort_key	Order versions: ISO dates > dotted-numeric > raw string.

Queries

Read queries over the catalogue, scoped to the latest version of each dataset by default.

queries.list_tables	List tables in scope, one aggregated row per logical table.
queries.describe	Return a table's rows, a page of its features, and the total feature count.
queries.search	Full-text search features by name, title, definition, value coding, and notes.
queries.expand_query	Build an FTS5 MATCH expression from a free-text query.
queries.find_feature	Look up features by name, table.name, or qualified id.
queries.feature_sources	Return up to four (role, file_path) source rows for a table.
queries.list_documents	List non-dictionary documentation files in scope.
queries.find_documents	Find documentation files whose title or path contains every token in name.
queries.latest_version_map	Map each dataset to its newest version id.

Diffing

Comparing a dataset’s dictionary across versions.

diff.diff_versions	Compare a dataset's dictionary between two versions.
diff.DiffResult	The differences between two versions of a dataset's dictionary.

Documentation files

Discovering and converting a version’s non-dictionary documents.

docs.discover_docs	Return (relative_path, kind, title) for documentation files under a version.
docs.Engine	A document-to-markdown conversion engine.
docs.resolve_engine	Return the engine used for src.
docs.convert_doc	Convert src to markdown at dest with engine, caching by mtime.
docs.extract_sections	Return windows of lines around each case-insensitive match of pattern.
docs.cache_path	Return the cache path for a document converted by engine.

Dictionary input

Reading Excel data dictionaries.

dictionary.sheet_names	Return the worksheet names in an Excel workbook, in document order.
dictionary.read_sheet	Read a worksheet as rows of cleaned string cells.

Output rendering

Rendering command results as a table, CSV, TSV, JSON, or Markdown.

output.Format	A serialisation format for tabular command output.
output.render	Render records in the requested format.

Paths and synonyms

Locating the repository and its catalogue, and loading query synonyms.

paths.find_repo_root	Walk up from start (or CWD) to the workspace root.
paths.data_root	Return the raw-datasets directory, <root>/data.
paths.catalogue_dir	Return the generated-catalogue directory, <root>/.catalogue.
paths.index_path	Return the path to the SQLite index, <root>/.catalogue/index.db.
paths.docs_cache_dir	Return the converted-documents cache directory, <root>/.catalogue/docs.
synonyms.load_synonyms	Load synonym pairs from the built-in groups and any project file.