cjm-substrate-qt-kit 0.0.1__tar.gz

cjm_substrate_qt_kit-0.0.1/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: cjm-substrate-qt-kit
+Version: 0.0.1
+Summary: Shared foundations for the PySide6 application lane (DEC c4b0d6e5): the loop-thread session base (a private asyncio loop behind a Qt shell), the row-style palette, and the keybinding helper — extracted at their first real duplication between cjm-graph-workbench-qt and cjm-transcription-qt, never speculatively. Born on-graph.
+Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
+License: Apache-2.0
+Project-URL: Repository, https://github.com/cj-mills/cjm-substrate-qt-kit
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: PySide6
+
+# cjm-substrate-qt-kit
+
+<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->
+
+Shared foundations for the PySide6 application lane (DEC c4b0d6e5): LoopThreadSession (a private asyncio loop behind a Qt shell — GraphSession and CapabilitySession both subclass it), the row-style palette (STYLE_COLORS/apply_row_style), and the keybinding helper. Every piece extracted at its first real duplication between cjm-graph-workbench-qt and cjm-transcription-qt — the kit grows by demand, never speculation. Semantic theming (a94fa56a) and in-app config (812beb51) land here at their demand points.
+
+## Modules
+
+- **`cjm_substrate_qt_kit`** — Shared foundations for the PySide6 application lane — extracted at first duplication (DEC dcf8a712).
+- **`cjm_substrate_qt_kit.keys`** — The keybinding helper both shells grew independently.
+- **`cjm_substrate_qt_kit.loopthread`** — The loop-thread session base: a private asyncio loop behind a Qt shell.
+- **`cjm_substrate_qt_kit.style`** — Row-style vocabulary for the lane's list widgets.
+
+## API
+
+### `cjm_substrate_qt_kit.keys`
+
+- `bind` _function_ — One QShortcut: `key` on `parent` (default: the owner window) fires `fn`.
+
+### `cjm_substrate_qt_kit.loopthread`
+
+- `LoopThreadSession` _class_ — Owns one daemon asyncio loop thread; subclasses put their subsystem's
+
+### `cjm_substrate_qt_kit.style`
+
+- `apply_row_style` _function_ — Map a row's style words onto a list item (color words + bold).
+
+## Dependencies
+
+**Depends on:** `PySide6`
+**Used by:** `cjm-graph-workbench-qt`, `cjm-transcription-qt`

cjm_substrate_qt_kit-0.0.1/README.md

@@ -0,0 +1,31 @@
+# cjm-substrate-qt-kit
+
+<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->
+
+Shared foundations for the PySide6 application lane (DEC c4b0d6e5): LoopThreadSession (a private asyncio loop behind a Qt shell — GraphSession and CapabilitySession both subclass it), the row-style palette (STYLE_COLORS/apply_row_style), and the keybinding helper. Every piece extracted at its first real duplication between cjm-graph-workbench-qt and cjm-transcription-qt — the kit grows by demand, never speculation. Semantic theming (a94fa56a) and in-app config (812beb51) land here at their demand points.
+
+## Modules
+
+- **`cjm_substrate_qt_kit`** — Shared foundations for the PySide6 application lane — extracted at first duplication (DEC dcf8a712).
+- **`cjm_substrate_qt_kit.keys`** — The keybinding helper both shells grew independently.
+- **`cjm_substrate_qt_kit.loopthread`** — The loop-thread session base: a private asyncio loop behind a Qt shell.
+- **`cjm_substrate_qt_kit.style`** — Row-style vocabulary for the lane's list widgets.
+
+## API
+
+### `cjm_substrate_qt_kit.keys`
+
+- `bind` _function_ — One QShortcut: `key` on `parent` (default: the owner window) fires `fn`.
+
+### `cjm_substrate_qt_kit.loopthread`
+
+- `LoopThreadSession` _class_ — Owns one daemon asyncio loop thread; subclasses put their subsystem's
+
+### `cjm_substrate_qt_kit.style`
+
+- `apply_row_style` _function_ — Map a row's style words onto a list item (color words + bold).
+
+## Dependencies
+
+**Depends on:** `PySide6`
+**Used by:** `cjm-graph-workbench-qt`, `cjm-transcription-qt`

cjm_substrate_qt_kit-0.0.1/cjm_substrate_qt_kit/__init__.py

@@ -0,0 +1 @@
+"""Shared foundations for the PySide6 application lane — extracted at first duplication (DEC dcf8a712)."""

cjm_substrate_qt_kit-0.0.1/cjm_substrate_qt_kit/keys.py

