Proposal
Rename dazzle.back.print_schema to format_schema (or schema_to_text).
- def print_schema(spec: BackendSpec) -> str:
+ def format_schema(spec: BackendSpec) -> str:
"""Render the backend schema as a multi-line string."""
...Why
The current name implies stdout output (Python's print(...) convention). The function actually returns a string — callers have to do their own print(format_schema(spec)) if they want to display it. The companion helper inspect_schema(spec: BackendSpec) -> dict[str, Any] is correctly named (it returns a dict, doesn't side-effect).
Anyone reading the public-helpers list:
- inspect_schema: function (spec: 'BackendSpec') -> 'dict[str, Any]'
- print_schema: function (spec: 'BackendSpec') -> 'str'
…reasonably assumes print_schema writes to stdout. It doesn't. Pre-1.0 cleanup window is the time to fix this.
Blast radius
Top-level export in dazzle.back._LOADERS. Search for current call sites:
grep -rn "print_schema" src/ tests/ examples/ docs/
Likely small — print_schema is a documentation/admin helper, not on a critical render path. Each call site changes from dazzle.back.print_schema(...) to dazzle.back.format_schema(...). Update the _LOADERS mapping in src/dazzle/back/__init__.py. Regenerate the baseline:
dazzle inspect-api public-helpers --write
CHANGELOG entry under Changed + Removed. ADR-0003 (no backward compat shims) applies — clean break.
Companion issues
Same pre-1.0 cleanup spirit; collectively close the audit-surfaced rename pass per /improve cycles 113, 126, 131 (api_surface_audit sub-strategy).
Discovered by
/improve cycle 131 framework-ux lane, api_surface_audit of docs/api-surface/public-helpers.txt. See dev_docs/api-surface-audit-log.md for the cycle's full walk notes (17 entries audited, 1 proposal worth filing).
Proposal
Rename
dazzle.back.print_schematoformat_schema(orschema_to_text).Why
The current name implies stdout output (Python's
print(...)convention). The function actually returns a string — callers have to do their ownprint(format_schema(spec))if they want to display it. The companion helperinspect_schema(spec: BackendSpec) -> dict[str, Any]is correctly named (it returns a dict, doesn't side-effect).Anyone reading the public-helpers list:
…reasonably assumes
print_schemawrites to stdout. It doesn't. Pre-1.0 cleanup window is the time to fix this.Blast radius
Top-level export in
dazzle.back._LOADERS. Search for current call sites:grep -rn "print_schema" src/ tests/ examples/ docs/Likely small —
print_schemais a documentation/admin helper, not on a critical render path. Each call site changes fromdazzle.back.print_schema(...)todazzle.back.format_schema(...). Update the_LOADERSmapping insrc/dazzle/back/__init__.py. Regenerate the baseline:CHANGELOG entry under Changed + Removed. ADR-0003 (no backward compat shims) applies — clean break.
Companion issues
Same pre-1.0 cleanup spirit; collectively close the audit-surfaced rename pass per
/improvecycles 113, 126, 131 (api_surface_auditsub-strategy).Discovered by
/improvecycle 131 framework-ux lane,api_surface_auditofdocs/api-surface/public-helpers.txt. Seedev_docs/api-surface-audit-log.mdfor the cycle's full walk notes (17 entries audited, 1 proposal worth filing).