coeftable 0.3.0__tar.gz → 0.4.0__tar.gz

{coeftable-0.3.0 → coeftable-0.4.0}/.github/workflows/publish.yml

@@ -11,11 +11,6 @@ on:
         description: "Git ref to build. Defaults to the triggering ref."
         required: false
         type: string
-      publish:
-        description: "Upload the built package to PyPI."
-        required: false
-        default: false
-        type: boolean
   workflow_dispatch:
 
 jobs:
@@ -40,29 +35,33 @@ jobs:
 
   publish:
     runs-on: ubuntu-latest
-    # PyPI must have a trusted publisher registered for BOTH entry points,
-    # each with environment "publish": this workflow, for a manual run or a
-    # hand-pushed tag, and release.yml, for an automated release. Upload
-    # authentication matches on the reusable workflow, but the build
-    # provenance attestation carries the TOP-LEVEL workflow, so an automated
-    # release presents release.yml and is rejected with "does not match
-    # expected Trusted Publisher" unless that entry point is registered too.
-    #
-    # A tag pushed by a workflow using the default token does not raise a
-    # push event, so a release cut by automation asks for the upload
-    # explicitly. Any other run sitting on a tag -- a hand-pushed tag, or a
-    # manual run selecting one, which is how a stranded release gets
-    # published -- is also a release build. A run on a branch never is.
-    if: inputs.publish || startsWith(github.ref, 'refs/tags')
+    # PyPI Trusted Publishing does not support reusable workflows
+    # (https://github.com/pypa/gh-action-pypi-publish/issues/166): a
+    # `workflow_call` invocation of this job would present the *caller's*
+    # workflow identity, not this one, and fail to match the Trusted
+    # Publisher entry registered for this workflow. So this job never
+    # publishes when called reusably -- release.yml calls this workflow
+    # for `build-package` only and does its own top-level publish. This
+    # job runs only for a direct trigger of this workflow sitting on a
+    # tag: a tag push, or a manual run selecting a tag ref (how a
+    # stranded release gets republished). A run on a branch never does.
+    if: startsWith(github.ref, 'refs/tags')
     environment:
       name: publish
       url: https://pypi.org/p/coeftable
     needs: build-package
     permissions:
+      contents: read
       id-token: write
     steps:
       - uses: actions/download-artifact@v8
         with:
           name: Packages
           path: dist
+      # Must be invoked straight from the job, never via a local composite
+      # action. This action builds a Docker trampoline whose image it names
+      # from `github.action_repository`/`github.action_ref`, and both are
+      # empty for an action nested inside another composite action
+      # (actions/runner#2473). It then falls back to this repository and its
+      # branch, and tries to pull an image that was never published.
       - uses: pypa/gh-action-pypi-publish@release/v1

{coeftable-0.3.0 → coeftable-0.4.0}/.github/workflows/release.yml

@@ -90,10 +90,12 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: gh release create "${{ steps.version.outputs.tag }}" --generate-notes
 
-  publish:
-    # Called directly rather than left to the tag-push trigger on the publish
-    # workflow: the tag above is pushed with the workflow token, and GitHub
-    # does not raise workflow-triggering events for it.
+  build:
+    # Called reusably for the build step only: `publish.yml`'s own
+    # `publish` job is gated on `startsWith(github.ref, 'refs/tags')`,
+    # which is false here (`github.ref` reflects this run's own
+    # branch/dispatch ref, not the `ref:` input below), so it no-ops --
+    # only `build-package` executes.
     needs: tag
     uses: ./.github/workflows/publish.yml
     permissions:
@@ -102,7 +104,37 @@ jobs:
       id-token: write
     with:
       ref: ${{ needs.tag.outputs.tag }}
