sheetmap 0.1.0__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.
- sheetmap-0.1.0/.gitignore +9 -0
- sheetmap-0.1.0/PKG-INFO +255 -0
- sheetmap-0.1.0/README.md +230 -0
- sheetmap-0.1.0/examples/lab/compare.yaml +23 -0
- sheetmap-0.1.0/examples/lab/february.xlsx +0 -0
- sheetmap-0.1.0/examples/lab/january.xlsx +0 -0
- sheetmap-0.1.0/examples/lab/map.yaml +14 -0
- sheetmap-0.1.0/pyproject.toml +65 -0
- sheetmap-0.1.0/scripts/build_example.py +83 -0
- sheetmap-0.1.0/scripts/release.py +40 -0
- sheetmap-0.1.0/src/sheetmap/__init__.py +9 -0
- sheetmap-0.1.0/src/sheetmap/__main__.py +5 -0
- sheetmap-0.1.0/src/sheetmap/addressing.py +57 -0
- sheetmap-0.1.0/src/sheetmap/cli.py +88 -0
- sheetmap-0.1.0/src/sheetmap/draw.py +417 -0
- sheetmap-0.1.0/src/sheetmap/errors.py +2 -0
- sheetmap-0.1.0/src/sheetmap/layout.py +247 -0
- sheetmap-0.1.0/src/sheetmap/model.py +246 -0
- sheetmap-0.1.0/src/sheetmap/page.py +268 -0
- sheetmap-0.1.0/src/sheetmap/py.typed +0 -0
- sheetmap-0.1.0/src/sheetmap/render.py +193 -0
- sheetmap-0.1.0/tests/test_layout.py +90 -0
- sheetmap-0.1.0/tests/test_render.py +306 -0
sheetmap-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: sheetmap
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Draw labelled cell ranges over Excel worksheets as PNGs and a standalone review page
|
|
5
|
+
Project-URL: Homepage, https://github.com/phlohouse/sheetmap
|
|
6
|
+
Project-URL: Repository, https://github.com/phlohouse/sheetmap
|
|
7
|
+
Project-URL: Issues, https://github.com/phlohouse/sheetmap/issues
|
|
8
|
+
Author: Phlo House
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
Keywords: excel,openpyxl,review,spreadsheet,visualisation
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Classifier: Topic :: File Formats
|
|
18
|
+
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
|
|
19
|
+
Classifier: Typing :: Typed
|
|
20
|
+
Requires-Python: >=3.12
|
|
21
|
+
Requires-Dist: openpyxl<4,>=3.1
|
|
22
|
+
Requires-Dist: pillow<13,>=10.1
|
|
23
|
+
Requires-Dist: pyyaml<7,>=6.0
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
# sheetmap
|
|
27
|
+
|
|
28
|
+
Draw labelled cell ranges over Excel worksheets. Each mapped sheet becomes a PNG showing its
|
|
29
|
+
contents, fills, borders and merged cells, with every region outlined and tagged with its label.
|
|
30
|
+
The PNGs are gathered into one standalone HTML page, side by side where they fit. With `--review`,
|
|
31
|
+
readers can also click a label to ask for a range to be removed or changed, then copy a summary of
|
|
32
|
+
their requests.
|
|
33
|
+
|
|
34
|
+
Use it to check that a parser, schema or extraction reads the cells you think it does, and to
|
|
35
|
+
let someone who knows the workbook review those choices without reading code.
|
|
36
|
+
|
|
37
|
+
## Run the example
|
|
38
|
+
|
|
39
|
+
From this folder:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
uv run sheetmap examples/lab/map.yaml
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Open `examples/lab/map.html`. The example workbook holds invented data.
|
|
46
|
+
|
|
47
|
+
To check a map against its workbook without writing anything, for example in CI:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
uv run sheetmap check examples/lab/map.yaml
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Write a map
|
|
54
|
+
|
|
55
|
+
A map file names a workbook and the regions to label. Paths resolve relative to the map file.
|
|
56
|
+
|
|
57
|
+
```yaml
|
|
58
|
+
title: Lab report
|
|
59
|
+
workbook: january.xlsx
|
|
60
|
+
subtitle: January example
|
|
61
|
+
preview:
|
|
62
|
+
Raw_Data: {rows: 12, columns: 6}
|
|
63
|
+
regions:
|
|
64
|
+
- {label: patient, ref: "Report!B3"}
|
|
65
|
+
- label: results
|
|
66
|
+
ref: "Report!A7:D"
|
|
67
|
+
columns: {A: sample_id, C: analyte, D: value}
|
|
68
|
+
- {label: flags, ref: "Report!F8:F", kind: list}
|
|
69
|
+
- {label: signals, ref: "Raw_Data!A1:D", kind: table}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Each region needs a `label`, unique within its map, and a `ref`:
|
|
73
|
+
|
|
74
|
+
| `ref` | Meaning |
|
|
75
|
+
| --- | --- |
|
|
76
|
+
| `B3` | One cell on the first worksheet |
|
|
77
|
+
| `Report!B3` | One cell on the `Report` sheet; quote names with spaces: `'Raw data'!B3` |
|
|
78
|
+
| `Report!A7:D20` | A rectangle |
|
|
79
|
+
| `Report!A7:D` | Open-ended: runs to the last row with a value in columns A to D |
|
|
80
|
+
|
|
81
|
+
A region can also take:
|
|
82
|
+
|
|
83
|
+
- `kind`: `cell`, `range`, `list` or `table`, which sets its colour. It defaults to `table` when
|
|
84
|
+
`columns` or `rows` are given, `cell` for one cell and `range` otherwise.
|
|
85
|
+
- `columns`: labels for table columns, keyed by letter. A column without a label continues the
|
|
86
|
+
label on its left when its cells are empty, so merged headers share one label. A column that has
|
|
87
|
+
values but no label is an error, because it usually means the mapping has missed something.
|
|
88
|
+
- `rows`: labels for a table that reads across, keyed by row number. Give `columns` or `rows`,
|
|
89
|
+
not both.
|
|
90
|
+
- `colour`: a hex colour such as `#be123c`, overriding the colour for its kind.
|
|
91
|
+
|
|
92
|
+
A label for one cell of a merged block highlights the whole block.
|
|
93
|
+
|
|
94
|
+
A map file can set `layout` and `review` for the page, as described below. A map can also take:
|
|
95
|
+
|
|
96
|
+
- `title` and `subtitle`, shown above each image. The title defaults to the workbook's name.
|
|
97
|
+
- `key`, which tells apart two maps with the same title. It defaults to the title and workbook name.
|
|
98
|
+
- `preview`, which limits named sheets to a number of `rows` and `columns`. The preview always
|
|
99
|
+
includes the first row of every region; regions that run further are cut off.
|
|
100
|
+
- `details`, extra lines added to each review request, such as a schema path or version.
|
|
101
|
+
- `scope`, text for a checkbox reviewers can tick to say a request applies more widely, for
|
|
102
|
+
example `Apply to every version of this schema`.
|
|
103
|
+
|
|
104
|
+
The page states each map's title once, and captions each image with its sheet, its number of regions
|
|
105
|
+
and any preview limit. The PNGs hold only the sheet, so they can be used on their own.
|
|
106
|
+
|
|
107
|
+
To put several workbooks on one page, list them under `maps:`, with an optional page `title`:
|
|
108
|
+
|
|
109
|
+
```yaml
|
|
110
|
+
title: Lab reports
|
|
111
|
+
maps:
|
|
112
|
+
- {workbook: january.xlsx, regions: [...]}
|
|
113
|
+
- {workbook: february.xlsx, regions: [...]}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
You can also pass several map files: `sheetmap a.yaml b.yaml -o reports.html`.
|
|
117
|
+
|
|
118
|
+
## Lay out the page
|
|
119
|
+
|
|
120
|
+
Every image has two dimensions: the **map** it belongs to and the **sheet** it shows. A `layout`
|
|
121
|
+
block in the map file says which dimension forms the sections of the page, which forms the rows and
|
|
122
|
+
which forms the columns. Each dimension can be used once.
|
|
123
|
+
|
|
124
|
+
```yaml
|
|
125
|
+
layout:
|
|
126
|
+
sections: sheet # auto (the default), none, map or sheet
|
|
127
|
+
rows: sheet # map or sheet
|
|
128
|
+
columns: map # map or sheet
|
|
129
|
+
wrap: 3 # flow into this many columns when rows and columns are not set
|
|
130
|
+
fit: true # scale grids to the window
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Some useful layouts:
|
|
134
|
+
|
|
135
|
+
| Layout | Result |
|
|
136
|
+
| --- | --- |
|
|
137
|
+
| *(none)* | A section per map, with its sheets side by side while they fit |
|
|
138
|
+
| `columns: map` | A section per sheet, with a column per map lined up down the page; good for comparing examples |
|
|
139
|
+
| `columns: sheet` | A section per map, with a column per sheet lined up down the page |
|
|
140
|
+
| `rows: sheet`, `columns: map` | One table: a row per sheet, a column per map, with headings on both |
|
|
141
|
+
| `sections: none`, `wrap: 3` | Every image in one grid, three to a row |
|
|
142
|
+
|
|
143
|
+
`sections: auto` uses whichever dimension the rows and columns leave free. When only one of `rows`
|
|
144
|
+
and `columns` is set and a dimension is left over, it fills the other axis. A position with no image,
|
|
145
|
+
such as a map without that sheet, shows a placeholder.
|
|
146
|
+
|
|
147
|
+
Images keep their full size by default, and a wide grid scrolls sideways. With `fit: true`, a grid
|
|
148
|
+
shares the window between its columns in proportion to their full widths, so every image is scaled by
|
|
149
|
+
the same amount and text stays the same size across the page. Images are never enlarged. Images that
|
|
150
|
+
flow, without rows, columns or `wrap`, always keep their full size.
|
|
151
|
+
|
|
152
|
+
To place images by hand, give `cells` instead: rows of `map/sheet` references, where map is a map's
|
|
153
|
+
`key` or `title`. Use `null` to leave a gap. Images you do not reference are left out.
|
|
154
|
+
|
|
155
|
+
```yaml
|
|
156
|
+
layout:
|
|
157
|
+
cells:
|
|
158
|
+
- [January/Report, February/Report]
|
|
159
|
+
- [January/Raw_Data, null]
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
`examples/lab/compare.yaml` compares January and February examples of the same report with
|
|
163
|
+
`columns: map`, and uses YAML anchors so both months share one list of regions:
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
uv run sheetmap examples/lab/compare.yaml
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
The command line overrides the file's layout: `--sections`, `--rows`, `--columns`, `--wrap N` and
|
|
170
|
+
`--fit`/`--no-fit`. Giving `--rows`, `--columns` or `--wrap` replaces the file's arrangement:
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
uv run sheetmap examples/lab/compare.yaml --rows sheet --columns map --fit
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## Review mappings
|
|
177
|
+
|
|
178
|
+
Review tools are off by default. Turn them on with `--review`, or `review: true` in the map file;
|
|
179
|
+
`--no-review` overrides the file.
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
uv run sheetmap examples/lab/map.yaml --review
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Each label then opens a dialogue for marking the range for removal or proposing a replacement,
|
|
186
|
+
with a note. **Review summary** collects the requests as text to copy. Requests are kept in the
|
|
187
|
+
browser's storage where it is available, and they change nothing in the workbooks or maps.
|
|
188
|
+
|
|
189
|
+
## Output
|
|
190
|
+
|
|
191
|
+
`sheetmap MAP` writes `MAP.html` beside the map, unless you give `-o` or `--output`. Beside it,
|
|
192
|
+
`MAP_assets/` holds a PNG per sheet and `manifest.json`, which lists each image with its regions,
|
|
193
|
+
their resolved areas and their axis labels.
|
|
194
|
+
|
|
195
|
+
- Only sheets with regions are drawn.
|
|
196
|
+
- Formula cells show the values Excel last saved; nothing is recalculated.
|
|
197
|
+
- Charts and images in the workbook are not drawn.
|
|
198
|
+
- Workbooks are opened for reading and never saved.
|
|
199
|
+
- An existing HTML file is replaced only if sheetmap wrote it. PNGs from earlier runs with other
|
|
200
|
+
names are left in place.
|
|
201
|
+
|
|
202
|
+
Without `--review` the page has no script. The page and PNGs contain the workbooks' contents, so share
|
|
203
|
+
them only with people who may see that data.
|
|
204
|
+
|
|
205
|
+
## Use from Python
|
|
206
|
+
|
|
207
|
+
```python
|
|
208
|
+
from sheetmap import Layout, Preview, Region, SheetMap, render
|
|
209
|
+
|
|
210
|
+
render(
|
|
211
|
+
[
|
|
212
|
+
SheetMap(
|
|
213
|
+
"january.xlsx",
|
|
214
|
+
[
|
|
215
|
+
Region("patient", "Report!B3"),
|
|
216
|
+
Region("results", "Report!A7:D", columns={"A": "sample_id", "C": "analyte", "D": "value"}),
|
|
217
|
+
],
|
|
218
|
+
title="Lab report",
|
|
219
|
+
preview={"Raw_Data": Preview(rows=40, columns=20)},
|
|
220
|
+
)
|
|
221
|
+
],
|
|
222
|
+
"maps.html",
|
|
223
|
+
layout=Layout(columns="map"),
|
|
224
|
+
review=False,
|
|
225
|
+
)
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
`sheetmap.check(maps)` checks maps against their workbooks without writing anything, and
|
|
229
|
+
`sheetmap.load_map_file(path)` reads a map file into a `MapFile` holding its maps and page settings. Problems raise `sheetmap.SheetmapError`.
|
|
230
|
+
|
|
231
|
+
## Development
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
make install # uv sync
|
|
235
|
+
make test
|
|
236
|
+
make lint
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
`scripts/build_example.py` rebuilds the example workbooks.
|
|
240
|
+
|
|
241
|
+
Text is drawn with DejaVu Sans or Arial when the system has one, and Pillow's built-in font
|
|
242
|
+
otherwise, so images can differ slightly between machines.
|
|
243
|
+
|
|
244
|
+
## Releasing
|
|
245
|
+
|
|
246
|
+
Versions come from git tags. To release from a clean `main`:
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
make release-check VERSION=0.1.0 # build locally at that version without tagging
|
|
250
|
+
make release VERSION=0.1.0 # tag v0.1.0 and push it
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Pushing the tag runs the publish workflow. It reruns CI, builds the sdist and wheel, uploads them to
|
|
254
|
+
PyPI through trusted publishing (the `pypi` environment), and creates a GitHub release with the
|
|
255
|
+
built files attached.
|
sheetmap-0.1.0/README.md
ADDED
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
# sheetmap
|
|
2
|
+
|
|
3
|
+
Draw labelled cell ranges over Excel worksheets. Each mapped sheet becomes a PNG showing its
|
|
4
|
+
contents, fills, borders and merged cells, with every region outlined and tagged with its label.
|
|
5
|
+
The PNGs are gathered into one standalone HTML page, side by side where they fit. With `--review`,
|
|
6
|
+
readers can also click a label to ask for a range to be removed or changed, then copy a summary of
|
|
7
|
+
their requests.
|
|
8
|
+
|
|
9
|
+
Use it to check that a parser, schema or extraction reads the cells you think it does, and to
|
|
10
|
+
let someone who knows the workbook review those choices without reading code.
|
|
11
|
+
|
|
12
|
+
## Run the example
|
|
13
|
+
|
|
14
|
+
From this folder:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
uv run sheetmap examples/lab/map.yaml
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Open `examples/lab/map.html`. The example workbook holds invented data.
|
|
21
|
+
|
|
22
|
+
To check a map against its workbook without writing anything, for example in CI:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
uv run sheetmap check examples/lab/map.yaml
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Write a map
|
|
29
|
+
|
|
30
|
+
A map file names a workbook and the regions to label. Paths resolve relative to the map file.
|
|
31
|
+
|
|
32
|
+
```yaml
|
|
33
|
+
title: Lab report
|
|
34
|
+
workbook: january.xlsx
|
|
35
|
+
subtitle: January example
|
|
36
|
+
preview:
|
|
37
|
+
Raw_Data: {rows: 12, columns: 6}
|
|
38
|
+
regions:
|
|
39
|
+
- {label: patient, ref: "Report!B3"}
|
|
40
|
+
- label: results
|
|
41
|
+
ref: "Report!A7:D"
|
|
42
|
+
columns: {A: sample_id, C: analyte, D: value}
|
|
43
|
+
- {label: flags, ref: "Report!F8:F", kind: list}
|
|
44
|
+
- {label: signals, ref: "Raw_Data!A1:D", kind: table}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Each region needs a `label`, unique within its map, and a `ref`:
|
|
48
|
+
|
|
49
|
+
| `ref` | Meaning |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| `B3` | One cell on the first worksheet |
|
|
52
|
+
| `Report!B3` | One cell on the `Report` sheet; quote names with spaces: `'Raw data'!B3` |
|
|
53
|
+
| `Report!A7:D20` | A rectangle |
|
|
54
|
+
| `Report!A7:D` | Open-ended: runs to the last row with a value in columns A to D |
|
|
55
|
+
|
|
56
|
+
A region can also take:
|
|
57
|
+
|
|
58
|
+
- `kind`: `cell`, `range`, `list` or `table`, which sets its colour. It defaults to `table` when
|
|
59
|
+
`columns` or `rows` are given, `cell` for one cell and `range` otherwise.
|
|
60
|
+
- `columns`: labels for table columns, keyed by letter. A column without a label continues the
|
|
61
|
+
label on its left when its cells are empty, so merged headers share one label. A column that has
|
|
62
|
+
values but no label is an error, because it usually means the mapping has missed something.
|
|
63
|
+
- `rows`: labels for a table that reads across, keyed by row number. Give `columns` or `rows`,
|
|
64
|
+
not both.
|
|
65
|
+
- `colour`: a hex colour such as `#be123c`, overriding the colour for its kind.
|
|
66
|
+
|
|
67
|
+
A label for one cell of a merged block highlights the whole block.
|
|
68
|
+
|
|
69
|
+
A map file can set `layout` and `review` for the page, as described below. A map can also take:
|
|
70
|
+
|
|
71
|
+
- `title` and `subtitle`, shown above each image. The title defaults to the workbook's name.
|
|
72
|
+
- `key`, which tells apart two maps with the same title. It defaults to the title and workbook name.
|
|
73
|
+
- `preview`, which limits named sheets to a number of `rows` and `columns`. The preview always
|
|
74
|
+
includes the first row of every region; regions that run further are cut off.
|
|
75
|
+
- `details`, extra lines added to each review request, such as a schema path or version.
|
|
76
|
+
- `scope`, text for a checkbox reviewers can tick to say a request applies more widely, for
|
|
77
|
+
example `Apply to every version of this schema`.
|
|
78
|
+
|
|
79
|
+
The page states each map's title once, and captions each image with its sheet, its number of regions
|
|
80
|
+
and any preview limit. The PNGs hold only the sheet, so they can be used on their own.
|
|
81
|
+
|
|
82
|
+
To put several workbooks on one page, list them under `maps:`, with an optional page `title`:
|
|
83
|
+
|
|
84
|
+
```yaml
|
|
85
|
+
title: Lab reports
|
|
86
|
+
maps:
|
|
87
|
+
- {workbook: january.xlsx, regions: [...]}
|
|
88
|
+
- {workbook: february.xlsx, regions: [...]}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
You can also pass several map files: `sheetmap a.yaml b.yaml -o reports.html`.
|
|
92
|
+
|
|
93
|
+
## Lay out the page
|
|
94
|
+
|
|
95
|
+
Every image has two dimensions: the **map** it belongs to and the **sheet** it shows. A `layout`
|
|
96
|
+
block in the map file says which dimension forms the sections of the page, which forms the rows and
|
|
97
|
+
which forms the columns. Each dimension can be used once.
|
|
98
|
+
|
|
99
|
+
```yaml
|
|
100
|
+
layout:
|
|
101
|
+
sections: sheet # auto (the default), none, map or sheet
|
|
102
|
+
rows: sheet # map or sheet
|
|
103
|
+
columns: map # map or sheet
|
|
104
|
+
wrap: 3 # flow into this many columns when rows and columns are not set
|
|
105
|
+
fit: true # scale grids to the window
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Some useful layouts:
|
|
109
|
+
|
|
110
|
+
| Layout | Result |
|
|
111
|
+
| --- | --- |
|
|
112
|
+
| *(none)* | A section per map, with its sheets side by side while they fit |
|
|
113
|
+
| `columns: map` | A section per sheet, with a column per map lined up down the page; good for comparing examples |
|
|
114
|
+
| `columns: sheet` | A section per map, with a column per sheet lined up down the page |
|
|
115
|
+
| `rows: sheet`, `columns: map` | One table: a row per sheet, a column per map, with headings on both |
|
|
116
|
+
| `sections: none`, `wrap: 3` | Every image in one grid, three to a row |
|
|
117
|
+
|
|
118
|
+
`sections: auto` uses whichever dimension the rows and columns leave free. When only one of `rows`
|
|
119
|
+
and `columns` is set and a dimension is left over, it fills the other axis. A position with no image,
|
|
120
|
+
such as a map without that sheet, shows a placeholder.
|
|
121
|
+
|
|
122
|
+
Images keep their full size by default, and a wide grid scrolls sideways. With `fit: true`, a grid
|
|
123
|
+
shares the window between its columns in proportion to their full widths, so every image is scaled by
|
|
124
|
+
the same amount and text stays the same size across the page. Images are never enlarged. Images that
|
|
125
|
+
flow, without rows, columns or `wrap`, always keep their full size.
|
|
126
|
+
|
|
127
|
+
To place images by hand, give `cells` instead: rows of `map/sheet` references, where map is a map's
|
|
128
|
+
`key` or `title`. Use `null` to leave a gap. Images you do not reference are left out.
|
|
129
|
+
|
|
130
|
+
```yaml
|
|
131
|
+
layout:
|
|
132
|
+
cells:
|
|
133
|
+
- [January/Report, February/Report]
|
|
134
|
+
- [January/Raw_Data, null]
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`examples/lab/compare.yaml` compares January and February examples of the same report with
|
|
138
|
+
`columns: map`, and uses YAML anchors so both months share one list of regions:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
uv run sheetmap examples/lab/compare.yaml
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
The command line overrides the file's layout: `--sections`, `--rows`, `--columns`, `--wrap N` and
|
|
145
|
+
`--fit`/`--no-fit`. Giving `--rows`, `--columns` or `--wrap` replaces the file's arrangement:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
uv run sheetmap examples/lab/compare.yaml --rows sheet --columns map --fit
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Review mappings
|
|
152
|
+
|
|
153
|
+
Review tools are off by default. Turn them on with `--review`, or `review: true` in the map file;
|
|
154
|
+
`--no-review` overrides the file.
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
uv run sheetmap examples/lab/map.yaml --review
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Each label then opens a dialogue for marking the range for removal or proposing a replacement,
|
|
161
|
+
with a note. **Review summary** collects the requests as text to copy. Requests are kept in the
|
|
162
|
+
browser's storage where it is available, and they change nothing in the workbooks or maps.
|
|
163
|
+
|
|
164
|
+
## Output
|
|
165
|
+
|
|
166
|
+
`sheetmap MAP` writes `MAP.html` beside the map, unless you give `-o` or `--output`. Beside it,
|
|
167
|
+
`MAP_assets/` holds a PNG per sheet and `manifest.json`, which lists each image with its regions,
|
|
168
|
+
their resolved areas and their axis labels.
|
|
169
|
+
|
|
170
|
+
- Only sheets with regions are drawn.
|
|
171
|
+
- Formula cells show the values Excel last saved; nothing is recalculated.
|
|
172
|
+
- Charts and images in the workbook are not drawn.
|
|
173
|
+
- Workbooks are opened for reading and never saved.
|
|
174
|
+
- An existing HTML file is replaced only if sheetmap wrote it. PNGs from earlier runs with other
|
|
175
|
+
names are left in place.
|
|
176
|
+
|
|
177
|
+
Without `--review` the page has no script. The page and PNGs contain the workbooks' contents, so share
|
|
178
|
+
them only with people who may see that data.
|
|
179
|
+
|
|
180
|
+
## Use from Python
|
|
181
|
+
|
|
182
|
+
```python
|
|
183
|
+
from sheetmap import Layout, Preview, Region, SheetMap, render
|
|
184
|
+
|
|
185
|
+
render(
|
|
186
|
+
[
|
|
187
|
+
SheetMap(
|
|
188
|
+
"january.xlsx",
|
|
189
|
+
[
|
|
190
|
+
Region("patient", "Report!B3"),
|
|
191
|
+
Region("results", "Report!A7:D", columns={"A": "sample_id", "C": "analyte", "D": "value"}),
|
|
192
|
+
],
|
|
193
|
+
title="Lab report",
|
|
194
|
+
preview={"Raw_Data": Preview(rows=40, columns=20)},
|
|
195
|
+
)
|
|
196
|
+
],
|
|
197
|
+
"maps.html",
|
|
198
|
+
layout=Layout(columns="map"),
|
|
199
|
+
review=False,
|
|
200
|
+
)
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
`sheetmap.check(maps)` checks maps against their workbooks without writing anything, and
|
|
204
|
+
`sheetmap.load_map_file(path)` reads a map file into a `MapFile` holding its maps and page settings. Problems raise `sheetmap.SheetmapError`.
|
|
205
|
+
|
|
206
|
+
## Development
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
make install # uv sync
|
|
210
|
+
make test
|
|
211
|
+
make lint
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
`scripts/build_example.py` rebuilds the example workbooks.
|
|
215
|
+
|
|
216
|
+
Text is drawn with DejaVu Sans or Arial when the system has one, and Pillow's built-in font
|
|
217
|
+
otherwise, so images can differ slightly between machines.
|
|
218
|
+
|
|
219
|
+
## Releasing
|
|
220
|
+
|
|
221
|
+
Versions come from git tags. To release from a clean `main`:
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
make release-check VERSION=0.1.0 # build locally at that version without tagging
|
|
225
|
+
make release VERSION=0.1.0 # tag v0.1.0 and push it
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Pushing the tag runs the publish workflow. It reruns CI, builds the sdist and wheel, uploads them to
|
|
229
|
+
PyPI through trusted publishing (the `pypi` environment), and creates a GitHub release with the
|
|
230
|
+
built files attached.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Compare two months of the same report. Each month gets a column, lined up all the way down the
|
|
2
|
+
# page; sections default to the dimension the columns leave free, so each sheet gets a section.
|
|
3
|
+
title: Lab reports by month
|
|
4
|
+
layout:
|
|
5
|
+
columns: map
|
|
6
|
+
maps:
|
|
7
|
+
- title: January
|
|
8
|
+
workbook: january.xlsx
|
|
9
|
+
preview: &preview
|
|
10
|
+
Raw_Data: {rows: 12, columns: 6}
|
|
11
|
+
regions: ®ions
|
|
12
|
+
- {label: patient, ref: "Report!B3"}
|
|
13
|
+
- {label: collected, ref: "Report!B4"}
|
|
14
|
+
- {label: reviewer, ref: "Report!B5"}
|
|
15
|
+
- label: results
|
|
16
|
+
ref: "Report!A7:D"
|
|
17
|
+
columns: {A: sample_id, C: analyte, D: value}
|
|
18
|
+
- {label: flags, ref: "Report!F8:F", kind: list}
|
|
19
|
+
- {label: signals, ref: "Raw_Data!A1:D", kind: table}
|
|
20
|
+
- title: February
|
|
21
|
+
workbook: february.xlsx
|
|
22
|
+
preview: *preview
|
|
23
|
+
regions: *regions
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
title: Lab report
|
|
2
|
+
workbook: january.xlsx
|
|
3
|
+
subtitle: January example
|
|
4
|
+
preview:
|
|
5
|
+
Raw_Data: {rows: 12, columns: 6}
|
|
6
|
+
regions:
|
|
7
|
+
- {label: patient, ref: "Report!B3"}
|
|
8
|
+
- {label: collected, ref: "Report!B4"}
|
|
9
|
+
- {label: reviewer, ref: "Report!B5"}
|
|
10
|
+
- label: results
|
|
11
|
+
ref: "Report!A7:D"
|
|
12
|
+
columns: {A: sample_id, C: analyte, D: value}
|
|
13
|
+
- {label: flags, ref: "Report!F8:F", kind: list}
|
|
14
|
+
- {label: signals, ref: "Raw_Data!A1:D", kind: table}
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling", "hatch-vcs"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "sheetmap"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Draw labelled cell ranges over Excel worksheets as PNGs and a standalone review page"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.12"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
authors = [{ name = "Phlo House" }]
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Development Status :: 3 - Alpha",
|
|
15
|
+
"Intended Audience :: Developers",
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Programming Language :: Python :: 3.12",
|
|
18
|
+
"Programming Language :: Python :: 3.13",
|
|
19
|
+
"Programming Language :: Python :: 3.14",
|
|
20
|
+
"Topic :: File Formats",
|
|
21
|
+
"Topic :: Office/Business :: Financial :: Spreadsheet",
|
|
22
|
+
"Typing :: Typed",
|
|
23
|
+
]
|
|
24
|
+
keywords = ["excel", "openpyxl", "spreadsheet", "visualisation", "review"]
|
|
25
|
+
dependencies = [
|
|
26
|
+
"openpyxl>=3.1,<4",
|
|
27
|
+
"Pillow>=10.1,<13",
|
|
28
|
+
"PyYAML>=6.0,<7",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
[dependency-groups]
|
|
32
|
+
dev = ["ruff>=0.16"]
|
|
33
|
+
|
|
34
|
+
[project.scripts]
|
|
35
|
+
sheetmap = "sheetmap.cli:main"
|
|
36
|
+
|
|
37
|
+
[project.urls]
|
|
38
|
+
Homepage = "https://github.com/phlohouse/sheetmap"
|
|
39
|
+
Repository = "https://github.com/phlohouse/sheetmap"
|
|
40
|
+
Issues = "https://github.com/phlohouse/sheetmap/issues"
|
|
41
|
+
|
|
42
|
+
[tool.hatch.build.targets.wheel]
|
|
43
|
+
packages = ["src/sheetmap"]
|
|
44
|
+
|
|
45
|
+
[tool.hatch.build.targets.sdist]
|
|
46
|
+
include = ["src", "tests", "examples/lab/*.yaml", "examples/lab/*.xlsx", "scripts", "README.md"]
|
|
47
|
+
|
|
48
|
+
[tool.hatch.version]
|
|
49
|
+
source = "vcs"
|
|
50
|
+
tag-pattern = "^v(?P<version>.+)$"
|
|
51
|
+
fallback-version = "0.0.0"
|
|
52
|
+
|
|
53
|
+
[tool.hatch.version.raw-options]
|
|
54
|
+
version_scheme = "no-guess-dev"
|
|
55
|
+
|
|
56
|
+
[tool.ruff]
|
|
57
|
+
line-length = 120
|
|
58
|
+
target-version = "py312"
|
|
59
|
+
|
|
60
|
+
[tool.ruff.lint]
|
|
61
|
+
select = ["E", "F", "W", "I", "B", "UP"]
|
|
62
|
+
|
|
63
|
+
[tool.ruff.lint.isort]
|
|
64
|
+
force-sort-within-sections = true
|
|
65
|
+
lines-after-imports = 2
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
"""Rebuild the invented lab report workbooks in examples/lab used by the README and CI."""
|
|
2
|
+
|
|
3
|
+
from datetime import date
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
|
|
6
|
+
import openpyxl
|
|
7
|
+
from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
EXAMPLES = Path(__file__).resolve().parent.parent / "examples" / "lab"
|
|
11
|
+
|
|
12
|
+
MONTHS = {
|
|
13
|
+
"january.xlsx": {
|
|
14
|
+
"collected": date(2026, 1, 14),
|
|
15
|
+
"reviewer": "A. Reviewer",
|
|
16
|
+
"results": [("S-001", "Glucose", 5.4), ("S-002", "Sodium", 139), ("S-003", "Potassium", 4.1)],
|
|
17
|
+
"flags": ["Haemolysed", "Repeat"],
|
|
18
|
+
"wells": 96,
|
|
19
|
+
},
|
|
20
|
+
"february.xlsx": {
|
|
21
|
+
"collected": date(2026, 2, 11),
|
|
22
|
+
"reviewer": "B. Checker",
|
|
23
|
+
"results": [
|
|
24
|
+
("S-101", "Glucose", 6.1),
|
|
25
|
+
("S-102", "Sodium", 141),
|
|
26
|
+
("S-103", "Potassium", 3.8),
|
|
27
|
+
("S-104", "Chloride", 102),
|
|
28
|
+
("S-105", "Urea", 5.2),
|
|
29
|
+
],
|
|
30
|
+
"flags": ["Lipaemic"],
|
|
31
|
+
"wells": 48,
|
|
32
|
+
},
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def build(path: Path, month: dict) -> None:
|
|
37
|
+
book = openpyxl.Workbook()
|
|
38
|
+
sheet = book.active
|
|
39
|
+
sheet.title = "Report"
|
|
40
|
+
heading = PatternFill("solid", fgColor="DBEAFE")
|
|
41
|
+
thin = Side(style="thin")
|
|
42
|
+
sheet["A1"] = "Lab report"
|
|
43
|
+
sheet["A1"].font = Font(bold=True, size=14)
|
|
44
|
+
sheet["A3"], sheet["A4"], sheet["A5"] = "Patient", "Collected", "Reviewer"
|
|
45
|
+
sheet.merge_cells("B3:D3")
|
|
46
|
+
sheet["B3"] = "Example Patient"
|
|
47
|
+
sheet["B4"] = month["collected"]
|
|
48
|
+
sheet["B5"] = month["reviewer"]
|
|
49
|
+
for col, title in zip("ABCD", ["Sample", "", "Analyte", "Result"], strict=True):
|
|
50
|
+
cell = sheet[f"{col}7"]
|
|
51
|
+
cell.value = title or None
|
|
52
|
+
cell.fill, cell.font, cell.border = heading, Font(bold=True), Border(bottom=thin)
|
|
53
|
+
sheet.merge_cells("A7:B7")
|
|
54
|
+
sheet["A7"].alignment = Alignment(horizontal="center")
|
|
55
|
+
for row, (sample, analyte, result) in enumerate(month["results"], start=8):
|
|
56
|
+
sheet.merge_cells(f"A{row}:B{row}")
|
|
57
|
+
sheet[f"A{row}"], sheet[f"C{row}"], sheet[f"D{row}"] = sample, analyte, result
|
|
58
|
+
sheet["F7"] = "Flags"
|
|
59
|
+
sheet["F7"].font = Font(bold=True)
|
|
60
|
+
for row, flag in enumerate(month["flags"], start=8):
|
|
61
|
+
sheet[f"F{row}"] = flag
|
|
62
|
+
sheet.column_dimensions["C"].width = 16
|
|
63
|
+
sheet.column_dimensions["F"].width = 14
|
|
64
|
+
|
|
65
|
+
raw = book.create_sheet("Raw_Data")
|
|
66
|
+
for col, title in enumerate(["Well", "Channel", "Signal", "Background"], start=1):
|
|
67
|
+
raw.cell(1, col, title).font = Font(bold=True)
|
|
68
|
+
for row in range(2, month["wells"] + 2):
|
|
69
|
+
raw.cell(row, 1, f"{'ABCDEFGH'[(row - 2) // 12]}{(row - 2) % 12 + 1}")
|
|
70
|
+
raw.cell(row, 2, "FAM")
|
|
71
|
+
raw.cell(row, 3, round(1000 + row * 13.7, 1))
|
|
72
|
+
raw.cell(row, 4, round(80 + row * 0.4, 1))
|
|
73
|
+
book.save(path)
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def main() -> None:
|
|
77
|
+
EXAMPLES.mkdir(parents=True, exist_ok=True)
|
|
78
|
+
for name, month in MONTHS.items():
|
|
79
|
+
build(EXAMPLES / name, month)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
if __name__ == "__main__":
|
|
83
|
+
main()
|