glitchlings 0.2.5__cp312-cp312-win_amd64.whl → 0.9.3__cp312-cp312-win_amd64.whl

glitchlings/conf/loaders.py

@@ -0,0 +1,331 @@
+"""Impure configuration loading functions.
+
+This module is IMPURE - it performs file IO, environment variable access,
+and maintains global state. Use the schema module for pure validation.
+
+Impure operations:
+- File reading (TOML, YAML)
+- Environment variable access
+- Global configuration cache
+- Optional dependency imports (jsonschema, yaml)
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from io import TextIOBase
+from pathlib import Path
+from typing import IO, TYPE_CHECKING, Any, Callable, Mapping, Protocol, cast
+
+from glitchlings.constants import DEFAULT_ATTACK_SEED, DEFAULT_CONFIG_PATH
+
+from ..compat.loaders import jsonschema
+from .schema import (
+    normalize_mapping,
+    validate_attack_config_schema,
+    validate_runtime_config_data,
+)
+from .types import ATTACK_CONFIG_SCHEMA, AttackConfig, RuntimeConfig
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from ..zoo import Gaggle, Glitchling
+
+
+# ---------------------------------------------------------------------------
+# TOML/YAML module loading (impure - module imports)
+# ---------------------------------------------------------------------------
+
+try:  # Python 3.11+
+    import tomllib as _tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python < 3.11
+    _tomllib = importlib.import_module("tomli")
+
+
+class _TomllibModule(Protocol):
+    def load(self, fp: IO[bytes]) -> Any: ...
+
+
+class _YamlModule(Protocol):
+    YAMLError: type[Exception]
+
+    def safe_load(self, stream: str) -> Any: ...
+
+
+tomllib = cast(_TomllibModule, _tomllib)
+yaml = cast(_YamlModule, importlib.import_module("yaml"))
+
+
+# ---------------------------------------------------------------------------
+# Environment and path resolution (impure - environment access)
+# ---------------------------------------------------------------------------
+
+CONFIG_ENV_VAR = "GLITCHLINGS_CONFIG"
+
+
+def _resolve_config_path() -> Path:
+    """Resolve the configuration file path from environment or default."""
+    override = os.environ.get(CONFIG_ENV_VAR)
+    if override:
+        return Path(override)
+    return DEFAULT_CONFIG_PATH
+
+
+# ---------------------------------------------------------------------------
+# Global configuration state (impure - mutable global)
+# ---------------------------------------------------------------------------
+
+_CONFIG: RuntimeConfig | None = None
+
+
+def reset_config() -> None:
+    """Forget any cached runtime configuration."""
+    global _CONFIG
+    _CONFIG = None
+
+
+def reload_config() -> RuntimeConfig:
+    """Reload the runtime configuration from disk."""
+    reset_config()
+    return get_config()
+
+
+def get_config() -> RuntimeConfig:
+    """Return the cached runtime configuration, loading it if necessary."""
+    global _CONFIG
+    if _CONFIG is None:
+        _CONFIG = _load_runtime_config()
+    return _CONFIG
+
+
+# ---------------------------------------------------------------------------
+# File IO helpers (impure - file system access)
+# ---------------------------------------------------------------------------
+
+
+def _read_text_source(
+    source: str | Path | TextIOBase,
+    *,
+    description: str,
+    encoding: str,
+    missing_error: Callable[[Path], Exception] | None,
+) -> tuple[str, str]:
+    """Read text content from a file path or stream."""
+    if isinstance(source, (str, Path)):
+        path = Path(source)
+        try:
+            text = path.read_text(encoding=encoding)
+        except FileNotFoundError as exc:
+            if missing_error is not None:
+                raise missing_error(path) from exc
+            raise
+        return text, str(path)
+
+    if isinstance(source, TextIOBase):
+        return source.read(), getattr(source, "name", "<stream>")
+
+    raise TypeError(f"{description} source must be a path or text stream.")
+
+
+def load_text_config(
+    source: str | Path | TextIOBase,
+    *,
+    loader: Callable[..., Any],
+    description: str,
+    encoding: str = "utf-8",
+    allow_empty: bool = False,
+    mapping_error: str = "must contain a top-level mapping.",
+    missing_error: Callable[[Path], Exception] | None = None,
+    pass_label: bool = False,
+) -> tuple[dict[str, Any], str]:
+    """Load text configuration data and validate the top-level mapping."""
+    text, label = _read_text_source(
+        source,
+        description=description,
+        encoding=encoding,
+        missing_error=missing_error,
+    )
+    if pass_label:
+        data = loader(text, label)
+    else:
+        data = loader(text)
+    mapping = normalize_mapping(
+        data,
+        source=label,
+        description=description,
+        allow_empty=allow_empty,
+        mapping_error=mapping_error,
+    )
+    return mapping, label
+
+
+def load_binary_config(
+    path: Path,
+    *,
+    loader: Callable[[IO[bytes]], Any],
+    description: str,
+    allow_missing: bool = False,
+    allow_empty: bool = False,
+    mapping_error: str = "must contain a top-level mapping.",
+) -> dict[str, Any]:
+    """Load binary configuration data from disk and validate the mapping."""
+    if not path.exists():
+        if allow_missing:
+            return {}
+        raise FileNotFoundError(f"{description} '{path}' not found.")
+
+    with path.open("rb") as handle:
+        data = loader(handle)
+
+    return normalize_mapping(
+        data,
+        source=str(path),
+        description=description,
+        allow_empty=allow_empty,
+        mapping_error=mapping_error,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Runtime configuration loading (impure - file IO + validation)
+# ---------------------------------------------------------------------------
+
+
+def _load_runtime_config() -> RuntimeConfig:
+    """Load runtime configuration from disk."""
+    path = _resolve_config_path()
+    data = load_binary_config(
+        path,
+        loader=tomllib.load,
+        description="Configuration file",
+        allow_missing=path == DEFAULT_CONFIG_PATH,
+        allow_empty=True,
+    )
+    validate_runtime_config_data(data, source=str(path))
+
+    return RuntimeConfig(path=path)
+
+
+# ---------------------------------------------------------------------------
+# Attack configuration loading (impure - file IO + validation)
+# ---------------------------------------------------------------------------
+
+
+def _load_yaml(text: str, label: str) -> Any:
+    """Parse YAML text, wrapping errors with source context."""
+    try:
+        return yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise ValueError(f"Failed to parse attack configuration '{label}': {exc}") from exc
+
+
+def load_attack_config(
+    source: str | Path | TextIOBase,
+    *,
+    encoding: str = "utf-8",
+) -> AttackConfig:
+    """Load and parse an attack configuration from YAML."""
+    mapping, label = load_text_config(
+        source,
+        loader=_load_yaml,
+        description="Attack configuration",
+        encoding=encoding,
+        mapping_error="must be a mapping.",
+        missing_error=lambda path: ValueError(f"Attack configuration '{path}' was not found."),
+        pass_label=True,
+    )
+    return parse_attack_config(mapping, source=label)
+
+
+def parse_attack_config(data: Any, *, source: str = "<config>") -> AttackConfig:
+    """Convert arbitrary YAML data into a validated ``AttackConfig``."""
+    mapping = validate_attack_config_schema(data, source=source)
+
+    # Optional jsonschema validation (impure - optional dependency)
+    schema_module = jsonschema.get()
+    if schema_module is not None:
+        try:
+            schema_module.validate(instance=mapping, schema=ATTACK_CONFIG_SCHEMA)
+        except schema_module.exceptions.ValidationError as exc:  # pragma: no cover - optional dep
+            message = exc.message
+            raise ValueError(f"Attack configuration '{source}' is invalid: {message}") from exc
+
+    raw_glitchlings = mapping["glitchlings"]
+
+    glitchlings: list["Glitchling"] = []
+    for index, entry in enumerate(raw_glitchlings, start=1):
+        glitchlings.append(_build_glitchling(entry, source, index))
+
+    seed = mapping.get("seed")
+
+    return AttackConfig(glitchlings=glitchlings, seed=seed)
+
+
+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
+
+    seed = seed_override if seed_override is not None else config.seed
+    if seed is None:
+        seed = DEFAULT_ATTACK_SEED
+
+    return Gaggle(config.glitchlings, seed=seed)
+
+
+def _build_glitchling(entry: Any, source: str, index: int) -> "Glitchling":
+    """Build a glitchling instance from a configuration entry."""
+    from ..zoo import get_glitchling_class, parse_glitchling_spec
+
+    if isinstance(entry, str):
+        try:
+            return parse_glitchling_spec(entry)
+        except ValueError as exc:
+            raise ValueError(f"{source}: glitchling #{index}: {exc}") from exc
+
+    if isinstance(entry, Mapping):
+        if "type" in entry:
+            raise ValueError(f"{source}: glitchling #{index} uses unsupported 'type'; use 'name'.")
+
+        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'.")
+
+        parameters = entry.get("parameters")
+        if parameters is not None:
+            if not isinstance(parameters, Mapping):
+                raise ValueError(
+                    f"{source}: glitchling '{name_value}' parameters must be a mapping."
+                )
+            kwargs = dict(parameters)
+        else:
+            kwargs = {
+                key: value for key, value in entry.items() if key not in {"name", "parameters"}
+            }
+
+        try:
+            glitchling_type = get_glitchling_class(name_value)
+        except ValueError as exc:
+            raise ValueError(f"{source}: glitchling #{index}: {exc}") from exc
+
+        try:
+            return glitchling_type(**kwargs)
+        except TypeError as exc:
+            raise ValueError(
+                f"{source}: glitchling #{index}: failed to instantiate '{name_value}': {exc}"
+            ) from exc
+
+    raise ValueError(f"{source}: glitchling #{index} must be a string or mapping.")
+
+
+__all__ = [
+    "CONFIG_ENV_VAR",
+    "build_gaggle",
+    "get_config",
+    "load_attack_config",
+    "load_binary_config",
+    "load_text_config",
+    "parse_attack_config",
+    "reload_config",
+    "reset_config",
+]

glitchlings/conf/schema.py

@@ -0,0 +1,156 @@
+"""Pure validation functions for configuration data.
+
+This module contains only pure validation functions that operate on already-
+loaded data structures. Functions here do not perform IO - they validate
+in-memory data and return normalized results.
+
+Pure guarantees:
+- No file IO
+- No environment variable access
+- No mutable global state
+- Same inputs always produce same outputs
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+
+def normalize_mapping(
+    data: Any,
+    *,
+    source: str,
+    description: str,
+    allow_empty: bool = False,
+    mapping_error: str = "must contain a top-level mapping.",
+) -> dict[str, Any]:
+    """Ensure ``data`` is a mapping, normalising error messages.
+
+    This is a pure validation function - it checks that ``data`` is a valid
+    mapping and returns a normalized dict copy.
+
+    Args:
+        data: The data to validate.
+        source: A label identifying where the data came from (for error messages).
+        description: A human-readable description of the data type.
+        allow_empty: If True, None values are converted to empty dicts.
+        mapping_error: Custom error message suffix when data is not a mapping.
+
+    Returns:
+        A dict copy of the mapping.
+
+    Raises:
+        ValueError: If the data is not a valid mapping.
+    """
+    if data is None:
+        if allow_empty:
+            return {}
+        raise ValueError(f"{description} '{source}' is empty.")
+    if not isinstance(data, Mapping):
+        raise ValueError(f"{description} '{source}' {mapping_error}")
+    return dict(data)
+
+
+def validate_runtime_config_data(data: Any, *, source: str) -> Mapping[str, Any]:
+    """Validate runtime configuration data structure.
+
+    This is a pure validation function that checks the structure of
+    already-loaded configuration data without performing any IO.
+
+    Args:
+        data: The configuration data (typically from TOML parsing).
+        source: A label identifying the data source (for error messages).
+
+    Returns:
+        The validated mapping.
+
+    Raises:
+        ValueError: If the configuration structure is invalid.
+    """
+    mapping = normalize_mapping(
+        data,
+        source=source,
+        description="Configuration file",
+        allow_empty=True,
+    )
+
+    # Accept empty configs for forwards compatibility
+    return mapping
+
+
+def validate_attack_config_schema(data: Any, *, source: str) -> Mapping[str, Any]:
+    """Validate attack configuration data structure.
+
+    This is a pure validation function that checks the structure of
+    already-loaded configuration data. It does NOT perform jsonschema
+    validation (that requires the optional dependency).
+
+    Args:
+        data: The configuration data (typically from YAML parsing).
+        source: A label identifying the data source (for error messages).
+
+    Returns:
+        The validated mapping.
+
+    Raises:
+        ValueError: If the configuration structure is invalid.
+    """
+    mapping = normalize_mapping(
+        data,
+        source=source,
+        description="Attack configuration",
+        mapping_error="must be a mapping.",
+    )
+
+    unexpected = [key for key in mapping if key not in {"glitchlings", "seed"}]
+    if unexpected:
+        extras = ", ".join(sorted(unexpected))
+        raise ValueError(f"Attack configuration '{source}' has unsupported fields: {extras}.")
+
+    if "glitchlings" not in mapping:
+        raise ValueError(f"Attack configuration '{source}' must define 'glitchlings'.")
+
+    raw_glitchlings = mapping["glitchlings"]
+    if not isinstance(raw_glitchlings, Sequence) or isinstance(raw_glitchlings, (str, bytes)):
+        raise ValueError(f"'glitchlings' in '{source}' must be a sequence.")
+
+    seed = mapping.get("seed")
+    if seed is not None and not isinstance(seed, int):
+        raise ValueError(f"Seed in '{source}' must be an integer if provided.")
+
+    for index, entry in enumerate(raw_glitchlings, start=1):
+        _validate_glitchling_entry(entry, source=source, index=index)
+
+    return mapping
+
+
+def _validate_glitchling_entry(entry: Any, *, source: str, index: int) -> None:
+    """Validate a single glitchling entry in an attack configuration."""
+    if isinstance(entry, str):
+        if not entry.strip():
+            raise ValueError(f"{source}: glitchling #{index} name cannot be empty.")
+        return
+
+    if isinstance(entry, Mapping):
+        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")
+        if parameters is not None and not isinstance(parameters, Mapping):
+            raise ValueError(
+                f"{source}: glitchling '{name_candidate}' parameters must be a mapping."
+            )
+        return
+
+    raise ValueError(f"{source}: glitchling #{index} must be a string or mapping.")
+
+
+__all__ = [
+    "normalize_mapping",
+    "validate_attack_config_schema",
+    "validate_runtime_config_data",
+]

