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.
@@ -0,0 +1,9 @@
1
+ __pycache__/
2
+ .venv/
3
+ *.egg-info/
4
+ build/
5
+ dist/
6
+ examples/**/*.html
7
+ examples/**/*_assets/
8
+ .env
9
+ .env.*
@@ -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.
@@ -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: &regions
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
@@ -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()