seqeyes-python 0.4.1__py3-none-any.whl → 0.4.3__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.
seqeyes/__init__.py CHANGED
@@ -29,4 +29,4 @@ from seqeyes._plot import set, reset
29
29
  from seqeyes._renderer import SeqEyesViewer
30
30
 
31
31
  __all__ = ["set", "reset", "SeqEyesViewer"]
32
- __version__ = "0.4.1"
32
+ __version__ = "0.4.3"
seqeyes/_renderer.py CHANGED
@@ -1,82 +1,112 @@
1
1
  """
2
2
  _renderer.py — Jupyter HTML renderer for the SeqEyes interactive viewer.
3
3
 
4
- Generates a self‑contained HTML string that Jupyter displays inline via
5
- ``_repr_html_()``, exactly the same mechanism Plotly uses. The viewer is
6
- an iframe embedding the SeqEyes web UI with sequence data injected.
4
+ The viewer is the standalone SeqEyes page (``web/index.html``) run as the
5
+ ``python`` host: the sequence and the display options are injected ahead of
6
+ the page's own script, the way the MATLAB toolbox does it. Jupyter displays
7
+ it inline via ``_repr_html_()`` in a ``data:`` iframe, the same mechanism
8
+ Plotly uses; such a frame can fetch nothing, so the stylesheet and both
9
+ scripts are inlined.
7
10
  """
8
11
 
9
12
  from __future__ import annotations
10
13
 
11
14
  import base64
12
15
  import json
16
+ import math
13
17
  import os
18
+ import re
14
19
  from pathlib import Path
15
- from typing import Any, Optional, Union
20
+ from typing import Any, List, Optional, Union
16
21
 
17
22
 
18
23
  # ── Paths ─────────────────────────────────────────────────────────────────
19
24
  _RESOURCES_DIR = Path(__file__).resolve().parent / "resources"
20
- _VIEWER_TEMPLATE_PATH = _RESOURCES_DIR / "viewer.html"
21
-
22
- # pulseq-bundle.js lives in the repo root; during dev we read it directly.
23
- # When installed as a package, a copy should be placed in resources/.
24
- _BUNDLE_CANDIDATES = [
25
- _RESOURCES_DIR / "pulseq-bundle.js",
26
- Path(__file__).resolve().parent.parent.parent.parent / "web" / "pulseq-bundle.js",
27
- Path.cwd() / "web" / "pulseq-bundle.js",
28
- ]
29
- # The label-row module shared with the web renderers. build:web copies it into
30
- # resources/; a source checkout can read it from the webview assets instead.
31
- _LABELS_SCRIPT_CANDIDATES = [
32
- _RESOURCES_DIR / "seqeyes-labels.js",
33
- Path(__file__).resolve().parent.parent.parent.parent / "src" / "editor" / "webview" / "assets" / "labels.js",
34
- Path.cwd() / "src" / "editor" / "webview" / "assets" / "labels.js",
35
- ]
25
+ # ``npm run build:web`` copies the page and its assets into resources/; a
26
+ # source checkout (python/src/seqeyes/) can read them from web/ instead.
27
+ _WEB_DIR = Path(__file__).resolve().parent.parent.parent.parent / "web"
28
+
29
+ # The page's references to its assets, each present exactly once.
30
+ _STYLESHEET_TAG = '<link rel="stylesheet" href="styles.css">'
31
+ _PULSEQ_TAG = '<script src="pulseq-bundle.js"></script>'
32
+ _WEBVIEW_TAG = '<script src="webview-bundle.js"></script>'
33
+ _BODY_TAG = "<body>"
34
+
36
35
  _VALID_GRAD_UNITS = {"Hz/m", "mT/m", "G/cm"}
36
+ # The two plain names Python has always accepted, resolved the way the page's
37
+ # own "system" theme resolves light and dark.
38
+ _THEME_ALIASES = {"light": "githublight", "dark": "github"}
37
39
  SequenceSource = Union[str, bytes, bytearray, memoryview]
38
40
 
39
41
 
