glitchlings 0.4.2__cp312-cp312-macosx_11_0_universal2.whl → 0.4.4__cp312-cp312-macosx_11_0_universal2.whl

glitchlings/__init__.py

@@ -2,6 +2,7 @@ from .config import AttackConfig, build_gaggle, load_attack_config
 from .util import SAMPLE_TEXT
 from .zoo import (
     Adjax,
+    Apostrofae,
     Gaggle,
     Glitchling,
     Jargoyle,
@@ -13,6 +14,7 @@ from .zoo import (
     Typogre,
     Zeedub,
     adjax,
+    apostrofae,
     is_rust_pipeline_enabled,
     is_rust_pipeline_supported,
     jargoyle,
@@ -38,6 +40,8 @@ __all__ = [
     "jargoyle",
     "Adjax",
     "adjax",
+    "Apostrofae",
+    "apostrofae",
     "Redactyl",
     "redactyl",
     "Reduple",

glitchlings/compat.py

@@ -6,16 +6,50 @@ import re
 from dataclasses import dataclass
 from importlib import import_module, metadata
 from types import ModuleType
-from typing import Any, Iterable
+from typing import Any, Callable, Iterable, Protocol, cast
+
+
+class _MissingSentinel:
+    __slots__ = ()
+
+
+_MISSING = _MissingSentinel()
+
+
+class _MarkerProtocol(Protocol):
+    def evaluate(self, environment: dict[str, str]) -> bool:
+        ...
+
+
+class _RequirementProtocol(Protocol):
+    marker: _MarkerProtocol | None
+    name: str
+
+    def __init__(self, requirement: str) -> None:
+        ...
+
+
+try:  # pragma: no cover - packaging is bundled with modern Python environments
+    from packaging.markers import default_environment as _default_environment
+except ModuleNotFoundError:  # pragma: no cover - fallback when packaging missing
+    _default_environment = None
 
 try:  # pragma: no cover - packaging is bundled with modern Python environments
-    from packaging.markers import default_environment
-    from packaging.requirements import Requirement
+    from packaging.requirements import Requirement as _RequirementClass
 except ModuleNotFoundError:  # pragma: no cover - fallback when packaging missing
-    Requirement = None  # type: ignore[assignment]
-    default_environment = None  # type: ignore[assignment]
+    _RequirementClass = None
 
-_MISSING = object()
+default_environment: Callable[[], dict[str, str]] | None
+if _default_environment is None:
+    default_environment = None
+else:
+    default_environment = cast(Callable[[], dict[str, str]], _default_environment)
+
+Requirement: type[_RequirementProtocol] | None
+if _RequirementClass is None:
+    Requirement = None
+else:
+    Requirement = cast(type[_RequirementProtocol], _RequirementClass)
 
 
 @dataclass
@@ -23,7 +57,7 @@ class OptionalDependency:
     """Lazily import an optional dependency and retain the import error."""
 
     module_name: str
-    _cached: ModuleType | object = _MISSING
+    _cached: ModuleType | None | _MissingSentinel = _MISSING
     _error: ModuleNotFoundError | None = None
 
     def _attempt_import(self) -> ModuleType | None:
@@ -40,11 +74,12 @@ class OptionalDependency:
 
     def get(self) -> ModuleType | None:
         """Return the imported module or ``None`` when unavailable."""
-        if self._cached is _MISSING:
+        cached = self._cached
+        if isinstance(cached, _MissingSentinel):
             return self._attempt_import()
-        if self._cached is None:
+        if cached is None:
             return None
-        return self._cached
+        return cached
 
     def load(self) -> ModuleType:
         """Return the dependency, raising the original import error when absent."""
@@ -87,16 +122,18 @@ class OptionalDependency:
         return self._error
 
 
+pytorch_lightning = OptionalDependency("pytorch_lightning")
 datasets = OptionalDependency("datasets")
 verifiers = OptionalDependency("verifiers")
 jellyfish = OptionalDependency("jellyfish")
 jsonschema = OptionalDependency("jsonschema")
 nltk = OptionalDependency("nltk")
+torch = OptionalDependency("torch")
 
 
 def reset_optional_dependencies() -> None:
     """Clear cached optional dependency imports (used by tests)."""
-    for dependency in (datasets, verifiers, jellyfish, jsonschema, nltk):
+    for dependency in (pytorch_lightning, datasets, verifiers, jellyfish, jsonschema, nltk, torch):
         dependency.reset()
 
 
@@ -110,6 +147,16 @@ def require_datasets(message: str = "datasets is not installed") -> ModuleType:
     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)
@@ -120,6 +167,28 @@ def require_jellyfish(message: str = "jellyfish is not installed") -> ModuleType
     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)
+
+
 def get_installed_extras(
     extras: Iterable[str] | None = None,
     *,

glitchlings/config.py

@@ -2,29 +2,46 @@
 
 from __future__ import annotations
 
+import importlib
 import os
 import warnings
 from dataclasses import dataclass, field
 from io import TextIOBase
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Mapping, Sequence
+from typing import IO, TYPE_CHECKING, Any, Mapping, Protocol, Sequence, cast
+
+from glitchlings.compat import jsonschema
 
 try:  # Python 3.11+
-    import tomllib
+    import tomllib as _tomllib
 except ModuleNotFoundError:  # pragma: no cover - Python < 3.11
-    import tomli as tomllib  # type: ignore[no-redef]
+    _tomllib = importlib.import_module("tomli")
+
+
+class _TomllibModule(Protocol):
+    def load(self, fp: IO[bytes]) -> Any:
+        ...
+
+
+tomllib = cast(_TomllibModule, _tomllib)
+
 
-import yaml
+class _YamlModule(Protocol):
+    YAMLError: type[Exception]
 
-from .compat import jsonschema
+    def safe_load(self, stream: str) -> Any:
+        ...
+
+
+yaml = cast(_YamlModule, importlib.import_module("yaml"))
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
-    from .zoo import Glitchling
+    from .zoo import Gaggle, Glitchling
 
 
 CONFIG_ENV_VAR = "GLITCHLINGS_CONFIG"
 DEFAULT_CONFIG_PATH = Path(__file__).with_name("config.toml")
-DEFAULT_LEXICON_PRIORITY = ["vector", "graph", "wordnet"]
+DEFAULT_LEXICON_PRIORITY = ["vector", "wordnet"]
 DEFAULT_ATTACK_SEED = 151
 
 ATTACK_CONFIG_SCHEMA: dict[str, Any] = {
@@ -72,7 +89,6 @@ class LexiconConfig:
 
     priority: list[str] = field(default_factory=lambda: list(DEFAULT_LEXICON_PRIORITY))
     vector_cache: Path | None = None
-    graph_cache: Path | None = None
 
 
 @dataclass(slots=True)
@@ -127,15 +143,9 @@ def _load_runtime_config() -> RuntimeConfig:
         lexicon_section.get("vector_cache"),
         base=path.parent,
     )
-    graph_cache = _resolve_optional_path(
-        lexicon_section.get("graph_cache"),
-        base=path.parent,
-    )
-
     lexicon_config = LexiconConfig(
         priority=normalized_priority,
         vector_cache=vector_cache,
-        graph_cache=graph_cache,
     )
 
     return RuntimeConfig(lexicon=lexicon_config, path=path)
@@ -154,7 +164,10 @@ def _read_toml(path: Path) -> dict[str, Any]:
             return {}
         raise FileNotFoundError(f"Configuration file '{path}' not found.")
     with path.open("rb") as handle:
-        return tomllib.load(handle)
+        loaded = tomllib.load(handle)
+    if isinstance(loaded, Mapping):
+        return dict(loaded)
+    raise ValueError(f"Configuration file '{path}' must contain a top-level mapping.")
 
 
 def _validate_runtime_config_data(data: Any, *, source: Path) -> Mapping[str, Any]:
@@ -173,13 +186,13 @@ def _validate_runtime_config_data(data: Any, *, source: Path) -> Mapping[str, An
     if not isinstance(lexicon_section, Mapping):
         raise ValueError("Configuration 'lexicon' section must be a table.")
 
-    allowed_lexicon_keys = {"priority", "vector_cache", "graph_cache"}
+    allowed_lexicon_keys = {"priority", "vector_cache"}
     unexpected_keys = [str(key) for key in lexicon_section if key not in allowed_lexicon_keys]
     if unexpected_keys:
         extras = ", ".join(sorted(unexpected_keys))
         raise ValueError(f"Unknown lexicon settings: {extras}.")
 
-    for key in ("vector_cache", "graph_cache"):
+    for key in ("vector_cache",):
         value = lexicon_section.get(key)
         if value is not None and not isinstance(value, (str, os.PathLike)):
             raise ValueError(f"lexicon.{key} must be a path or string when provided.")
@@ -287,7 +300,7 @@ def parse_attack_config(data: Any, *, source: str = "<config>") -> AttackConfig:
     return AttackConfig(glitchlings=glitchlings, seed=seed)
 
 
-def build_gaggle(config: AttackConfig, *, seed_override: int | None = None):
+def build_gaggle(config: AttackConfig, *, seed_override: int | None = None) -> "Gaggle":
     """Instantiate a ``Gaggle`` according to ``config``."""
     from .zoo import Gaggle  # Imported lazily to avoid circular dependencies
 
@@ -305,7 +318,7 @@ def _load_yaml(text: str, label: str) -> Any:
         raise ValueError(f"Failed to parse attack configuration '{label}': {exc}") from exc
 
 
-def _build_glitchling(entry: Any, source: str, index: int):
+def _build_glitchling(entry: Any, source: str, index: int) -> "Glitchling":
     from .zoo import get_glitchling_class, parse_glitchling_spec
 
     if isinstance(entry, str):

glitchlings/config.toml

@@ -1,3 +1,3 @@
 [lexicon]
-priority = ["vector", "graph", "wordnet"]
+priority = ["vector", "wordnet"]
 vector_cache = "lexicon/data/default_vector_cache.json"

glitchlings/dlc/__init__.py

@@ -1,5 +1,7 @@
 """Optional DLC integrations for Glitchlings."""
 
 from .huggingface import install as install_huggingface
+from .pytorch import install as install_pytorch
+from .pytorch_lightning import install as install_pytorch_lightning
 
-__all__ = ["install_huggingface"]
+__all__ = ["install_huggingface", "install_pytorch", "install_pytorch_lightning"]

glitchlings/dlc/_shared.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 from collections.abc import Callable, Sequence
 from typing import Any
 
+from ..zoo.core import Gaggle, _is_transcript
+
 
 def resolve_environment(
     env: Any,
@@ -65,4 +67,87 @@ def resolve_columns(dataset: Any, columns: Sequence[str] | None) -> list[str]:
     raise ValueError("Unable to determine which dataset columns to corrupt.")
 
 
-__all__ = ["resolve_columns", "resolve_environment"]
+def normalise_column_spec(
+    columns: str | int | Sequence[str | int] | None,
+) -> list[str | int] | None:
+    """Normalise a column specification into a list of keys or indices.
+
+    Args:
+        columns: Column specification as a single value, sequence of values, or None.
+
+    Returns:
+        A list of column identifiers, or None if input was None.
+
+    Raises:
+        ValueError: If an empty sequence is provided.
+    """
+    if columns is None:
+        return None
+
+    if isinstance(columns, (str, int)):
+        return [columns]
+
+    normalised = list(columns)
+    if not normalised:
+        raise ValueError("At least one column must be specified")
+    return normalised
+
+
+def is_textual_candidate(value: Any) -> bool:
+    """Return ``True`` when ``value`` looks like text that glitchlings can corrupt.
+
+    Args:
+        value: The value to check for textual content.
+
+    Returns:
+        True if the value appears to be textual content.
+    """
+    if isinstance(value, str):
+        return True
+
+    if _is_transcript(value, allow_empty=False, require_all_content=True):
+        return True
+
+    if isinstance(value, Sequence) and not isinstance(value, (bytes, bytearray, str)):
+        if not value:
+            return False
+        if all(isinstance(item, str) for item in value):
+            return True
+        if _is_transcript(list(value), allow_empty=False, require_all_content=True):
+            return True
+
+    return False
+
+
+def corrupt_text_value(value: Any, gaggle: Gaggle) -> Any:
+    """Return ``value`` with glitchlings applied when possible.
+
+    Args:
+        value: The value to corrupt (string, transcript, or sequence of strings).
+        gaggle: The gaggle of glitchlings to apply.
+
+    Returns:
+        The corrupted value, preserving the original type where possible.
+    """
+    if isinstance(value, str):
+        return gaggle.corrupt(value)
+
+    if _is_transcript(value, allow_empty=True):
+        return gaggle.corrupt(value)
+
+    if isinstance(value, list) and value and all(isinstance(item, str) for item in value):
+        return [gaggle.corrupt(item) for item in value]
+
+    if isinstance(value, tuple) and value and all(isinstance(item, str) for item in value):
+        return tuple(gaggle.corrupt(item) for item in value)
+
+    return value
+
+
+__all__ = [
+    "corrupt_text_value",
+    "is_textual_candidate",
+    "normalise_column_spec",
+    "resolve_columns",
+    "resolve_environment",
+]

glitchlings/dlc/pytorch.py

@@ -0,0 +1,166 @@
+"""Integration helpers for PyTorch data loaders."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Mapping, MutableMapping, Sequence
+from typing import Any, cast
+
+from ..compat import get_torch_dataloader, require_torch
+from ..compat import torch as _torch_dependency
+from ..util.adapters import coerce_gaggle
+from ..zoo import Gaggle, Glitchling
+from ._shared import corrupt_text_value, is_textual_candidate, normalise_column_spec
+
+
+def _apply_to_batch(batch: Any, targets: list[str | int] | None, gaggle: Gaggle) -> Any:
+    """Return ``batch`` with glitchlings applied to the specified ``targets``."""
+    if targets is None:
+        return corrupt_text_value(batch, gaggle)
+
+    if isinstance(batch, Mapping):
+        mutated = cast(MutableMapping[str, Any], dict(batch))
+        for key in targets:
+            if not isinstance(key, str):
+                raise TypeError("Mapping batches require string column names")
+            if key not in mutated:
+                raise ValueError(f"Column '{key}' not found in DataLoader batch")
+            mutated[key] = corrupt_text_value(mutated[key], gaggle)
+        return mutated
+
+    if isinstance(batch, Sequence) and not isinstance(batch, (bytes, bytearray, str)):
+        mutated_sequence = list(batch)
+        for index in targets:
+            if not isinstance(index, int):
+                raise TypeError("Sequence batches require integer column indices")
+            try:
+                mutated_sequence[index] = corrupt_text_value(mutated_sequence[index], gaggle)
+            except IndexError as exc:  # pragma: no cover - defensive
+                raise IndexError("Column index out of range for DataLoader batch") from exc
+        if isinstance(batch, tuple):
+            return tuple(mutated_sequence)
+        return mutated_sequence
+
+    raise TypeError("Unsupported DataLoader batch type for glitching")
+
+
+def _infer_targets(batch: Any) -> list[str | int] | None:
+    """Infer which fields should be glitched from a representative ``batch``."""
+    if isinstance(batch, Mapping):
+        inferred = [key for key, value in batch.items() if is_textual_candidate(value)]
+        if inferred:
+            return inferred
+        raise ValueError("Unable to infer which mapping columns contain text")
+
+    if isinstance(batch, Sequence) and not isinstance(batch, (bytes, bytearray, str)):
+        inferred_indices: list[str | int] = [
+            idx for idx, value in enumerate(batch) if is_textual_candidate(value)
+        ]
+        if inferred_indices:
+            return inferred_indices
+        raise ValueError("Unable to infer which sequence indices contain text")
+
+    if is_textual_candidate(batch):
+        return None
+
+    raise TypeError("Unsupported DataLoader batch type for glitching")
+
+
+class _GlitchedDataLoader(Iterable[Any]):
+    """Wrapper that applies glitchlings lazily to each batch from a data loader."""
+
+    def __init__(
+        self,
+        dataloader: Any,
+        gaggle: Gaggle,
+        *,
+        columns: list[str | int] | None,
+    ) -> None:
+        self._dataloader = dataloader
+        self._gaggle = gaggle
+        self._explicit_columns = columns
+        self._inferred_columns: list[str | int] | None | _Sentinel = _UNINITIALISED
+
+    def __iter__(self) -> Iterator[Any]:
+        # Reset all glitchling RNGs before each fresh pass for determinism.
+        self._gaggle.sort_glitchlings()
+        for batch in self._dataloader:
+            targets = self._resolve_columns(batch)
+            yield _apply_to_batch(batch, targets, self._gaggle)
+
+    def __len__(self) -> int:
+        return len(self._dataloader)
+
+    def __getattr__(self, attribute: str) -> Any:
+        return getattr(self._dataloader, attribute)
+
+    def _resolve_columns(self, batch: Any) -> list[str | int] | None:
+        if self._explicit_columns is not None:
+            return self._explicit_columns
+
+        if self._inferred_columns is _UNINITIALISED:
+            self._inferred_columns = _infer_targets(batch)
+
+        return cast(list[str | int] | None, self._inferred_columns)
+
+
+class _Sentinel:
+    """Sentinel type for deferred column inference."""
+
+
+_UNINITIALISED = _Sentinel()
+
+
+def _ensure_dataloader_class() -> type[Any]:
+    """Return :class:`torch.utils.data.DataLoader` patched with ``.glitch``."""
+    dataloader_cls = get_torch_dataloader()
+    if dataloader_cls is None:
+        require_torch("torch is not installed; install glitchlings[torch]")
+        dataloader_cls = get_torch_dataloader()
+        if dataloader_cls is None:  # pragma: no cover - defensive
+            message = "torch.utils.data.DataLoader is not available"
+            error = _torch_dependency.error
+            if error is not None:
+                raise ModuleNotFoundError(message) from error
+            raise ModuleNotFoundError(message)
+
+    if getattr(dataloader_cls, "glitch", None) is None:
+
+        def glitch(
+            self: Any,
+            glitchlings: Iterable[str | Glitchling] | Glitchling | str | Gaggle,
+            *,
+            columns: str | int | Sequence[str | int] | None = None,
+            seed: int = 151,
+        ) -> _GlitchedDataLoader:
+            """Return a lazily glitched view of the loader's batches."""
+            gaggle = coerce_gaggle(glitchlings, seed=seed)
+            normalised = normalise_column_spec(columns)
+            return _GlitchedDataLoader(self, gaggle, columns=normalised)
+
+        setattr(dataloader_cls, "glitch", glitch)
+
+    return cast(type[Any], dataloader_cls)
+
+
+def _optional_dataloader_class() -> type[Any] | None:
+    """Return the PyTorch :class:`~torch.utils.data.DataLoader` when importable."""
+    dataloader_cls = get_torch_dataloader()
+    if dataloader_cls is None:
+        return None
+    return cast(type[Any], dataloader_cls)
+
+
+def install() -> None:
+    """Monkeypatch PyTorch's :class:`~torch.utils.data.DataLoader` with ``.glitch``."""
+    _ensure_dataloader_class()
+
+
+DataLoader: type[Any] | None
+_DataLoaderAlias = _optional_dataloader_class()
+if _DataLoaderAlias is not None:
+    DataLoader = _ensure_dataloader_class()
+else:  # pragma: no cover - torch is an optional dependency
+    DataLoader = None
+
+
+__all__ = ["DataLoader", "install"]