glitchlings/conf/types.py

@@ -0,0 +1,72 @@
+"""Pure type definitions for configuration structures.
+
+This module contains only dataclass definitions and type constants with no
+side effects. It can be safely imported anywhere without triggering IO or
+module loading.
+
+Pure guarantees:
+- No import side effects
+- No file IO
+- No environment variable access
+- No mutable global state
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from ..zoo import Glitchling
+
+
+@dataclass(slots=True)
+class RuntimeConfig:
+    """Top-level runtime configuration loaded from ``config.toml``."""
+
+    path: Path
+
+
+@dataclass(slots=True)
+class AttackConfig:
+    """Structured representation of a glitchling roster loaded from YAML."""
+
+    glitchlings: list["Glitchling"]
+    seed: int | None = None
+
+
+# JSON Schema for attack configuration validation
+ATTACK_CONFIG_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "required": ["glitchlings"],
+    "properties": {
+        "glitchlings": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+                "anyOf": [
+                    {"type": "string", "minLength": 1},
+                    {
+                        "type": "object",
+                        "required": ["name"],
+                        "properties": {
+                            "name": {"type": "string", "minLength": 1},
+                            "parameters": {"type": "object"},
+                        },
+                        "additionalProperties": True,
+                    },
+                ]
+            },
+        },
+        "seed": {"type": "integer"},
+    },
+    "additionalProperties": False,
+}
+
+
+__all__ = [
+    "ATTACK_CONFIG_SCHEMA",
+    "AttackConfig",
+    "RuntimeConfig",
+]

glitchlings/config.toml

@@ -0,0 +1,2 @@
+# Glitchlings configuration file
+# This file is kept for backwards compatibility and future extension.

glitchlings/constants.py

@@ -0,0 +1,59 @@
+"""Centralized defaults and shared configuration constants."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# Global configuration defaults
+DEFAULT_ATTACK_SEED = 151
+DEFAULT_CONFIG_PATH = Path(__file__).with_name("config.toml")
+
+# Character-level glitchling default rates
+DEFAULT_TYPOGRE_RATE = 0.02
+DEFAULT_TYPOGRE_KEYBOARD = "CURATOR_QWERTY"
+DEFAULT_MIM1C_RATE = 0.02
+DEFAULT_SCANNEQUIN_RATE = 0.02
+DEFAULT_ZEEDUB_RATE = 0.02
+
+# Word-level glitchling default rates
+DEFAULT_EKKOKIN_RATE = 0.02
+DEFAULT_EKKOKIN_WEIGHTING = "flat"
+DEFAULT_JARGOYLE_RATE = 0.01
+DEFAULT_REDACTYL_RATE = 0.025
+DEFAULT_REDACTYL_CHAR = "\u2588"  # █ FULL BLOCK
+
+# Rushmore default rates per mode
+RUSHMORE_DEFAULT_RATES = {
+    "delete": 0.01,
+    "duplicate": 0.01,
+    "swap": 0.5,
+}
+
+# Mim1c Unicode script class defaults
+MIM1C_DEFAULT_CLASSES: tuple[str, ...] = ("LATIN", "GREEK", "CYRILLIC", "COMMON")
+
+# Zeedub zero-width character palette
+ZEEDUB_DEFAULT_ZERO_WIDTHS: tuple[str, ...] = (
+    "\u200b",  # ZERO WIDTH SPACE
+    "\u200c",  # ZERO WIDTH NON-JOINER
+    "\u200d",  # ZERO WIDTH JOINER
+    "\ufeff",  # BYTE ORDER MARK (zero-width no-break space)
+)
+
+__all__ = [
+    "DEFAULT_ATTACK_SEED",
+    "DEFAULT_CONFIG_PATH",
+    "DEFAULT_EKKOKIN_RATE",
+    "DEFAULT_EKKOKIN_WEIGHTING",
+    "DEFAULT_JARGOYLE_RATE",
+    "DEFAULT_MIM1C_RATE",
+    "DEFAULT_REDACTYL_CHAR",
+    "DEFAULT_REDACTYL_RATE",
+    "DEFAULT_SCANNEQUIN_RATE",
+    "DEFAULT_TYPOGRE_KEYBOARD",
+    "DEFAULT_TYPOGRE_RATE",
+    "DEFAULT_ZEEDUB_RATE",
+    "MIM1C_DEFAULT_CLASSES",
+    "RUSHMORE_DEFAULT_RATES",
+    "ZEEDUB_DEFAULT_ZERO_WIDTHS",
+]

