sdb-reader 0.9.0__py3-none-any.whl

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,546 @@
1
+ """What one safety data sheet says about itself as a document.
2
+
3
+ Not about our reading of it: whether a sheet can meet the Annex II in force,
4
+ whether it states a classification at all, and what it prints outside its
5
+ label are the supplier's to put right, and no parser work changes them. They
6
+ are judged from what the parser read; reporting them is the caller's.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import re
12
+ from collections.abc import Collection, Iterable, Mapping, Sequence
13
+ from dataclasses import asdict
14
+ from datetime import date
15
+ from enum import StrEnum
16
+
17
+ from .messages import Message
18
+ from .parser import (
19
+ CLASSIFIED_BEFORE_CLP,
20
+ EUH_WORDING_OUTSIDE_LABEL,
21
+ LABEL_UNDETERMINED,
22
+ SheetPart,
23
+ )
24
+ from .schema import HazardStatements, SafetyDataSheet, Section, StatedClassification
25
+ from .statements import SHEET_ON_REQUEST, deviates_from_regulation, label_statements
26
+
27
+ # Annex II of REACH in the version of Regulation (EU) 2020/878 applies from
28
+ # 1 January 2021; sheets not conforming to it could be supplied until
29
+ # 31 December 2022. A sheet last revised before this date therefore cannot
30
+ # comply -- not as a matter of judgement but of structure, because it lacks
31
+ # fields the 2020 amendment introduced: the UFI, nanoform particle
32
+ # characteristics, endocrine-disrupting properties in 2.3, 11.2 and 12.6, and
33
+ # ATE and M-factors in section 3.
34
+ ANNEX_II_2020_878 = date(2021, 1, 1)
35
+
36
+
37
+ # Mixtures are classified and labelled under CLP from 1 June 2015 (Regulation
38
+ # (EC) No 1272/2008, Art. 61). A sheet last revised before that cannot be the
39
+ # valid sheet of a product that needs one.
40
+ CLP_FOR_MIXTURES = date(2015, 6, 1)
41
+
42
+
43
+ def predates_clp(revised: date) -> bool:
44
+ """Whether a sheet last revised on *revised* predates CLP for mixtures.
45
+
46
+ >>> from datetime import date
47
+ >>> predates_clp(date(2015, 5, 31)), predates_clp(date(2015, 6, 1))
48
+ (True, False)
49
+ """
50
+ return revised < CLP_FOR_MIXTURES
51
+
52
+
53
+ def predates_annex_ii(revised: date) -> bool:
54
+ """Whether a sheet last revised on *revised* cannot meet Annex II as amended
55
+ by Regulation (EU) 2020/878.
56
+
57
+ >>> from datetime import date
58
+ >>> predates_annex_ii(date(2020, 12, 31)), predates_annex_ii(date(2021, 1, 1))
59
+ (True, False)
60
+ """
61
+ return revised < ANNEX_II_2020_878
62
+
63
+
64
+ # What a sheet in the 2020 version of Annex II prints and an older one cannot:
65
+ # the endocrine-disrupting properties (2.3, 11.2.1, 12.6) and the subsections
66
+ # the amendment added, 11.2 and 12.7. A date alone does not show the format:
67
+ # sheets in the older one could be issued until 31 December 2022, and some
68
+ # carry a later date all the same. Measured over 12,600 sheets, 97 % of
69
+ # those revised in 2023 or later print all three; one is enough here, because
70
+ # what is missing may also be what the reader did not get.
71
+ _ENDOCRINE = re.compile(r"endokrin", re.IGNORECASE)
72
+ _SUBSECTION_11_2 = re.compile(
73
+ r"(?m)^[^\S\n]*[-·•*]?[^\S\n]*11\s?\.\s?2\b(?!\s?\.?\s?\d)"
74
+ )
75
+ _SUBSECTION_12_7 = re.compile(r"(?m)^[^\S\n]*[-·•*]?[^\S\n]*12\s?\.\s?7\b")
76
+
77
+
78
+ def lacks_annex_ii_2020(section_text: Mapping[Section, str]) -> bool:
79
+ """Whether a sheet prints none of what the 2020 version of Annex II added.
80
+
81
+ Judged only where sections 11 and 12 were read: without them their
82
+ subsections cannot be missed.
83
+
84
+ >>> lacks_annex_ii_2020(
85
+ ... {Section.TOXICOLOGY: "11.1 Angaben", Section.ECOLOGY: "12.1 Toxizität"}
86
+ ... )
87
+ True
88
+ >>> lacks_annex_ii_2020(
89
+ ... {
90
+ ... Section.TOXICOLOGY: "11.2 Angaben über sonstige Gefahren",
91
+ ... Section.ECOLOGY: "12.7 Andere schädliche Wirkungen",
92
+ ... }
93
+ ... )
94
+ False
95
+ """
96
+ toxicology = section_text.get(Section.TOXICOLOGY) or ""
97
+ ecology = section_text.get(Section.ECOLOGY) or ""
98
+ if not toxicology.strip() or not ecology.strip():
99
+ return False
100
+ if _SUBSECTION_11_2.search(toxicology) or _SUBSECTION_12_7.search(ecology):
101
+ return False
102
+ return not any(_ENDOCRINE.search(text or "") for text in section_text.values())
103
+
104
+
105
+ def requires_sheet(sheet: SafetyDataSheet) -> bool:
106
+ """Whether a sheet is issued for a product that needs one.
107
+
108
+ SDB-76, SDB-142, SDB-154.
109
+
110
+ REACH Article 31(1) requires a safety data sheet for a classified product
111
+ and Article 31(3) one on request where the label carries EUH210. So a
112
+ sheet is required where section 2 classifies the product
113
+ (``stated_classification``, as SDB-75 reads it), or where the label carries what only a classified
114
+ product's label does -- an H statement, a signal word, a pictogram -- or
115
+ an EUH statement, or the sentence that a safety data sheet is to be had
116
+ on request, under whichever law the label stands. P statements alone are
117
+ advice a supplier may print on anything. A sheet without any of it is
118
+ issued voluntarily.
119
+
120
+ A sheet that says of itself that it is issued voluntarily or that none is
121
+ prescribed for its product (``stated_voluntary``, as SDB-142 reads it) is
122
+ taken at its word where the duty allows it. For an article
123
+ (``stated_article``: the sheet
124
+ calls the product one, beside that sentence or by saying that as an
125
+ article it is not subject to labelling, SDB-154) Article 31 knows no
126
+ duty, whatever the label prints and whether or not the sheet calls
127
+ itself voluntary. For a mixture it is so while the mixture is
128
+ not classified: not where section 2 classifies it or the label carries an
129
+ H statement, since Article 31(4) spares the supplier the sheet of a
130
+ hazardous mixture only towards the general public and leaves it due to a
131
+ downstream user or distributor who asks. In either case a label that
132
+ carries EUH210 or the sentence that a sheet is to be had on request goes
133
+ first: there the supplier says at the label that one is due.
134
+
135
+ A sheet kept as a record is read back with ``sheet_from_dict``.
136
+
137
+ >>> from sdb_reader import HazardStatements
138
+ >>> def sheet(label=None, **stated):
139
+ ... return SafetyDataSheet(
140
+ ... None, None, None, None, "de",
141
+ ... hazard_statements=label or HazardStatements(), **stated
142
+ ... )
143
+ >>> requires_sheet(sheet(HazardStatements(hazard_codes=["H315"])))
144
+ True
145
+ >>> requires_sheet(sheet(HazardStatements(supplemental_codes=["EUH210"])))
146
+ True
147
+ >>> requires_sheet(sheet(HazardStatements(precautionary_codes=["P102"])))
148
+ False
149
+ >>> requires_sheet(
150
+ ... sheet(
151
+ ... HazardStatements(
152
+ ... supplemental_text="Sicherheitsdatenblatt auf Anfrage für "
153
+ ... "berufsmäßige Verwender erhältlich."
154
+ ... )
155
+ ... )
156
+ ... )
157
+ True
158
+ >>> requires_sheet(sheet(stated_classification=StatedClassification.CLASSIFIED))
159
+ True
160
+ >>> requires_sheet(
161
+ ... sheet(
162
+ ... HazardStatements(hazard_codes=["H314"]),
163
+ ... stated_voluntary=True,
164
+ ... stated_article=True,
165
+ ... )
166
+ ... )
167
+ False
168
+ >>> requires_sheet(
169
+ ... sheet(
170
+ ... stated_classification=StatedClassification.CLASSIFIED,
171
+ ... stated_article=True,
172
+ ... )
173
+ ... )
174
+ False
175
+ >>> requires_sheet(
176
+ ... sheet(HazardStatements(supplemental_codes=["EUH210"]), stated_article=True)
177
+ ... )
178
+ True
179
+ >>> requires_sheet(
180
+ ... sheet(HazardStatements(hazard_codes=["H314"]), stated_voluntary=True)
181
+ ... )
182
+ True
183
+ >>> requires_sheet(
184
+ ... sheet(HazardStatements(supplemental_codes=["EUH208"]), stated_voluntary=True)
185
+ ... )
186
+ False
187
+ >>> requires_sheet(
188
+ ... sheet(HazardStatements(supplemental_codes=["EUH210"]), stated_voluntary=True)
189
+ ... )
190
+ True
191
+ """
192
+ return _label_requires_sheet(
193
+ sheet.hazard_statements,
194
+ sheet.stated_classification,
195
+ voluntary=sheet.stated_voluntary,
196
+ article=sheet.stated_article,
197
+ )
198
+
199
+
200
+ def _label_requires_sheet(
201
+ hazards: HazardStatements,
202
+ stated: StatedClassification = StatedClassification.NOT_STATED,
203
+ *,
204
+ voluntary: bool = False,
205
+ article: bool = False,
206
+ ) -> bool:
207
+ """``requires_sheet`` for a label and what the sheet states beside it."""
208
+ # In the words of the directive before CLP the sentence stands under no
209
+ # code (SDB-123): it is what asks for the sheet.
210
+ on_request = (
211
+ hazards.supplemental_text is not None
212
+ and SHEET_ON_REQUEST.search(hazards.supplemental_text) is not None
213
+ )
214
+ classified = stated in (
215
+ StatedClassification.CLASSIFIED,
216
+ StatedClassification.OLD_SYSTEM,
217
+ )
218
+ hazardous = classified or bool(hazards.hazard_codes)
219
+ if article or (voluntary and not hazardous):
220
+ return on_request or "EUH210" in hazards.supplemental_codes
221
+ if classified:
222
+ return True
223
+ if (
224
+ hazards.hazard_codes
225
+ or hazards.supplemental_codes
226
+ or hazards.signal_word
227
+ or hazards.pictograms
228
+ ):
229
+ return True
230
+ return on_request
231
+
232
+
233
+ def contradicts_label(sheet: SafetyDataSheet) -> bool:
234
+ """Whether section 2 says "not classified" while the label carries what only
235
+ a classified product's label does (SDB-79): an H statement, a signal word or
236
+ a pictogram. An EUH statement is no contradiction; an unclassified mixture
237
+ may have to carry one.
238
+
239
+ >>> from sdb_reader import HazardStatements
240
+ >>> def sheet(label):
241
+ ... return SafetyDataSheet(
242
+ ... None, None, None, None, "de", hazard_statements=label,
243
+ ... stated_classification=StatedClassification.NOT_CLASSIFIED,
244
+ ... )
245
+ >>> contradicts_label(sheet(HazardStatements(signal_word="Achtung")))
246
+ True
247
+ >>> contradicts_label(sheet(HazardStatements(supplemental_codes=["EUH210"])))
248
+ False
249
+ """
250
+ label = sheet.hazard_statements
251
+ return sheet.stated_classification is StatedClassification.NOT_CLASSIFIED and bool(
252
+ label.hazard_codes or label.signal_word or label.pictograms
253
+ )
254
+
255
+
256
+ class Classification(StrEnum):
257
+ """What a sheet's label states about the product's classification."""
258
+
259
+ # The label says the classification was not determined: neither classified
260
+ # nor established as not classified, a sheet without an answer.
261
+ UNDETERMINED = "undetermined"
262
+ # The label carries an H-code or a signal word.
263
+ CLASSIFIED = "classified"
264
+ # Section 2 classifies by the rules before CLP, with R phrases and hazard
265
+ # symbols (SDB-73): the product is classified, and the sheet has no label
266
+ # the regulation in force knows.
267
+ OLD_SYSTEM = "classified-old-system"
268
+ NOT_CLASSIFIED = "not-classified"
269
+
270
+
271
+ def classification(
272
+ hazard_codes: Collection[str],
273
+ signal_word: str | None,
274
+ parser_warnings: Iterable[Message],
275
+ ) -> Classification:
276
+ """What the label states, from the parser's codes, signal word and warnings.
277
+
278
+ A label that says nobody determined the classification counts as that even
279
+ where the parser found codes elsewhere in section 2.
280
+
281
+ >>> classification(["H315"], "Achtung", []).value
282
+ 'classified'
283
+ >>> classification([], None, []).value
284
+ 'not-classified'
285
+ """
286
+ noted = {warning.code for warning in parser_warnings}
287
+ if LABEL_UNDETERMINED in noted:
288
+ return Classification.UNDETERMINED
289
+ if CLASSIFIED_BEFORE_CLP in noted:
290
+ return Classification.OLD_SYSTEM
291
+ if hazard_codes:
292
+ return Classification.CLASSIFIED
293
+ if signal_word is not None and signal_word.strip().lower() in {
294
+ "gefahr",
295
+ "achtung",
296
+ }:
297
+ return Classification.CLASSIFIED
298
+ return Classification.NOT_CLASSIFIED
299
+
300
+
301
+ def euh_outside_label(parser_warnings: Iterable[Message]) -> list[Message]:
302
+ """The EUH statements the sheet prints only outside its label (SDB-28).
303
+
304
+ The parser's messages about them, each with the statement's code and the
305
+ sentence as printed.
306
+ """
307
+ return [
308
+ warning
309
+ for warning in parser_warnings
310
+ if warning.code == EUH_WORDING_OUTSIDE_LABEL
311
+ ]
312
+
313
+
314
+ # How a sheet names the part of a product it is for: "Komponente A", "Komp.
315
+ # B", "Comp. A", "Part C", "Teil B", "PTA", "erste Komponente".
316
+ _COMPONENT = re.compile(
317
+ r"\b(?:(?:komponente|komp\.?|component|comp\.?|part|teil)\s*([a-d])[a-z]?"
318
+ r"|pt([a-d])|(?:erste|zweite|dritte)\s+komponente)\b",
319
+ re.IGNORECASE,
320
+ )
321
+ # What a part of a product is called beside its letter, or instead of it.
322
+ _COMPONENT_ROLE = re.compile(
323
+ r"\b(?:harz|härter|haerter|mörtel|moertel|basis)\b", re.IGNORECASE
324
+ )
325
+ # An addition in brackets or a number at the end of a name: "(Finish)", "-019".
326
+ _NAME_TAIL = re.compile(r"(?:\([^()]*\)|[\s,;:–-]+\d{2,4})\s*$")
327
+ _NOT_A_NAME_S = re.compile(r"[^\w]+")
328
+
329
+
330
+ def _folded_name(name: str) -> str:
331
+ return _NOT_A_NAME_S.sub(" ", name.casefold()).strip()
332
+
333
+
334
+ def _product(name: str) -> str:
335
+ """*name* without what tells one part of a product from another (SDB-139)."""
336
+ name = _COMPONENT.sub(" ", name)
337
+ name = _COMPONENT_ROLE.sub(" ", name)
338
+ stripped = _NAME_TAIL.sub("", name.strip())
339
+ while stripped != name.strip():
340
+ name, stripped = stripped, _NAME_TAIL.sub("", stripped.strip())
341
+ return _folded_name(stripped)
342
+
343
+
344
+ def same_product(names: Sequence[str]) -> bool:
345
+ """Whether sheets named *names* are for one product (SDB-139).
346
+
347
+ They are where the names are the same once a component's designation, a
348
+ component's role, an addition in brackets at the end and a number at the
349
+ end are left out; and where every name carries a component's letter and
350
+ the letters are not all the same ("… PTA" beside "… PART B").
351
+
352
+ >>> same_product(["Musterkleber Komponente A", "Musterkleber Komponente B"])
353
+ True
354
+ >>> same_product(["Musterfarbe (Harz)", "Musterfarbe (Härter)"])
355
+ True
356
+ >>> same_product(["Musterfarbe", "Musterlack"])
357
+ False
358
+ """
359
+ if len({_product(name) for name in names}) <= 1:
360
+ return True
361
+ letters = [
362
+ {(match.group(1) or match.group(2) or "").casefold() for match in found} - {""}
363
+ for found in (list(_COMPONENT.finditer(name)) for name in names)
364
+ ]
365
+ return all(letters) and len(set().union(*letters)) > 1
366
+
367
+
368
+ # What sheets of one product for different countries are compared in.
369
+ _EDITION_FIELDS = (
370
+ "hazard_codes",
371
+ "precautionary_codes",
372
+ "supplemental_codes",
373
+ "signal_word",
374
+ "pictograms",
375
+ )
376
+
377
+
378
+ def several_sheets_findings(parts: Sequence[SheetPart]) -> list[Message]:
379
+ """What the sheets of one file say about each other (SDB-139, SDB-140).
380
+
381
+ *parts* are the sheets of a file that holds several, each read on its
382
+ own (``ParsedSheet.parts``). That they are for different products
383
+ is said where every sheet's product name is read and the names are not
384
+ one product's (``same_product``); where a name is not read, nothing is
385
+ said, because it cannot be told. Sheets with the same name that are for
386
+ different countries are compared, and the fields they differ in are
387
+ named.
388
+ """
389
+ findings: list[Message] = []
390
+ names = [part.sheet.product_identifier or "" for part in parts]
391
+ if len(parts) > 1 and all(names) and not same_product(names):
392
+ findings.append(
393
+ Message("different-products", {"products": list(dict.fromkeys(names))})
394
+ )
395
+ differing: list[str] = []
396
+ for index, one in enumerate(parts):
397
+ for other in parts[index + 1 :]:
398
+ if not _are_editions(one.sheet, other.sheet):
399
+ continue
400
+ differing.extend(
401
+ name
402
+ for name in _edition_differences(one.sheet, other.sheet)
403
+ if name not in differing
404
+ )
405
+ if differing:
406
+ findings.append(Message("country-editions-differ", {"fields": differing}))
407
+ return findings
408
+
409
+
410
+ def _are_editions(one: SafetyDataSheet, other: SafetyDataSheet) -> bool:
411
+ """Whether two sheets are the same product's for different countries."""
412
+ return bool(
413
+ one.product_identifier
414
+ and other.product_identifier
415
+ and _folded_name(one.product_identifier)
416
+ == _folded_name(other.product_identifier)
417
+ and one.countries
418
+ and other.countries
419
+ and set(one.countries) != set(other.countries)
420
+ )
421
+
422
+
423
+ def _edition_differences(one: SafetyDataSheet, other: SafetyDataSheet) -> list[str]:
424
+ a, b = asdict(one.hazard_statements), asdict(other.hazard_statements)
425
+ names = [
426
+ name
427
+ for name in _EDITION_FIELDS
428
+ if (set(a[name] or ()) if isinstance(a[name], list) else a[name])
429
+ != (set(b[name] or ()) if isinstance(b[name], list) else b[name])
430
+ ]
431
+ if one.stated_classification is not other.stated_classification:
432
+ names.append("stated_classification")
433
+ return names
434
+
435
+
436
+ def sheet_findings(
437
+ sheet: SafetyDataSheet,
438
+ parser_warnings: Sequence[Message],
439
+ *,
440
+ today: date | None = None,
441
+ parts: Sequence[SheetPart] = (),
442
+ ) -> list[Message]:
443
+ """What is wrong with *sheet* as a document (SDW-6, SDW-7, SDW-9).
444
+
445
+ *parts* are the sheets of a file that holds several
446
+ (``ParsedSheet.parts``); with them, what they say about each other
447
+ is among the findings (``several_sheets_findings``).
448
+
449
+ *today* is the day the caller takes as the present; the library has no
450
+ clock of its own. With it, a revision date (or, where the sheet names
451
+ none, an issue date) after that day is reported and does not count for
452
+ the sheet's age: the sheet is judged by its issue date where that is no
453
+ later than *today*, else like a sheet without a date (SDB-137). Without
454
+ *today* no date is questioned.
455
+
456
+ *parser_warnings* are the warnings of the parser's result for the sheet.
457
+ Each finding is a message; where it concerns one statement, its values
458
+ name it as ``statement``.
459
+
460
+ >>> from sdb_reader import extraction_from_dict, read_extraction
461
+ >>> text = (
462
+ ... "Sicherheitsdatenblatt\\n"
463
+ ... "ABSCHNITT 1: Bezeichnung des Stoffs bzw. des Gemischs\\n"
464
+ ... "Produktname: Musterfarbe\\n"
465
+ ... "ABSCHNITT 2: Mögliche Gefahren\\n"
466
+ ... "Verordnung (EG) Nr. 1907/2006\\n"
467
+ ... "Signalwort: Achtung\\n"
468
+ ... "H315: Verursacht Hautreizungen.\\n"
469
+ ... )
470
+ >>> result = read_extraction(
471
+ ... extraction_from_dict(
472
+ ... {"text": text, "extractor": "pymupdf", "pages_sampled": 1, "warnings": []}
473
+ ... )
474
+ ... ).parser_result
475
+ >>> [finding.code for finding in sheet_findings(result.sheet, result.warnings)]
476
+ ['undated']
477
+ """
478
+ findings: list[Message] = []
479
+ for statement in label_statements(sheet.hazard_statements):
480
+ if (
481
+ statement.sheet is not None
482
+ and statement.regulation is not None
483
+ and deviates_from_regulation(statement.code, statement.sheet)
484
+ ):
485
+ findings.append(
486
+ Message(
487
+ "wording-deviates",
488
+ {
489
+ "statement": statement.code,
490
+ "sheet": statement.sheet,
491
+ "regulation": statement.regulation,
492
+ },
493
+ )
494
+ )
495
+
496
+ stated = sheet.revision_date or sheet.issue_date
497
+ revised = next(
498
+ (
499
+ day
500
+ for day in (sheet.revision_date, sheet.issue_date)
501
+ if day is not None and (today is None or day <= today)
502
+ ),
503
+ None,
504
+ )
505
+ if today is not None and stated is not None and stated > today:
506
+ findings.append(
507
+ Message(
508
+ "revised-in-future",
509
+ {"revised": stated.isoformat(), "today": today.isoformat()},
510
+ )
511
+ )
512
+ if revised is None:
513
+ findings.append(Message("undated"))
514
+ elif predates_annex_ii(revised):
515
+ findings.append(Message("predates-annex-ii", {"revised": revised.isoformat()}))
516
+
517
+ hazards = sheet.hazard_statements
518
+ state = classification(hazards.hazard_codes, hazards.signal_word, parser_warnings)
519
+ if state is Classification.UNDETERMINED:
520
+ findings.append(Message("classification-undetermined"))
521
+ if state is Classification.OLD_SYSTEM:
522
+ findings.append(Message("old-classification"))
523
+ if (
524
+ revised is not None
525
+ and not predates_annex_ii(revised)
526
+ and requires_sheet(sheet)
527
+ and lacks_annex_ii_2020(sheet.section_text)
528
+ ):
529
+ findings.append(Message("old-format", {"revised": revised.isoformat()}))
530
+
531
+ if (
532
+ state is Classification.NOT_CLASSIFIED
533
+ and sheet.stated_classification is StatedClassification.NOT_STATED
534
+ and not _label_requires_sheet(hazards)
535
+ ):
536
+ findings.append(Message("classification-not-stated"))
537
+
538
+ if contradicts_label(sheet):
539
+ findings.append(Message("classification-contradicts-label"))
540
+
541
+ findings.extend(
542
+ Message("euh-outside-label", dict(outside.params))
543
+ for outside in euh_outside_label(parser_warnings)
544
+ )
545
+ findings.extend(several_sheets_findings(parts))
546
+ return findings
sdb_reader/current.py ADDED
@@ -0,0 +1,134 @@
1
+ """Which of several sheets of one product is the current one (BIB-6 to BIB-9).
2
+
3
+ Pure data in, a position out: nothing here reads a file or knows where the
4
+ dates and versions came from. Which sheets belong together is the caller's
5
+ knowledge.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from collections.abc import Sequence
11
+ from dataclasses import dataclass, replace
12
+ from datetime import date
13
+ from enum import Enum
14
+
15
+
16
+ @dataclass(frozen=True, slots=True)
17
+ class SheetState:
18
+ """What a sheet says about its own state: all the choice looks at."""
19
+
20
+ revision_date: date | None = None
21
+ issue_date: date | None = None
22
+ # As printed, such as "2.01"; read as numbers between dots.
23
+ version: str | None = None
24
+ # The countries the sheet is issued for; empty where it names none.
25
+ countries: Sequence[str] = ()
26
+
27
+
28
+ class ChoiceReason(Enum):
29
+ """Why a state is the current one."""
30
+
31
+ # First in the order of BIB-7, and not issued for other countries only.
32
+ NEWEST = "newest"
33
+ # A sheet for the wanted country, in place of a newer one for another
34
+ # country that is not ahead of it in version (BIB-8).
35
+ STANDS_IN = "stands-in"
36
+ # Issued for other countries only, and no sheet for the wanted country
37
+ # can take its place: that country's sheet of this state is missing.
38
+ OTHER_COUNTRY = "other-country"
39
+
40
+
41
+ @dataclass(frozen=True, slots=True)
42
+ class Choice:
43
+ """The current state among those given to ``current_state``."""
44
+
45
+ # Position in the sequence given.
46
+ index: int
47
+ reason: ChoiceReason
48
+ # With STANDS_IN: the position of the newer sheet for another country.
49
+ instead_of: int | None = None
50
+
51
+
52
+ def current_state(
53
+ states: Sequence[SheetState],
54
+ *,
55
+ country: str | None = "DE",
56
+ today: date | None = None,
57
+ ) -> Choice:
58
+ """Choose the current one of *states*, the sheets of one product.
59
+
60
+ The newest revision date leads; among sheets of one date the one for
61
+ *country* comes first, then the higher version, then the newer issue date,
62
+ then the later one given (BIB-7). Where the sheet so chosen is issued for
63
+ other countries only, the first sheet for *country* takes its place if
64
+ both carry a readable version and its own is not lower (BIB-8). With
65
+ *country* None, countries play no part (BIB-9).
66
+
67
+ *today* is the day the caller takes as the present. With it, a revision
68
+ or issue date after that day counts as missing (BIB-19): a sheet that
69
+ prints an impossible date is not the newest because of it, and ranks as
70
+ a sheet without that date does. Without *today* every date counts as
71
+ printed.
72
+
73
+ Raises ValueError when *states* is empty.
74
+
75
+ >>> from datetime import date
76
+ >>> choice = current_state(
77
+ ... [
78
+ ... SheetState(date(2022, 7, 20), version="2", countries=("DE",)),
79
+ ... SheetState(date(2023, 7, 10), version="2", countries=("CH",)),
80
+ ... ]
81
+ ... )
82
+ >>> choice.index, choice.reason.value, choice.instead_of
83
+ (0, 'stands-in', 1)
84
+ """
85
+ if not states:
86
+ raise ValueError("no states to choose from")
87
+ if today is not None:
88
+ states = [
89
+ replace(
90
+ state,
91
+ revision_date=_not_after(state.revision_date, today),
92
+ issue_date=_not_after(state.issue_date, today),
93
+ )
94
+ for state in states
95
+ ]
96
+
97
+ def rank(index: int) -> tuple[date, bool, tuple[int, ...], date, int]:
98
+ state = states[index]
99
+ return (
100
+ state.revision_date or date.min,
101
+ country is not None and country in state.countries,
102
+ _version(state),
103
+ state.issue_date or date.min,
104
+ index,
105
+ )
106
+
107
+ chosen = max(range(len(states)), key=rank)
108
+ if country is None or not states[chosen].countries:
109
+ return Choice(chosen, ChoiceReason.NEWEST)
110
+ if country in states[chosen].countries:
111
+ return Choice(chosen, ChoiceReason.NEWEST)
112
+
113
+ wanted = [i for i in range(len(states)) if country in states[i].countries]
114
+ if wanted:
115
+ candidate = max(wanted, key=rank)
116
+ ahead, own = _version(states[chosen]), _version(states[candidate])
117
+ if ahead and own and own >= ahead:
118
+ return Choice(candidate, ChoiceReason.STANDS_IN, instead_of=chosen)
119
+ return Choice(chosen, ChoiceReason.OTHER_COUNTRY)
120
+
121
+
122
+ def _not_after(day: date | None, today: date) -> date | None:
123
+ """*day*, or None where it lies after *today*."""
124
+ return day if day is None or day <= today else None
125
+
126
+
127
+ def _version(state: SheetState) -> tuple[int, ...]:
128
+ """The version as numbers; empty where there is none that can be read."""
129
+ if not state.version:
130
+ return ()
131
+ try:
132
+ return tuple(int(part) for part in state.version.strip().split("."))
133
+ except ValueError:
134
+ return ()