Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions .github/workflows/benchmark.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
name: benchmark
# Publishes the timings the tests job measured (benchmarks/run.py) to the
# gh-pages branch; nothing is measured here, so the tests run only once.
on:
workflow_run:
workflows: [tests]
types: [completed]
branches: [main]
workflow_dispatch:

# contents: the action commits benchmark data to the gh-pages branch.
# actions: the artifact is downloaded from the tests run.
permissions:
contents: write
actions: read

concurrency:
group: benchmark
cancel-in-progress: false

jobs:
benchmark:
if: github.event.workflow_run.conclusion == 'success'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.workflow_run.head_sha }}
- uses: actions/download-artifact@v4
with:
name: benchmark
path: benchmarks
run-id: ${{ github.event.workflow_run.id }}
github-token: ${{ secrets.GITHUB_TOKEN }}
# The action needs the data branch to exist; create it on the first run.
- run: |
if ! git ls-remote --exit-code --heads origin gh-pages >/dev/null; then
git config user.name github-actions && git config user.email github-actions@github.com
git checkout --orphan gh-pages && git rm -rfq . && git commit --allow-empty -m "Benchmark data branch"
git push origin gh-pages && git checkout -
fi
- uses: benchmark-action/github-action-benchmark@v1
with:
name: funlib.geometry
tool: customSmallerIsBetter
output-file-path: benchmarks/output.json
ref: ${{ github.event.workflow_run.head_sha }}
github-token: ${{ secrets.GITHUB_TOKEN }}
gh-pages-branch: gh-pages
benchmark-data-dir-path: dev/bench
auto-push: true
alert-threshold: "150%"
comment-on-alert: true
fail-on-alert: false
summary-always: true
39 changes: 39 additions & 0 deletions .github/workflows/docs.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
name: docs
on:
# Rebuild after every benchmark run so the charts carry the newest point;
# workflow_run fires on the default branch only.
workflow_run:
workflows: [benchmark]
types: [completed]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v6
- run: uv sync --locked --group docs
- run: uv run --locked --group docs sphinx-build -W docs/source docs/build/html -b html
# The benchmark action keeps its data and dashboard on gh-pages; the
# site is deployed from this artifact, so bring them along.
- run: |
if git fetch --depth=1 origin gh-pages 2>/dev/null && git checkout origin/gh-pages -- dev/bench 2>/dev/null; then
mkdir -p docs/build/html/dev && mv dev/bench docs/build/html/dev/
fi
- uses: actions/upload-pages-artifact@v3
with:
path: docs/build/html
deploy:
if: github.ref == 'refs/heads/main'
needs: build
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- id: deployment
uses: actions/deploy-pages@v4
14 changes: 13 additions & 1 deletion .github/workflows/tests.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -20,4 +20,16 @@ jobs:
with:
python-version: ${{ matrix.python-version }}
- run: uv sync --resolution ${{ matrix.resolution }}
- run: uv run pytest --cov --cov-report=term-missing --cov-report=xml
- name: tests
run: |
start=$(date +%s%N)
uv run pytest
echo "PYTEST_SECONDS=$(awk "BEGIN {print ($(date +%s%N) - $start) / 1e9}")" >> "$GITHUB_ENV"
# The benchmark workflow publishes these numbers after this run completes.
- if: github.event_name != 'pull_request' && matrix.python-version == '3.10' && matrix.resolution == 'highest'
run: uv run python benchmarks/run.py --pytest-seconds "$PYTEST_SECONDS" --pytest-command "uv run pytest"
- if: github.event_name != 'pull_request' && matrix.python-version == '3.10' && matrix.resolution == 'highest'
uses: actions/upload-artifact@v4
with:
name: benchmark
path: benchmarks/output.json
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,5 @@ build

