glitchlings 0.5.0__cp312-cp312-macosx_11_0_universal2.whl → 0.5.1__cp312-cp312-macosx_11_0_universal2.whl

glitchlings/compat.py

@@ -6,7 +6,7 @@ import re
 from dataclasses import dataclass
 from importlib import import_module, metadata
 from types import ModuleType
-from typing import Any, Callable, Iterable, Protocol, cast
+from typing import Any, Callable, Iterable, Mapping, NoReturn, Protocol, cast
 
 
 class _MissingSentinel:
@@ -50,26 +50,106 @@ else:
     Requirement = cast(type[_RequirementProtocol], _RequirementClass)
 
 
+def _build_lightning_stub() -> ModuleType:
+    """Return a minimal PyTorch Lightning stub when the dependency is absent."""
+
+    module = ModuleType("pytorch_lightning")
+
+    class LightningDataModule:  # pragma: no cover - simple compatibility shim
+        """Lightweight stand-in for PyTorch Lightning's ``LightningDataModule``."""
+
+        def __init__(self, *args: Any, **kwargs: Any) -> None:  # noqa: D401 - parity with real class
+            pass
+
+        def prepare_data(self, *args: Any, **kwargs: Any) -> None:  # noqa: D401 - parity with real class
+            return None
+
+        def setup(self, *args: Any, **kwargs: Any) -> None:
+            return None
+
+        def teardown(self, *args: Any, **kwargs: Any) -> None:
+            return None
+
+        def state_dict(self) -> dict[str, Any]:
+            return {}
+
+        def load_state_dict(self, state_dict: Mapping[str, Any]) -> None:
+            return None
+
+        def transfer_batch_to_device(self, batch: Any, device: Any, dataloader_idx: int) -> Any:
+            return batch
+
+        def on_before_batch_transfer(self, batch: Any, dataloader_idx: int) -> Any:
+            return batch
+
+        def on_after_batch_transfer(self, batch: Any, dataloader_idx: int) -> Any:
+            return batch
+
+        def train_dataloader(self, *args: Any, **kwargs: Any) -> Any:
+            return []
+
+        def val_dataloader(self, *args: Any, **kwargs: Any) -> Any:
+            return []
+
+        def test_dataloader(self, *args: Any, **kwargs: Any) -> Any:
+            return []
+
+        def predict_dataloader(self, *args: Any, **kwargs: Any) -> Any:
+            return []
+
+    setattr(module, "LightningDataModule", LightningDataModule)
+    setattr(module, "__all__", ["LightningDataModule"])
+    setattr(
+        module,
+        "__doc__",
+        "Lightweight stub module that exposes a minimal LightningDataModule "
+        "when PyTorch Lightning is unavailable.",
+    )
+    setattr(module, "__version__", "0.0.0-stub")
+    return module
+
+
 @dataclass
 class OptionalDependency:
     """Lazily import an optional dependency and retain the import error."""
 
     module_name: str
+    fallback_factory: Callable[[], ModuleType] | None = None
     _cached: ModuleType | None | _MissingSentinel = _MISSING
     _error: ModuleNotFoundError | None = None
+    _used_fallback: bool = False
+    _fallback_instance: ModuleType | None = None
 
     def _attempt_import(self) -> ModuleType | None:
         try:
             module = import_module(self.module_name)
         except ModuleNotFoundError as exc:
+            if self.fallback_factory is not None:
+                if self._fallback_instance is None:
+                    self._fallback_instance = self.fallback_factory()
+                module = self._fallback_instance
+                self._cached = module
+                # Preserve the original error so load()/require() can re-raise it
+                self._error = exc
+                self._used_fallback = True
+                return module
             self._cached = None
             self._error = exc
             return None
         else:
             self._cached = module
             self._error = None
+            self._used_fallback = False
             return module
 
+    def _raise_missing_error(self) -> NoReturn:
+        """Raise ModuleNotFoundError for the missing dependency."""
+        error = self._error
+        if error is not None:
+            raise error
+        message = f"{self.module_name} is not installed"
+        raise ModuleNotFoundError(message)
+
     def get(self) -> ModuleType | None:
         """Return the imported module or ``None`` when unavailable."""
         cached = self._cached
@@ -82,12 +162,10 @@ class OptionalDependency:
     def load(self) -> ModuleType:
         """Return the dependency, raising the original import error when absent."""
         module = self.get()
+        if self._used_fallback:
+            self._raise_missing_error()
         if module is None:
