endstation 0.2.2__tar.gz → 0.2.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. endstation-0.2.4/PKG-INFO +239 -0
  2. endstation-0.2.4/README.md +200 -0
  3. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/__init__.py +3 -3
  4. endstation-0.2.4/src/endstation/docs/__init__.py +34 -0
  5. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/docs/index.py +16 -16
  6. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/docs/markdown.py +25 -25
  7. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/docs/mathtext.py +27 -26
  8. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/forms.py +27 -26
  9. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/optional.py +35 -35
  10. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/paths.py +27 -27
  11. endstation-0.2.4/src/endstation/progress.py +134 -0
  12. endstation-0.2.4/src/endstation/qt/__init__.py +124 -0
  13. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/qt/canvas.py +38 -37
  14. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/qt/jobs.py +35 -33
  15. endstation-0.2.4/src/endstation/qt/liveness.py +47 -0
  16. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/qt/sizing.py +11 -10
  17. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/qt/tokens.py +20 -18
  18. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/testing/boundary.py +29 -27
  19. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/testing/plugin.py +27 -26
  20. endstation-0.2.4/src/endstation/tools/__init__.py +34 -0
  21. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/tools/make_app.py +18 -17
  22. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/tools/make_icon.py +15 -14
  23. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/tools/publish_wiki.py +10 -10
  24. endstation-0.2.4/src/endstation.egg-info/PKG-INFO +239 -0
  25. {endstation-0.2.2 → endstation-0.2.4}/tests/test_packaging.py +18 -0
  26. endstation-0.2.2/PKG-INFO +0 -228
  27. endstation-0.2.2/README.md +0 -189
  28. endstation-0.2.2/src/endstation/docs/__init__.py +0 -34
  29. endstation-0.2.2/src/endstation/progress.py +0 -131
  30. endstation-0.2.2/src/endstation/qt/__init__.py +0 -121
  31. endstation-0.2.2/src/endstation/qt/liveness.py +0 -48
  32. endstation-0.2.2/src/endstation/tools/__init__.py +0 -33
  33. endstation-0.2.2/src/endstation.egg-info/PKG-INFO +0 -228
  34. {endstation-0.2.2 → endstation-0.2.4}/LICENSE +0 -0
  35. {endstation-0.2.2 → endstation-0.2.4}/pyproject.toml +0 -0
  36. {endstation-0.2.2 → endstation-0.2.4}/setup.cfg +0 -0
  37. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/py.typed +0 -0
  38. {endstation-0.2.2 → endstation-0.2.4}/src/endstation/testing/__init__.py +0 -0
  39. {endstation-0.2.2 → endstation-0.2.4}/src/endstation.egg-info/SOURCES.txt +0 -0
  40. {endstation-0.2.2 → endstation-0.2.4}/src/endstation.egg-info/dependency_links.txt +0 -0
  41. {endstation-0.2.2 → endstation-0.2.4}/src/endstation.egg-info/entry_points.txt +0 -0
  42. {endstation-0.2.2 → endstation-0.2.4}/src/endstation.egg-info/requires.txt +0 -0
  43. {endstation-0.2.2 → endstation-0.2.4}/src/endstation.egg-info/top_level.txt +0 -0
  44. {endstation-0.2.2 → endstation-0.2.4}/tests/test_boundary_helper.py +0 -0
  45. {endstation-0.2.2 → endstation-0.2.4}/tests/test_core_has_no_dependencies.py +0 -0
  46. {endstation-0.2.2 → endstation-0.2.4}/tests/test_docs.py +0 -0
  47. {endstation-0.2.2 → endstation-0.2.4}/tests/test_forms.py +0 -0
  48. {endstation-0.2.2 → endstation-0.2.4}/tests/test_optional.py +0 -0
  49. {endstation-0.2.2 → endstation-0.2.4}/tests/test_paths.py +0 -0
  50. {endstation-0.2.2 → endstation-0.2.4}/tests/test_progress.py +0 -0
  51. {endstation-0.2.2 → endstation-0.2.4}/tests/test_qt_jobs.py +0 -0
  52. {endstation-0.2.2 → endstation-0.2.4}/tests/test_qt_tokens.py +0 -0
  53. {endstation-0.2.2 → endstation-0.2.4}/tests/test_qt_widgets.py +0 -0
  54. {endstation-0.2.2 → endstation-0.2.4}/tests/test_template.py +0 -0
  55. {endstation-0.2.2 → endstation-0.2.4}/tests/test_tools.py +0 -0
