endstation 0.2.0__tar.gz

endstation-0.2.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Jake McCoy
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

endstation-0.2.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: endstation
+Version: 0.2.0
+Summary: Shared scaffolding for desktop scientific applications: optional-dependency guards, cancellable workers, Qt/matplotlib panes, and macOS app bundling
+Author: Jake McCoy
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/jamccoy/endstation
+Keywords: gui,pyside6,matplotlib,macos,scientific,packaging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: qt
+Requires-Dist: PySide6-Essentials>=6.7; extra == "qt"
+Requires-Dist: matplotlib>=3.8; extra == "qt"
+Provides-Extra: mpl
+Requires-Dist: matplotlib>=3.8; extra == "mpl"
+Provides-Extra: docs
+Requires-Dist: matplotlib>=3.8; extra == "docs"
+Provides-Extra: testing
+Requires-Dist: pytest>=7; extra == "testing"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-qt>=4.5; extra == "dev"
+Requires-Dist: PySide6-Essentials>=6.7; extra == "dev"
+Requires-Dist: matplotlib>=3.8; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: copier>=9; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: PyYAML>=6; extra == "dev"
+Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
+Dynamic: license-file
+
+# endstation
+
+Shared scaffolding for desktop scientific applications.
+
+Not a science library. This is the apparatus that surrounds an analysis:
+guarding optional dependencies, reporting and cancelling slow work, collecting
+form errors, locating research data that is deliberately not in the checkout,
+running work off the UI thread, embedding a figure, rendering a documentation
+page, and building a macOS bundle.
+
+The name is the point. At a synchrotron the endstation is the shared apparatus
+every experiment bolts onto — goniometer, detector, motion control — distinct
+from the science each experiment does.
+
+## Why it exists
+
+Four projects were four independent builds of the same artifact: a Python
+science package with an optional PySide6/matplotlib front-end, a hand-rolled
+macOS `.app`, private research data held outside the checkout, and a test suite
+that has to stay runnable headless. Every one of those concerns had been solved
+three or four times, and the copies had already drifted:
+
+- One project derives its layout floor from platform metrics after the
+  hardcoded-width bug shipped twice unnoticed; two others still hardcode a
+  pixel count.
+- One worker fixed a slot-ordering bug and a garbage-collection crash during
+  teardown; two others have neither fix.
+- The test that keeps a toolkit out of the pure layer exists three times, and
+  the strongest version — a subprocess import, which catches *transitive*
+  imports — is in only one of them.
+
+Each of those is a fix that landed in one place and not the others. That is the
+problem this package exists to stop.
+
+## The one rule
+
+**The core has no dependencies.**
+
+```toml
+dependencies = []
+```
+
+`eblfrac` declares exactly that, so its fracture engine and GPF writer install
+anywhere. A shared package that quietly pulled numpy in would take that away at
+install time, from every downstream user, with no error to notice.
+
+So `endstation`, `endstation.optional`, `endstation.progress`,
+`endstation.forms` and `endstation.paths` import nothing third-party at all, and
+`tests/test_core_has_no_dependencies.py` fails if that ever stops being true.
+Everything heavier lives behind an extra:
+
+| Subpackage | Extra | Needs |
+|---|---|---|
+| `endstation.qt` | `qt` | PySide6, matplotlib |
+| `endstation.docs` | `docs` | matplotlib, for math only |
+| `endstation.testing` | `testing` | pytest |
+| `endstation.tools` | — | macOS `sips`/`iconutil` at runtime |
+
+`requires-python = ">=3.10"`, because `eblfrac` declares 3.10. A shared package
+must not raise its consumers' floor.
+
+## Install
+
+From PyPI, from 0.2.0 on:
+
+```bash
+pip install "endstation[qt]"
+```
+
+Or straight from git, pinning a tag for anything that matters:
+
+```bash
+pip install "endstation @ git+https://github.com/jamccoy/endstation.git@v0.2.0"
+```
+
+For work on endstation itself:
+
+```bash
+pip install -e '.[dev]'
+```
+
+### Publishing
+
+`.github/workflows/publish.yml` releases to PyPI when a `v*` tag is pushed,
+using Trusted Publishing — there is no API token anywhere, so there is nothing
+to leak or rotate. It needs a one-time *pending publisher* registered at
+<https://pypi.org/manage/account/publishing/> for `jamccoy/endstation`,
+workflow `publish.yml`, environment `pypi`.
+
+## What is in it
+
+### `endstation.optional` — dependencies that explain themselves
+
+```python
+from endstation import require_extra, optional_module
+
+require_extra("PySide6", "gui", still_works="The analysis works without it.")
+
+astropy = optional_module("astropy", "trapezoid", package="als_eff_meas")
+```
+
+`require_extra` is a check that uses `find_spec`, so it costs nothing when the
+dependency is present and is safe to call from a module forbidden to import a
+toolkit. `optional_module` is a lazy proxy, so one missing package breaks only
+the functions that actually need it rather than every function in the module.
+
+The install command in the message is quoted, and the quotes are load-bearing:
+square brackets are glob characters, and zsh answers an unquoted
+`pip install .[gui]` with `no matches found`.
+
+### `endstation.progress` — cancellation that actually stops the work
+
+One callback, `progress(done, total)`. A callback that wants to stop raises
+`Cancelled`, and the loops let it propagate.
+
+```python
+from endstation.progress import cancelling, throttled
+
+report = cancelling(throttled(on_progress), cancel_event.is_set)
+```
+
+A Python thread cannot be killed and a NumPy-bound call has no check point, so
+the progress callback is the only moment a caller gets to interrupt. Without it
+cancelling stops the *waiting* — the CPU keeps working and the result is
+computed and thrown away.
+
+Reporting is throttled; the cancellation check is not. A Cancel click lands at
+the next unit of work, not the next percent.
+
+### `endstation.forms` — errors collected, not raised on the first failure
+
+A form with three bad fields reports three problems, rather than making the user
+fix them one at a time and rediscover the next on each attempt.
+
+```python
+errors = ErrorCollector()
+if period <= 0:
+    errors.add("period", "must be positive")
+if not 0 <= trim < MAX_TRIM:
+    errors.add("trim", f"must be between 0 and {MAX_TRIM}")
+errors.raise_if_any()
+```
+
+### `endstation.paths` — data that is deliberately not in the checkout
+
+```python
+scans = find_data("GRATINGLAB_AFM_DIR", "~/Documents/afm_scans",
+                  hint="docs/DATA.md")
+```
+
+A missing root is reported by name. `FileNotFoundError: [Errno 2]` on a path the
+user never typed is unactionable; naming the variable and the resolved path
+makes it a one-line fix.
+
+### `endstation.testing` — a headless suite without the conftest preamble
+
+Registered through the `pytest11` entry point, so no conftest has to name it. It
+sets `QT_QPA_PLATFORM=offscreen`, `QT_API`, `PYTEST_QT_API` and `MPLBACKEND` —
+all with `setdefault`, so `QT_QPA_PLATFORM=cocoa pytest tests/test_gui.py` still
+opens a real window. `ENDSTATION_NO_HEADLESS=1` disables it entirely.
+
+## Tests
+
+```bash
+.venv/bin/python -m pytest -q
+```
+
+## The template
+
+The pyproject skeleton, the CI workflow, the headless conftest and the ignore
+rules are duplicated across these projects too — but they must not become a
+runtime dependency, so they live in a [copier](https://copier.readthedocs.io)
+template rather than in the package:
+
+```bash
+pipx run copier copy gh:jamccoy/endstation my-project
+```
+
+It asks whether the project has a PySide6 window and whether its tests read data
+held outside the checkout, and renders accordingly — a library project gets no
+`gui/` directory, and no apt step installing Qt system libraries into a CI run
+that will never open a window.
+
+What it carries that is easy to get wrong:
+
+- The CI step that **constructs a `QApplication`** rather than merely importing
+  PySide6. The import succeeds long before the platform plugin is asked to load,
+  which is where a missing system library actually bites — and it fails next to
+  the apt step that would be at fault.
+- The check that data-dependent tests **skipped rather than failed**, and the
+  floor on how many tests must pass. A suite that quietly shrinks goes green
+  while testing almost nothing.
+- No `qt_api` in `[tool.pytest.ini_options]`. It is a pytest-qt option, so
+  declaring it makes the suite unrunnable without the toolkit — the plugin
+  exports `PYTEST_QT_API` instead.
+- Local working notes ignored from the first commit, as a category, so a
+  scratch file never lands in a published repository by accident.
+
+`tests/test_template.py` renders both variants and inspects the output, so a
+Jinja typo or a `${{ }}` the renderer ate fails here rather than the next time
+someone starts a project.

endstation-0.2.0/README.md

@@ -0,0 +1,201 @@
+# endstation
+
+Shared scaffolding for desktop scientific applications.
+
+Not a science library. This is the apparatus that surrounds an analysis:
+guarding optional dependencies, reporting and cancelling slow work, collecting
+form errors, locating research data that is deliberately not in the checkout,
+running work off the UI thread, embedding a figure, rendering a documentation
+page, and building a macOS bundle.
+
+The name is the point. At a synchrotron the endstation is the shared apparatus
+every experiment bolts onto — goniometer, detector, motion control — distinct
+from the science each experiment does.
+
+## Why it exists
+
+Four projects were four independent builds of the same artifact: a Python
+science package with an optional PySide6/matplotlib front-end, a hand-rolled
+macOS `.app`, private research data held outside the checkout, and a test suite
+that has to stay runnable headless. Every one of those concerns had been solved
+three or four times, and the copies had already drifted:
+
+- One project derives its layout floor from platform metrics after the
+  hardcoded-width bug shipped twice unnoticed; two others still hardcode a
+  pixel count.
+- One worker fixed a slot-ordering bug and a garbage-collection crash during
+  teardown; two others have neither fix.
+- The test that keeps a toolkit out of the pure layer exists three times, and
+  the strongest version — a subprocess import, which catches *transitive*
+  imports — is in only one of them.
+
+Each of those is a fix that landed in one place and not the others. That is the
+problem this package exists to stop.
+
+## The one rule
+
+**The core has no dependencies.**
+
+```toml
+dependencies = []
+```
+
+`eblfrac` declares exactly that, so its fracture engine and GPF writer install
+anywhere. A shared package that quietly pulled numpy in would take that away at
+install time, from every downstream user, with no error to notice.
+
+So `endstation`, `endstation.optional`, `endstation.progress`,
+`endstation.forms` and `endstation.paths` import nothing third-party at all, and
+`tests/test_core_has_no_dependencies.py` fails if that ever stops being true.
+Everything heavier lives behind an extra:
+
+| Subpackage | Extra | Needs |
+|---|---|---|
+| `endstation.qt` | `qt` | PySide6, matplotlib |
+| `endstation.docs` | `docs` | matplotlib, for math only |
+| `endstation.testing` | `testing` | pytest |
+| `endstation.tools` | — | macOS `sips`/`iconutil` at runtime |
+
+`requires-python = ">=3.10"`, because `eblfrac` declares 3.10. A shared package
+must not raise its consumers' floor.
+
+## Install
+
+From PyPI, from 0.2.0 on:
+
+```bash
+pip install "endstation[qt]"
+```
+
+Or straight from git, pinning a tag for anything that matters:
+
+```bash
+pip install "endstation @ git+https://github.com/jamccoy/endstation.git@v0.2.0"
+```
+
+For work on endstation itself:
+
+```bash
+pip install -e '.[dev]'
+```
+
+### Publishing
+
+`.github/workflows/publish.yml` releases to PyPI when a `v*` tag is pushed,
+using Trusted Publishing — there is no API token anywhere, so there is nothing
+to leak or rotate. It needs a one-time *pending publisher* registered at
+<https://pypi.org/manage/account/publishing/> for `jamccoy/endstation`,
+workflow `publish.yml`, environment `pypi`.
+
+## What is in it
+
+### `endstation.optional` — dependencies that explain themselves
+
+```python
+from endstation import require_extra, optional_module
+
+require_extra("PySide6", "gui", still_works="The analysis works without it.")
+
+astropy = optional_module("astropy", "trapezoid", package="als_eff_meas")
+```
+
+`require_extra` is a check that uses `find_spec`, so it costs nothing when the
+dependency is present and is safe to call from a module forbidden to import a
+toolkit. `optional_module` is a lazy proxy, so one missing package breaks only
+the functions that actually need it rather than every function in the module.
+
+The install command in the message is quoted, and the quotes are load-bearing:
+square brackets are glob characters, and zsh answers an unquoted
+`pip install .[gui]` with `no matches found`.
+
+### `endstation.progress` — cancellation that actually stops the work
+
+One callback, `progress(done, total)`. A callback that wants to stop raises
+`Cancelled`, and the loops let it propagate.
+
+```python
+from endstation.progress import cancelling, throttled
+
+report = cancelling(throttled(on_progress), cancel_event.is_set)
+```
+
+A Python thread cannot be killed and a NumPy-bound call has no check point, so
+the progress callback is the only moment a caller gets to interrupt. Without it
+cancelling stops the *waiting* — the CPU keeps working and the result is
+computed and thrown away.
+
+Reporting is throttled; the cancellation check is not. A Cancel click lands at
+the next unit of work, not the next percent.
+
+### `endstation.forms` — errors collected, not raised on the first failure
+
+A form with three bad fields reports three problems, rather than making the user
+fix them one at a time and rediscover the next on each attempt.
+
+```python
+errors = ErrorCollector()
+if period <= 0:
+    errors.add("period", "must be positive")
+if not 0 <= trim < MAX_TRIM:
+    errors.add("trim", f"must be between 0 and {MAX_TRIM}")
+errors.raise_if_any()
+```
+
+### `endstation.paths` — data that is deliberately not in the checkout
+
+```python
+scans = find_data("GRATINGLAB_AFM_DIR", "~/Documents/afm_scans",
+                  hint="docs/DATA.md")
+```
+
+A missing root is reported by name. `FileNotFoundError: [Errno 2]` on a path the
+user never typed is unactionable; naming the variable and the resolved path
+makes it a one-line fix.
+
+### `endstation.testing` — a headless suite without the conftest preamble
+
+Registered through the `pytest11` entry point, so no conftest has to name it. It
+sets `QT_QPA_PLATFORM=offscreen`, `QT_API`, `PYTEST_QT_API` and `MPLBACKEND` —
+all with `setdefault`, so `QT_QPA_PLATFORM=cocoa pytest tests/test_gui.py` still
+opens a real window. `ENDSTATION_NO_HEADLESS=1` disables it entirely.
+
+## Tests
+
+```bash
+.venv/bin/python -m pytest -q
+```
+
+## The template
+
+The pyproject skeleton, the CI workflow, the headless conftest and the ignore
+rules are duplicated across these projects too — but they must not become a
+runtime dependency, so they live in a [copier](https://copier.readthedocs.io)
+template rather than in the package:
+
+```bash
+pipx run copier copy gh:jamccoy/endstation my-project
+```
+
+It asks whether the project has a PySide6 window and whether its tests read data
+held outside the checkout, and renders accordingly — a library project gets no
+`gui/` directory, and no apt step installing Qt system libraries into a CI run
+that will never open a window.
+
+What it carries that is easy to get wrong:
+
+- The CI step that **constructs a `QApplication`** rather than merely importing
+  PySide6. The import succeeds long before the platform plugin is asked to load,
+  which is where a missing system library actually bites — and it fails next to
+  the apt step that would be at fault.
+- The check that data-dependent tests **skipped rather than failed**, and the
+  floor on how many tests must pass. A suite that quietly shrinks goes green
+  while testing almost nothing.
+- No `qt_api` in `[tool.pytest.ini_options]`. It is a pytest-qt option, so
+  declaring it makes the suite unrunnable without the toolkit — the plugin
+  exports `PYTEST_QT_API` instead.
+- Local working notes ignored from the first commit, as a category, so a
+  scratch file never lands in a published repository by accident.
+
+`tests/test_template.py` renders both variants and inspects the output, so a
+Jinja typo or a `${{ }}` the renderer ate fails here rather than the next time
+someone starts a project.

endstation-0.2.0/pyproject.toml

@@ -0,0 +1,155 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "endstation"
+# Read from `endstation.__version__` rather than restated here. Two literals
+# drift, and the one that drifts is always the one nobody looks at.
+dynamic = ["version"]
+description = "Shared scaffolding for desktop scientific applications: optional-dependency guards, cancellable workers, Qt/matplotlib panes, and macOS app bundling"
+readme = "README.md"
+# 3.10 rather than 3.12: `eblfrac` declares >=3.10 and `gratinglab` >=3.11.
+# A shared package cannot raise the floor of the projects it serves.
+requires-python = ">=3.10"
+license = { text = "BSD-3-Clause" }
+authors = [{ name = "Jake McCoy" }]
+keywords = ["gui", "pyside6", "matplotlib", "macos", "scientific", "packaging"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+
+# Deliberately empty, and the one line in this file worth defending.
+#
+# `eblfrac` declares `dependencies = []` on purpose -- its fracture engine and
+# GPF writer install anywhere, including on a machine with no scientific stack
+# at all. A shared package that forced numpy on it would take that away, and it
+# would take it away silently, at install time, from every downstream user.
+# Everything here that needs numpy, matplotlib or a toolkit lives behind an
+# extra and is imported inside the function that needs it.
+dependencies = []
+
+[project.optional-dependencies]
+# PySide6-Essentials rather than the PySide6 meta-package: the Addons
+# (WebEngine, Multimedia, 3D) are hundreds of megabytes no window served by
+# this package touches. Essentials still carries QtSvg, which matplotlib's Qt
+# shim imports unconditionally.
+#
+# PySide6 (LGPLv3) rather than PyQt5/PyQt6 (GPL). This package is BSD-3, and an
+# optional, dynamically-linked LGPL dependency keeps it that way -- the same
+# reasoning every project downstream of it already applies to its own GUI extra.
+#
+# matplotlib belongs here, not only in `mpl`. `endstation.qt.canvas` embeds a
+# figure and `use_qt_backend` pins the backend, so a `qt` install without it
+# gives a FigurePane that raises on construction -- and raises with a bare
+# ModuleNotFoundError, which is the exact failure this package exists to
+# replace. Declaring it is the fix; `require_extra` in use_qt_backend is the
+# backstop for anyone who installs the pieces by hand.
+qt = ["PySide6-Essentials>=6.7", "matplotlib>=3.8"]
+mpl = ["matplotlib>=3.8"]
+# Rendering documentation needs matplotlib for the equations and nothing else:
+# the markdown subset Qt actually renders is small enough that a full CommonMark
+# implementation would mostly be output this cannot use, and the conversion has
+# to interleave with math extraction anyway.
+docs = ["matplotlib>=3.8"]
+testing = ["pytest>=7"]
+dev = [
+    "pytest>=7",
+    "pytest-qt>=4.5",
+    "PySide6-Essentials>=6.7",
+    "matplotlib>=3.8",
+    "ruff>=0.16",
+    "copier>=9",
+    "pytest-cov>=4",
+    # Named rather than inherited. `tests/test_packaging.py` reads the CI
+    # workflow as YAML, and PyYAML reaches this environment only as a transitive
+    # dependency of copier -- so the day copier stops needing it, a packaging
+    # test errors on import instead of skipping, and it does so in a file that
+    # has nothing to do with templates.
+    "PyYAML>=6",
+    # tomllib is 3.11+; this package supports 3.10 to match eblfrac's floor, and
+    # the packaging tests read pyproject on every version. A backport is cheaper
+    # than a skipif per test file -- the second of which is how the same gap
+    # reached CI twice.
+    "tomli>=2; python_version < '3.11'",
+]
+
+[project.scripts]
+endstation-icon = "endstation.tools.make_icon:main"
+endstation-app = "endstation.tools.make_app:main"
+endstation-publish-wiki = "endstation.tools.publish_wiki:main"
+
+[project.urls]
+Homepage = "https://github.com/jamccoy/endstation"
+
+# The pytest plugin is registered here rather than requiring every downstream
+# conftest to name it. `endstation.testing.plugin` is import-safe without
+# pytest installed at the module level only because pytest is what loads it.
+[project.entry-points.pytest11]
+endstation = "endstation.testing.plugin"
+
+[tool.setuptools.dynamic]
+version = { attr = "endstation.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# PEP 561. Every module here is annotated, and without this marker a consumer's
+# type checker silently ignores all of it -- the annotations exist and do
+# nothing, which is worse than not having them.
+[tool.setuptools.package-data]
+endstation = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["error"]
+# No `qt_api` here on purpose: it is a pytest-qt option, and this suite has
+# to run in an environment that has never installed a toolkit. The plugin
+# exports PYTEST_QT_API instead, which pytest-qt honours and which costs
+# nothing when pytest-qt is absent.
+
+# Coverage is what the CI "did the suite shrink" step was reaching for. That
+# step counted passing tests, which answers a different question badly: a floor
+# of 130 against a suite of 186 tolerated a 30% collapse, and the number needed
+# raising by hand every time the suite grew -- so it only ever rotted downward.
+#
+# **Measure with `coverage run -m pytest`, never `pytest --cov`.** This package
+# registers a `pytest11` entry point, and pytest imports entry-point plugins
+# before it imports its own conftest -- which is the whole reason
+# `testing.plugin` is a plugin rather than a fixture. `endstation.testing.plugin`
+# imports `..paths`, which imports the package, which imports the entire
+# dependency-free core. Under `--cov` that all happens before coverage starts
+# recording, so `forms.py` reports 31% when it is 88% covered and `plugin.py`
+# reports 0%. The difference is 8 points of total coverage that do not exist.
+# `coverage run` starts first and sees the imports.
+[tool.coverage.run]
+source = ["endstation"]
+branch = true
+
+[tool.coverage.report]
+# A ratchet, not a target: it sits just under what the suite currently reports,
+# so a regression fails and an improvement is free. Raise it when a phase lands,
+# never lower it to make a red run green.
+fail_under = 78
+show_missing = true
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "\\.\\.\\.",
+]
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.lint]
+# Ruff's own zero-config default before 0.x expanded it. Pyflakes (F) and the
+# handful of pycodestyle error codes that are real bugs rather than style
+# opinions -- undefined names, syntax errors, bare except -- not the ~900-rule
+# everything selection ruff now applies with no config at all.
+select = ["E4", "E7", "E9", "F"]

endstation-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

endstation-0.2.0/src/endstation/__init__.py

@@ -0,0 +1,60 @@
+"""Shared scaffolding for desktop scientific applications.
+
+Not a science library. Everything here is the apparatus that surrounds an
+analysis: guarding optional dependencies, reporting and cancelling slow work,
+collecting form errors, locating research data that is deliberately not in the
+checkout, running work off the UI thread, embedding a figure, rendering a
+documentation page, and building a macOS bundle.
+
+**The core imports nothing.** ``endstation``, ``endstation.optional``,
+``endstation.progress``, ``endstation.forms`` and ``endstation.paths`` have no
+third-party dependencies at all, so a package that declares
+``dependencies = []`` can adopt them without giving that up. numpy, matplotlib
+and a Qt binding live behind extras and are imported inside the functions that
+need them:
+
+========================  ===========  ====================================
+Subpackage                Extra        Needs
+========================  ===========  ====================================
+``endstation.qt``         ``qt``       PySide6, matplotlib
+``endstation.docs``       ``docs``     matplotlib, for math only
+``endstation.testing``    ``testing``  pytest
+``endstation.tools``      --           macOS ``sips``/``iconutil`` at runtime
+========================  ===========  ====================================
+
+Importing this module must therefore stay cheap and toolkit-free; the names
+re-exported below are from the dependency-free core only. Reach into the
+subpackages explicitly for anything else.
+"""
+
+from __future__ import annotations
+
+from .forms import ErrorCollector, FieldError, FormErrors
+from .optional import MissingExtra, optional_module, require_extra
+from .paths import MissingData, data_root, find_data, find_project_root, require_dir
+from .progress import Cancelled, cancelling, report, throttled
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    # optional dependencies
+    "MissingExtra",
+    "optional_module",
+    "require_extra",
+    # progress and cancellation
+    "Cancelled",
+    "cancelling",
+    "report",
+    "throttled",
+    # form validation
+    "ErrorCollector",
+    "FieldError",
+    "FormErrors",
+    # paths
+    "MissingData",
+    "data_root",
+    "find_data",
+    "find_project_root",
+    "require_dir",
+]