gleplot 6.0.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,74 @@
1
+ """Structured import report: typed notes behind :class:`RecognizedFigure`.
2
+
3
+ ``parse_gle_figure`` used to hand back only a flat list of prefix-tagged
4
+ strings (``"structure: ..."``, ``"data: ..."``, ...). GLEstudio's import
5
+ report (SPEC 8.1.5 / 10.4) needs to group, filter and locate those recovery
6
+ notes -- categorize by kind, and where possible point at the original source
7
+ lines that produced them -- which a bare string cannot support. This module
8
+ defines the typed record; :mod:`gleplot.parser.recognizer` is the only
9
+ producer (see its module docstring, "Warnings taxonomy").
10
+
11
+ :class:`RecognizedFigure.warnings` (the string form every existing consumer
12
+ was written against) is now a *derived* view: :attr:`ImportNote.rendered`
13
+ reproduces exactly the ``"category: message"`` string the un-typed API used
14
+ to build directly, so ``warnings`` stays byte-identical for the whole
15
+ existing test corpus with the notes as the single source of truth.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ from dataclasses import dataclass
21
+ from enum import Enum
22
+ from typing import Optional, Tuple
23
+
24
+ __all__ = ["ImportCategory", "ImportNote"]
25
+
26
+
27
+ class ImportCategory(str, Enum):
28
+ """The recovery-note categories the recognizer emits.
29
+
30
+ Each member's value is the prefix of :attr:`ImportNote.rendered`
31
+ (``ImportCategory.DATA.value == "data"``). What each category means is in
32
+ the "Opening GLE Files" guide.
33
+ """
34
+
35
+ METADATA = "metadata"
36
+ STRUCTURE = "structure"
37
+ DATA = "data"
38
+ LEGEND = "legend"
39
+ LAYOUT = "layout"
40
+ SMOOTH = "smooth"
41
+ PROGRAMMATIC = "programmatic"
42
+
43
+
44
+ @dataclass(frozen=True)
45
+ class ImportNote:
46
+ """One recovered ambiguity or loss from a ``.gle`` import.
47
+
48
+ Attributes
49
+ ----------
50
+ category : ImportCategory
51
+ What kind of recovery this is (see :class:`ImportCategory`).
52
+ message : str
53
+ Human-readable description of what was recovered and how.
54
+ source_span : (int, int) or None
55
+ 1-indexed, inclusive ``(start_line, end_line)`` into the *original*
56
+ file, when the recognizer can point at the source that produced the
57
+ note. ``None`` when no single location is responsible -- either the
58
+ note is a whole-figure aggregate (e.g. mixed ``smooth`` flags across
59
+ every line dataset) or the underlying helper is shared by too many
60
+ call sites to attribute a location without guessing. A single-line
61
+ note has ``start_line == end_line``.
62
+ """
63
+
64
+ category: ImportCategory
65
+ message: str
66
+ source_span: Optional[Tuple[int, int]] = None
67
+
68
+ @property
69
+ def rendered(self) -> str:
70
+ """The note as a ``"category: message"`` string."""
71
+ return f"{self.category.value}: {self.message}"
72
+
73
+ def __str__(self) -> str: # pragma: no cover - convenience only
74
+ return self.rendered