@@ -0,0 +1,239 @@
1
+ Metadata-Version: 2.4
2
+ Name: endstation
3
+ Version: 0.2.4
4
+ Summary: Shared scaffolding for desktop scientific applications: optional-dependency guards, cancellable workers, Qt/matplotlib panes, and macOS app bundling
5
+ Author: Jake McCoy
6
+ License: BSD-3-Clause
7
+ Project-URL: Homepage, https://github.com/jamccoy/endstation
8
+ Keywords: gui,pyside6,matplotlib,macos,scientific,packaging
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: License :: OSI Approved :: BSD License
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Topic :: Scientific/Engineering
16
+ Requires-Python: >=3.10
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Provides-Extra: qt
20
+ Requires-Dist: PySide6-Essentials>=6.7; extra == "qt"
21
+ Requires-Dist: matplotlib>=3.8; extra == "qt"
22
+ Provides-Extra: mpl
23
+ Requires-Dist: matplotlib>=3.8; extra == "mpl"
24
+ Provides-Extra: docs
25
+ Requires-Dist: matplotlib>=3.8; extra == "docs"
26
+ Provides-Extra: testing
27
+ Requires-Dist: pytest>=7; extra == "testing"
28
+ Provides-Extra: dev
29
+ Requires-Dist: pytest>=7; extra == "dev"
30
+ Requires-Dist: pytest-qt>=4.5; extra == "dev"
31
+ Requires-Dist: PySide6-Essentials>=6.7; extra == "dev"
32
+ Requires-Dist: matplotlib>=3.8; extra == "dev"
33
+ Requires-Dist: ruff>=0.16; extra == "dev"
34
+ Requires-Dist: copier>=9; extra == "dev"
35
+ Requires-Dist: pytest-cov>=4; extra == "dev"
36
+ Requires-Dist: PyYAML>=6; extra == "dev"
37
+ Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
38
+ Dynamic: license-file
39
+
40
+ # endstation
41
+
42
+ [![PyPI](https://img.shields.io/pypi/v/endstation?cacheSeconds=3600)](https://pypi.org/project/endstation/)
43
+ [![Python](https://img.shields.io/pypi/pyversions/endstation?cacheSeconds=3600)](https://pypi.org/project/endstation/)
44
+ [![tests](https://github.com/jamccoy/endstation/actions/workflows/test.yml/badge.svg)](https://github.com/jamccoy/endstation/actions/workflows/test.yml)
45
+ [![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue)](https://github.com/jamccoy/endstation/blob/master/LICENSE)
46
+
47
+ **[PyPI](https://pypi.org/project/endstation/)** · **[Changelog](https://github.com/jamccoy/endstation/blob/master/CHANGELOG.md)** · **[Issues](https://github.com/jamccoy/endstation/issues)**
48
+
49
+ endstation is a library of shared components for desktop scientific applications
50
+ written in Python. It provides the parts of such an application that surround the
51
+ analysis itself: guards for optional dependencies, progress reporting and
52
+ cancellation for slow work, collection of form errors, location of research data
53
+ kept outside the checkout, background workers for the user interface, embedded
54
+ figures, rendered documentation pages, and macOS application bundles.
55
+
56
+ The name is taken from synchrotron beamlines, where the endstation is the shared
57
+ apparatus to which each experiment is attached, such as the goniometer, detector and
58
+ motion control, as distinct from the science each experiment carries out.
59
+
60
+ ## Why it exists
61
+
62
+ Four projects share the same structure: a Python science package with an optional
63
+ PySide6 and matplotlib front end, a macOS `.app`, research data held outside the
64
+ checkout, and a test suite that runs without a display. Each had solved those problems
65
+ separately, and the copies had diverged; a layout fix, a fix to worker shutdown and a
66
+ stronger test of the toolkit import had each been made in one project and not in the
67
+ others. This package now holds those components, so that a fix made once applies to
68
+ every project.
69
+
70
+ ## The core has no dependencies
71
+
72
+ ```toml
73
+ dependencies = []
74
+ ```
75
+
76
+ One of the projects that depend on endstation, `eblfrac`, a fracturing tool for
77
+ electron-beam lithography patterns, declares exactly that, so its fracture engine and
78
+ GPF writer can be installed anywhere. A shared package that required numpy would remove
79
+ that property from every project that depends on it, and nothing would report the
80
+ change.
81
+
82
+ `endstation`, `endstation.optional`, `endstation.progress`, `endstation.forms` and
83
+ `endstation.paths` import no third-party packages, and
84
+ `tests/test_core_has_no_dependencies.py` fails if that changes. Everything that needs
85
+ more is installed through an extra:
86
+
87
+ | Subpackage | Extra | Needs |
88
+ |---|---|---|
89
+ | `endstation.qt` | `qt` | PySide6, matplotlib |
90
+ | `endstation.docs` | `docs` | matplotlib, for math only |
91
+ | `endstation.testing` | `testing` | pytest |
92
+ | `endstation.tools` | none | macOS `sips`/`iconutil` at runtime |
93
+
94
+ The package declares `requires-python = ">=3.10"`, because `eblfrac` declares 3.10 and
95
+ a shared package should not raise the minimum Python version of the projects that use
96
+ it.
97
+
98
+ ## Install
99
+
100
+ ```bash
101
+ pip install "endstation[qt]"
102
+ ```
103
+
104
+ With [uv](https://docs.astral.sh/uv/), the same extras work:
105
+
106
+ ```bash
107
+ uv pip install "endstation[qt]" # into the active environment
108
+ uv add endstation # as a dependency of a uv project
109
+ ```
110
+
111
+ Or from git, pinned to a tag:
112
+
113
+ ```bash
114
+ pip install "endstation @ git+https://github.com/jamccoy/endstation.git@v0.2.4"
115
+ ```
116
+
117
+ For working on endstation itself:
118
+
119
+ ```bash
120
+ pip install -e '.[dev]'
121
+ ```
122
+
123
+ ### Publishing
124
+
125
+ `.github/workflows/publish.yml` releases to PyPI when a `v*` tag is pushed, using
126
+ Trusted Publishing, so no API token needs to be stored. The publisher is registered at
127
+ <https://pypi.org/manage/account/publishing/> for `jamccoy/endstation`, workflow
128
+ `publish.yml`, environment `pypi`.
129
+
130
+ ## Contents
131
+
132
+ ### `endstation.optional`: optional dependencies
133
+
134
+ ```python
135
+ from endstation import require_extra, optional_module
136
+
137
+ require_extra("PySide6", "gui", still_works="The analysis works without it.")
138
+
139
+ astropy = optional_module("astropy", "trapezoid", package="als_eff_meas")
140
+ ```
141
+
142
+ `require_extra` checks for the dependency with `find_spec`, so it costs nothing when the
143
+ dependency is present and can be called from a module that must not import a toolkit.
144
+ When the dependency is missing, the error names the extra that provides it and the
145
+ command that installs it. `optional_module` returns a lazy proxy, so a missing package
146
+ affects only the functions that use it and not the rest of the module.
147
+
148
+ The install command in the error message is quoted, because square brackets are glob
149
+ characters and zsh rejects an unquoted `pip install .[gui]` with `no matches found`.
150
+
151
+ ### `endstation.progress`: progress reporting and cancellation
152
+
153
+ Progress is reported through a single callback, `progress(done, total)`. A callback
154
+ that needs to stop the work raises `Cancelled`, and the loops let the exception
155
+ propagate.
156
+
157
+ ```python
158
+ from endstation.progress import cancelling, throttled
159
+
160
+ report = cancelling(throttled(on_progress), cancel_event.is_set)
161
+ ```
162
+
163
+ A Python thread cannot be terminated from outside, and a NumPy call has no point at
164
+ which it can be interrupted, so the progress callback is the only place a caller can
165
+ stop the computation. Without it, a Cancel button would stop only the waiting, while
166
+ the computation continued and its result was discarded.
167
+
168
+ Progress reports are throttled, but the cancellation check runs at every call, so a
169
+ Cancel click takes effect at the next unit of work.
170
+
171
+ ### `endstation.forms`: form validation
172
+
173
+ A form with several invalid fields reports all of them together, so that the user does
174
+ not have to correct them one at a time.
175
+
176
+ ```python
177
+ errors = ErrorCollector()
178
+ if period <= 0:
179
+ errors.add("period", "must be positive")
180
+ if not 0 <= trim < MAX_TRIM:
181
+ errors.add("trim", f"must be between 0 and {MAX_TRIM}")
182
+ errors.raise_if_any()
183
+ ```
184
+
185
+ ### `endstation.paths`: data kept outside the checkout
186
+
187
+ ```python
188
+ scans = find_data("GRATINGLAB_AFM_DIR", "~/Documents/afm_scans",
189
+ hint="docs/DATA.md")
190
+ ```
191
+
192
+ A missing data directory is reported with the name of the environment variable and the
193
+ path it resolved to. A bare `FileNotFoundError: [Errno 2]` on a path the user never
194
+ entered gives no indication of what to change.
195
+
196
+ ### `endstation.testing`: headless test suites
197
+
198
+ The plugin is registered through the `pytest11` entry point, so no conftest needs to
199
+ load it. It sets `QT_QPA_PLATFORM=offscreen`, `QT_API`, `PYTEST_QT_API` and
200
+ `MPLBACKEND`, each with `setdefault`, so `QT_QPA_PLATFORM=cocoa pytest tests/test_gui.py`
201
+ still opens a real window. Setting `ENDSTATION_NO_HEADLESS=1` disables it.
202
+
203
+ ## Tests
204
+
205
+ ```bash
206
+ .venv/bin/python -m pytest -q
207
+ ```
208
+
209
+ ## The template
210
+
211
+ The same pyproject skeleton, CI workflow, headless conftest and ignore rules are also
212
+ repeated across these projects. They should not be a runtime dependency, so they are
213
+ provided as a [copier](https://copier.readthedocs.io) template instead:
214
+
215
+ ```bash
216
+ pipx run copier copy gh:jamccoy/endstation my-project
217
+ ```
218
+
219
+ The template asks whether the project has a PySide6 window and whether its tests read
220
+ data from outside the checkout. A library project receives no `gui/` directory, and its
221
+ CI does not install Qt system libraries it does not need.
222
+
223
+ The template also includes several details that are easy to overlook:
224
+
225
+ - A CI step that constructs a `QApplication` instead of only importing PySide6. The
226
+ import succeeds before the platform plugin loads, and a missing system library only
227
+ shows up when the plugin loads, so constructing the application makes the failure
228
+ appear next to the installation step that caused it.
229
+ - A check that data-dependent tests were skipped rather than failed, and a minimum
230
+ number of passing tests, so that a suite which loses tests without notice fails CI.
231
+ - No `qt_api` setting in `[tool.pytest.ini_options]`. It is a pytest-qt option, so
232
+ setting it makes the suite fail on a machine without the toolkit; the plugin sets
233
+ `PYTEST_QT_API` instead.
234
+ - Local working notes are ignored from the first commit, so a scratch file is not
235
+ published by accident.
236
+
237
+ `tests/test_template.py` renders both variants of the template and checks the output,
238
+ so a Jinja error, or a `${{ }}` expression consumed by the renderer, fails in this
239
+ repository rather than in a newly generated project.
@@ -0,0 +1,200 @@
1
+ # endstation
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/endstation?cacheSeconds=3600)](https://pypi.org/project/endstation/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/endstation?cacheSeconds=3600)](https://pypi.org/project/endstation/)
5
+ [![tests](https://github.com/jamccoy/endstation/actions/workflows/test.yml/badge.svg)](https://github.com/jamccoy/endstation/actions/workflows/test.yml)
6
+ [![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue)](https://github.com/jamccoy/endstation/blob/master/LICENSE)
7
+
8
+ **[PyPI](https://pypi.org/project/endstation/)** · **[Changelog](https://github.com/jamccoy/endstation/blob/master/CHANGELOG.md)** · **[Issues](https://github.com/jamccoy/endstation/issues)**
9
+
10
+ endstation is a library of shared components for desktop scientific applications
11
+ written in Python. It provides the parts of such an application that surround the
12
+ analysis itself: guards for optional dependencies, progress reporting and
13
+ cancellation for slow work, collection of form errors, location of research data
14
+ kept outside the checkout, background workers for the user interface, embedded
15
+ figures, rendered documentation pages, and macOS application bundles.
16
+
17
+ The name is taken from synchrotron beamlines, where the endstation is the shared
18
+ apparatus to which each experiment is attached, such as the goniometer, detector and
19
+ motion control, as distinct from the science each experiment carries out.
20
+
21
+ ## Why it exists
22
+
23
+ Four projects share the same structure: a Python science package with an optional
24
+ PySide6 and matplotlib front end, a macOS `.app`, research data held outside the
25
+ checkout, and a test suite that runs without a display. Each had solved those problems
26
+ separately, and the copies had diverged; a layout fix, a fix to worker shutdown and a
27
+ stronger test of the toolkit import had each been made in one project and not in the
28
+ others. This package now holds those components, so that a fix made once applies to
29
+ every project.
30
+
31
+ ## The core has no dependencies
32
+
33
+ ```toml
34
+ dependencies = []
35
+ ```
36
+
37
+ One of the projects that depend on endstation, `eblfrac`, a fracturing tool for
38
+ electron-beam lithography patterns, declares exactly that, so its fracture engine and
39
+ GPF writer can be installed anywhere. A shared package that required numpy would remove
40
+ that property from every project that depends on it, and nothing would report the
41
+ change.
42
+
43
+ `endstation`, `endstation.optional`, `endstation.progress`, `endstation.forms` and
44
+ `endstation.paths` import no third-party packages, and
45
+ `tests/test_core_has_no_dependencies.py` fails if that changes. Everything that needs
46
+ more is installed through an extra:
47
+
48
+ | Subpackage | Extra | Needs |
49
+ |---|---|---|
50
+ | `endstation.qt` | `qt` | PySide6, matplotlib |
51
+ | `endstation.docs` | `docs` | matplotlib, for math only |
52
+ | `endstation.testing` | `testing` | pytest |
53
+ | `endstation.tools` | none | macOS `sips`/`iconutil` at runtime |
54
+
55
+ The package declares `requires-python = ">=3.10"`, because `eblfrac` declares 3.10 and
56
+ a shared package should not raise the minimum Python version of the projects that use
57
+ it.
58
+
59
+ ## Install
60
+
61
+ ```bash
62
+ pip install "endstation[qt]"
63
+ ```
64
+
65
+ With [uv](https://docs.astral.sh/uv/), the same extras work:
66
+
67
+ ```bash
68
+ uv pip install "endstation[qt]" # into the active environment
69
+ uv add endstation # as a dependency of a uv project
70
+ ```
71
+
72
+ Or from git, pinned to a tag:
73
+
74
+ ```bash
75
+ pip install "endstation @ git+https://github.com/jamccoy/endstation.git@v0.2.4"
76
+ ```
77
+
78
+ For working on endstation itself:
79
+
80
+ ```bash
81
+ pip install -e '.[dev]'
82
+ ```
83
+
84
+ ### Publishing
85
+
86
+ `.github/workflows/publish.yml` releases to PyPI when a `v*` tag is pushed, using
87
+ Trusted Publishing, so no API token needs to be stored. The publisher is registered at
88
+ <https://pypi.org/manage/account/publishing/> for `jamccoy/endstation`, workflow
89
+ `publish.yml`, environment `pypi`.
90
+
91
+ ## Contents
92
+
93
+ ### `endstation.optional`: optional dependencies
94
+
95
+ ```python
96
+ from endstation import require_extra, optional_module
97
+
98
+ require_extra("PySide6", "gui", still_works="The analysis works without it.")
99
+
100
+ astropy = optional_module("astropy", "trapezoid", package="als_eff_meas")
101
+ ```
102
+
103
+ `require_extra` checks for the dependency with `find_spec`, so it costs nothing when the
104
+ dependency is present and can be called from a module that must not import a toolkit.
105
+ When the dependency is missing, the error names the extra that provides it and the
106
+ command that installs it. `optional_module` returns a lazy proxy, so a missing package
107
+ affects only the functions that use it and not the rest of the module.
108
+
109
+ The install command in the error message is quoted, because square brackets are glob
110
+ characters and zsh rejects an unquoted `pip install .[gui]` with `no matches found`.
111
+
112
+ ### `endstation.progress`: progress reporting and cancellation
113
+
114
+ Progress is reported through a single callback, `progress(done, total)`. A callback
115
+ that needs to stop the work raises `Cancelled`, and the loops let the exception
116
+ propagate.
117
+
118
+ ```python
119
+ from endstation.progress import cancelling, throttled
120
+
121
+ report = cancelling(throttled(on_progress), cancel_event.is_set)
122
+ ```
123
+
124
+ A Python thread cannot be terminated from outside, and a NumPy call has no point at
125
+ which it can be interrupted, so the progress callback is the only place a caller can
126
+ stop the computation. Without it, a Cancel button would stop only the waiting, while
127
+ the computation continued and its result was discarded.
128
+
129
+ Progress reports are throttled, but the cancellation check runs at every call, so a
130
+ Cancel click takes effect at the next unit of work.
131
+
132
+ ### `endstation.forms`: form validation
133
+
134
+ A form with several invalid fields reports all of them together, so that the user does
135
+ not have to correct them one at a time.
136
+
137
+ ```python
138
+ errors = ErrorCollector()
139
+ if period <= 0:
140
+ errors.add("period", "must be positive")
141
+ if not 0 <= trim < MAX_TRIM:
142
+ errors.add("trim", f"must be between 0 and {MAX_TRIM}")
143
+ errors.raise_if_any()
144
+ ```
145
+
146
+ ### `endstation.paths`: data kept outside the checkout
147
+
148
+ ```python
149
+ scans = find_data("GRATINGLAB_AFM_DIR", "~/Documents/afm_scans",
150
+ hint="docs/DATA.md")
151
+ ```
152
+
153
+ A missing data directory is reported with the name of the environment variable and the
154
+ path it resolved to. A bare `FileNotFoundError: [Errno 2]` on a path the user never
155
+ entered gives no indication of what to change.
156
+
157
+ ### `endstation.testing`: headless test suites
158
+
159
+ The plugin is registered through the `pytest11` entry point, so no conftest needs to
160
+ load it. It sets `QT_QPA_PLATFORM=offscreen`, `QT_API`, `PYTEST_QT_API` and
161
+ `MPLBACKEND`, each with `setdefault`, so `QT_QPA_PLATFORM=cocoa pytest tests/test_gui.py`
162
+ still opens a real window. Setting `ENDSTATION_NO_HEADLESS=1` disables it.
163
+
164
+ ## Tests
165
+
166
+ ```bash
167
+ .venv/bin/python -m pytest -q
168
+ ```
169
+
170
+ ## The template
171
+
172
+ The same pyproject skeleton, CI workflow, headless conftest and ignore rules are also
173
+ repeated across these projects. They should not be a runtime dependency, so they are
174
+ provided as a [copier](https://copier.readthedocs.io) template instead:
175
+
176
+ ```bash
177
+ pipx run copier copy gh:jamccoy/endstation my-project
178
+ ```
179
+
180
+ The template asks whether the project has a PySide6 window and whether its tests read
181
+ data from outside the checkout. A library project receives no `gui/` directory, and its
182
+ CI does not install Qt system libraries it does not need.
183
+
184
+ The template also includes several details that are easy to overlook:
185
+
186
+ - A CI step that constructs a `QApplication` instead of only importing PySide6. The
187
+ import succeeds before the platform plugin loads, and a missing system library only
188
+ shows up when the plugin loads, so constructing the application makes the failure
189
+ appear next to the installation step that caused it.
190
+ - A check that data-dependent tests were skipped rather than failed, and a minimum
191
+ number of passing tests, so that a suite which loses tests without notice fails CI.
192
+ - No `qt_api` setting in `[tool.pytest.ini_options]`. It is a pytest-qt option, so
193
+ setting it makes the suite fail on a machine without the toolkit; the plugin sets
194
+ `PYTEST_QT_API` instead.
195
+ - Local working notes are ignored from the first commit, so a scratch file is not
196
+ published by accident.
197
+
198
+ `tests/test_template.py` renders both variants of the template and checks the output,
199
+ so a Jinja error, or a `${{ }}` expression consumed by the renderer, fails in this
200
+ repository rather than in a newly generated project.
@@ -1,12 +1,12 @@
1
1
  """Shared scaffolding for desktop scientific applications.
2
2
 
3
- Not a science library. It covers what surrounds an
3
+ The package is not itself a science library. It covers what surrounds an
4
4
  analysis: guarding optional dependencies, reporting and cancelling slow work,
5
5
  collecting form errors, locating research data kept outside the
6
6
  checkout, running work off the UI thread, embedding a figure, rendering a
7
7
  documentation page, and building a macOS bundle.
8
8
 
9
- The core imports nothing. ``endstation``, ``endstation.optional``,
9
+ The core imports no third-party packages. ``endstation``, ``endstation.optional``,
10
10
  ``endstation.progress``, ``endstation.forms`` and ``endstation.paths`` have no
11
11
  third-party dependencies at all, so a package that declares
12
12
  ``dependencies = []`` can adopt them without giving that up. numpy, matplotlib
@@ -34,7 +34,7 @@ from .optional import MissingExtra, optional_module, require_extra
34
34
  from .paths import MissingData, data_root, find_data, find_project_root, require_dir
35
35
  from .progress import Cancelled, cancelling, report, throttled
36
36
 
37
- __version__ = "0.2.2"
37
+ __version__ = "0.2.4"
38
38
 
39
39
  __all__ = [
40
40
  "__version__",
@@ -0,0 +1,34 @@
1
+ """Documentation pages: an ordered index, and markdown rendered for a Qt viewer.
2
+
3
+ Four projects had a version of this, and each had a capability the others
4
+ lacked: one rendered LaTeX, one prerendered HTML for an older Qt, one shipped
5
+ its pages as package data, and one published them to a GitHub wiki. This
6
+ subpackage combines all four.
7
+
8
+ The subpackage is toolkit-free, and nothing here imports Qt.
9
+ :mod:`endstation.docs.markdown` produces HTML plus a dictionary of PNG bytes,
10
+ and the widget layer registers those with ``QTextDocument.addResource``. As a
11
+ result the whole pipeline can be tested down to the bytes without a display.
12
+
13
+ Math rendering needs matplotlib, which is the ``mpl`` extra. Structure
14
+ conversion alone works without it if ``render_math=False`` is passed.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ from .index import Page, PageIndex, load_pages, title_of
20
+ from .markdown import MATH_URL_PREFIX, RenderedPage, to_html
21
+ from .mathtext import Segment, split_segments, strip_boxed
22
+
23
+ __all__ = [
24
+ "MATH_URL_PREFIX",
25
+ "Page",
26
+ "PageIndex",
27
+ "RenderedPage",
28
+ "Segment",
29
+ "load_pages",
30
+ "split_segments",
31
+ "strip_boxed",
32
+ "title_of",
33
+ "to_html",
34
+ ]
@@ -1,23 +1,23 @@
1
1
  """Which documentation pages exist, and what order they read in.
2
2
 
3
- Toolkit-free on purpose, like the rest of the pure layer: a build script needs
4
- to know what to generate, a test needs to check the set is current, and a CLI
5
- ``--explain`` should be able to print the same prose the window shows. None of
6
- those should need a GUI installed.
7
-
8
- Ordering is explicit, not alphabetical. A reader should meet the overview
9
- before the correction it motivates, and alphabetical ordering puts
10
- ``facet-fitting`` before ``overview`` for no reason anyone can defend. A page
11
- listed in the order but missing from disk is skipped rather than raising -- a
12
- half-written set should not stop a window opening -- and a page found on disk
13
- but absent from the order is appended, so adding a file does not also require
14
- registering it in a second place.
3
+ This module is toolkit-free by design, like the rest of the pure layer. A
4
+ build script needs to know what to generate, a test needs to check that the
5
+ set is current, and a CLI ``--explain`` should be able to print the same prose
6
+ the window shows. None of these should require a GUI to be installed.
7
+
8
+ Ordering is explicit. A reader should meet the overview before the correction
9
+ it motivates, and alphabetical ordering would place ``facet-fitting`` before
10
+ ``overview`` for no good reason. A page listed in the order but missing from
11
+ disk is skipped without raising, because a half-written set should not stop a
12
+ window from opening. A page found on disk but absent from the order is
13
+ appended, so that adding a file does not also require registering it in a
14
+ second place.
15
15
 
16
16
  A missing directory degrades to an explanatory entry. Pages that live at
17
17
  the repository root ship in a checkout and not in a wheel; pages shipped as
18
- package data ship in both. Either is a legitimate arrangement, but a Help menu
19
- that silently loses half its items when installed is not -- so an unavailable
20
- page still appears and says why.
18
+ package data ship in both. Either arrangement is legitimate, but a Help menu
19
+ that silently loses half its items when installed is not acceptable, so an
20
+ unavailable page still appears and states why.
21
21
  """
22
22
 
23
23
  from __future__ import annotations
@@ -104,7 +104,7 @@ def load_pages(
104
104
  ) -> PageIndex:
105
105
  """Build an index from ``directory``.
106
106
 
107
- ``order`` lists slugs -- filenames without ``.md`` -- in reading order.
107
+ ``order`` lists slugs (filenames without ``.md``) in reading order.
108
108
  Slugs in ``order`` but not on disk are skipped; files on disk but not in
109
109
  ``order`` are appended in sorted order.
110
110
 
@@ -1,37 +1,37 @@
1
- r"""Documentation pages as rich text: markdown structure *and* typeset math.
1
+ r"""Documentation pages as rich text, with both markdown structure and typeset math.
2
2
 
3
- Qt's rich-text engine parses a small HTML subset, which makes this cheap: this
3
+ Qt's rich-text engine parses a small HTML subset, which keeps this simple: this
4
4
  module converts a page to that subset, and the widget layer only displays it.
5
5
 
6
- Getting equations rendering and stopping there is a tempting place to stop, and
7
- it goes bad: tables and bullet lists stay as literal pipes and dashes. Real
8
- documentation puts the evidence *in* the tables -- an angle-convention
9
- reconciliation, an errata list, a three-way comparison -- and those are the
10
- content, in the one place a reader goes to understand what the software does.
6
+ Rendering equations alone is not sufficient, because tables and bullet lists
7
+ would then remain as literal pipes and dashes. Real documentation places much
8
+ of its evidence in tables (an angle-convention reconciliation, an errata list,
9
+ a three-way comparison), and those tables are content in the one place a reader
10
+ goes to understand what the software does.
11
11
 
12
- No markdown dependency. The subset Qt renders is small enough that a full
13
- CommonMark implementation would mostly be output this cannot use, and the
14
- conversion has to interleave with math extraction anyway (see below). This
15
- handles headings, paragraphs, bullet and numbered lists, tables, fenced and
16
- inline code, bold, italic, links, block quotes and rules, which is what the
17
- pages contain.
12
+ The module has no markdown dependency. The subset Qt renders is small enough
13
+ that most of the output of a full CommonMark implementation could not be used,
14
+ and the conversion has to interleave with math extraction in any case (see
15
+ below). The module handles headings, paragraphs, bullet and numbered lists,
16
+ tables, fenced and inline code, bold, italic, links, block quotes and rules,
17
+ which covers what the pages contain.
18
18
 
19
- Three things worth knowing before editing:
19
+ Three properties of the design should be understood before editing.
20
20
 
21
21
  Math is split out before anything is escaped. Math spans in real pages
22
22
  contain ``<`` and ``>``. Escaping first would hand mathtext ``t &lt; w``, which
23
- it renders literally. So :func:`~endstation.docs.mathtext.split_segments` runs
24
- on the raw source and only the *text* spans are escaped.
23
+ it renders literally. :func:`~endstation.docs.mathtext.split_segments` therefore
24
+ runs on the raw source, and only the text spans are escaped.
25
25
 
26
- Images are referenced by key, not embedded. ``QTextDocument.loadResource``
27
- does not handle ``data:`` URLs, so each rendered equation gets an
26
+ Images are referenced by key and are not embedded. ``QTextDocument.loadResource``
27
+ does not handle ``data:`` URLs, so each rendered equation is given an
28
28
  ``endstation-math:N`` src and the viewer registers the bytes with
29
- ``addResource``. That also keeps this module free of base64 padding it would
30
- only have to undo.
29
+ ``addResource``. This also spares the module a base64 encoding that the viewer
30
+ would only have to undo.
31
31
 
32
- A render failure degrades rather than crashing. The raw ``$...$`` source
33
- appears in a distinct colour, so a future edit using an unsupported macro is
34
- diagnosable at a glance instead of taking down the page.
32
+ A render failure degrades without crashing. The raw ``$...$`` source
33
+ appears in a distinct colour, so a future edit that uses an unsupported macro
34
+ can be diagnosed at a glance and does not take down the page.
35
35
  """
36
36
 
37
37
  from __future__ import annotations
@@ -236,8 +236,8 @@ _TOKEN = "\x00MATH{}\x00"
236
236
  def to_html(source: str, *, render_math: bool = True) -> RenderedPage:
237
237
  """Convert a markdown page to the HTML subset ``QTextDocument`` renders.
238
238
 
239
- ``render_math=False`` skips rasterisation entirely -- for a test that cares
240
- about structure, or an environment with no matplotlib.
239
+ ``render_math=False`` skips rasterisation entirely, which suits a test
240
+ concerned with structure or an environment without matplotlib.
241
241
  """
242
242
  segments = split_segments(source)
243
243