@@ -0,0 +1,16 @@
+"""The keybinding helper both shells grew independently."""
+
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QKeySequence, QShortcut
+
+
+def bind(owner, key: str, fn, parent=None, context=Qt.WindowShortcut) -> QShortcut:
+    """One QShortcut: `key` on `parent` (default: the owner window) fires `fn`.
+
+    Returns the shortcut so callers can retune context/enabled later; the
+    default WindowShortcut context pairs with modal dialogs for text entry
+    (single-letter bindings never fight a focused editor)."""
+    shortcut = QShortcut(QKeySequence(key), parent or owner)
+    shortcut.setContext(context)
+    shortcut.activated.connect(fn)
+    return shortcut

cjm_substrate_qt_kit-0.0.1/cjm_substrate_qt_kit/loopthread.py

@@ -0,0 +1,64 @@
+"""The loop-thread session base: a private asyncio loop behind a Qt shell.
+
+Extracted from the third repetition of the pattern (GraphSession in
+cjm-graph-workbench-qt, CapabilitySession in cjm-transcription-qt): async
+subsystems — the projection lens layer, the capability stack — live on a
+daemon loop thread; the Qt shell submits coroutines and resolves the returned
+concurrent Futures through queued Signals, so the paint thread never blocks.
+Qt-free on purpose: sessions test headless, and non-Qt callers (probes,
+scripts) can drive them the same way."""
+
+import asyncio
+import threading
+from concurrent.futures import Future
+from typing import Optional
+
+
+class LoopThreadSession:
+    """Owns one daemon asyncio loop thread; subclasses put their subsystem's
+    verbs on top as submit()-wrapped coroutines.
+
+    start() spins the loop (subclasses may extend it to open resources ON the
+    loop); close() runs the on_close() coroutine hook, then stops the thread.
+    submit() is the non-blocking bridge (Future -> queued Signal in a shell);
+    call() blocks — teardown paths and headless tests."""
+
+    thread_name = "loop-session"
+
+    def __init__(self, timeout: float = 60.0):
+        self.timeout = timeout
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._thread: Optional[threading.Thread] = None
+
+    @property
+    def running(self) -> bool:
+        return self._loop is not None
+
+    def start(self) -> None:
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._loop.run_forever,
+                                        name=self.thread_name, daemon=True)
+        self._thread.start()
+
+    def submit(self, coro) -> Future:
+        """Schedule a coroutine on the loop thread; resolves there."""
+        return asyncio.run_coroutine_threadsafe(coro, self._loop)
+
+    def call(self, coro):
+        """Blocking submit (the sync facade)."""
+        return self.submit(coro).result(self.timeout)
+
+    async def on_close(self) -> None:
+        """Subclass hook: release loop-side resources before the loop stops."""
+
+    def close(self) -> None:
+        if self._loop is None:
+            return
+        try:
+            self.call(self.on_close())
+        finally:
+            self._loop.call_soon_threadsafe(self._loop.stop)
+            if self._thread is not None:
+                self._thread.join(timeout=5)
+            self._loop = None
+            self._thread = None

cjm_substrate_qt_kit-0.0.1/cjm_substrate_qt_kit/style.py

@@ -0,0 +1,26 @@
+"""Row-style vocabulary for the lane's list widgets.
+
+Spine row dicts carry Rich-ish style words ("green", "dim", "bold", …); the
+shells map them onto QListWidgetItems. Theme-neutral hexes readable on light
+and dark — the same palette both shells shipped with before extraction."""
+
+from typing import Optional
+
+from PySide6.QtGui import QColor
+from PySide6.QtWidgets import QListWidgetItem
+
+STYLE_COLORS = {"red": "#c74a3c", "yellow": "#b9770e", "cyan": "#2b8a9d",
+                "magenta": "#9b59b6", "green": "#3f9d55", "blue": "#4a6fb5",
+                "dim": "#8a9299"}
+
+
+def apply_row_style(item: QListWidgetItem, style: Optional[str]) -> None:
+    """Map a row's style words onto a list item (color words + bold)."""
+    parts = str(style or "").split()
+    for word in parts:
+        if word in STYLE_COLORS:
+            item.setForeground(QColor(STYLE_COLORS[word]))
+    if "bold" in parts:
+        font = item.font()
+        font.setBold(True)
+        item.setFont(font)