40
- def _find_bundle() -> str:
41
- """Locate and read the pulseq-bundle.js file."""
42
- for p in _BUNDLE_CANDIDATES:
43
- if p.is_file():
44
- return p.read_text(encoding="utf-8")
42
+ def _read_resource(name: str) -> str:
43
+ """Read one of the page's files from resources/, or from web/ in a checkout."""
44
+ for directory in (_RESOURCES_DIR, _WEB_DIR):
45
+ path = directory / name
46
+ if path.is_file():
47
+ return path.read_text(encoding="utf-8")
45
48
  raise FileNotFoundError(
46
- "pulseq-bundle.js not found. "
47
- "Build it with: npm run build:web (from the repo root), "
48
- "or copy it to python/src/seqeyes/resources/"
49
+ f"{name} not found in {_RESOURCES_DIR}. "
50
+ "Build it with: npm run build:web (from the repo root)."
49
51
  )
50
52
 
51
53
 
52
- def _find_labels_script() -> str:
53
- """Locate and read the label-row script (SeqEyesLabels)."""
54
- for p in _LABELS_SCRIPT_CANDIDATES:
55
- if p.is_file():
56
- return p.read_text(encoding="utf-8")
57
- raise FileNotFoundError(
58
- "seqeyes-labels.js not found. "
59
- "Build it with: npm run build:web (from the repo root), "
60
- "or copy src/editor/webview/assets/labels.js to python/src/seqeyes/resources/seqeyes-labels.js"
61
- )
54
+ def _normalize_grad_disp(unit: str) -> str:
55
+ """Return a viewer-supported gradient unit."""
56
+ return unit if unit in _VALID_GRAD_UNITS else "mT/m"
62
57
 
63
58
 
