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.
- endstation-0.2.4/PKG-INFO +239 -0
- endstation-0.2.4/README.md +200 -0
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/__init__.py +3 -3
- endstation-0.2.4/src/endstation/docs/__init__.py +34 -0
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/docs/index.py +16 -16
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/docs/markdown.py +25 -25
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/docs/mathtext.py +27 -26
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/forms.py +27 -26
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/optional.py +35 -35
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/paths.py +27 -27
- endstation-0.2.4/src/endstation/progress.py +134 -0
- endstation-0.2.4/src/endstation/qt/__init__.py +124 -0
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/qt/canvas.py +38 -37
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/qt/jobs.py +35 -33
- endstation-0.2.4/src/endstation/qt/liveness.py +47 -0
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/qt/sizing.py +11 -10
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/qt/tokens.py +20 -18
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/testing/boundary.py +29 -27
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/testing/plugin.py +27 -26
- endstation-0.2.4/src/endstation/tools/__init__.py +34 -0
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/tools/make_app.py +18 -17
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/tools/make_icon.py +15 -14
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/tools/publish_wiki.py +10 -10
- endstation-0.2.4/src/endstation.egg-info/PKG-INFO +239 -0
- {endstation-0.2.2 → endstation-0.2.4}/tests/test_packaging.py +18 -0
- endstation-0.2.2/PKG-INFO +0 -228
- endstation-0.2.2/README.md +0 -189
- endstation-0.2.2/src/endstation/docs/__init__.py +0 -34
- endstation-0.2.2/src/endstation/progress.py +0 -131
- endstation-0.2.2/src/endstation/qt/__init__.py +0 -121
- endstation-0.2.2/src/endstation/qt/liveness.py +0 -48
- endstation-0.2.2/src/endstation/tools/__init__.py +0 -33
- endstation-0.2.2/src/endstation.egg-info/PKG-INFO +0 -228
- {endstation-0.2.2 → endstation-0.2.4}/LICENSE +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/pyproject.toml +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/setup.cfg +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/py.typed +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation/testing/__init__.py +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation.egg-info/SOURCES.txt +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation.egg-info/dependency_links.txt +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation.egg-info/entry_points.txt +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation.egg-info/requires.txt +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/src/endstation.egg-info/top_level.txt +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/tests/test_boundary_helper.py +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/tests/test_core_has_no_dependencies.py +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/tests/test_docs.py +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/tests/test_forms.py +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/tests/test_optional.py +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/tests/test_paths.py +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/tests/test_progress.py +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/tests/test_qt_jobs.py +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/tests/test_qt_tokens.py +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/tests/test_qt_widgets.py +0 -0
- {endstation-0.2.2 → endstation-0.2.4}/tests/test_template.py +0 -0
- {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
|
+
[](https://pypi.org/project/endstation/)
|
|
43
|
+
[](https://pypi.org/project/endstation/)
|
|
44
|
+
[](https://github.com/jamccoy/endstation/actions/workflows/test.yml)
|
|
45
|
+
[](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
|
+
[](https://pypi.org/project/endstation/)
|
|
4
|
+
[](https://pypi.org/project/endstation/)
|
|
5
|
+
[](https://github.com/jamccoy/endstation/actions/workflows/test.yml)
|
|
6
|
+
[](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
|
-
|
|
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
|
|
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.
|
|
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
|
-
|
|
4
|
-
to know what to generate, a test needs to check the
|
|
5
|
-
``--explain`` should be able to print the same prose
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
Ordering is explicit
|
|
9
|
-
|
|
10
|
-
``
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
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
|
|
19
|
-
that silently loses half its items when installed is not
|
|
20
|
-
page still appears and
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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
|
-
|
|
13
|
-
|
|
14
|
-
conversion has to interleave with math extraction
|
|
15
|
-
handles headings, paragraphs, bullet and numbered lists,
|
|
16
|
-
inline code, bold, italic, links, block quotes and rules,
|
|
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
|
|
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 < w``, which
|
|
23
|
-
it renders literally.
|
|
24
|
-
on the raw source and only the
|
|
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
|
|
27
|
-
does not handle ``data:`` URLs, so each rendered equation
|
|
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``.
|
|
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
|
|
33
|
-
appears in a distinct colour, so a future edit
|
|
34
|
-
|
|
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
|
|
240
|
-
|
|
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
|
|