cjm_substrate_qt_kit-0.0.1/cjm_substrate_qt_kit.egg-info/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: cjm-substrate-qt-kit
+Version: 0.0.1
+Summary: Shared foundations for the PySide6 application lane (DEC c4b0d6e5): the loop-thread session base (a private asyncio loop behind a Qt shell), the row-style palette, and the keybinding helper — extracted at their first real duplication between cjm-graph-workbench-qt and cjm-transcription-qt, never speculatively. Born on-graph.
+Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
+License: Apache-2.0
+Project-URL: Repository, https://github.com/cj-mills/cjm-substrate-qt-kit
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: PySide6
+
+# cjm-substrate-qt-kit
+
+<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->
+
+Shared foundations for the PySide6 application lane (DEC c4b0d6e5): LoopThreadSession (a private asyncio loop behind a Qt shell — GraphSession and CapabilitySession both subclass it), the row-style palette (STYLE_COLORS/apply_row_style), and the keybinding helper. Every piece extracted at its first real duplication between cjm-graph-workbench-qt and cjm-transcription-qt — the kit grows by demand, never speculation. Semantic theming (a94fa56a) and in-app config (812beb51) land here at their demand points.
+
+## Modules
+
+- **`cjm_substrate_qt_kit`** — Shared foundations for the PySide6 application lane — extracted at first duplication (DEC dcf8a712).
+- **`cjm_substrate_qt_kit.keys`** — The keybinding helper both shells grew independently.
+- **`cjm_substrate_qt_kit.loopthread`** — The loop-thread session base: a private asyncio loop behind a Qt shell.
+- **`cjm_substrate_qt_kit.style`** — Row-style vocabulary for the lane's list widgets.
+
+## API
+
+### `cjm_substrate_qt_kit.keys`
+
+- `bind` _function_ — One QShortcut: `key` on `parent` (default: the owner window) fires `fn`.
+
+### `cjm_substrate_qt_kit.loopthread`
+
+- `LoopThreadSession` _class_ — Owns one daemon asyncio loop thread; subclasses put their subsystem's
+
+### `cjm_substrate_qt_kit.style`
+
+- `apply_row_style` _function_ — Map a row's style words onto a list item (color words + bold).
+
+## Dependencies
+
+**Depends on:** `PySide6`
+**Used by:** `cjm-graph-workbench-qt`, `cjm-transcription-qt`

cjm_substrate_qt_kit-0.0.1/cjm_substrate_qt_kit.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+cjm_substrate_qt_kit/__init__.py
+cjm_substrate_qt_kit/keys.py
+cjm_substrate_qt_kit/loopthread.py
+cjm_substrate_qt_kit/style.py
+cjm_substrate_qt_kit.egg-info/PKG-INFO
+cjm_substrate_qt_kit.egg-info/SOURCES.txt
+cjm_substrate_qt_kit.egg-info/dependency_links.txt
+cjm_substrate_qt_kit.egg-info/requires.txt
+cjm_substrate_qt_kit.egg-info/top_level.txt
+tests/test_loopthread.py

cjm_substrate_qt_kit-0.0.1/cjm_substrate_qt_kit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cjm_substrate_qt_kit-0.0.1/cjm_substrate_qt_kit.egg-info/requires.txt

@@ -0,0 +1 @@
+PySide6

cjm_substrate_qt_kit-0.0.1/cjm_substrate_qt_kit.egg-info/top_level.txt

@@ -0,0 +1 @@
+cjm_substrate_qt_kit

cjm_substrate_qt_kit-0.0.1/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cjm-substrate-qt-kit"
+version = "0.0.1"
+description = "Shared foundations for the PySide6 application lane (DEC c4b0d6e5): the loop-thread session base (a private asyncio loop behind a Qt shell), the row-style palette, and the keybinding helper — extracted at their first real duplication between cjm-graph-workbench-qt and cjm-transcription-qt, never speculatively. Born on-graph."
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "Apache-2.0"}
+authors = [{name = "Christian J. Mills", email = "9126128+cj-mills@users.noreply.github.com"}]
+classifiers = ["Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only"]
+dependencies = ['PySide6']
+
+[project.urls]
+Repository = "https://github.com/cj-mills/cjm-substrate-qt-kit"
+
+[tool.setuptools.packages.find]
+include = ["cjm_substrate_qt_kit*"]

cjm_substrate_qt_kit-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cjm_substrate_qt_kit-0.0.1/tests/test_loopthread.py

@@ -0,0 +1,43 @@
+"""LoopThreadSession contract: submit/call resolve on the loop thread, the
+on_close hook runs before the loop stops, close is idempotent."""
+
+import asyncio
+import threading
+
+from cjm_substrate_qt_kit.loopthread import LoopThreadSession
+
+
+class Probe(LoopThreadSession):
+    thread_name = "probe-loop"
+
+    def __init__(self):
+        super().__init__(timeout=5.0)
+        self.closed_on: str = ""
+
+    async def where(self) -> str:
+        return threading.current_thread().name
+
+    async def on_close(self) -> None:
+        await asyncio.sleep(0)
+        self.closed_on = threading.current_thread().name
+
+
+def test_submit_and_call_run_on_the_loop_thread():
+    p = Probe()
+    assert not p.running
+    p.start()
+    assert p.running
+    assert p.call(p.where()) == "probe-loop"
+    assert p.submit(p.where()).result(5) == "probe-loop"
+    p.close()
+
+
+def test_on_close_runs_on_loop_then_thread_stops():
+    p = Probe()
+    p.start()
+    thread = p._thread
+    p.close()
+    assert p.closed_on == "probe-loop"
+    assert not thread.is_alive()
+    assert not p.running
+    p.close()  # idempotent