# pytest-cov output
coverage.xml
docs/build/
benchmarks/output.json
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
[![tests](https://github.com/funkelab/funlib.geometry/actions/workflows/tests.yaml/badge.svg)](https://github.com/funkelab/funlib.geometry/actions/workflows/tests.yaml)
[![lint](https://github.com/funkelab/funlib.geometry/actions/workflows/lint.yaml/badge.svg)](https://github.com/funkelab/funlib.geometry/actions/workflows/lint.yaml)
[![docs](https://github.com/funkelab/funlib.geometry/actions/workflows/docs.yaml/badge.svg)](https://funkelab.github.io/funlib.geometry)
[![publish](https://github.com/funkelab/funlib.geometry/actions/workflows/publish.yaml/badge.svg)](https://pypi.org/project/funlib.geometry/)

# funlib.geometry
A package for Coordinates, Rois and common operations in Coordinate spaces

**Documentation:** https://funkelab.github.io/funlib.geometry

## Install

```bash
Expand Down Expand Up @@ -92,8 +95,10 @@ git clone https://github.com/funkelab/funlib.geometry
cd funlib.geometry
uv sync # Python, dependencies, dev tools (from uv.lock)
uv run pytest # tests with coverage
uv run pytest --no-cov tests/<file>.py # one file, without the coverage floor
uv run ruff check . && uv run ruff format --check . # lint and formatting
uv run ty check # types
uv run --group docs sphinx-build -W docs/source docs/build/html # docs
```

`uv.lock` pins the development environment; the `lock-upgrade` workflow refreshes it monthly and opens a pull request.
81 changes: 81 additions & 0 deletions benchmarks/run.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
#!/usr/bin/env python3
"""Emit benchmarks/output.json in github-action-benchmark's customSmallerIsBetter format.

Metrics:
import … (cold) wall time of `python -I -c "import <IMPORTS>"` minus
`python -I -c "pass"`, median of N runs
pytest wall time the duration of the test suite, passed in with
--pytest-seconds by the tests job that just ran it

Run from the repo root: uv run python benchmarks/run.py --pytest-seconds 12.3
"""

from __future__ import annotations

import argparse
import json
import statistics
import subprocess
import sys
import time
from pathlib import Path

# The modules a user imports first; the top-level package where its __init__
# carries the public surface, the headline submodules where it does not.
IMPORTS = ["funlib.geometry"]
ROOT = Path(__file__).resolve().parent.parent


def wall(cmd: list[str], runs: int) -> list[float]:
out = []
for _ in range(runs):
t = time.perf_counter()
subprocess.run(cmd, check=True, capture_output=True, cwd=ROOT)
out.append(time.perf_counter() - t)
return out


def import_time(runs: int) -> dict:
base = wall([sys.executable, "-I", "-c", "pass"], runs)
full = wall([sys.executable, "-I", "-c", f"import {', '.join(IMPORTS)}"], runs)
delta = [max(0.0, f - statistics.median(base)) for f in full]
return entry(
f"import {', '.join(IMPORTS)} (cold)",
statistics.median(delta) * 1e3,
"ms",
pstdev(delta) * 1e3,
f"interpreter startup {statistics.median(base) * 1e3:.1f} ms subtracted; n={runs}",
)


def pytest_time(seconds: float, command: str) -> dict:
return entry(
"pytest wall time", seconds, "s", None, f"`{command}` in the tests job"
)


def pstdev(xs):
return statistics.pstdev(xs) if len(xs) > 1 else 0.0


def entry(name, value, unit, rng, extra):
e = {"name": name, "unit": unit, "value": round(value, 3)}
if rng is not None:
e["range"] = f"± {rng:.3f}"
if extra:
e["extra"] = extra
return e


if __name__ == "__main__":
ap = argparse.ArgumentParser()
ap.add_argument("--output", default="benchmarks/output.json")
ap.add_argument("--runs", type=int, default=10)
ap.add_argument("--pytest-seconds", type=float, default=None)
ap.add_argument("--pytest-command", default="uv run pytest")
args = ap.parse_args()
results = [import_time(args.runs)]
if args.pytest_seconds is not None:
results.append(pytest_time(args.pytest_seconds, args.pytest_command))
Path(args.output).write_text(json.dumps(results, indent=2) + "\n")
print(json.dumps(results, indent=2))
107 changes: 107 additions & 0 deletions docs/source/_static/benchmarks.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
// Renders one line chart per benchmark from window.BENCHMARK_DATA, the file
// github-action-benchmark writes to gh-pages:dev/bench/data.js.

function benchmarksUnavailable() {
const status = document.getElementById("benchmark-status");
if (status) {
status.textContent =
"No benchmark data in this build. Data appears once the benchmark " +
"workflow has run on main and the docs have been rebuilt.";
}
}

function renderBenchmarks() {
const data = window.BENCHMARK_DATA;
const container = document.getElementById("benchmark-charts");
if (!data || !container) {
benchmarksUnavailable();
return;
}
const status = document.getElementById("benchmark-status");
if (status) {
status.remove();
}
const dark = document.documentElement.dataset.theme === "dark";
const text = dark ? "#d0d0d0" : "#333";
const grid = dark ? "rgba(255,255,255,0.12)" : "rgba(0,0,0,0.1)";

for (const [suite, entries] of Object.entries(data.entries)) {
const names = [];
for (const entry of entries) {
for (const bench of entry.benches) {
if (!names.includes(bench.name)) {
names.push(bench.name);
}
}
}
for (const name of names) {
const points = entries
.map((entry) => {
const bench = entry.benches.find((b) => b.name === name);
return bench ? { entry, bench } : null;
})
.filter(Boolean);
const unit = points[0].bench.unit;

const heading = document.createElement("h2");
heading.textContent = entries.length > 1 && Object.keys(data.entries).length > 1
? `${suite}: ${name}`
: name;
container.appendChild(heading);
const canvas = document.createElement("canvas");
canvas.height = 90;
container.appendChild(canvas);

const chart = new Chart(canvas, {
type: "line",
data: {
labels: points.map((p) => p.entry.commit.id.slice(0, 7)),
datasets: [
{
label: `${name} (${unit})`,
data: points.map((p) => p.bench.value),
borderColor: "#2a6fdb",
backgroundColor: "#2a6fdb",
tension: 0.1,
pointRadius: 4,
pointHoverRadius: 6,
},
],
},
options: {
animation: false,
scales: {
x: { title: { display: true, text: "commit", color: text }, ticks: { color: text }, grid: { color: grid } },
y: { beginAtZero: true, title: { display: true, text: unit, color: text }, ticks: { color: text }, grid: { color: grid } },
},
plugins: {
legend: { display: false },
tooltip: {
callbacks: {
title: (items) => {
const p = points[items[0].dataIndex];
return p.entry.commit.message.split("\n")[0];
},
label: (item) => {
const p = points[item.dataIndex];
const spread = p.bench.range ? ` ${p.bench.range}` : "";
return `${p.bench.value} ${unit}${spread}`;
},
afterLabel: (item) => {
const p = points[item.dataIndex];
return `${p.entry.commit.id.slice(0, 7)} · ${new Date(p.entry.commit.timestamp).toLocaleString()}`;
},
},
},
},
onClick: (_event, elements) => {
if (elements.length) {
window.open(points[elements[0].index].entry.commit.url, "_blank");
}
},
},
});
chart.canvas.style.cursor = "pointer";
}
}
}
36 changes: 36 additions & 0 deletions docs/source/_static/custom.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
/* Use the whole window on wide screens; the theme caps the page at 88rem. */
.bd-page-width,
.bd-container,
.bd-main .bd-content .bd-article-container {
max-width: 100% !important;
}
.bd-article-container {
padding-left: 2rem;
padding-right: 2rem;
}

/* Wide tables scroll inside the page rather than clipping. */
table.table {
display: block;
overflow-x: auto;
white-space: nowrap;
}

/* Images fill the available width. */
.bd-article img {
max-width: 100%;
height: auto;
}

/* One parameter per line in API signatures, as in volara's docs. */
.sig-param::before {
content: "\a\20\20\20\20\20\20\20\20\20\20\20\20\20\20\20\20";
white-space: pre;
}
dt em.sig-param:last-of-type::after {
content: "\a";
white-space: pre;
}
dl.class > dt:first-of-type {
display: block !important;
}
15 changes: 15 additions & 0 deletions docs/source/api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# API

Both classes are importable from `funlib.geometry`.

```{eval-rst}
.. automodule:: funlib.geometry.coordinate
:members:
:undoc-members:
:special-members: __add__, __sub__, __mul__, __truediv__, __floordiv__, __mod__, __pow__, __neg__, __abs__

.. automodule:: funlib.geometry.roi
:members:
:undoc-members:
:special-members: __add__, __sub__, __mul__, __truediv__, __floordiv__, __eq__
```
Loading
Loading