glitchlings 0.4.5__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/config.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import importlib
 import os
-import warnings
 from dataclasses import dataclass, field
 from io import TextIOBase
 from pathlib import Path
@@ -57,17 +56,6 @@ ATTACK_CONFIG_SCHEMA: dict[str, Any] = {
                         "required": ["name"],
                         "properties": {
                             "name": {"type": "string", "minLength": 1},
-                            "type": {"type": "string", "minLength": 1},
-                            "parameters": {"type": "object"},
-                        },
-                        "additionalProperties": True,
-                    },
-                    {
-                        "type": "object",
-                        "required": ["type"],
-                        "properties": {
-                            "name": {"type": "string", "minLength": 1},
-                            "type": {"type": "string", "minLength": 1},
                             "parameters": {"type": "object"},
                         },
                         "additionalProperties": True,
@@ -263,7 +251,12 @@ def _validate_attack_config_schema(data: Any, *, source: str) -> Mapping[str, An
 
     for index, entry in enumerate(raw_glitchlings, start=1):
         if isinstance(entry, Mapping):
-            name_candidate = entry.get("name") or entry.get("type")
+            if "type" in entry:
+                raise ValueError(
+                    f"{source}: glitchling #{index} uses unsupported 'type'; use 'name'."
+                )
+
+            name_candidate = entry.get("name")
             if not isinstance(name_candidate, str) or not name_candidate.strip():
                 raise ValueError(f"{source}: glitchling #{index} is missing a 'name'.")
             parameters = entry.get("parameters")
@@ -326,17 +319,12 @@ def _build_glitchling(entry: Any, source: str, index: int) -> "Glitchling":
             raise ValueError(f"{source}: glitchling #{index}: {exc}") from exc
 
     if isinstance(entry, Mapping):
-        name_value = entry.get("name")
-        legacy_type = entry.get("type")
-        if name_value is None and legacy_type is not None:
-            warnings.warn(
-                f"{source}: glitchling #{index} uses 'type'; prefer 'name'.",
-                DeprecationWarning,
-                stacklevel=2,
+        if "type" in entry:
+            raise ValueError(
+                f"{source}: glitchling #{index} uses unsupported 'type'; use 'name'."
             )
-            name_value = legacy_type
-        elif name_value is None:
-            name_value = legacy_type
+
+        name_value = entry.get("name")
 
         if not isinstance(name_value, str) or not name_value.strip():
             raise ValueError(f"{source}: glitchling #{index} is missing a 'name'.")
@@ -352,7 +340,7 @@ def _build_glitchling(entry: Any, source: str, index: int) -> "Glitchling":
             kwargs = {
                 key: value
                 for key, value in entry.items()
-                if key not in {"name", "type", "parameters"}
+                if key not in {"name", "parameters"}
             }
 
         try:

glitchlings/dev/__init__.py

@@ -0,0 +1,5 @@
+"""Developer-facing utilities for maintaining the Glitchlings repository."""
+
+from .sync_assets import sync_assets
+
+__all__ = ["sync_assets"]

glitchlings/dev/sync_assets.py

@@ -0,0 +1,130 @@
+"""Maintain the canonical glitchling asset bundle shared by Python and Rust."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Iterator, Sequence
+
+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:
+    if default is not None:
+        return default
+    return Path(__file__).resolve().parents[3]
+
+
+def _canonical_asset_dir(project_root: Path) -> Path:
+    canonical = project_root / "assets"
+    if not canonical.is_dir():
+        raise RuntimeError(
+            "expected canonical assets under 'assets'; "
+            "run this command from the repository root"
+        )
+    return canonical
+
+
+def _legacy_rust_asset_dir(project_root: Path) -> Path:
+    return project_root / "rust" / "zoo" / "assets"
+
+
+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():
+            yield path
+
+
+def sync_assets(
+    project_root: Path | None = None,
+    *,
+    check: bool = False,
+    quiet: bool = False,
+) -> bool:
+    """Ensure pipeline assets exist only at their canonical location."""
+
+    root = _project_root(project_root)
+    canonical_dir = _canonical_asset_dir(root)
+    rust_dir = _legacy_rust_asset_dir(root)
+
+    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}")
+
+    legacy_assets = list(_iter_legacy_assets(rust_dir))
+
+    if check:
+        if legacy_assets:
+            if not quiet:
+                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("No legacy Rust asset copies detected.")
+        return True
+
+    removed_any = False
+    for duplicate in legacy_assets:
+        duplicate.unlink()
+        removed_any = True
+        if not quiet:
+            print(f"Removed legacy vendored asset {duplicate.relative_to(root)}")
+
+    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="Prune legacy vendored Rust assets so only canonical copies remain.",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="exit with a non-zero status when vendored assets diverge",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="suppress status output",
+    )
+    parser.add_argument(
+        "--project-root",
+        type=Path,
+        help="override the detected project root (useful for testing)",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    ok = sync_assets(project_root=args.project_root, check=args.check, quiet=args.quiet)
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":  # pragma: no cover - CLI entry point
+    raise SystemExit(main())

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/util/stretchability.py

@@ -2,11 +2,11 @@
 
 from __future__ import annotations
 
-import json
 import re
 from dataclasses import dataclass
-from importlib import resources
-from typing import Any, Protocol, Sequence, TypedDict, cast
+from typing import Protocol, Sequence, TypedDict, cast
+
+from glitchlings.zoo import assets
 
 # Regexes reused across the module
 TOKEN_REGEX = re.compile(r"\w+|\W+")
@@ -32,12 +32,7 @@ class RandomLike(Protocol):
 
 # Lexical prior probabilities and pragmatic lexica shared with the Rust fast path.
 def _load_assets() -> HokeyAssets:
-    with (
-        resources.files("glitchlings.data")
-        .joinpath("hokey_assets.json")
-        .open("r", encoding="utf-8") as payload
-    ):
-        data: Any = json.load(payload)
+    data = assets.load_json("hokey_assets.json")
     return cast(HokeyAssets, data)
 
 

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/_ocr_confusions.py

@@ -1,18 +1,18 @@
 from __future__ import annotations
 
-from importlib import resources
+from .assets import read_text
 
 _CONFUSION_TABLE: list[tuple[str, list[str]]] | None = None
 
 
 def load_confusion_table() -> list[tuple[str, list[str]]]:
     """Load the OCR confusion table shared by Python and Rust implementations."""
+
     global _CONFUSION_TABLE
     if _CONFUSION_TABLE is not None:
         return _CONFUSION_TABLE
 
-    data = resources.files(__package__) / "ocr_confusions.tsv"
-    text = data.read_text(encoding="utf-8")
+    text = read_text("ocr_confusions.tsv")
     indexed_entries: list[tuple[int, tuple[str, list[str]]]] = []
     for line_number, line in enumerate(text.splitlines()):
         stripped = line.strip()

glitchlings/zoo/_text_utils.py

@@ -21,9 +21,9 @@ def split_token_edges(token: str) -> tuple[str, str, str]:
     return match.group(1), match.group(2), match.group(3)
 
 
-def token_core_length(token: str) -> int:
-    """Return the length of the main word characters for weighting heuristics."""
-    _, core, _ = split_token_edges(token)
+def _resolve_core_length(core: str, token: str) -> int:
+    """Return a stable core-length measurement used by weighting heuristics."""
+
     candidate = core if core else token
     length = len(candidate)
     if length <= 0:
@@ -34,6 +34,12 @@ def token_core_length(token: str) -> int:
     return length
 
 
+def token_core_length(token: str) -> int:
+    """Return the length of the main word characters for weighting heuristics."""
+    _, core, _ = split_token_edges(token)
+    return _resolve_core_length(core, token)
+
+
 @dataclass(frozen=True)
 class WordToken:
     """Metadata describing a non-whitespace token yielded by word splitters."""
@@ -71,12 +77,7 @@ def collect_word_tokens(
             continue
 
         prefix, core, suffix = split_token_edges(token)
-        core_length = len(core)
-        if core_length <= 0:
-            stripped = token.strip()
-            core_length = len(stripped) if stripped else len(token)
-        if core_length <= 0:
-            core_length = 1
+        core_length = _resolve_core_length(core, token)
 
         collected.append(
             WordToken(

glitchlings/zoo/adjax.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import random
 from typing import Any, cast
 
-from ._rate import resolve_rate
 from ._rust_extensions import get_rust_operation
 from ._text_utils import split_preserving_whitespace, split_token_edges
 from .core import AttackWave, Glitchling
@@ -66,16 +65,9 @@ def swap_adjacent_words(
     rate: float | None = None,
     seed: int | None = None,
     rng: random.Random | None = None,
-    *,
-    swap_rate: float | None = None,
 ) -> str:
     """Swap adjacent word cores while preserving spacing and punctuation."""
-    effective_rate = resolve_rate(
-        rate=rate,
-        legacy_value=swap_rate,
-        default=0.5,
-        legacy_name="swap_rate",
-    )
+    effective_rate = 0.5 if rate is None else rate
     clamped_rate = max(0.0, min(effective_rate, 1.0))
 
     if rng is None:
@@ -94,16 +86,9 @@ class Adjax(Glitchling):
         self,
         *,
         rate: float | None = None,
-        swap_rate: float | None = None,
         seed: int | None = None,
     ) -> None:
-        self._param_aliases = {"swap_rate": "rate"}
-        effective_rate = resolve_rate(
-            rate=rate,
-            legacy_value=swap_rate,
-            default=0.5,
-            legacy_name="swap_rate",
-        )
+        effective_rate = 0.5 if rate is None else rate
         super().__init__(
             name="Adjax",
             corruption_function=swap_adjacent_words,
@@ -118,7 +103,7 @@ class Adjax(Glitchling):
             return None
         return {
             "type": "swap_adjacent",
-            "swap_rate": float(rate),
+            "rate": float(rate),
         }
 
 

glitchlings/zoo/apostrofae.py

@@ -2,13 +2,12 @@
 
 from __future__ import annotations
 
-import json
 import random
 from functools import cache
-from importlib import resources
 from typing import Any, Sequence, cast
 
 from ._rust_extensions import get_rust_operation
+from .assets import load_json
 from .core import AttackOrder, AttackWave, Gaggle, Glitchling
 
 # Load Rust-accelerated operation if available
@@ -19,9 +18,7 @@ _apostrofae_rust = get_rust_operation("apostrofae")
 def _load_replacement_pairs() -> dict[str, list[tuple[str, str]]]:
     """Load the curated mapping of straight quotes to fancy pairs."""
 
-    resource = resources.files(f"{__package__}.assets").joinpath("apostrofae_pairs.json")
-    with resource.open("r", encoding="utf-8") as handle:
-        data: dict[str, list[Sequence[str]]] = json.load(handle)
+    data: dict[str, list[Sequence[str]]] = load_json("apostrofae_pairs.json")
 
     parsed: dict[str, list[tuple[str, str]]] = {}
     for straight, replacements in data.items():