-      publish: true
+
+  publish:
+    # A real top-level job, not delegated via `uses:`: PyPI Trusted
+    # Publishing does not support reusable workflows -- the OIDC
+    # certificate's Build Config URI reflects the top-level caller
+    # (release.yml) for a `uses:`-invoked job, which then fails to match
+    # a Trusted Publisher entry registered for the *called* workflow.
+    # See https://github.com/pypa/gh-action-pypi-publish/issues/166 and
+    # the "Non-goals" section of that action's README: "keep the job
+    # calling pypi-publish in a top-level [workflow]". `build-package`
+    # itself has no such restriction and stays reusable above.
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: publish
+      url: https://pypi.org/p/coeftable
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: Packages
+          path: dist
+      # Must be invoked straight from the job, never via a local composite
+      # action. This action builds a Docker trampoline whose image it names
+      # from `github.action_repository`/`github.action_ref`, and both are
+      # empty for an action nested inside another composite action
+      # (actions/runner#2473). It then falls back to this repository and its
+      # branch, and tries to pull an image that was never published.
+      - uses: pypa/gh-action-pypi-publish@release/v1
 
   changelog:
     # Same reason as the publish job above: the release is created with the

{coeftable-0.3.0 → coeftable-0.4.0}/.gitignore

@@ -18,3 +18,5 @@ src/coeftable/_version.py
 /.roborev/
 # internal planning docs (not shipped, not for the public repo)
 docs/superpowers/
+# local feature worktrees
+/.worktrees/

{coeftable-0.3.0 → coeftable-0.4.0}/CHANGELOG.md

