forgegraph 0.1.0__tar.gz → 0.2.0__tar.gz

{forgegraph-0.1.0 → forgegraph-0.2.0}/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ForgeGraph follows [semantic versioning](https://semver.org). Before 1.0, a minor version may change how graphs look or how specs are written. From 0.1.0 on, each release's entry links its visual changelog: before and after images of every catalog card and regression graph that changed, made with `scripts/visual_changelog.py`.
 
+## 0.2.0 (2026-10-24)
+
+Images that changed: the [visual changelog](review/visual-changelog/0.2.0.html).
+
+### Changed
+
+- Error bars are black by default in both built-in themes, and their color (`layer.error_bar.color`) is a variable parameter: a GraphSpec may set `series` or any hex color.
+- Three internal modules are renamed so none shares a name with the API: `forgegraph.render` is `forgegraph.drawing`, `forgegraph.layout` is `forgegraph.layouts` and `forgegraph.blank` is `forgegraph.canvas`. `import forgegraph.layouts as m` now gives the module, not `fg.layout`. The API is unchanged.
+
+### Fixed
+
+- `forgegraph --version` and `--help` no longer load matplotlib and pandas, so they answer at once, even on a new install. The API loads on first use.
+- The README and the skill's reference say when the main config is written: the first time a command reads the configs, such as `catalog` or `render`.
+- Error bars on side-by-side bars (`series.offset: side_by_side`) are drawn on their own bars. Before, every series but the middle one had its error bars drawn where they were first placed, before layout, usually off the axes.
+
 ## 0.1.0 (2026-10-24)
 
 The first public release.

{forgegraph-0.1.0 → forgegraph-0.2.0}/CONTRIBUTING.md

@@ -9,12 +9,14 @@ uv sync
 uv run pre-commit install
 ```
 
-The checks a pull request must pass:
+While you work, `uv run pytest` runs the development suite: every test not marked slow, in parallel. The full suite adds the slow ones (every catalog card drawn, the image baselines, the catalog pages, and any test over a second). CI runs it on every pull request, and it's the one to run before a release:
 
 ```bash
-uv run pytest && uv run ruff check . && uv run pyright
+uv run pytest --full && uv run ruff check . && uv run pyright
 ```
 
+Mark a new test `@pytest.mark.slow` if it takes over a second (`uv run pytest --durations=20` lists the slowest).
+
 ## After changing a definition or how graphs are drawn
 
 A new or changed parameter needs its card in the matching catalog file under `src/forgegraph/catalogs/`; the build refuses a catalog that misses one.

{forgegraph-0.1.0 → forgegraph-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgegraph
-Version: 0.1.0
+Version: 0.2.0
 Summary: Consistent, high-quality graphs from pandas DataFrames, for people and AI agents. Early development.
 Project-URL: Repository, https://github.com/sskaye/forgegraph
 Author: Steven Kaye
@@ -123,7 +123,7 @@ Every named theme, format, GraphSpec, layout and schedule comes from a **pack**,
 
 A **config** lists the packs that may be used:
 
-- The main config, `~/.config/forgegraph/config.toml` (or the file `FORGEGRAPH_CONFIG` names), applies to all work. ForgeGraph writes it the first time it runs, listing the built-in packs.
+- The main config, `~/.config/forgegraph/config.toml` (or the file `FORGEGRAPH_CONFIG` names), applies to all work. ForgeGraph writes it, listing the built-in packs, the first time a command reads the configs, such as `catalog` or `render`.
 - A folder config, `forgegraph.toml`, applies to the files in its folder and every folder below it. A file may use only the packs it lists.
 - A pack that a folder config lists but the main config doesn't still works, but it's non-standard: graphs drawn with it are watermarked, and ForgeGraph's commands say so. That way you can make and try a pack without changing an organization's main config.
 
@@ -169,16 +169,16 @@ uv sync && uv run pre-commit install
 ```
 
 ```bash
-uv run pytest && uv run ruff check . && uv run pyright
+uv run pytest --full && uv run ruff check . && uv run pyright
 ```
 
 ## Repository map
 
 - **src/forgegraph/**: the package.
-  - `graph.py`: the Python API (`fg.xy`, `fg.render`, `fg.graphspec`, `fg.load`) and the `Graph` object; `blank.py`: the themed canvas.
+  - `graph.py`: the Python API (`fg.xy`, `fg.render`, `fg.graphspec`, `fg.load`) and the `Graph` object; `canvas.py`: the themed canvas.
   - **cli/**: the `forgegraph` command.
   - **spec/**: reading, checking and resolving specs, and the provenance record.
-  - **render/**: drawing, layout and lint. **layout/**: layouts. **jobs/**: scheduled renders.
+  - **drawing/**: drawing, layout and lint. **layouts/**: layouts. **jobs/**: scheduled renders.
   - **packs/**: packs and configs, and the built-in packs `forgegraph_base` and `forgegraph_base_2`. **fonts/**: bundled fonts and their licences.
   - **graph_types/**, **layers/**: the graph type and layer type definitions. **catalog/**, **catalogs/**: the catalog builder, and each definition's catalog file.
   - **skill/forgegraph/**: the agent skill.

{forgegraph-0.1.0 → forgegraph-0.2.0}/README.md

@@ -98,7 +98,7 @@ Every named theme, format, GraphSpec, layout and schedule comes from a **pack**,
 
 A **config** lists the packs that may be used:
 
-- The main config, `~/.config/forgegraph/config.toml` (or the file `FORGEGRAPH_CONFIG` names), applies to all work. ForgeGraph writes it the first time it runs, listing the built-in packs.
+- The main config, `~/.config/forgegraph/config.toml` (or the file `FORGEGRAPH_CONFIG` names), applies to all work. ForgeGraph writes it, listing the built-in packs, the first time a command reads the configs, such as `catalog` or `render`.
 - A folder config, `forgegraph.toml`, applies to the files in its folder and every folder below it. A file may use only the packs it lists.
 - A pack that a folder config lists but the main config doesn't still works, but it's non-standard: graphs drawn with it are watermarked, and ForgeGraph's commands say so. That way you can make and try a pack without changing an organization's main config.
 
@@ -144,16 +144,16 @@ uv sync && uv run pre-commit install
 ```
 
 ```bash
-uv run pytest && uv run ruff check . && uv run pyright
+uv run pytest --full && uv run ruff check . && uv run pyright
 ```
 
 ## Repository map
 
 - **src/forgegraph/**: the package.
-  - `graph.py`: the Python API (`fg.xy`, `fg.render`, `fg.graphspec`, `fg.load`) and the `Graph` object; `blank.py`: the themed canvas.
+  - `graph.py`: the Python API (`fg.xy`, `fg.render`, `fg.graphspec`, `fg.load`) and the `Graph` object; `canvas.py`: the themed canvas.
   - **cli/**: the `forgegraph` command.
   - **spec/**: reading, checking and resolving specs, and the provenance record.
-  - **render/**: drawing, layout and lint. **layout/**: layouts. **jobs/**: scheduled renders.
+  - **drawing/**: drawing, layout and lint. **layouts/**: layouts. **jobs/**: scheduled renders.
   - **packs/**: packs and configs, and the built-in packs `forgegraph_base` and `forgegraph_base_2`. **fonts/**: bundled fonts and their licences.
   - **graph_types/**, **layers/**: the graph type and layer type definitions. **catalog/**, **catalogs/**: the catalog builder, and each definition's catalog file.
   - **skill/forgegraph/**: the agent skill.

{forgegraph-0.1.0 → forgegraph-0.2.0}/docs/architecture.md

@@ -502,8 +502,8 @@ forgegraph/
 │   ├── graph_types/   # xy/, bar/ — graph_type.yaml + render.py + samples/
 │   ├── layers/        # reference_line/, note/, … — layer.yaml + render.py
 │   ├── fonts/         # bundled fonts
-│   ├── render/        # matplotlib engine, text markup, lint, export, provenance
-│   ├── layout/        # multi-panel figures and dashboards
+│   ├── drawing/       # matplotlib engine, text markup, lint, export, provenance
+│   ├── layouts/       # multi-panel figures and dashboards
 │   ├── jobs/          # running a schedule, status files
 │   ├── packs/         # finding packs and configs; the built-in packs forgegraph_base/ and forgegraph_base_2/
 │   ├── catalog/       # HTML catalog, Forgemark carry-over

{forgegraph-0.1.0 → forgegraph-0.2.0}/docs/decisions.md

@@ -73,11 +73,11 @@ Decisions made while building that refine or depart from [architecture.md](archi
 
 **Default look, round 1 (Steven).** The default format's height is auto (the plot box keeps plot\_box.aspect) and its base font 18 pt. Tick labels: a y label's digits are centred on its tick, and the new theme parameter tick.label\_gap\_mult sets the gap from a tick to its label's digits on both axes (matplotlib measured both from a text box that reaches well above the digits). A colour bar is exactly the plot box's height, so an auto figure size can't stretch it. Tests draw at their own fixed size (150 × 140 mm, 12 pt), so tuning the defaults doesn't change what they check.
 
-**Text is measured to its letters (Steven, phase 3).** Matplotlib spaces text by a box sized for the font's tallest letters and deepest descenders, so its gaps aren't the gaps you see. Following the CSS `text-box: trim-both cap alphabetic` convention, Figma's vertical trim and D3's axis offsets, a text's edges run from the font's capital height to its baseline and grow only where its letters reach further (superscripts, descenders). Rows of text share one set of edges; collision checks use the letters themselves. forgegraph/render/text.py measures; render/spacing.py sets the tick-label, axis-title and title gaps from it; render/figure.py lays the figure out itself (no matplotlib layout engine), placing the plot box so what's drawn sits a fixed margin from each edge; render/key.py draws legends and style keys. New theme parameters: title.gap\_mult, axis\_title.gap\_mult; legend title\_align, frame\_width\_mult, padding\_mult (one value for every side), title\_gap\_mult, row\_gap\_mult, handle\_length\_mult, handle\_gap\_mult, inset\_mult; color\_bar width\_mult and gap\_mult (its ticks and title use the axes' settings); watermark weight, angle and span (it is centred on, and fitted to, the plot box); tick.minor\_num, minor\_length\_mult and minor\_width\_mult.
+**Text is measured to its letters (Steven, phase 3).** Matplotlib spaces text by a box sized for the font's tallest letters and deepest descenders, so its gaps aren't the gaps you see. Following the CSS `text-box: trim-both cap alphabetic` convention, Figma's vertical trim and D3's axis offsets, a text's edges run from the font's capital height to its baseline and grow only where its letters reach further (superscripts, descenders). Rows of text share one set of edges; collision checks use the letters themselves. forgegraph/drawing/text.py measures; drawing/spacing.py sets the tick-label, axis-title and title gaps from it; drawing/figure.py lays the figure out itself (no matplotlib layout engine), placing the plot box so what's drawn sits a fixed margin from each edge; drawing/key.py draws legends and style keys. New theme parameters: title.gap\_mult, axis\_title.gap\_mult; legend title\_align, frame\_width\_mult, padding\_mult (one value for every side), title\_gap\_mult, row\_gap\_mult, handle\_length\_mult, handle\_gap\_mult, inset\_mult; color\_bar width\_mult and gap\_mult (its ticks and title use the axes' settings); watermark weight, angle and span (it is centred on, and fitted to, the plot box); tick.minor\_num, minor\_length\_mult and minor\_width\_mult.
 
 **Default look, round 2 (Steven).** Legend rows and the title-to-first-entry gap are about half what they were, the sample-to-name gap 20% less, and the legend title is left-aligned. series.marker\_edge\_width\_mult is 0.06. interior\_label.max\_axis\_extension is a limit: the x-axis grows by the least that fits the labels. The example GraphSpec titles its color bar by column.
 
-**Default look, round 3 (Steven).** Roboto (SIL Open Font License) is the default font, chosen from a comparison of 13 open fonts. Major ticks on linear axes come from a published algorithm chosen by tick.algorithm (render/ticks.py): extended\_wilkinson (Talbot, Lin & Hanrahan 2010, the default), wilkinson, heckbert, nelder (AS 96), r\_pretty or matplotlib; each gets a target label count from the axis length. Text is drawn without font hinting, so it has the same width at every resolution and what's laid out is what's saved; the box lines' half-widths count in the layout's visible extent, so the figure's margins are exact.
+**Default look, round 3 (Steven).** Roboto (SIL Open Font License) is the default font, chosen from a comparison of 13 open fonts. Major ticks on linear axes come from a published algorithm chosen by tick.algorithm (drawing/ticks.py): extended\_wilkinson (Talbot, Lin & Hanrahan 2010, the default), wilkinson, heckbert, nelder (AS 96), r\_pretty or matplotlib; each gets a target label count from the axis length. Text is drawn without font hinting, so it has the same width at every resolution and what's laid out is what's saved; the box lines' half-widths count in the layout's visible extent, so the figure's margins are exact.
 
 **Parameter names and the catalog page, round 4 (Steven).** Parameters nest in categories and sub-categories to any depth (a mapping inside a category is a sub-category); no path is a prefix of another, across kinds. No parameter name says \_mult: every size, width, length and gap is × figure.base\_size. The scheme: theme font, background, title, axis (title, tick, tick.label, tick.minor), plot\_area, grid, series (line, marker, benchmark), legend (label, direct, key, color\_bar), error\_bar, watermark; format figure, output, provenance; graph type axis (x, y), encoding (color, line\_style, marker\_shape, marker\_fill, detail, order), benchmark, mark (line, marker), legend (method, key.title.text, color\_bar.title.text). Where a standard term exists it follows Vega-Lite (encoding, mark, detail), keeping ForgeGraph's nesting, snake\_case and units; Vega-Lite's names weren't adopted wholesale, since a third of the parameters have no equivalent there. "Legend" is the umbrella for every way of naming what colors and styles mean (Vega-Lite's usage); the legend methods are direct, key and none, chosen by legend.method within the theme's legend.methods. series.colors is a named palette (color\_blind, Tableau's Color Blind palette; tableau\_10; okabe\_ito; tol\_bright; tol\_muted) or a list of hex colors. legend.color\_bar.layout places a color bar's title: title\_above (the default), title\_along (reading downward, its baseline facing the bar) or below (a horizontal bar under the x-axis title). The catalog page writes allowed values tersely (float > 0, int ≥ 0, float, 0-1, hex color code, alternatives separated by |, None last, lists in []), has no baseline-value column, groups each table by category, and shows cards only for variable parameters; the perturbation test still draws every card in the catalog files. The default format saves at 600 dpi, and its output.file\_types is variable (default [png]).
 
@@ -111,13 +111,13 @@ Decisions made while building that refine or depart from [architecture.md](archi
 
 **The layout always fits its tick labels.** The layout lays out, measures the room needed around the plot box, and repeats until a pass changes the figure's size by under 0.001 in and moves the box by under 0.0001 of the figure. Tick labels can keep it from settling: a taller box gets more, wider labels, which make it shorter again. After 6 unsettled passes it lays out once more with, on each side, the most room either of the last two passes needed: an alternation has both its states there, so whichever labels the final draw has fit. Earlier passes, made while the figure was far from its size, don't count; including them left too little room on a graph that was settling slowly. Ticks are cleaned of float noise by rounding to decimal places that suit their step, not to whole multiples of it, which merged ticks that start off a multiple (1950, 1970… became 1960, 1960…).
 
-**Log-axis ticks come from published algorithms (Steven, phase 4).** The theme's axis.tick.log\_algorithm picks one: breaks\_log (the default), a port of R's scales::breaks\_log (ggplot2's default for log axes; MIT licence, notice in render/ticks.py), or matplotlib, matplotlib's LogLocator (powers of ten only). breaks\_log's target number of breaks is how many ticks the theme's linear algorithm places across the axis's log10 range; where it gives up (an axis within one power of ten), the linear algorithm places the ticks. On either, the labels must fit: while the drawn labels would overlap or come within the tick-label gap of each other, the algorithm is asked for one tick fewer. This replaced a rule of ForgeGraph's own (1-2-5 steps within three decades), whose labels ran together on short axes in the skill evals.
+**Log-axis ticks come from published algorithms (Steven, phase 4).** The theme's axis.tick.log\_algorithm picks one: breaks\_log (the default), a port of R's scales::breaks\_log (ggplot2's default for log axes; MIT licence, notice in drawing/ticks.py), or matplotlib, matplotlib's LogLocator (powers of ten only). breaks\_log's target number of breaks is how many ticks the theme's linear algorithm places across the axis's log10 range; where it gives up (an axis within one power of ten), the linear algorithm places the ticks. On either, the labels must fit: while the drawn labels would overlap or come within the tick-label gap of each other, the algorithm is asked for one tick fewer. This replaced a rule of ForgeGraph's own (1-2-5 steps within three decades), whose labels ran together on short axes in the skill evals.
 
 ## After phase 4
 
 **The watermark belongs to the theme's author (Steven).** A GraphSpec can't change the watermark, since its parameters are fixed in the theme; a theme's author can restyle it however they like, even out of sight. An organisation that wants it required keeps those parameters fixed in its own theme. Its text must have at least one visible character, since it's drawn from its letters' outlines; a theme whose text has none is an error.
 
-**The figure checks itself.** A ForgeGraph figure is a GraphFigure on a GraphCanvas (render/figure.py). Whatever draws or saves it, ForgeGraph or matplotlib directly (`figure.savefig`, a notebook showing the figure), first checks whether it's still as rendering left it: the same artists, drawing the same pixels (a hash of the figure drawn at its own size and resolution). A graph found changed stays non-standard, and every drawing of it carries the watermark, which sizes itself to the plot box each time it's drawn. Every save embeds the provenance record, through one function per file type's carrier (render/export.py), unless the caller sets the carrier's own key, as the catalog does to keep its images free of metadata.
+**The figure checks itself.** A ForgeGraph figure is a GraphFigure on a GraphCanvas (drawing/figure.py). Whatever draws or saves it, ForgeGraph or matplotlib directly (`figure.savefig`, a notebook showing the figure), first checks whether it's still as rendering left it: the same artists, drawing the same pixels (a hash of the figure drawn at its own size and resolution). A graph found changed stays non-standard, and every drawing of it carries the watermark, which sizes itself to the plot box each time it's drawn. Every save embeds the provenance record, through one function per file type's carrier (drawing/export.py), unless the caller sets the carrier's own key, as the catalog does to keep its images free of metadata.
 
 **provenance: off keeps the non-standard flag.** With off, a standard graph's files carry no record; a non-standard graph's carry `level: off`, the ForgeGraph version and `nonstandard: true`, so they can still be told apart. `forgegraph load` reports such a record and can't recover a GraphSpec from it.
 

{forgegraph-0.1.0 → forgegraph-0.2.0}/docs/specs/catalog/base_theme.md

@@ -196,7 +196,7 @@ variations:          *# Every parameter of the theme, by category: its
     layer:\
         error_bar:\
             cap_size: {value: 0.8, from: error_bars}          *# \[positive float\]; Cap width, × base size.*\
-            color: {value: "#000000", from: error_bars}          *# \[series, hex color\]; Error bar color. series: the series' color.*\
+            color: {value: series, from: error_bars}          *# \[series, hex color\]; Error bar color. series: the series' color.*\
             line_width: {value: 0.25, from: error_bars}          *# \[positive float\]; Line width, × base size.*\
         reference_line:\
             line_style: {value: dotted, from: target}          *# \[solid, dashed, dotted, dashdot\]; Line style.*\

{forgegraph-0.1.0 → forgegraph-0.2.0}/docs/specs/graphspec/polarization.md

@@ -127,6 +127,9 @@ variable_parameters:          *# List of variable parameters for the G
         file_types: \[png\]          *# \[png, jpg, tiff, svg, pdf, html\]; File types saved.*\
     provenance:\
         level: full          *# \[full, minimal, off\]; Which entries of the provenance record (docs/specs/provenance) each saved file carries. off: none.*\
+    layer:\
+        error_bar:\
+            color: "#000000"          *# \[series, hex color\]; Error bar color. series: the series' color.*\
     layers:          *# Layers drawn on the graph, each under a name of the GraphSpec's choosing, drawn in this order.*\
         target:\
             type: reference_line          *# \[layer type\]; The layer's type: one of the graph type's layer.types.*\

{forgegraph-0.1.0 → forgegraph-0.2.0}/docs/specs/pack/forgegraph_base.md

@@ -3,7 +3,7 @@
 This page mirrors src/forgegraph/packs/forgegraph_base/pack.yaml, which is the specification. A test fails if they ever differ.
 
 name: forgegraph_base          *# \[text\]; The pack's name, either a folder where the pack is stored or a pip pack's entry point.*\
-version: 0.1.0          *# \[text\]; The pack's release version.*\
+version: 0.2.0          *# \[text\]; The pack's release version.*\
 description: ForgeGraph's base specs, complete, for other specs to extend or to use as they are.          *# \[text\]; One line, describing what the pack is.*\
 issues: https://github.com/sskaye/forgegraph/issues          *# \[text\]; Where to file feature requests and bug reports about the pack's specs.*\
 requires: None          *# \[None, version specifier\]; The ForgeGraph versions the pack works with, as pip writes them, e.g. ">=0.6, <1". None: any.*

{forgegraph-0.1.0 → forgegraph-0.2.0}/docs/specs/theme/base_theme.md

@@ -99,7 +99,6 @@ fixed_parameters:          *# List of fixed parameters for the theme.*
         error_bar:\
             cap_size: 0.25          *# \[positive float\]; Cap width, × base size.*\
             line_width: 0.08          *# \[positive float\]; Line width, × base size.*\
-            color: series          *# \[series, hex color\]; Error bar color. series: the series' color.*\
         reference_line:\
             color: "#808080"          *# \[hex color\]; Line and label color, unless drawn per series.*\
             line_style: dashed          *# \[solid, dashed, dotted, dashdot\]; Line style.*\
@@ -156,4 +155,7 @@ variable_parameters:          *# List of variable parameters for the t
             max_relative_distance: 0.8          *# \[0-1\]; Most a label's distance to its series may be, ÷ its distance to the next nearest.*\
             max_axis_extension: 0.15          *# \[0-1\]; Most the x-axis may grow to fit labels, × its range.*\
         color_bar:\
-            colors: viridis          *# \[viridis, cividis, plasma, inferno, magma, greys, blues, red_blue, hex color, two hex colors\]; Colors for a numeric encoding.color: a named scale, one hex color (light to it) or two (first to second).*
+            colors: viridis          *# \[viridis, cividis, plasma, inferno, magma, greys, blues, red_blue, hex color, two hex colors\]; Colors for a numeric encoding.color: a named scale, one hex color (light to it) or two (first to second).*\
+    layer:\
+        error_bar:\
+            color: "#000000"          *# \[series, hex color\]; Error bar color. series: the series' color.*

{forgegraph-0.1.0 → forgegraph-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "forgegraph"
-version = "0.1.0"
+version = "0.2.0"
 description = "Consistent, high-quality graphs from pandas DataFrames, for people and AI agents. Early development."
 readme = "README.md"
 license = "MIT"
@@ -36,6 +36,7 @@ forgegraph = "forgegraph.cli:app"
 dev = [
     "pytest>=8",
     "pytest-cov>=5",
+    "pytest-xdist>=3.6",  # tests run in parallel
     "ruff>=0.6",
     "pyright>=1.1.380",
     "pre-commit>=3.8",
@@ -74,7 +75,8 @@ typeCheckingMode = "standard"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "--strict-markers"
+addopts = "--strict-markers -n auto"  # -n 0 runs them one at a time
+markers = ["slow: over a second, or drawing every catalog card; run only with --full"]
 
 [tool.coverage.run]
 source = ["forgegraph"]

{forgegraph-0.1.0 → forgegraph-0.2.0}/scripts/build_recreations.py

@@ -24,7 +24,7 @@ import tempfile  # noqa: E402
 from recreations import LAYOUT_RECREATIONS, RECREATIONS  # noqa: E402
 
 from forgegraph.catalog.build import write  # noqa: E402
-from forgegraph.render.style import isolated  # noqa: E402
+from forgegraph.drawing.style import isolated  # noqa: E402
 
 BASELINE_DPI = 72
 CSS_DPI = 96  # a CSS inch, so images show at the figure's real size

{forgegraph-0.1.0 → forgegraph-0.2.0}/scripts/run_skill_evals.py

@@ -292,7 +292,7 @@ def _layout_checks(want: dict[str, Any], ws: Path, allowed: list[str]) -> list[C
     """The final layout: it draws, its tabs and tiles, a spanning tile, a blank cell, its
     column widths, and its lint."""
     import forgegraph as fg
-    from forgegraph.layout import _load
+    from forgegraph.layouts import _load
     from forgegraph.spec.layout import BLANK, tabs
 
     layouts = _named(ws, ".layout.yaml")

{forgegraph-0.1.0 → forgegraph-0.2.0}/scripts/visual_changelog.py

@@ -4,8 +4,8 @@ uv run python scripts/visual_changelog.py main            # main against the wor
 uv run python scripts/visual_changelog.py v0.1.0 v0.2.0   # between two commits
     [--out review/visual-changelog.html]
 
-Compares the regression baselines (tests/baselines/*.png) and the catalog's figures (by id),
-and writes one page showing each changed, added or removed image.
+Compares the regression baselines (tests/baselines/*.png) and each catalog page's figures (by
+id), and writes one page showing each changed, added or removed image.
 """
 
 from __future__ import annotations
@@ -20,7 +20,7 @@ from pathlib import Path
 ROOT = Path(__file__).parents[1]
 BASELINES = "tests/baselines"
 CATALOG = "catalog/forgegraph_base.html"
-EARLIER_CATALOG = "catalog/catalog.html"  # its name before phase 6
+EARLIER_CATALOG = "catalog/catalog.html"  # forgegraph_base's page before phase 6
 FIGURE = re.compile(r'<figure id="([^"]+)"><img [^>]*src="data:image/png;base64,([^"]+)"')
 
 
@@ -37,9 +37,18 @@ def _baselines(ref: str | None) -> dict[str, bytes]:
     }
 
 
-def _catalog(ref: str | None) -> dict[str, bytes]:
+def _pages(ref: str | None) -> set[str]:
+    """The catalog pages at a commit, or in the working tree, by path."""
+    if ref is None:
+        return {f"catalog/{p.name}" for p in (ROOT / "catalog").glob("*.html")}
+    names = _git("ls-tree", "--name-only", f"{ref}:catalog").decode().split()
+    pages = {f"catalog/{n}" for n in names if n.endswith(".html")}
+    return {CATALOG if p == EARLIER_CATALOG else p for p in pages}
+
+
+def _catalog(ref: str | None, page: str) -> dict[str, bytes]:
     text = None
-    for name in (CATALOG, EARLIER_CATALOG):
+    for name in (page, EARLIER_CATALOG) if page == CATALOG else (page,):
         try:
             text = (
                 (ROOT / name).read_text(encoding="utf-8")
@@ -94,7 +103,15 @@ def page(before: str, after: str | None) -> str:
     body = "\n".join(
         [
             _section("Regression baselines", "baselines", _baselines(before), _baselines(after)),
-            _section("Catalog", "catalog", _catalog(before), _catalog(after)),
+            *(
+                _section(
+                    f"Catalog: {Path(p).stem}",
+                    Path(p).stem,
+                    _catalog(before, p),
+                    _catalog(after, p),
+                )
+                for p in sorted(_pages(before) | _pages(after))
+            ),
         ]
     )
     return (

forgegraph-0.2.0/src/forgegraph/__init__.py

@@ -0,0 +1,58 @@
+"""ForgeGraph: consistent, high-quality graphs from a declarative GraphSpec.
+
+The API loads on first use, so `forgegraph --version` and `--help` don't load matplotlib and
+pandas.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING, Any
+
+try:
+    __version__ = version("forgegraph")
+except PackageNotFoundError:  # running from a source tree without installation
+    __version__ = "0.0.0"
+
+if TYPE_CHECKING:
+    from forgegraph.canvas import Blank, blank
+    from forgegraph.graph import Graph, SpecError, graphspec, load, render, xy
+    from forgegraph.layouts import Layout
+    from forgegraph.layouts import render_layout as layout
+
+_API = {  # name: (module, attribute)
+    "Blank": ("forgegraph.canvas", "Blank"),
+    "blank": ("forgegraph.canvas", "blank"),
+    "Graph": ("forgegraph.graph", "Graph"),
+    "SpecError": ("forgegraph.graph", "SpecError"),
+    "graphspec": ("forgegraph.graph", "graphspec"),
+    "load": ("forgegraph.graph", "load"),
+    "render": ("forgegraph.graph", "render"),
+    "xy": ("forgegraph.graph", "xy"),
+    "Layout": ("forgegraph.layouts", "Layout"),
+    "layout": ("forgegraph.layouts", "render_layout"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _API:
+        raise AttributeError(f"module 'forgegraph' has no attribute {name!r}")
+    module, attribute = _API[name]
+    value = globals()[name] = getattr(import_module(module), attribute)
+    return value
+
+
+__all__ = [
+    "Blank",
+    "Graph",
+    "Layout",
+    "SpecError",
+    "__version__",
+    "blank",
+    "graphspec",
+    "layout",
+    "load",
+    "render",
+    "xy",
+]

forgegraph-0.1.0/src/forgegraph/blank.py → forgegraph-0.2.0/src/forgegraph/canvas.py

@@ -19,9 +19,8 @@ from typing import Any
 from matplotlib.axes import Axes
 
 from forgegraph import __version__
-from forgegraph.graph import SpecError, _created, _plain, spec_record
-from forgegraph.render import export
-from forgegraph.render.figure import (
+from forgegraph.drawing import export
+from forgegraph.drawing.figure import (
     GraphFigure,
     LayoutError,
     Watermark,
@@ -29,7 +28,8 @@ from forgegraph.render.figure import (
     layout,
     new_figure,
 )
-from forgegraph.render.style import PALETTES, Style, isolated
+from forgegraph.drawing.style import PALETTES, Style, isolated
+from forgegraph.graph import SpecError, _created, _plain, spec_record
 from forgegraph.spec.documents import (
     Registry,
     name_problems,

{forgegraph-0.1.0 → forgegraph-0.2.0}/src/forgegraph/catalog/examples.py

@@ -11,9 +11,9 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
+from forgegraph.drawing import export
+from forgegraph.drawing.style import isolated
 from forgegraph.graph import Graph, data_path, render
-from forgegraph.render import export
-from forgegraph.render.style import isolated
 from forgegraph.spec.documents import Registry, builtin, resolve, resolve_layers
 from forgegraph.spec.parameters import NONE, Parameter, definitions, tree_has, tree_set
 

{forgegraph-0.1.0 → forgegraph-0.2.0}/src/forgegraph/cli/__init__.py

@@ -88,7 +88,7 @@ def render(
     several tabs saves a file per tab (name-<tab>.png), a PDF with a page per tab, and an
     HTML page with every tab."""
     import forgegraph as fg
-    from forgegraph.layout import is_layout, stem
+    from forgegraph.layouts import is_layout, stem
     from forgegraph.spec.documents import nonstandard_note
 
     drawn: Any
@@ -138,7 +138,7 @@ def explain(
     """Show every value a graph is drawn with, whether it's fixed, and which file set it. For
     a layout: its own values, then each tile's, under tabs.<tab>.tiles.<tile>."""
     import forgegraph as fg
-    from forgegraph.layout import explain_layout, is_layout, nonstandard_packs_of
+    from forgegraph.layouts import explain_layout, is_layout, nonstandard_packs_of
     from forgegraph.spec.documents import explain as explain_values
     from forgegraph.spec.documents import load as load_yaml
     from forgegraph.spec.documents import nonstandard_note, packs_used, registry_for, validate

{forgegraph-0.1.0/src/forgegraph/render → forgegraph-0.2.0/src/forgegraph/drawing}/axes.py

@@ -2,7 +2,7 @@
 
 - **Type** (data.type): decimal, integer, datetime or categorical. auto takes it from the
   column: dates and times, then numbers (integer for an integer column), otherwise
-  categorical. An integer axis's automatic ticks are whole numbers (forgegraph.render.ticks).
+  categorical. An integer axis's automatic ticks are whole numbers (forgegraph.drawing.ticks).
 - **Categories** sit at positions 0, 1, 2 … in data.order: as in the data (a pandas
   Categorical's own order), alphanumeric (natural: Run 2 before Run 10), or by the other
   axis's value (the total at each category), ascending or descending. Every value present is
@@ -43,9 +43,9 @@ from matplotlib.dates import date2num, num2date
 from matplotlib.text import Text
 from matplotlib.ticker import FixedLocator, Formatter, Locator, MultipleLocator
 
-from forgegraph.render.markup import literal
-from forgegraph.render.style import Style
-from forgegraph.render.ticks import LogTicks, NiceTicks, target
+from forgegraph.drawing.markup import literal
+from forgegraph.drawing.style import Style
+from forgegraph.drawing.ticks import LogTicks, NiceTicks, target
 
 
 class DrawError(ValueError):

{forgegraph-0.1.0/src/forgegraph/render → forgegraph-0.2.0/src/forgegraph/drawing}/colorbar.py

@@ -21,10 +21,10 @@ from matplotlib.cm import ScalarMappable
 from matplotlib.colors import Colormap, Normalize
 from matplotlib.transforms import Affine2D, Bbox, ScaledTranslation
 
-from forgegraph.render import spacing, text
-from forgegraph.render.figure import WATERMARK, texts_of, tick_marks
-from forgegraph.render.style import Style
-from forgegraph.render.ticks import NiceTicks
+from forgegraph.drawing import spacing, text
+from forgegraph.drawing.figure import WATERMARK, texts_of, tick_marks
+from forgegraph.drawing.style import Style
+from forgegraph.drawing.ticks import NiceTicks
 
 TITLE_ABOVE, TITLE_ALONG, BELOW = "title_above", "title_along", "below"
 

{forgegraph-0.1.0/src/forgegraph/render → forgegraph-0.2.0/src/forgegraph/drawing}/export.py

@@ -7,7 +7,7 @@ The record is one JSON document, stored invisibly in each file type:
 - pdf: the document information dictionary, key /ForgeGraph;
 - jpg: a JPEG comment segment;
 - tiff: the ImageDescription tag;
-- html: a JSON script in the page's head (render/page.py), with each figure's SVG carrying
+- html: a JSON script in the page's head (drawing/page.py), with each figure's SVG carrying
   its own record too.
 
 A layout's PDF has a page per tab, and the document's record covers them all.
@@ -31,7 +31,7 @@ from matplotlib.backends.backend_pdf import PdfPages
 from matplotlib.figure import Figure
 from PIL import Image
 
-from forgegraph.render import page
+from forgegraph.drawing import page
 
 KEY = "ForgeGraph"
 FILE_TYPES = ("png", "jpg", "tiff", "svg", "pdf", "html")
@@ -77,7 +77,7 @@ def with_record(kind: str, kwargs: dict[str, Any], record: dict[str, Any] | None
 
 def save(fig: Figure, path: Path, dpi: int) -> Path:
     """Save fig to path (its suffix is the file type). A ForgeGraph figure's canvas adds the
-    provenance record (forgegraph.render.figure.GraphCanvas)."""
+    provenance record (forgegraph.drawing.figure.GraphCanvas)."""
     kind = kind_of(path)
     if kind not in IMAGES:
         raise ValueError(f"can't save as .{kind}; file types are {', '.join(FILE_TYPES)}")

{forgegraph-0.1.0/src/forgegraph/render → forgegraph-0.2.0/src/forgegraph/drawing}/figure.py

@@ -1,7 +1,7 @@
 """Figures sized by the format, laid out by what's visible.
 
 Width and height are in mm. ForgeGraph lays the figure out itself rather than with
-matplotlib's layout engines, which space text by its box (see forgegraph.render.text): the
+matplotlib's layout engines, which space text by its box (see forgegraph.drawing.text): the
 plot box is placed so that everything drawn, measured to its letters and lines, sits MARGIN
 from each edge of the figure. With both sizes given, the plot box takes the space left; with
 one auto, the plot box keeps the theme's plot_area.aspect and the figure is fitted around it.
@@ -26,10 +26,10 @@ from matplotlib.text import Text
 from matplotlib.textpath import TextPath
 from matplotlib.transforms import Affine2D, Bbox, ScaledTranslation
 
-from forgegraph.render import export, spacing, text
-from forgegraph.render.key import keys
-from forgegraph.render.markup import literal
-from forgegraph.render.style import MM_PER_INCH, Style, isolated
+from forgegraph.drawing import export, spacing, text
+from forgegraph.drawing.key import keys
+from forgegraph.drawing.markup import literal
+from forgegraph.drawing.style import MM_PER_INCH, Style, isolated
 
 MARGIN_IN = 0.04  # space kept between what's drawn and the figure's edges
 WATERMARK = "forgegraph-watermark"

{forgegraph-0.1.0/src/forgegraph/render → forgegraph-0.2.0/src/forgegraph/drawing}/key.py

@@ -1,7 +1,7 @@
 """Keys: a legend naming the series, or a style key explaining line styles and markers.
 
 ForgeGraph lays a key out itself, with every gap measured to the letters (see
-forgegraph.render.text): an optional title, then one row per entry, a line sample then the
+forgegraph.drawing.text): an optional title, then one row per entry, a line sample then the
 entry's name. The theme's legend parameters set the frame, its padding (the same on every
 side), the gaps between title and rows and between rows, the sample's length and its gap to
 the name, and the key's inset from the plot box.
@@ -24,9 +24,9 @@ from matplotlib.patches import Rectangle
 from matplotlib.text import Text
 from matplotlib.transforms import Affine2D, Bbox, ScaledTranslation, Transform
 
-from forgegraph.render import text
-from forgegraph.render.marks import Bars
-from forgegraph.render.style import Style
+from forgegraph.drawing import text
+from forgegraph.drawing.marks import Bars
+from forgegraph.drawing.style import Style
 
 # Each position: where it is on the plot box (axes fraction), and which way the key extends
 # from it: right (1), left (-1) or centred (0); down (-1), up (1) or centred (0).

{forgegraph-0.1.0/src/forgegraph/render → forgegraph-0.2.0/src/forgegraph/drawing}/labels.py

@@ -29,10 +29,10 @@ from matplotlib.lines import Line2D
 from matplotlib.ticker import FixedLocator
 from matplotlib.transforms import Bbox
 
-from forgegraph.render import text
-from forgegraph.render.key import KEY, Entry, Key
-from forgegraph.render.marks import Bars
-from forgegraph.render.style import Style
+from forgegraph.drawing import text
+from forgegraph.drawing.key import KEY, Entry, Key
+from forgegraph.drawing.marks import Bars
+from forgegraph.drawing.style import Style
 
 DIRECTIONS = [(1, 0), (-1, 0), (0, 1), (0, -1), (1, 1), (-1, 1), (1, -1), (-1, -1)]
 SERIES_LABEL = "forgegraph-series-label"

{forgegraph-0.1.0/src/forgegraph/render → forgegraph-0.2.0/src/forgegraph/drawing}/layers.py

@@ -33,10 +33,10 @@ from matplotlib.axes import Axes
 from matplotlib.text import Annotation
 from matplotlib.transforms import Bbox
 
-from forgegraph.render import marks
-from forgegraph.render.axes import DrawError
-from forgegraph.render.markup import markup
-from forgegraph.render.style import LINE_STYLES, Style, unset
+from forgegraph.drawing import marks
+from forgegraph.drawing.axes import DrawError
+from forgegraph.drawing.markup import markup
+from forgegraph.drawing.style import LINE_STYLES, Style, unset
 
 NOTE = "forgegraph-note"
 REFERENCE = "forgegraph-reference-line"

{forgegraph-0.1.0/src/forgegraph/render → forgegraph-0.2.0/src/forgegraph/drawing}/lint.py

@@ -37,9 +37,9 @@ from matplotlib.lines import Line2D
 from matplotlib.text import Text
 from matplotlib.transforms import Bbox
 
-from forgegraph.render import text
-from forgegraph.render.figure import WATERMARK, texts_of
-from forgegraph.render.key import KEY, keys
+from forgegraph.drawing import text
+from forgegraph.drawing.figure import WATERMARK, texts_of
+from forgegraph.drawing.key import KEY, keys
 
 MIN_TEXT_PT = 6.0  # the smallest text journals accept in a printed figure
 OVERLAP_PX = 0.5  # letters closer than this count as touching, not overlapping