glitchlings 0.10.2__cp312-cp312-macosx_11_0_universal2.whl

glitchlings/auggie.py

@@ -0,0 +1,284 @@
+"""Laboratory assistant for composing gaggles with behaviour-focused helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from typing import Collection, Literal
+
+from .zoo.core import Gaggle, Glitchling
+from .zoo.hokey import Hokey
+from .zoo.jargoyle import (
+    DEFAULT_LEXEMES,
+    DEFAULT_MODE,
+    Jargoyle,
+    JargoyleMode,
+)
+from .zoo.mim1c import Mim1c
+from .zoo.pedant import Pedant
+from .zoo.pedant.stones import PedantStone
+from .zoo.redactyl import FULL_BLOCK, Redactyl
+from .zoo.rushmore import Rushmore, RushmoreMode
+from .zoo.scannequin import Scannequin
+from .zoo.typogre import Typogre
+from .zoo.wherewolf import Wherewolf
+from .zoo.zeedub import Zeedub
+
+
+class Auggie(Gaggle):
+    """Assistant that incrementally assembles glitchlings into a gaggle."""
+
+    def __init__(
+        self,
+        glitchlings: Iterable[Glitchling] | None = None,
+        *,
+        seed: int = 151,
+    ) -> None:
+        self._blueprint: list[Glitchling] = []
+        initial = list(glitchlings or [])
+        super().__init__(initial, seed=seed)
+        if initial:
+            self._blueprint = [glitchling.clone() for glitchling in initial]
+            self._rebuild_plan()
+        else:
+            self._blueprint = []
+
+    def _rebuild_plan(self) -> None:
+        self._clones_by_index = []
+        for index, glitchling in enumerate(self._blueprint):
+            clone = glitchling.clone()
+            setattr(clone, "_gaggle_index", index)
+            self._clones_by_index.append(clone)
+        self.sort_glitchlings()
+        self._invalidate_pipeline_cache()
+
+    def _enqueue(self, glitchling: Glitchling) -> "Auggie":
+        self._blueprint.append(glitchling)
+        self._rebuild_plan()
+        return self
+
+    def clone(self, seed: int | None = None) -> "Auggie":
+        clone_seed = seed if seed is not None else self.seed
+        resolved_seed = 151 if clone_seed is None else int(clone_seed)
+        blueprint = [glitch.clone() for glitch in self._blueprint]
+        return Auggie(blueprint, seed=resolved_seed)
+
+    def typo(
+        self,
+        *,
+        rate: float | None = None,
+        keyboard: str = "CURATOR_QWERTY",
+        seed: int | None = None,
+    ) -> "Auggie":
+        """Add :class:`Typogre` using behaviour-driven nomenclature."""
+
+        return self._enqueue(Typogre(rate=rate, keyboard=keyboard, seed=seed))
+
+    def confusable(
+        self,
+        *,
+        rate: float | None = None,
+        classes: list[str] | Literal["all"] | None = None,
+        banned_characters: Collection[str] | None = None,
+        seed: int | None = None,
+    ) -> "Auggie":
+        """Add :class:`Mim1c` for homoglyph substitutions."""
+
+        return self._enqueue(
+            Mim1c(
+                rate=rate,
+                classes=classes,
+                banned_characters=banned_characters,
+                seed=seed,
+            )
+        )
+
+    def curly_quotes(self, *, seed: int | None = None) -> "Auggie":
+        """Add :class:`Pedant` evolved with Curlite to smarten punctuation."""
+
+        return self._enqueue(Pedant(stone=PedantStone.CURLITE, seed=seed))
+
+    def stretch(
+        self,
+        *,
+        rate: float = 0.3,
+        extension_min: int = 2,
+        extension_max: int = 5,
+        word_length_threshold: int = 6,
+        base_p: float = 0.45,
+        seed: int | None = None,
+    ) -> "Auggie":
+        """Add :class:`Hokey` for elongated, expressive words."""
+
+        return self._enqueue(
+            Hokey(
+                rate=rate,
+                extension_min=extension_min,
+                extension_max=extension_max,
+                word_length_threshold=word_length_threshold,
+                base_p=base_p,
+                seed=seed,
+            )
+        )
+
+    def homophone(
+        self,
+        *,
+        rate: float | None = None,
+        seed: int | None = None,
+    ) -> "Auggie":
+        """Add :class:`Wherewolf` to swap words for homophones."""
+
+        return self._enqueue(Wherewolf(rate=rate, seed=seed))
+
+    def pedantry(
+        self,
+        *,
+        stone: PedantStone | str = PedantStone.COEURITE,
+        seed: int | None = None,
+    ) -> "Auggie":
+        """Add :class:`Pedant` to evolve text via a chosen stone."""
+
+        return self._enqueue(Pedant(stone=stone, seed=seed))
+
+    def remix(
+        self,
+        *,
+        modes: RushmoreMode | str | Iterable[RushmoreMode | str] | None = None,
+        rate: float | None = None,
+        delete_rate: float | None = None,
+        duplicate_rate: float | None = None,
+        swap_rate: float | None = None,
+        seed: int | None = None,
+        unweighted: bool = False,
+        delete_unweighted: bool | None = None,
+        duplicate_unweighted: bool | None = None,
+    ) -> "Auggie":
+        """Add :class:`Rushmore` for deletion, duplication, and swap attacks."""
+
+        return self._enqueue(
+            Rushmore(
+                modes=modes,
+                rate=rate,
+                delete_rate=delete_rate,
+                duplicate_rate=duplicate_rate,
+                swap_rate=swap_rate,
+                seed=seed,
+                unweighted=unweighted,
+                delete_unweighted=delete_unweighted,
+                duplicate_unweighted=duplicate_unweighted,
+            )
+        )
+
+    def redact(
+        self,
+        *,
+        replacement_char: str = FULL_BLOCK,
+        rate: float | None = None,
+        merge_adjacent: bool = False,
+        seed: int | None = 151,
+        unweighted: bool = False,
+    ) -> "Auggie":
+        """Add :class:`Redactyl` to blackout words."""
+
+        return self._enqueue(
+            Redactyl(
+                replacement_char=replacement_char,
+                rate=rate,
+                merge_adjacent=merge_adjacent,
+                seed=seed if seed is not None else 151,
+                unweighted=unweighted,
+            )
+        )
+
+    def recolor(self, *, mode: JargoyleMode = "literal", seed: int | None = None) -> "Auggie":
+        """Add :class:`Jargoyle` with ``lexemes="colors"`` to remap colour terms.
+
+        Args:
+            mode: "literal" for deterministic first-entry swaps,
+                  "drift" for random selection from palette.
+            seed: Seed for deterministic randomness.
+
+        Returns:
+            Self for method chaining.
+        """
+        return self._enqueue(Jargoyle(lexemes="colors", mode=mode, rate=1.0, seed=seed))
+
+    def drift(
+        self,
+        *,
+        lexemes: str = DEFAULT_LEXEMES,
+        mode: JargoyleMode = DEFAULT_MODE,
+        rate: float | None = None,
+        seed: int | None = None,
+    ) -> "Auggie":
+        """Add :class:`Jargoyle` for dictionary-based word drift.
+
+        Swaps words with alternatives from the specified lexeme dictionary.
+
+        Args:
+            lexemes: Dictionary to use. One of:
+                "colors" (color term swapping),
+                "synonyms" (general synonyms),
+                "corporate" (business jargon),
+                "academic" (scholarly terms).
+            mode: "literal" for deterministic first-entry swaps,
+                  "drift" for random selection.
+            rate: Probability of transforming each matching word.
+            seed: Seed for deterministic randomness.
+
+        Returns:
+            Self for method chaining.
+        """
+        return self._enqueue(Jargoyle(lexemes=lexemes, mode=mode, rate=rate, seed=seed))
+
+    def ocr(
+        self,
+        *,
+        rate: float | None = None,
+        seed: int | None = None,
+    ) -> "Auggie":
+        """Add :class:`Scannequin` to simulate OCR artefacts."""
+
+        return self._enqueue(Scannequin(rate=rate, seed=seed))
+
+    def zero_width(
+        self,
+        *,
+        rate: float | None = None,
+        seed: int | None = None,
+        characters: Sequence[str] | None = None,
+    ) -> "Auggie":
+        """Add :class:`Zeedub` to hide zero-width glyphs inside text."""
+
+        return self._enqueue(Zeedub(rate=rate, seed=seed, characters=characters))
+
+    def synonym(
+        self,
+        *,
+        rate: float | None = None,
+        seed: int | None = None,
+        lexemes: str = "synonyms",
+        mode: JargoyleMode = "drift",
+    ) -> "Auggie":
+        """Add :class:`Jargoyle` for synonym substitutions.
+
+        Args:
+            rate: Probability of transforming each matching word.
+            seed: Seed for deterministic randomness.
+            lexemes: Dictionary to use (default "synonyms").
+            mode: "literal" or "drift" (default "drift").
+
+        Returns:
+            Self for method chaining.
+        """
+        return self._enqueue(
+            Jargoyle(
+                rate=rate,
+                seed=seed,
+                lexemes=lexemes,
+                mode=mode,
+            )
+        )
+
+
+__all__ = ["Auggie"]

glitchlings/compat/__init__.py

@@ -0,0 +1,9 @@
+"""Compatibility helpers centralising optional dependency imports and extras.
+
+For 1.0, this package no longer re-exports loader utilities or type sentinels.
+Import directly from ``glitchlings.compat.loaders`` or ``glitchlings.compat.types``.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