@@ -1,3 +1,46 @@
+## Unreleased
+
+### Features
+- Add typed rule and band annotations to forest plots and sparklines, including row-specific field binding and domain-aware layering.
+
+<a id="v0.3.1"></a>
+# [v0.3.1](https://github.com/kylejcaron/coeftable/releases/tag/v0.3.1) - 2026-08-14
+
+<!-- Release notes generated using configuration in .github/release.yml at v0.3.1 -->
+
+## What's Changed
+### Bug Fixes
+* Fix row-group handling: labels spanning groups, row striping, and layout key collisions by [@kylejcaron](https://github.com/kylejcaron) in [#26](https://github.com/kylejcaron/coeftable/pull/26)
+* Build core metadata 2.4 so releases pass validation by [@kylejcaron](https://github.com/kylejcaron) in [#27](https://github.com/kylejcaron/coeftable/pull/27)
+### Maintenance
+* Update changelog for v0.3.0 by [@github-actions](https://github.com/github-actions)[bot] in [#21](https://github.com/kylejcaron/coeftable/pull/21)
+* Fix automated releases: PyPI Trusted Publishing rejects reusable workflows by [@kylejcaron](https://github.com/kylejcaron) in [#22](https://github.com/kylejcaron/coeftable/pull/22)
+
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/compare/v0.3.0...v0.3.1
+
+[Changes][v0.3.1]
+
+
+<a id="v0.3.0"></a>
+# [v0.3.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.3.0) - 2026-08-05
+
+<!-- Release notes generated using configuration in .github/release.yml at v0.3.0 -->
+
+## What's Changed
+### Maintenance
+* Update changelog for v0.2.1 by [@github-actions](https://github.com/github-actions)[bot] in [#13](https://github.com/kylejcaron/coeftable/pull/13)
+* Document the PyPI trusted-publisher requirement for both entry points by [@kylejcaron](https://github.com/kylejcaron) in [#14](https://github.com/kylejcaron/coeftable/pull/14)
+* Add collapsible group sections by [@kylejcaron](https://github.com/kylejcaron) in [#18](https://github.com/kylejcaron/coeftable/pull/18)
+* Allow ref=None on Sparkline to drop the reference line and its domain constraint by [@kylejcaron](https://github.com/kylejcaron) in [#19](https://github.com/kylejcaron/coeftable/pull/19)
+* Support multiple overlaid series in one sparkline cell by [@kylejcaron](https://github.com/kylejcaron) in [#20](https://github.com/kylejcaron/coeftable/pull/20)
+
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/compare/v0.2.1...v0.3.0
+
+[Changes][v0.3.0]
+
+
 <a id="v0.2.1"></a>
 # [v0.2.1](https://github.com/kylejcaron/coeftable/releases/tag/v0.2.1) - 2026-08-05
 
@@ -54,6 +97,8 @@
 [Changes][v0.1.0]
 
 
+[v0.3.1]: https://github.com/kylejcaron/coeftable/compare/v0.3.0...v0.3.1
+[v0.3.0]: https://github.com/kylejcaron/coeftable/compare/v0.2.1...v0.3.0
 [v0.2.1]: https://github.com/kylejcaron/coeftable/compare/v0.2.0...v0.2.1
 [v0.2.0]: https://github.com/kylejcaron/coeftable/compare/v0.1.0...v0.2.0
 [v0.1.0]: https://github.com/kylejcaron/coeftable/tree/v0.1.0

{coeftable-0.3.0 → coeftable-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coeftable
-Version: 0.3.0
+Version: 0.4.0
 Summary: Publication-quality summary tables for estimates with uncertainty.
 Project-URL: Homepage, https://github.com/kylejcaron/coeftable
 Project-URL: Repository, https://github.com/kylejcaron/coeftable
@@ -104,7 +104,10 @@ a `parameter` column.
 **Dimensions:**
 - `rows` — the label for each row in the table (e.g. a metric name).
 - `nest` — an optional secondary label stacked below each row.
-- `groups` — an optional column whose values produce section headers. Pass
+- `groups` — an optional column whose values produce section headers. A row
+  label may appear under more than one group, in which case it renders once per
+  section — so the same set of metrics can be reported per region without
+  inventing a `nest` column to tell them apart. Pass
   `collapsible_groups=True` to make those sections collapsible in the rendered
   HTML — a pure CSS toggle (relies on `:has()`, Baseline since late 2023; on an
   older browser without it the toggle no-ops and sections stay expanded), no
@@ -182,6 +185,34 @@ methods = pl.DataFrame(
 )
 ```
 
+## Repeating metrics across sections
+
+A row label may appear under more than one `groups` value. The same metrics can
+therefore be reported per region, each section repeating the full set:
+
+```python
+import polars as pl
+import coeftable as ct
+
+regions = pl.DataFrame(
+    {
+        "metric": ["Revenue", "Signups", "Revenue", "Signups"],
+        "region": ["US", "US", "EU", "EU"],
+        "est": [1.2, 0.4, 2.1, 0.9],
+        "lb": [0.8, 0.1, 1.5, 0.5],
+        "ub": [1.6, 0.7, 2.7, 1.3],
+    }
+)
+
+(
+    ct.CoefTable(
+        regions, rows="metric", groups="region", collapsible_groups=True
+    )
+    .estimate("Effect", "est", ci=("lb", "ub"))
+    .forest("Effect Plot", of="Effect", ref=0.0, symmetric=True)
+)
+```
+
 ## Theming
 
 Four built-in themes are available from `coeftable.theme`:
@@ -236,8 +267,13 @@ companion-frame choice used elsewhere in coeftable:
 arrives in: a SQL export, a dbt model, an experimentation platform's daily
 metrics table. Pass `data=` a separate frame with one row per point, and
 `value` / `ci` / `x` name *scalar* columns on it. coeftable groups the
-companion frame by the table's `rows` (+ `nest`, + `split_columns`) keys
-and collapses each group into a series internally:
+companion frame by the table's `rows` (+ `nest`, + `groups`, +
+`split_columns`) keys and collapses each group into a series internally.
+`groups` participates only when `data` actually carries that column, so a
+companion frame keyed on the row alone stays valid. The one case that needs
+it is a row label appearing under more than one group: without the group
+column in `data` those rows are indistinguishable, so coeftable reports it
+rather than serving every section the same merged series.
 
 ```python
 import datetime as dt
@@ -403,3 +439,59 @@ absolute = pl.DataFrame(
     .sparkline("Hidden reference", value="value", ref=0.0, show_ref=False)
 )
 ```
+
+## Plot annotations
+
+`ct.Rule` draws a line and `ct.Band` shades an interval in a forest plot or
+sparkline. A numeric, date, or datetime coordinate is a literal; a string is
+the name of a scalar column on the main table frame. A missing field value
+leaves that annotation out of that row, which makes row-specific marks
+possible:
+
+```python
+import polars as pl
+import coeftable as ct
+
+annotated = pl.DataFrame(
+    {
+        "metric": ["Revenue", "Latency"],
+        "estimate": [1.2, -0.4],
+        "lower": [0.8, -0.8],
+        "upper": [1.6, 0.1],
+        # Only Revenue receives the second vertical rule.
+        "target": [1.5, None],
+        "trend": [[1.0, 1.2, 1.4], [-0.1, -0.3, -0.4]],
+        "guard_low": [0.9, -0.6],
+        "guard_high": [1.6, 0.0],
+    }
+)
+
+(
+    ct.CoefTable(annotated, rows="metric")
+    .estimate("Effect", "estimate", ci=("lower", "upper"))
+    .forest(
+        "Effect plot",
+        of="Effect",
+        annotations=(ct.Rule("target", axis="x"),),
+    )
+    .sparkline(
+        "Trend",
+        value="trend",
+        annotations=(ct.Band("guard_low", "guard_high", axis="y"),),
+    )
+)
+```
+
+Forest annotations use `axis="x"` only. Sparklines accept `axis="x"` and
+`axis="y"`; use the former for a shared time or sequence position and the
+latter for a value threshold or range. `layer="underlay"` (the default for
+bands) draws before the plot; `layer="overlay"` (the default for rules) draws
+after it. `affect_domain=True` by default expands an automatic axis domain to
+include the annotation; set it to `False` to keep the existing domain and
+allow the mark to be clipped. `ylim` overrides the Forest x-domain and the
+Sparkline y-domain, so annotations on those axes do not expand them. Sparkline
+x annotations still participate in their shared x-domain; `max_ylim` can cap
+the Sparkline y-domain and clip or omit distant marks. Annotations supplement
+rather than replace
+`ref`: `ref` remains the built-in semantic reference that controls colors and
+its optional dashed line.

{coeftable-0.3.0 → coeftable-0.4.0}/README.md

@@ -50,7 +50,10 @@ a `parameter` column.
 **Dimensions:**
 - `rows` — the label for each row in the table (e.g. a metric name).
 - `nest` — an optional secondary label stacked below each row.
-- `groups` — an optional column whose values produce section headers. Pass
+- `groups` — an optional column whose values produce section headers. A row
+  label may appear under more than one group, in which case it renders once per
+  section — so the same set of metrics can be reported per region without
+  inventing a `nest` column to tell them apart. Pass
   `collapsible_groups=True` to make those sections collapsible in the rendered
   HTML — a pure CSS toggle (relies on `:has()`, Baseline since late 2023; on an
   older browser without it the toggle no-ops and sections stay expanded), no
@@ -128,6 +131,34 @@ methods = pl.DataFrame(
 )
 ```
 
+## Repeating metrics across sections
+
+A row label may appear under more than one `groups` value. The same metrics can
+therefore be reported per region, each section repeating the full set:
+
+```python
+import polars as pl
+import coeftable as ct
+
+regions = pl.DataFrame(
+    {
+        "metric": ["Revenue", "Signups", "Revenue", "Signups"],
+        "region": ["US", "US", "EU", "EU"],
+        "est": [1.2, 0.4, 2.1, 0.9],
+        "lb": [0.8, 0.1, 1.5, 0.5],
+        "ub": [1.6, 0.7, 2.7, 1.3],
+    }
+)
+
+(
+    ct.CoefTable(
+        regions, rows="metric", groups="region", collapsible_groups=True
+    )
+    .estimate("Effect", "est", ci=("lb", "ub"))
+    .forest("Effect Plot", of="Effect", ref=0.0, symmetric=True)
+)
+```
+
 ## Theming
 
 Four built-in themes are available from `coeftable.theme`:
@@ -182,8 +213,13 @@ companion-frame choice used elsewhere in coeftable:
 arrives in: a SQL export, a dbt model, an experimentation platform's daily
 metrics table. Pass `data=` a separate frame with one row per point, and
 `value` / `ci` / `x` name *scalar* columns on it. coeftable groups the
-companion frame by the table's `rows` (+ `nest`, + `split_columns`) keys
-and collapses each group into a series internally:
+companion frame by the table's `rows` (+ `nest`, + `groups`, +
+`split_columns`) keys and collapses each group into a series internally.
+`groups` participates only when `data` actually carries that column, so a
+companion frame keyed on the row alone stays valid. The one case that needs
+it is a row label appearing under more than one group: without the group
+column in `data` those rows are indistinguishable, so coeftable reports it
+rather than serving every section the same merged series.
 
 ```python
 import datetime as dt
@@ -349,3 +385,59 @@ absolute = pl.DataFrame(
     .sparkline("Hidden reference", value="value", ref=0.0, show_ref=False)
 )
 ```
+
+## Plot annotations
+
+`ct.Rule` draws a line and `ct.Band` shades an interval in a forest plot or
+sparkline. A numeric, date, or datetime coordinate is a literal; a string is
+the name of a scalar column on the main table frame. A missing field value
+leaves that annotation out of that row, which makes row-specific marks
+possible:
+
+```python
+import polars as pl
+import coeftable as ct
+
+annotated = pl.DataFrame(
+    {
+        "metric": ["Revenue", "Latency"],
+        "estimate": [1.2, -0.4],
+        "lower": [0.8, -0.8],
+        "upper": [1.6, 0.1],
+        # Only Revenue receives the second vertical rule.
+        "target": [1.5, None],
+        "trend": [[1.0, 1.2, 1.4], [-0.1, -0.3, -0.4]],
+        "guard_low": [0.9, -0.6],
+        "guard_high": [1.6, 0.0],
+    }
+)
+
+(
+    ct.CoefTable(annotated, rows="metric")
+    .estimate("Effect", "estimate", ci=("lower", "upper"))
+    .forest(
+        "Effect plot",
+        of="Effect",
+        annotations=(ct.Rule("target", axis="x"),),
+    )
+    .sparkline(
+        "Trend",
+        value="trend",
+        annotations=(ct.Band("guard_low", "guard_high", axis="y"),),
+    )
+)
+```
+
+Forest annotations use `axis="x"` only. Sparklines accept `axis="x"` and
+`axis="y"`; use the former for a shared time or sequence position and the
+latter for a value threshold or range. `layer="underlay"` (the default for
+bands) draws before the plot; `layer="overlay"` (the default for rules) draws
+after it. `affect_domain=True` by default expands an automatic axis domain to
+include the annotation; set it to `False` to keep the existing domain and
+allow the mark to be clipped. `ylim` overrides the Forest x-domain and the
+Sparkline y-domain, so annotations on those axes do not expand them. Sparkline
+x annotations still participate in their shared x-domain; `max_ylim` can cap
+the Sparkline y-domain and clip or omit distant marks. Annotations supplement
+rather than replace
+`ref`: `ref` remains the built-in semantic reference that controls colors and
+its optional dashed line.

{coeftable-0.3.0 → coeftable-0.4.0}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["hatchling>=1.25", "hatch-vcs>=0.4"]
+requires = ["hatchling>=1.27", "hatch-vcs>=0.4"]
 build-backend = "hatchling.build"
 
 [project]
@@ -44,8 +44,14 @@ Homepage = "https://github.com/kylejcaron/coeftable"
 Repository = "https://github.com/kylejcaron/coeftable"
 Issues = "https://github.com/kylejcaron/coeftable/issues"
 
+# PyPI rejects core metadata 2.5, which hatchling 1.30 defaults to.
+# Drop once https://github.com/pypi/warehouse/issues/19083 ships.
 [tool.hatch.build.targets.wheel]
 packages = ["src/coeftable"]
+core-metadata-version = "2.4"
+
+[tool.hatch.build.targets.sdist]
+core-metadata-version = "2.4"
 
 [tool.hatch.version]
 source = "vcs"

{coeftable-0.3.0 → coeftable-0.4.0}/src/coeftable/__init__.py

@@ -2,6 +2,8 @@
 
 from importlib.metadata import PackageNotFoundError, version
 
+from coeftable.annotations import Band, Rule
+from coeftable.errors import ColumnNotFoundError, SpecError
 from coeftable.format import (
     CalendarStep,
     CIStyle,
@@ -11,15 +13,7 @@ from coeftable.format import (
     Percent,
     TimeFormat,
 )
-from coeftable.spec import (
-    CoefTable,
-    ColumnNotFoundError,
-    Estimate,
-    Forest,
-    Passthrough,
-    Sparkline,
-    SpecError,
-)
+from coeftable.spec import CoefTable, Estimate, Forest, Passthrough, Sparkline
 from coeftable.theme import Theme, role_for
 
 try:
@@ -28,6 +22,7 @@ except PackageNotFoundError:  # pragma: no cover
     __version__ = "0.0.0.dev0"
 
 __all__ = [
+    "Band",
     "CIStyle",
     "CalendarStep",
     "CoefTable",
@@ -39,6 +34,7 @@ __all__ = [
     "Number",
     "Passthrough",
     "Percent",
+    "Rule",
     "Sparkline",
     "SpecError",
     "Theme",

coeftable-0.4.0/src/coeftable/_axis.py

@@ -0,0 +1,55 @@
+"""Shared axis coercion helpers."""
+
+from __future__ import annotations
+
+import datetime
+import math
+from collections.abc import Iterable
+from typing import Any
+
+# Deliberately naive: paired with elapsed-time subtraction in _epoch_seconds
+# so relative spacing never depends on the host machine's local timezone.
+_EPOCH = datetime.datetime(1970, 1, 1)
+
+
+def _epoch_seconds(value: datetime.date) -> float:
+    """Convert a date/datetime to seconds since the Unix epoch.
+
+    A timezone-aware `datetime` is converted to UTC first; a naive
+    `datetime` (or a plain `date`, read as midnight) is measured as an
+    elapsed-time delta from a naive epoch, never through
+    `datetime.timestamp()` -- which reads a naive value against the host's
+    *local* timezone and would make relative spacing depend on where the
+    code runs.
+    """
+    if isinstance(value, datetime.datetime):
+        if value.tzinfo is not None:
+            value = value.astimezone(datetime.UTC).replace(tzinfo=None)
+        return (value - _EPOCH).total_seconds()
+    return (datetime.datetime(value.year, value.month, value.day) - _EPOCH).total_seconds()
+
+
+def _detect_temporal(values: Iterable[Any]) -> bool:
+    """Return True when the first non-missing value is a date or datetime."""
+    for value in values:
+        if value is not None:
+            return isinstance(value, datetime.date)
+    return False
+
+
+def _coerce_temporal(values: Iterable[Any]) -> list[float | None]:
+    """Coerce raw date/datetime values to epoch seconds, `None` for missing.
+
+    A bare `None` is missing directly; pandas' `NaT` is not `None` but is
+    still an `isinstance(..., datetime.datetime)` whose epoch delta
+    degenerates to NaN rather than raising, so the result is checked for
+    NaN too -- mirroring `coerce_numeric`'s own missing-value handling.
+    """
+    out: list[float | None] = []
+    for value in values:
+        if value is None:
+            out.append(None)
+            continue
+        seconds = _epoch_seconds(value)
+        out.append(None if math.isnan(seconds) else seconds)
+    return out

{coeftable-0.3.0 → coeftable-0.4.0}/src/coeftable/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.0'
-__version_tuple__ = version_tuple = (0, 3, 0)
+__version__ = version = '0.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
 
 __commit_id__ = commit_id = None