glitchlings/dev/__init__.py

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

glitchlings/dev/docs.py

@@ -0,0 +1,45 @@
+"""Developer helpers for refreshing generated documentation assets."""
+
+from __future__ import annotations
+
+import runpy
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+DOCS_DIR = REPO_ROOT / "docs"
+
+
+def _run_script(path: Path) -> None:
+    if not path.exists():
+        raise FileNotFoundError(f"Documentation helper not found: {path}")
+    runpy.run_path(str(path))
+
+
+def refresh_cli_reference() -> None:
+    """Regenerate the CLI reference docs page."""
+    _run_script(DOCS_DIR / "build_cli_reference.py")
+
+
+def refresh_monster_manual() -> None:
+    """Regenerate the Monster Manual."""
+    _run_script(DOCS_DIR / "build_monster_manual.py")
+
+
+def refresh_gallery() -> None:
+    """Regenerate the glitchling gallery page."""
+    _run_script(DOCS_DIR / "build_glitchling_gallery.py")
+
+
+def refresh_all() -> None:
+    """Regenerate CLI reference, Monster Manual, and gallery docs in one call."""
+    refresh_cli_reference()
+    refresh_monster_manual()
+    refresh_gallery()
+
+
+def main() -> None:
+    refresh_all()
+
+
+if __name__ == "__main__":
+    main()

glitchlings/dlc/__init__.py

@@ -1,5 +1,19 @@
-"""Optional DLC integrations for Glitchlings."""
+"""Optional DLC integrations for Glitchlings.
 
-from .huggingface import install as install_huggingface
+This module provides explicit wrapper classes for integrating glitchlings
+with popular ML frameworks:
 
-__all__ = ["install_huggingface"]
+- :class:`~glitchlings.dlc.huggingface.GlitchedDataset`: Wrap Hugging Face datasets
+- :class:`~glitchlings.dlc.pytorch.GlitchedDataLoader`: Wrap PyTorch data loaders
+- :class:`~glitchlings.dlc.pytorch_lightning.GlitchedLightningDataModule`: Wrap
+  Lightning data modules
+- :class:`~glitchlings.dlc.gutenberg.GlitchenbergAPI`: Wrap Project Gutenberg API
+
+Example:
+    >>> from glitchlings.dlc.huggingface import GlitchedDataset
+    >>> from datasets import Dataset
+    >>> dataset = Dataset.from_dict({"text": ["hello", "world"]})
+    >>> corrupted = GlitchedDataset(dataset, "typogre", column="text")
+"""
+
+__all__: list[str] = []