glitchlings/compat/loaders.py

@@ -0,0 +1,355 @@
+"""Lazy loading infrastructure for optional dependencies.
+
+This module is IMPURE - it performs import attempts and caches results.
+Import-time side effects: None (lazy loading only happens on access).
+Runtime side effects: Module imports, file IO for metadata queries.
+
+The OptionalDependency class provides lazy loading with:
+- Cached import results
+- Fallback factories for stub modules
+- Error preservation for better diagnostics
+- Thread-unsafe caching (by design - single-threaded use expected)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from importlib import import_module, metadata
+from types import ModuleType
+from typing import Any, Callable, Iterable, NoReturn, cast
+
+from packaging.markers import default_environment
+from packaging.requirements import Requirement
+
+from .types import MISSING, _MissingSentinel
+
+
+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: dict[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.
+
+    This class is impure:
+    - Performs module imports on first access
+    - Caches results in mutable instance state
+    - May trigger fallback factory execution
+    """
+
+    module_name: str
+    fallback_factory: Callable[[], ModuleType] | None = None
+    _cached: ModuleType | None | _MissingSentinel = field(default=MISSING)
+    _error: ModuleNotFoundError | None = field(default=None)
+    _used_fallback: bool = field(default=False)
+    _fallback_instance: ModuleType | None = field(default=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
+        if isinstance(cached, _MissingSentinel):
+            return self._attempt_import()
+        if cached is None:
+            return None
+        return cached
+
+    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:
+            self._raise_missing_error()
+        return module
+
+    def require(self, message: str) -> ModuleType:
+        """Return the dependency or raise ``ModuleNotFoundError`` with ``message``."""
+        try:
+            return self.load()
+        except ModuleNotFoundError as exc:
+            raise ModuleNotFoundError(message) from exc
+
+    def available(self) -> bool:
+        """Return ``True`` when the dependency can be imported."""
+        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
+    def error(self) -> ModuleNotFoundError | None:
+        """Return the most recent ``ModuleNotFoundError`` (if any)."""
+        self.get()
+        return self._error
+
+
+# ---------------------------------------------------------------------------
+# Global dependency instances (mutable singletons)
+# ---------------------------------------------------------------------------
+
+pytorch_lightning = OptionalDependency(
+    "pytorch_lightning",
+    fallback_factory=_build_lightning_stub,
+)
+datasets = OptionalDependency("datasets")
+verifiers = OptionalDependency("verifiers")
+jellyfish = OptionalDependency("jellyfish")
+jsonschema = OptionalDependency("jsonschema")
+torch = OptionalDependency("torch")
+
+
+def reset_optional_dependencies() -> None:
+    """Clear cached optional dependency imports (used by tests)."""
+    for dependency in (pytorch_lightning, datasets, verifiers, jellyfish, jsonschema, torch):
+        dependency.reset()
+
+
+# ---------------------------------------------------------------------------
+# Convenience accessors
+# ---------------------------------------------------------------------------
+
+
+def get_datasets_dataset() -> Any | None:
+    """Return Hugging Face ``Dataset`` class when the dependency is installed."""
+    return datasets.attr("Dataset")
+
+
+def require_datasets(message: str = "datasets is not installed") -> ModuleType:
+    """Ensure the Hugging Face datasets dependency is present."""
+    return datasets.require(message)
+
+
+def get_pytorch_lightning_datamodule() -> Any | None:
+    """Return the PyTorch Lightning ``LightningDataModule`` when available."""
+    return pytorch_lightning.attr("LightningDataModule")
+
+
+def require_pytorch_lightning(message: str = "pytorch_lightning is not installed") -> ModuleType:
+    """Ensure the PyTorch Lightning dependency is present."""
+    return pytorch_lightning.require(message)
+
+
+def require_verifiers(message: str = "verifiers is not installed") -> ModuleType:
+    """Ensure the verifiers dependency is present."""
+    return verifiers.require(message)
+
+
+def require_jellyfish(message: str = "jellyfish is not installed") -> ModuleType:
+    """Ensure the jellyfish dependency is present."""
+    return jellyfish.require(message)
+
+
+def require_torch(message: str = "torch is not installed") -> ModuleType:
+    """Ensure the PyTorch dependency is present."""
+    return torch.require(message)
+
+
+def get_torch_dataloader() -> Any | None:
+    """Return PyTorch ``DataLoader`` when the dependency is installed."""
+    torch_module = torch.get()
+    if torch_module is None:
+        return None
+
+    utils_module = getattr(torch_module, "utils", None)
+    if utils_module is None:
+        return None
+
+    data_module = getattr(utils_module, "data", None)
+    if data_module is None:
+        return None
+
+    return getattr(data_module, "DataLoader", None)
+
+
+# ---------------------------------------------------------------------------
+# Extras metadata inspection (impure - queries package metadata)
+# ---------------------------------------------------------------------------
+
+
+def get_installed_extras(
+    extras: Iterable[str] | None = None,
+    *,
+    distribution: str = "glitchlings",
+) -> dict[str, bool]:
+    """Return a mapping of optional extras to installation availability."""
+    try:
+        dist = metadata.distribution(distribution)
+    except metadata.PackageNotFoundError:
+        return {}
+
+    provided = {extra.lower() for extra in dist.metadata.get_all("Provides-Extra") or []}
+    targets = {extra.lower() for extra in extras} if extras is not None else provided
+    requirements = dist.requires or []
+    mapping: dict[str, set[str]] = {extra: set() for extra in provided}
+
+    for requirement in requirements:
+        names = _extras_from_requirement(requirement, provided)
+        if not names:
+            continue
+        req_name = _requirement_name(requirement)
+        for extra in names:
+            mapping.setdefault(extra, set()).add(req_name)
+
+    status: dict[str, bool] = {}
+    for extra in targets:
+        deps = mapping.get(extra)
+        if not deps:
+            status[extra] = False
+            continue
+        status[extra] = all(_distribution_installed(dep) for dep in deps)
+    return status
+
+
+def _distribution_installed(name: str) -> bool:
+    try:
+        metadata.distribution(name)
+    except metadata.PackageNotFoundError:
+        return False
+    return True
+
+
+def _extras_from_requirement(requirement: str, candidates: set[str]) -> set[str]:
+    req = Requirement(requirement)
+    if req.marker is None:
+        return set()
+    extras: set[str] = set()
+    for extra in candidates:
+        environment = {k: str(v) for k, v in default_environment().items()}
+        environment["extra"] = extra
+        if req.marker.evaluate(environment):
+            extras.add(extra)
+    return extras
+
+
+def _requirement_name(requirement: str) -> str:
+    req = Requirement(requirement)
+    return cast(str, req.name)
+
+
+__all__ = [
+    # Core class
+    "OptionalDependency",
+    # Global instances
+    "pytorch_lightning",
+    "datasets",
+    "verifiers",
+    "jellyfish",
+    "jsonschema",
+    "torch",
+    # Accessors
+    "get_datasets_dataset",
+    "require_datasets",
+    "get_pytorch_lightning_datamodule",
+    "require_pytorch_lightning",
+    "require_verifiers",
+    "require_jellyfish",
+    "require_torch",
+    "get_torch_dataloader",
+    # Utilities
+    "reset_optional_dependencies",
+    "get_installed_extras",
+]

glitchlings/compat/types.py

@@ -0,0 +1,41 @@
+"""Pure type definitions for compatibility infrastructure.
+
+This module contains only type definitions and sentinels with no side effects.
+It can be safely imported anywhere without triggering module loading or IO.
+
+Pure guarantees:
+- No import side effects
+- No module loading attempts
+- No file IO
+- No RNG instantiation
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+
+class _MissingSentinel:
+    """Sentinel value indicating no cached import attempt has been made."""
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "<MISSING>"
+
+
+class Dataset(Protocol):
+    """Protocol mirroring the subset of Hugging Face datasets API we use."""
+
+    def with_transform(self, function: Any) -> "Dataset": ...
+
+
+MISSING: _MissingSentinel = _MissingSentinel()
+"""Singleton sentinel for uninitialized optional dependency cache."""
+
+
+__all__ = [
+    "Dataset",
+    "MISSING",
+    "_MissingSentinel",
+]