Inspection

ggstyle exposes resolved policy as plain data before callers commit a finishing request. Inspection never draws a canvas, changes artists, installs a layout engine, or mutates global Matplotlib settings.

Semantic results

ggstyle.line(), ggstyle.points(), ggstyle.ribbon(), and ggstyle.guides() return concrete objects implementing ggstyle.RenderedResult:

result = gs.points(data, x="x", y="y", color="score", ax=ax)
audit_record = result.as_dict()
print(result.describe())

Geometry summaries contain the committed layer identifier, native artist count and type, trained scale descriptions, and diagnostics. Guide summaries contain native legend and colorbar counts and titles. Both are bounded strict-JSON representations: the original axes and live artists remain available on the concrete result but are never serialized. Each call returns fresh containers suitable for logs and snapshot tests.

Facet plans

ggstyle.facet_plan() exposes dataframe partitioning and layout decisions before any figure exists. Its ggstyle.FacetPlan inspection contains variables, resolved levels, fixed/free scale policy, layout shape, per-panel row counts, missing-row diagnostics, and the panel safety limit. Source data and the concrete positional indices used by later rendering are omitted from the bounded JSON representation.

ggstyle.facets() returns a ggstyle.FacetGrid whose matching as_dict() and describe() methods nest that plan and add only the applied theme, active panel count, diagnostics, and number of completed callback passes. Live figures, axes, callbacks, callback results, and dataframe contents are excluded.

The grid summary also reports whether facet date integration is configured, its mode and limit policy, the number of populated handles, and the number of independent registry groups. It does not serialize observation values; inspect the aligned native grid.date_handles when interactive access to those dates is needed.

Finishing plans

Pass dry_run=True to ggstyle.finish() to receive the same ggstyle.FinishPlan that a successful commit would retain:

plan = gs.finish(
    ax,
    title="Revenue",
    theme=gs.theme_spec("minimal", base_size=11),
    y=gs.axis(
        title="USD",
        labels=gs.label_currency("$", scale=1_000_000, suffix="M"),
    ),
    dry_run=True,
)

payload = plan.as_dict()
print(plan.describe())

as_dict() returns fresh JSON-compatible containers containing the requested text, nested theme, numeric-labeller and endpoint-label policy, resolved direct-label and layout actions, ordered managed changes, and diagnostics. describe() renders that same payload as deterministic, strict JSON. Neither form contains axes, artists, callables, mapping proxies, or pandas objects.

The representation is intended for logs, review, and snapshot tests. It is not a round-trip recipe format: reusable recipe serialization remains deferred until real composition use cases establish its schema.

Date-axis summaries

ggstyle.DateAxis.summary() returns an immutable ggstyle.AxisSummary. Its matching inspection methods expose the resolved coordinate mode, observation range, frequency, cadences, display timezone, and missing-value count:

summary = gs.dates(ax).ticks("monthly").summary()
audit_record = summary.as_dict()
print(summary.describe())

Timestamp values use ISO 8601 strings in the JSON-safe representation. The original summary.start and summary.end attributes remain pandas Timestamp objects for ordinary Python analysis.