recon_gen.common.tree.datasets

Dataset tree nodes (L.1.7) + typed Column refs (L.1.17).

Dataset is a first-class tree concept: visuals and filters reference a Dataset instance by object ref instead of by string identifier, and the App walks the tree to derive the precise dependency graph — which Sheet / Visual / FilterGroup uses which Dataset.

The dependency graph drives: - Selective deploy (only re-create datasets that downstream changes

touch).

  • Matview REFRESH ordering (REFRESH only the matviews backing Datasets that an updated deploy surface depends on).

Construction-time check (in App.emit_analysis): every Dataset referenced from the tree must be registered on the App via app.add_dataset(). Catches “visual references undeclared dataset” at emit time, where the existing string-keyed pattern lets the mismatch flow through to deploy.

Typed Column refs (L.1.17 — fragility fix). Bare-string column names in Dim(ds, "column_name") were silently typo-able. The new path:

  • ds["column_name"] validates column_name against the dataset’s registered DatasetContract (raises KeyError at the wiring site on typos) and returns a typed Column wrapper.

  • Column chains into the field-well factories: ds["col"].dim(), ds["col"].sum(), ds["col"].distinct_count(), etc. The chained form is the preferred new style — single source of truth for the (dataset, column) pair, validated.

  • Bare strings still work as the escape hatch for cases where no contract is registered (test fixtures, kitchen-sink) — the resolver treats string and Column refs uniformly at emit.

Classes

Column(dataset, name)

Typed column reference — dataset object ref + column name.

Dataset(identifier, arn)

Tree node for one dataset registration on the App.
class recon_gen.common.tree.datasets.Column(dataset, name)[source]

Bases: object

Typed column reference — dataset object ref + column name.

Authors construct via ds["col_name"] (which validates against the contract). Pass to Dim/Measure constructors directly, or use the chained factories below for the most concise wiring:

ds[“amount”].sum() # Measure.sum ds[“recipient_id”].dim() # categorical Dim ds[“window_end”].date() # date Dim ds[“depth”].numerical() # numerical Dim ds[“recipient_id”].distinct_count()

Frozen + hashable so a Column can be reused across visual slots (the chain ds["col"] returns a value-equal Column each time; ds["col"] == ds["col"] is True, useful for set membership in column-coverage tests).

Imports are lazy inside the factory methods to break the Dataset → Column → Dim/Measure → Dataset circular import.

Parameters:
average(*, field_id=AUTO, currency=False, decimals=None)[source]
Return type:

Measure

Parameters:

  • field_id (str | Literal[_AutoSentinel.AUTO])

  • currency (bool)

  • decimals (int | None)

count(*, field_id=AUTO)[source]
Return type:

Measure

Parameters:

field_id (str | Literal[_AutoSentinel.AUTO])

dataset: Dataset
date(*, date_granularity='DAY', field_id=AUTO)[source]
Return type:

Dim

Parameters:

  • date_granularity (Literal['YEAR', 'QUARTER', 'MONTH', 'WEEK', 'DAY', 'HOUR', 'MINUTE', 'SECOND', 'MILLISECOND'] | None)

  • field_id (str | Literal[_AutoSentinel.AUTO])

dim(*, kind='categorical', field_id=AUTO)[source]
Return type:

Dim

Parameters:

  • kind (Literal['categorical', 'date', 'numerical'])

  • field_id (str | Literal[_AutoSentinel.AUTO])

distinct_count(*, field_id=AUTO)[source]
Return type:

Measure

Parameters:

field_id (str | Literal[_AutoSentinel.AUTO])

property human_name: str

Plain-English header label for this column (v8.5.0).

Looks up the column on the dataset’s registered contract and returns the contract’s human_name (override or auto-derived title-case). Returns the title-cased column name as a fallback if the dataset has no contract — keeps the test fixtures (which construct Datasets directly without going through build_dataset) usable without forcing a registry round-trip.

max(*, field_id=AUTO, currency=False, decimals=None)[source]
Return type:

Measure

Parameters:

  • field_id (str | Literal[_AutoSentinel.AUTO])

  • currency (bool)

  • decimals (int | None)

min(*, field_id=AUTO, currency=False, decimals=None)[source]
Return type:

Measure

Parameters:

  • field_id (str | Literal[_AutoSentinel.AUTO])

  • currency (bool)

  • decimals (int | None)

name: str
numerical(*, field_id=AUTO, currency=False)[source]
Return type:

Dim

Parameters:

  • field_id (str | Literal[_AutoSentinel.AUTO])

  • currency (bool)

sum(*, field_id=AUTO, currency=False, decimals=None)[source]
Return type:

Measure

Parameters:

  • field_id (str | Literal[_AutoSentinel.AUTO])

  • currency (bool)

  • decimals (int | None)

class recon_gen.common.tree.datasets.Dataset(identifier, arn)[source]

Bases: object

Tree node for one dataset registration on the App.

identifier is the logical identifier visuals/filters reference (the existing per-app DS_INV_ACCOUNT_NETWORK / DS_AR_TRANSACTIONS strings — values like "inv-account-network-ds"). arn is the AWS QuickSight DataSetArn the deployed analysis points at.

Frozen because Dataset acts as the dependency-graph KEY: it must be hashable so visuals/filters that reference it can be collected into set[Dataset] for the dependency walk.

ds["column_name"] returns a typed Column ref (validated against the dataset’s registered DatasetContract if one exists) — see Column docstring for the chained factory pattern.

Parameters:

  • identifier (str)

  • arn (str)

arn: str
emit_declaration()[source]
Return type:

DataSetIdentifierDeclaration

identifier: str