64
- def _read_viewer_template() -> str:
65
- """Read the standalone viewer HTML template."""
66
- if _VIEWER_TEMPLATE_PATH.is_file():
67
- return _VIEWER_TEMPLATE_PATH.read_text(encoding="utf-8")
68
- alt = Path.cwd() / "python" / "src" / "seqeyes" / "resources" / "viewer.html"
69
- if alt.is_file():
70
- return alt.read_text(encoding="utf-8")
71
- raise FileNotFoundError(
72
- f"Viewer template not found at {_VIEWER_TEMPLATE_PATH}. "
73
- "Ensure the package is installed correctly."
59
+ def _page_theme(theme: Optional[str]) -> Optional[str]:
60
+ """Map a Python theme name to one of the page's theme names."""
61
+ if not theme:
62
+ return None
63
+ return _THEME_ALIASES.get(str(theme), str(theme))
64
+
65
+
66
+ def _finite_or_none(value: Any) -> Optional[float]:
67
+ try:
68
+ number = float(value)
69
+ except (TypeError, ValueError):
70
+ return None
71
+ return number if math.isfinite(number) else None
72
+
73
+
74
+ def _time_range_option(time_range: Any) -> List[Optional[float]]:
75
+ """Seconds, with None for an open end; ``[0, None]`` keeps the page's first view."""
76
+ try:
77
+ start, end = time_range
78
+ except (TypeError, ValueError):
79
+ return [0.0, None]
80
+ return [_finite_or_none(start), _finite_or_none(end)]
81
+
82
+
83
+ def _script_json(value: Any) -> str:
84
+ """JSON for an inline script, with no character the HTML parser acts on."""
85
+ return (
86
+ json.dumps(value, allow_nan=False, separators=(",", ":"))
87
+ .replace("<", "\\u003c")
88
+ .replace(">", "\\u003e")
89
+ .replace("&", "\\u0026")
74
90
  )
75
91
 
76
92
 
77
- def _normalize_grad_disp(unit: str) -> str:
78
- """Return a viewer-supported gradient unit."""
79
- return unit if unit in _VALID_GRAD_UNITS else "mT/m"
93
+ def _inline_script(source: str) -> str:
94
+ # A literal "</script" would end the element early; "<\/" means the same in JS.
95
+ return "<script>\n" + re.sub(r"</(?=script)", r"<\\/", source, flags=re.IGNORECASE) + "\n</script>"
96
+
97
+
98
+ def _inline_style(source: str) -> str:
99
+ # Likewise for "</style"; "\/" is an escaped "/" in CSS.
100
+ return "<style>\n" + re.sub(r"</(?=style)", r"<\\/", source, flags=re.IGNORECASE) + "\n</style>"
101
+
102
+
103
+ def _replace_tags(page: str, replacements: dict) -> str:
104
+ """Replace each tag, which must occur exactly once, in a single pass."""
105
+ for tag in replacements:
106
+ if page.count(tag) != 1:
107
+ raise ValueError(f"index.html no longer has exactly one {tag!r}")
108
+ pattern = "|".join(re.escape(tag) for tag in replacements)
109
+ return re.sub(pattern, lambda match: replacements[match.group(0)], page)
80
110
 
81
111
 
82
112
  def _build_html(
@@ -97,77 +127,65 @@ def _build_html(
97
127
  sequence_source : str or bytes-like
98
128
  Raw text ``.seq`` content or binary ``.bseq`` bytes.
99
129
  theme : str or None
100
- CSS theme class to apply to ``<body>``.
130
+ Viewer theme: ``"system"``, ``"light"``, ``"dark"``, or one of the
131
+ page's themes (``"onelight"``, ``"onedark"``, ``"dracula"``,
132
+ ``"nord"``, ``"githublight"``, ``"github"``). None uses the page's
133
+ remembered or system theme.
101
134
  inject_bundle : bool
102
- If True, inline the pulseq-bundle.js parser into the HTML.
135
+ If True, inline the stylesheet and both scripts so the page is
136
+ self-contained. If False, keep the page's relative references to
137
+ ``styles.css``, ``pulseq-bundle.js`` and ``webview-bundle.js``, for a
138
+ page served next to copies of those files.
103
139
  label : str
104
- Display label (injected as JS variable, not yet rendered).
140
+ Sequence file name: names exported files, and titles the page when
141
+ the sequence defines no ``Name``.
105
142
  show_blocks : bool
106
143
  Initial block‑boundary visibility.
107
144
  time_range : tuple[float, float]
108
- Initial viewport range in seconds.
145
+ Initial viewport range in seconds. ``(0, inf)`` keeps the viewer's
146
+ own first view; an infinite end means the end of the sequence.
109
147
  time_disp : str
110
148
  Initial time display unit (``"s"``, ``"ms"``, ``"us"``).
111
149
  grad_disp : str
112
150
  Initial gradient display unit (``"mT/m"``, the default, ``"Hz/m"``
113
151
  or ``"G/cm"``).
114
152
  """
115
- template = _read_viewer_template()
116
- grad_disp = _normalize_grad_disp(grad_disp)
153
+ page = _read_resource("index.html")
117
154
  source_is_text = isinstance(sequence_source, str)
118
- source_bytes = sequence_source.encode("utf-8") if source_is_text else bytes(sequence_source)
119
- source_b64 = base64.b64encode(source_bytes).decode("ascii")
120
-
121
- # 1. Inject the pulseq-bundle.js
122
- bundle_placeholder = "<!-- PULSEQ_BUNDLE_PLACEHOLDER -->"
123
- if inject_bundle and bundle_placeholder in template:
124
- bundle_js = _find_bundle()
125
- template = template.replace(
126
- bundle_placeholder,
127
- f"<script>\n{bundle_js}\n</script>",
128
- )
129
- elif bundle_placeholder in template:
130
- template = template.replace(bundle_placeholder, "")
131
-
132
- labels_placeholder = "<!-- LABELS_SCRIPT_PLACEHOLDER -->"
133
- if inject_bundle and labels_placeholder in template:
134
- template = template.replace(
135
- labels_placeholder,
136
- f"<script>\n{_find_labels_script()}\n</script>",
137
- )
138
- elif labels_placeholder in template:
139
- template = template.replace(labels_placeholder, "")
140
-
141
- # 2. Build options injection block (sequence data + display opts)
142
- opts = [
143
- f"window.SEQEYES_RAW_B64 = {json.dumps(source_b64)};",
144
- f"window.SEQEYES_SOURCE_KIND = {json.dumps('text' if source_is_text else 'bytes')};",
145
- f"window.SEQEYES_SOURCE_NAME = {json.dumps(label)};",
146
- f"window.SEQEYES_LABEL = {json.dumps(label)};",
147
- f"window.SEQEYES_SHOW_BLOCKS = {json.dumps(show_blocks)};",
148
- f"window.SEQEYES_TIME_RANGE = {json.dumps(list(time_range))};",
149
- f"window.SEQEYES_TIME_DISP = {json.dumps(time_disp)};",
150
- f"window.SEQEYES_GRAD_DISP = {json.dumps(grad_disp)};",
151
- ]
152
- opts_block = "\n".join(opts)
153
-
154
- data_placeholder = "/* SEQEYES_DATA_PLACEHOLDER */"
155
- if data_placeholder in template:
156
- template = template.replace(data_placeholder, opts_block)
155
+ file_name = label or ("sequence.seq" if source_is_text else "sequence.bseq")
156
+ if source_is_text:
157
+ preload = {"text": sequence_source, "fileName": file_name}
157
158
  else:
158
- template = template.replace(
159
- "</body>",
160
- f"<script>{opts_block}</script>\n</body>",
161
- )
162
-
163
- # 3. Apply theme if specified
164
- if theme:
165
- template = template.replace(
166
- "<body>",
167
- f'<body class="theme-{theme}">',
168
- )
159
+ source_b64 = base64.b64encode(bytes(sequence_source)).decode("ascii")
160
+ preload = {"base64": source_b64, "fileName": file_name}
161
+ page_theme = _page_theme(theme)
162
+ options = {
163
+ "theme": page_theme,
164
+ "timeUnit": time_disp,
165
+ "gradUnit": _normalize_grad_disp(grad_disp),
166
+ "showBlocks": bool(show_blocks),
167
+ "timeRange": _time_range_option(time_range),
168
+ }
169
+ # Runs before both bundles and the page's own script, which read these.
170
+ host_script = (
171
+ "<script>"
172
+ 'window._SEQEYES_HOST="python";'
173
+ f"window._SEQEYES_PRELOAD={_script_json(preload)};"
174
+ f"window._SEQEYES_OPTIONS={_script_json(options)};"
175
+ "</script>\n"
176
+ )
169
177
 
170
- return template
178
+ replacements = {_PULSEQ_TAG: host_script + _PULSEQ_TAG}
179
+ if inject_bundle:
180
+ replacements = {
181
+ _STYLESHEET_TAG: _inline_style(_read_resource("styles.css")),
182
+ _PULSEQ_TAG: host_script + _inline_script(_read_resource("pulseq-bundle.js")),
183
+ _WEBVIEW_TAG: _inline_script(_read_resource("webview-bundle.js")),
184
+ }
185
+ # Themed from the first paint; the page's script then applies the same choice.
186
+ if page_theme and page_theme != "system" and re.fullmatch(r"[\w-]+", page_theme):
187
+ replacements[_BODY_TAG] = f'<body class="theme-{page_theme}">'
188
+ return _replace_tags(page, replacements)
171
189
 
172
190
 
173
191
  class SeqEyesViewer:
@@ -181,18 +199,21 @@ class SeqEyesViewer:
181
199
  sequence_source : str or bytes-like
182
200
  Raw text ``.seq`` content or binary ``.bseq`` bytes.
183
201
  label : str
184
- Display label (not yet rendered on the viewer).
202
+ Sequence file name: names exported files, and titles the viewer when
203
+ the sequence defines no ``Name``.
185
204
  show_blocks : bool
186
205
  Whether to show block‑boundary lines initially.
187
206
  time_range : tuple[float, float]
188
207
  Initial time viewport ``(start_sec, end_sec)``. ``(0, inf)``
189
- shows the whole sequence.
208
+ keeps the viewer's own first view (the first TR when one is found).
190
209
  time_disp : str
191
210
  Time axis unit — ``"s"``, ``"ms"``, or ``"us"``.
192
211
  grad_disp : str
193
212
  Gradient axis unit — ``"mT/m"`` (default), ``"Hz/m"``, or ``"G/cm"``.
194
213
  theme : str or None
195
- Colour theme.
214
+ Colour theme: ``"system"``, ``"light"``, ``"dark"``, ``"onelight"``,
215
+ ``"onedark"``, ``"dracula"``, ``"nord"``, ``"githublight"`` or
216
+ ``"github"``.
196
217
  width : str
197
218
  CSS width of the iframe (e.g. ``"100%"``).
198
219
  height : str
@@ -281,7 +302,12 @@ class SeqEyesViewer:
281
302
  # ── Direct HTML access (for debugging / custom embedding) ──────────
282
303
 
283
304
  def to_html(self, *, inject_bundle: bool = True) -> str:
284
- """Return the full standalone HTML string (for saving to a file)."""
305
+ """Return the full standalone HTML string (for saving to a file).
306
+
307
+ With ``inject_bundle=False`` the page references ``styles.css``,
308
+ ``pulseq-bundle.js`` and ``webview-bundle.js`` by relative URL
309
+ instead of inlining them, so it works only next to copies of them.
310
+ """
285
311
  return _build_html(
286
312
  self._sequence_source,
287
313
  theme=self._theme,