duckplus.examples.pi_demo#

Raspberry Pi typed-expression demo anchored around π calculations.

The prose that lived in docs.pi_demo now resides here so the code is the single source of truth. The helpers show how to combine duckplus.static_typed primitives to generate deterministic projection and aggregation SQL while preserving metadata such as dependencies and type annotations. Everything runs without importing DuckDB at module load so the example stays friendly to resource-constrained hosts.

Running the demo queries#

Execute the module directly to render the generated SQL and, when possible, fetch the results from DuckDB:

python -m duckplus.examples.pi_demo

If DuckDB is unavailable the script prints installation guidance alongside the projection and aggregation statements so you can still inspect the generated queries.

Type checker feedback#

The module includes reveal_type probes guarded by TYPE_CHECKING so tools like mypy can confirm the expression shapes. Running:

mypy -p duckplus.examples.pi_demo

produces output similar to:

note: Revealed type is "duckplus.static_typed.expressions.numeric.NumericExpression"
note: Revealed type is "duckplus.static_typed.expressions.numeric.NumericExpression"

This gives immediate assurance that downstream helpers receive strongly typed expressions with preserved dependencies.

Attributes#

_radius_probe

Classes#

CircleExpressions

Reusable expressions describing circle metrics.

Functions#

build_circle_expressions(→ CircleExpressions)

Construct numeric expressions for circle area and circumference.

project_circle_metrics(...)

Return aliased projections for radius, area, and circumference.

summarise_circle_metrics(...)

Produce aggregations that total area and circumference.

render_select_sql(→ str)

Render a SELECT statement using the provided expressions.

build_demo_queries(→ dict[str, str])

Generate demo SQL queries illustrating projection and aggregation.

run_duckdb_demo(→ Sequence[tuple[str, ...)

Execute the demo SQL against DuckDB if the package is installed.

main(→ None)

Entry point used when running the module as a script.

Module Contents#

duckplus.examples.pi_demo._radius_probe#
class duckplus.examples.pi_demo.CircleExpressions#

Reusable expressions describing circle metrics.

The trio of expressions—radius, area, and circumference—feed the projections and aggregations showcased when you execute the module as a script. Each retains the dependency metadata expected by summarise_circle_metrics().

radius: duckplus.static_typed.NumericExpression#
area: duckplus.static_typed.NumericExpression#
circumference: duckplus.static_typed.NumericExpression#
duckplus.examples.pi_demo.build_circle_expressions(radius_column: str = 'radius') → CircleExpressions#

Construct numeric expressions for circle area and circumference.

Parameters:

  • radius_column – Name of the column supplying circle radii.

  • described (The expressions power both the projection and aggregation queries)

  • π (in the module documentation. They demonstrate how literal values—such as)

  • explicit (and the 2 used for circumference—can be embedded with)

  • deterministic. (duck_type metadata so downstream render calls remain)

duckplus.examples.pi_demo.project_circle_metrics(radius_column: str = 'radius') → Sequence[duckplus.static_typed.AliasedExpression]#

Return aliased projections for radius, area, and circumference.

These projections correspond to the “projection” query printed when the demo runs. Each alias ensures the rendered SQL lines up with the sample output in the documentation and makes the resulting relation ergonomic to inspect.

duckplus.examples.pi_demo.summarise_circle_metrics(radius_column: str = 'radius') → Sequence[duckplus.static_typed.AliasedExpression]#

Produce aggregations that total area and circumference.

The aggregation is the second query executed by run_duckdb_demo(). It totals each derived metric while demonstrating how typed expressions compose with aggregation helpers such as sum.

duckplus.examples.pi_demo.render_select_sql(select_list: Iterable[duckplus.static_typed.TypedExpression], relation_sql: str) → str#

Render a SELECT statement using the provided expressions.

build_demo_queries uses this helper to produce the projection and aggregation SQL quoted in the module documentation. The function keeps the demo self-contained by avoiding reliance on higher-level relation objects.

duckplus.examples.pi_demo.build_demo_queries(radius_column: str = 'radius') → dict[str, str]#

Generate demo SQL queries illustrating projection and aggregation.

The returned dictionary includes projection and summary keys. When the module is executed as a script the queries are printed verbatim so they can be compared to the mypy output captured in the documentation.

duckplus.examples.pi_demo.run_duckdb_demo() → Sequence[tuple[str, Sequence[tuple[object, Ellipsis]]]]#

Execute the demo SQL against DuckDB if the package is installed.

The helper returns a list of (name, rows) tuples that mirror the console output produced by python -m duckplus.examples.pi_demo. A friendly RuntimeError guides readers towards pip install duckdb when the dependency is missing, matching the behaviour described in the module docstring.

duckplus.examples.pi_demo.main() → None#

Entry point used when running the module as a script.