-            error = self._error
-            if error is not None:
-                raise error
-            message = f"{self.module_name} is not installed"
-            raise ModuleNotFoundError(message)
+            self._raise_missing_error()
         return module
 
     def require(self, message: str) -> ModuleType:
@@ -99,18 +177,27 @@ class OptionalDependency:
 
     def available(self) -> bool:
         """Return ``True`` when the dependency can be imported."""
-        return self.get() is not None
+        module = self.get()
+        if module is None:
+            return False
+        if self._used_fallback:
+            return False
+        return True
 
     def reset(self) -> None:
         """Forget any cached import result."""
         self._cached = _MISSING
         self._error = None
+        self._used_fallback = False
+        self._fallback_instance = None
 
     def attr(self, attribute: str) -> Any | None:
         """Return ``attribute`` from the dependency when available."""
         module = self.get()
         if module is None:
             return None
+        if self._used_fallback:
+            return None
         return getattr(module, attribute, None)
 
     @property
@@ -120,7 +207,10 @@ class OptionalDependency:
         return self._error
 
 
-pytorch_lightning = OptionalDependency("pytorch_lightning")
+pytorch_lightning = OptionalDependency(
+    "pytorch_lightning",
+    fallback_factory=_build_lightning_stub,
+)
 datasets = OptionalDependency("datasets")
 verifiers = OptionalDependency("verifiers")
 jellyfish = OptionalDependency("jellyfish")

glitchlings/dev/sync_assets.py

@@ -1,17 +1,20 @@
-"""Synchronise canonical glitchling assets with the vendored Rust copies."""
+"""Maintain the canonical glitchling asset bundle shared by Python and Rust."""
 
 from __future__ import annotations
 
 import argparse
-import shutil
 import sys
 from pathlib import Path
 from typing import Iterator, Sequence
 
-RUST_VENDORED_ASSETS: frozenset[str] = frozenset({
-    "hokey_assets.json",
-    "ocr_confusions.tsv",
-})
+PIPELINE_ASSETS: frozenset[str] = frozenset(
+    {
+        "apostrofae_pairs.json",
+        "ekkokin_homophones.json",
+        "hokey_assets.json",
+        "ocr_confusions.tsv",
+    }
+)
 
 
 def _project_root(default: Path | None = None) -> Path:
@@ -21,24 +24,24 @@ def _project_root(default: Path | None = None) -> Path:
 
 
 def _canonical_asset_dir(project_root: Path) -> Path:
-    canonical = project_root / "src" / "glitchlings" / "zoo" / "assets"
+    canonical = project_root / "assets"
     if not canonical.is_dir():
         raise RuntimeError(
-            "expected canonical assets under 'src/glitchlings/zoo/assets'; "
+            "expected canonical assets under 'assets'; "
             "run this command from the repository root"
         )
     return canonical
 
 
-def _rust_asset_dir(project_root: Path) -> Path:
+def _legacy_rust_asset_dir(project_root: Path) -> Path:
     return project_root / "rust" / "zoo" / "assets"
 
 
-def _iter_extraneous_assets(rust_dir: Path) -> Iterator[Path]:
+def _iter_legacy_assets(rust_dir: Path) -> Iterator[Path]:
     if not rust_dir.exists():
         return
     for path in rust_dir.iterdir():
-        if path.is_file() and path.name not in RUST_VENDORED_ASSETS:
+        if path.is_file():
             yield path
 
 
@@ -48,81 +51,55 @@ def sync_assets(
     check: bool = False,
     quiet: bool = False,
 ) -> bool:
-    """Synchronise the vendored Rust asset copies with the canonical sources."""
+    """Ensure pipeline assets exist only at their canonical location."""
 
     root = _project_root(project_root)
     canonical_dir = _canonical_asset_dir(root)
-    rust_dir = _rust_asset_dir(root)
+    rust_dir = _legacy_rust_asset_dir(root)
 
-    missing_sources = [
-        name
-        for name in RUST_VENDORED_ASSETS
-        if not (canonical_dir / name).is_file()
-    ]
+    missing_sources = [name for name in PIPELINE_ASSETS if not (canonical_dir / name).is_file()]
     if missing_sources:
         missing_list = ", ".join(sorted(missing_sources))
         raise RuntimeError(f"missing canonical assets: {missing_list}")
 
-    extraneous = list(_iter_extraneous_assets(rust_dir))
-
-    mismatched: list[tuple[str, str]] = []
-    for name in sorted(RUST_VENDORED_ASSETS):
-        source = canonical_dir / name
-        target = rust_dir / name
-        if not target.exists():
-            mismatched.append((name, "missing"))
-            continue
-        if source.read_bytes() != target.read_bytes():
-            mismatched.append((name, "outdated"))
+    legacy_assets = list(_iter_legacy_assets(rust_dir))
 
     if check:
-        if mismatched or extraneous:
+        if legacy_assets:
             if not quiet:
-                for name, reason in mismatched:
-                    target = rust_dir / name
-                    print(
-                        f"{target.relative_to(root)} is {reason}; run sync_assets to refresh it",
-                        file=sys.stderr,
-                    )
-                for extra in extraneous:
-                    print(
-                        (
-                            "unexpected vendored asset "
-                            f"{extra.relative_to(root)}; run sync_assets to prune it"
-                        ),
-                        file=sys.stderr,
+                for duplicate in legacy_assets:
+                    message = (
+                        "legacy vendored asset "
+                        f"{duplicate.relative_to(root)} still exists; "
+                        "run sync_assets to remove it"
                     )
+                    print(message, file=sys.stderr)
             return False
         if not quiet:
-            print("Rust asset bundle is up to date.")
+            print("No legacy Rust asset copies detected.")
         return True
 
-    rust_dir.mkdir(parents=True, exist_ok=True)
-
-    for name, reason in mismatched:
-        source = canonical_dir / name
-        target = rust_dir / name
-        shutil.copy2(source, target)
-        if not quiet:
-            verb = "Copied" if reason == "missing" else "Updated"
-            print(
-                f"{verb} {source.relative_to(root)} -> {target.relative_to(root)}",
-            )
-
-    for extra in extraneous:
-        extra.unlink()
+    removed_any = False
+    for duplicate in legacy_assets:
+        duplicate.unlink()
+        removed_any = True
         if not quiet:
-            print(f"Removed extraneous vendored asset {extra.relative_to(root)}")
+            print(f"Removed legacy vendored asset {duplicate.relative_to(root)}")
 
-    if not mismatched and not extraneous and not quiet:
-        print("Rust asset bundle already aligned with canonical copies.")
+    if removed_any:
+        try:
+            rust_dir.rmdir()
+        except OSError:
+            pass
+    elif not quiet:
+        print("No legacy Rust asset copies to remove.")
 
     return True
 
 
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
-        description="Synchronise canonical glitchling assets with the vendored Rust copies.",
+        description="Prune legacy vendored Rust assets so only canonical copies remain.",
     )
     parser.add_argument(
         "--check",

glitchlings/dlc/pytorch_lightning.py

@@ -187,7 +187,19 @@ def _ensure_datamodule_class() -> Any:
         setattr(datamodule_cls, "glitch", glitch)
 
     if not issubclass(_GlitchedLightningDataModule, datamodule_cls):
-        _GlitchedLightningDataModule.__bases__ = (datamodule_cls,)
+        try:
+            _GlitchedLightningDataModule.__bases__ = (datamodule_cls,)
+        except TypeError:
+            namespace = {
+                name: value
+                for name, value in vars(_GlitchedLightningDataModule).items()
+                if name not in {"__dict__", "__weakref__"}
+            }
+            replacement = cast(
+                type[Any],
+                type("_GlitchedLightningDataModule", (datamodule_cls,), namespace),
+            )
+            globals()["_GlitchedLightningDataModule"] = replacement
 
     return datamodule_cls
 

glitchlings/spectroll.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .zoo.spectroll import Spectroll, spectroll, swap_colors
+
+__all__ = ["Spectroll", "spectroll", "swap_colors"]

glitchlings/zoo/__init__.py

@@ -14,6 +14,7 @@ from .core import (
     plan_glitchling_specs,
     plan_glitchlings,
 )
+from .ekkokin import Ekkokin, ekkokin
 from .hokey import Hokey, hokey
 from .jargoyle import Jargoyle, jargoyle
 from .jargoyle import dependencies_available as _jargoyle_available
@@ -22,6 +23,7 @@ from .redactyl import Redactyl, redactyl
 from .reduple import Reduple, reduple
 from .rushmore import Rushmore, rushmore
 from .scannequin import Scannequin, scannequin
+from .spectroll import Spectroll, spectroll
 from .typogre import Typogre, typogre
 from .zeedub import Zeedub, zeedub
 
@@ -32,6 +34,8 @@ __all__ = [
     "mim1c",
     "Jargoyle",
     "jargoyle",
+    "Ekkokin",
+    "ekkokin",
     "Apostrofae",
     "apostrofae",
     "Hokey",
@@ -44,6 +48,8 @@ __all__ = [
     "rushmore",
     "Redactyl",
     "redactyl",
+    "Spectroll",
+    "spectroll",
     "Scannequin",
     "scannequin",
     "Zeedub",
@@ -64,10 +70,10 @@ __all__ = [
 
 _HAS_JARGOYLE = _jargoyle_available()
 
-_BUILTIN_GLITCHLING_LIST: list[Glitchling] = [typogre, apostrofae, hokey, mim1c]
+_BUILTIN_GLITCHLING_LIST: list[Glitchling] = [typogre, apostrofae, hokey, mim1c, ekkokin]
 if _HAS_JARGOYLE:
     _BUILTIN_GLITCHLING_LIST.append(jargoyle)
-_BUILTIN_GLITCHLING_LIST.extend([adjax, reduple, rushmore, redactyl, scannequin, zeedub])
+_BUILTIN_GLITCHLING_LIST.extend([adjax, reduple, rushmore, redactyl, spectroll, scannequin, zeedub])
 
 BUILTIN_GLITCHLINGS: dict[str, Glitchling] = {
     glitchling.name.lower(): glitchling for glitchling in _BUILTIN_GLITCHLING_LIST
@@ -75,6 +81,7 @@ BUILTIN_GLITCHLINGS: dict[str, Glitchling] = {
 
 _BUILTIN_GLITCHLING_TYPES: dict[str, type[Glitchling]] = {
     typogre.name.lower(): Typogre,
+    ekkokin.name.lower(): Ekkokin,
     apostrofae.name.lower(): Apostrofae,
     hokey.name.lower(): Hokey,
     mim1c.name.lower(): Mim1c,
@@ -82,6 +89,7 @@ _BUILTIN_GLITCHLING_TYPES: dict[str, type[Glitchling]] = {
     reduple.name.lower(): Reduple,
     rushmore.name.lower(): Rushmore,
     redactyl.name.lower(): Redactyl,
+    spectroll.name.lower(): Spectroll,
     scannequin.name.lower(): Scannequin,
     zeedub.name.lower(): Zeedub,
 }

glitchlings/zoo/assets/__init__.py

@@ -1,19 +1,41 @@
 from __future__ import annotations
 
 import json
+from functools import cache
 from hashlib import blake2b
 from importlib import resources
 from importlib.resources.abc import Traversable
-from typing import Any, BinaryIO, TextIO, cast
+from pathlib import Path
+from typing import Any, BinaryIO, Iterable, TextIO, cast
 
 _DEFAULT_DIGEST_SIZE = 32
 
 
+def _iter_asset_roots() -> Iterable[Traversable]:
+    """Yield candidate locations for the shared glitchling asset bundle."""
+
+    package_root: Traversable | None
+    try:
+        package_root = resources.files("glitchlings").joinpath("assets")
+    except ModuleNotFoundError:  # pragma: no cover - defensive guard for install issues
+        package_root = None
+    if package_root is not None and package_root.is_dir():
+        yield package_root
+
+    repo_root = Path(__file__).resolve().parents[4] / "assets"
+    if repo_root.is_dir():
+        yield cast(Traversable, repo_root)
+
+
 def _asset(name: str) -> Traversable:
-    asset = resources.files(__name__).joinpath(name)
-    if not asset.is_file():  # pragma: no cover - defensive guard for packaging issues
-        raise FileNotFoundError(f"Asset '{name}' not found at {asset}")
-    return asset
+    asset_roots = list(_iter_asset_roots())
+    for root in asset_roots:
+        candidate = root.joinpath(name)
+        if candidate.is_file():
+            return candidate
+
+    searched = ", ".join(str(root.joinpath(name)) for root in asset_roots) or "<unavailable>"
+    raise FileNotFoundError(f"Asset '{name}' not found in: {searched}")
 
 
 def read_text(name: str, *, encoding: str = "utf-8") -> str:
@@ -51,4 +73,19 @@ def hash_asset(name: str) -> str:
     return digest.hexdigest()
 
 
-__all__ = ["read_text", "open_text", "open_binary", "load_json", "hash_asset"]
+@cache
+def load_homophone_groups(name: str = "ekkokin_homophones.json") -> tuple[tuple[str, ...], ...]:
+    """Return the curated homophone sets bundled for the Ekkokin glitchling."""
+
+    data: list[list[str]] = load_json(name)
+    return tuple(tuple(group) for group in data)
+
+
+__all__ = [
+    "read_text",
+    "open_text",
+    "open_binary",
+    "load_json",
+    "hash_asset",
+    "load_homophone_groups",
+]