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

glitchlings/internal/__init__.py

@@ -0,0 +1,16 @@
+"""Internal utilities shared across the glitchlings package.
+
+This subpackage contains impure modules that handle side effects:
+
+- ``rust.py``: Low-level Rust extension loader and FFI primitives
+- ``rust_ffi.py``: High-level Rust operation wrappers (preferred entry point)
+
+Pure modules should NOT import from this package. Use the operations in
+``rust_ffi.py`` at boundary layers only.
+
+See AGENTS.md "Functional Purity Architecture" for details.
+"""
+
+from __future__ import annotations
+
+__all__ = []

glitchlings/internal/rust.py

@@ -0,0 +1,159 @@
+"""Shared helpers for loading the compiled Rust extension."""
+
+from __future__ import annotations
+
+import random
+import sys
+from importlib import machinery, util
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Callable, Mapping, MutableMapping, cast
+
+_EXTENSION_STEM = "_zoo_rust"
+
+
+class RustExtensionImportError(RuntimeError):
+    """Raised when the compiled Rust extension cannot be imported."""
+
+
+def _iter_extension_candidates() -> tuple[Path, ...]:
+    """Return likely paths for the compiled extension within the package."""
+
+    package_root = Path(__file__).resolve().parents[1]
+    extension_dir = package_root / _EXTENSION_STEM
+    search_roots = (extension_dir, package_root)
+
+    candidates: list[Path] = []
+    for root in search_roots:
+        for suffix in machinery.EXTENSION_SUFFIXES:
+            candidate = (root / _EXTENSION_STEM).with_suffix(suffix)
+            if candidate.exists():
+                candidates.append(candidate)
+    return tuple(candidates)
+
+
+def _existing_compiled_module() -> ModuleType | None:
+    """Return a previously loaded compiled module if one is present."""
+
+    for name in ("glitchlings._zoo_rust", "_zoo_rust"):
+        module = sys.modules.get(name)
+        if module is None:
+            continue
+        module_file = getattr(module, "__file__", "")
+        if module_file and not str(module_file).endswith("__init__.py"):
+            return module
+    return None
+
+
+def _load_extension_from_disk() -> ModuleType:
+    """Load the compiled extension from disk or raise if unavailable."""
+
+    candidates = _iter_extension_candidates()
+    for candidate in candidates:
+        spec = util.spec_from_file_location(_EXTENSION_STEM, candidate)
+        if spec is None or spec.loader is None:
+            continue
+        module = util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        return module
+
+    searched = ", ".join(str(path) for path in candidates) or "<unavailable>"
+    message = (
+        "glitchlings._zoo_rust failed to import. Rebuild the project with "
+        "`pip install .` or `maturin develop` so the compiled extension is available "
+        f"(searched: {searched})."
+    )
+    raise RustExtensionImportError(message)
+
+
+def load_rust_module() -> ModuleType:
+    """Return the compiled Rust module, loading it on demand."""
+
+    existing = _existing_compiled_module()
+    if existing is not None:
+        return existing
+
+    module = _load_extension_from_disk()
+    sys.modules.setdefault("glitchlings._zoo_rust", module)
+    sys.modules.setdefault("_zoo_rust", module)
+    return module
+
+
+_RUST_MODULE: ModuleType | None = None
+_OPERATION_CACHE: MutableMapping[str, Callable[..., Any]] = {}
+
+
+def _get_rust_module() -> ModuleType:
+    """Return the compiled Rust module, importing it on first use."""
+
+    global _RUST_MODULE
+
+    if _RUST_MODULE is None:
+        _RUST_MODULE = load_rust_module()
+
+    return _RUST_MODULE
+
+
+def _build_missing_operation_error(name: str) -> RuntimeError:
+    message = (
+        "Rust operation '{name}' is not exported by glitchlings._zoo_rust. "
+        "Rebuild the project to refresh the compiled extension."
+    )
+    return RuntimeError(message.format(name=name))
+
+
+def resolve_seed(seed: int | None, rng: random.Random | None) -> int:
+    """Resolve a 64-bit seed using an optional RNG."""
+
+    if seed is not None:
+        return int(seed) & 0xFFFFFFFFFFFFFFFF
+    if rng is not None:
+        return rng.getrandbits(64)
+    return random.getrandbits(64)
+
+
+def get_rust_operation(operation_name: str) -> Callable[..., Any]:
+    """Return a callable exported by :mod:`glitchlings._zoo_rust`.
+
+    Parameters
+    ----------
+    operation_name : str
+        Name of the function to retrieve from the compiled extension.
+
+    Raises
+    ------
+    RuntimeError
+        If the operation cannot be located or is not callable.
+    """
+
+    operation = _OPERATION_CACHE.get(operation_name)
+    if operation is not None:
+        return operation
+
+    module = _get_rust_module()
+    try:
+        candidate = getattr(module, operation_name)
+    except AttributeError as exc:
+        raise _build_missing_operation_error(operation_name) from exc
+
+    if not callable(candidate):
+        raise _build_missing_operation_error(operation_name)
+
+    operation = cast(Callable[..., Any], candidate)
+    _OPERATION_CACHE[operation_name] = operation
+    return operation
+
+
+def preload_operations(*operation_names: str) -> Mapping[str, Callable[..., Any]]:
+    """Eagerly load multiple Rust operations at once."""
+
+    return {name: get_rust_operation(name) for name in operation_names}
+
+
+__all__ = [
+    "RustExtensionImportError",
+    "get_rust_operation",
+    "load_rust_module",
+    "preload_operations",
+    "resolve_seed",
+]

glitchlings/internal/rust_ffi.py

@@ -0,0 +1,432 @@
+"""Centralized Rust FFI operations module.
+
+This module is the **single entry point** for all Rust FFI calls in the codebase.
+All glitchling transformations that delegate to Rust must go through this module.
+
+**Design Philosophy:**
+
+This module is explicitly *impure* - it loads and invokes compiled Rust functions
+which are stateful operations. By centralizing all FFI here:
+
+1. Pure modules (validation.py, transforms.py, rng.py) never import Rust
+2. The Rust dependency is explicit and traceable
+3. Testing can mock this module to verify Python-only paths
+4. Side effects from FFI are isolated to one location
+
+**Usage Pattern:**
+
+    # In a glitchling module (e.g., typogre.py)
+    from glitchlings.internal.rust_ffi import fatfinger_rust
+
+    def fatfinger(text: str, rate: float, ...) -> str:
+        # ... validation and setup ...
+        return fatfinger_rust(text, rate, layout, seed)
+
+See AGENTS.md "Functional Purity Architecture" for full details.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Mapping, Sequence, cast
+
+from .rust import get_rust_operation, resolve_seed
+
+# Re-export resolve_seed for backward compatibility
+__all__ = [
+    # Seed resolution (re-exported from rust.py)
+    "resolve_seed",
+    # Orchestration operations
+    "plan_glitchlings_rust",
+    "compose_glitchlings_rust",
+    # Character-level operations
+    "fatfinger_rust",
+    "slip_modifier_rust",
+    "mim1c_rust",
+    "ocr_artifacts_rust",
+    "inject_zero_widths_rust",
+    "hokey_rust",
+    # Word-level operations
+    "delete_random_words_rust",
+    "reduplicate_words_rust",
+    "swap_adjacent_words_rust",
+    "redact_words_rust",
+    "jargoyle_drift_rust",
+    "list_lexeme_dictionaries_rust",
+    "ekkokin_homophones_rust",
+    # Grammar operations
+    "pedant_rust",
+]
+
+
+# ---------------------------------------------------------------------------
+# Type Aliases
+# ---------------------------------------------------------------------------
+
+# Orchestration types
+PlanResult = list[tuple[int, int]]
+PipelineDescriptor = Mapping[str, Any]
+
+
+# ---------------------------------------------------------------------------
+# Orchestration Operations
+# ---------------------------------------------------------------------------
+
+
+def plan_glitchlings_rust(
+    specs: Sequence[Mapping[str, Any]],
+    master_seed: int,
+) -> PlanResult:
+    """Invoke Rust orchestration planner.
+
+    Args:
+        specs: Sequence of glitchling specifications with name/scope/order.
+        master_seed: Master seed for deterministic ordering.
+
+    Returns:
+        List of (index, derived_seed) tuples defining execution order.
+    """
+    plan_fn = get_rust_operation("plan_glitchlings")
+    plan = plan_fn(specs, int(master_seed))
+    return [(int(index), int(seed)) for index, seed in plan]
+
+
+def compose_glitchlings_rust(
+    text: str,
+    descriptors: Sequence[PipelineDescriptor],
+    master_seed: int,
+) -> str:
+    """Execute a sequence of glitchlings through the Rust pipeline.
+
+    Args:
+        text: Input text to transform.
+        descriptors: Pipeline descriptors for each glitchling.
+        master_seed: Master seed for determinism.
+
+    Returns:
+        Transformed text.
+    """
+    compose_fn = get_rust_operation("compose_glitchlings")
+    return cast(str, compose_fn(text, descriptors, int(master_seed)))
+
+
+# ---------------------------------------------------------------------------
+# Character-Level Operations
+# ---------------------------------------------------------------------------
+
+
+def fatfinger_rust(
+    text: str,
+    rate: float,
+    layout: Mapping[str, Sequence[str]],
+    seed: int,
+    *,
+    shift_slip_rate: float | None = None,
+    shift_slip_exit_rate: float | None = None,
+    shift_map: Mapping[str, str] | None = None,
+) -> str:
+    """Introduce keyboard typos via Rust.
+
+    Args:
+        text: Input text.
+        rate: Probability of corrupting each character.
+        layout: Keyboard neighbor mapping.
+        seed: Deterministic seed.
+        shift_slip_rate: Probability of entering a shifted burst before fat-fingering.
+        shift_slip_exit_rate: Probability of releasing shift during a burst.
+        shift_map: Mapping of unshifted -> shifted keys for the active layout.
+
+    Returns:
+        Text with simulated typing errors.
+    """
+    fn = get_rust_operation("fatfinger")
+    return cast(
+        str,
+        fn(text, rate, layout, seed, shift_slip_rate, shift_slip_exit_rate, shift_map),
+    )
+
+
+def slip_modifier_rust(
+    text: str,
+    enter_rate: float,
+    exit_rate: float,
+    shift_map: Mapping[str, str],
+    seed: int | None,
+) -> str:
+    """Apply a modifier slippage burst using Rust.
+
+    Args:
+        text: Input text.
+        enter_rate: Probability of starting a shift burst.
+        exit_rate: Probability of ending a burst once started.
+        shift_map: Mapping of unshifted -> shifted characters.
+        seed: Deterministic seed.
+
+    Returns:
+        Text with modifier slippage applied.
+    """
+    fn = get_rust_operation("slip_modifier")
+    return cast(str, fn(text, enter_rate, exit_rate, shift_map, seed))
+
+
+def mim1c_rust(
+    text: str,
+    rate: float,
+    classes: list[str] | Literal["all"] | None,
+    banned: list[str] | None,
+    seed: int,
+) -> str:
+    """Replace characters with homoglyphs via Rust.
+
+    Args:
+        text: Input text.
+        rate: Probability of swapping each character.
+        classes: Homoglyph classes to use, or "all".
+        banned: Characters to never replace with.
+        seed: Deterministic seed.
+
+    Returns:
+        Text with homoglyph substitutions.
+    """
+    fn = get_rust_operation("mim1c")
+    return cast(str, fn(text, rate, classes, banned, seed))
+
+
+def ocr_artifacts_rust(
+    text: str,
+    rate: float,
+    seed: int,
+) -> str:
+    """Introduce OCR-like artifacts via Rust.
+
+    Args:
+        text: Input text.
+        rate: Probability of introducing artifacts.
+        seed: Deterministic seed.
+
+    Returns:
+        Text with simulated OCR errors.
+    """
+    fn = get_rust_operation("ocr_artifacts")
+    return cast(str, fn(text, rate, seed))
+
+
+def inject_zero_widths_rust(
+    text: str,
+    rate: float,
+    characters: list[str],
+    seed: int | None,
+) -> str:
+    """Inject zero-width characters via Rust.
+
+    Args:
+        text: Input text.
+        rate: Probability of injection between characters.
+        characters: Palette of zero-width characters to use.
+        seed: Deterministic seed.
+
+    Returns:
+        Text with injected zero-width characters.
+    """
+    fn = get_rust_operation("inject_zero_widths")
+    return cast(str, fn(text, rate, characters, seed))
+
+
+def hokey_rust(
+    text: str,
+    rate: float,
+    extension_min: int,
+    extension_max: int,
+    word_length_threshold: int,
+    base_p: float,
+    seed: int | None,
+) -> str:
+    """Extend expressive segments via Rust.
+
+    Args:
+        text: Input text.
+        rate: Selection rate for candidate words.
+        extension_min: Minimum extra repetitions.
+        extension_max: Maximum extra repetitions.
+        word_length_threshold: Preferred max word length.
+        base_p: Base probability for sampler.
+        seed: Deterministic seed.
+
+    Returns:
+        Text with extended expressive segments.
+    """
+    fn = get_rust_operation("hokey")
+    return cast(
+        str,
+        fn(text, rate, extension_min, extension_max, word_length_threshold, base_p, seed),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Word-Level Operations
+# ---------------------------------------------------------------------------
+
+
+def delete_random_words_rust(
+    text: str,
+    rate: float,
+    unweighted: bool,
+    seed: int,
+) -> str:
+    """Delete random words via Rust.
+
+    Args:
+        text: Input text.
+        rate: Probability of deleting each word.
+        unweighted: If True, use uniform selection; else weight by length.
+        seed: Deterministic seed.
+
+    Returns:
+        Text with words deleted.
+    """
+    fn = get_rust_operation("delete_random_words")
+    return cast(str, fn(text, rate, unweighted, seed))
+
+
+def reduplicate_words_rust(
+    text: str,
+    rate: float,
+    unweighted: bool,
+    seed: int,
+) -> str:
+    """Reduplicate random words via Rust.
+
+    Args:
+        text: Input text.
+        rate: Probability of duplicating each word.
+        unweighted: If True, use uniform selection; else weight by length.
+        seed: Deterministic seed.
+
+    Returns:
+        Text with words duplicated.
+    """
+    fn = get_rust_operation("reduplicate_words")
+    return cast(str, fn(text, rate, unweighted, seed))
+
+
+def swap_adjacent_words_rust(
+    text: str,
+    rate: float,
+    seed: int,
+) -> str:
+    """Swap adjacent words via Rust.
+
+    Args:
+        text: Input text.
+        rate: Probability of swapping adjacent word pairs.
+        seed: Deterministic seed.
+
+    Returns:
+        Text with adjacent words swapped.
+    """
+    fn = get_rust_operation("swap_adjacent_words")
+    return cast(str, fn(text, rate, seed))
+
+
+def redact_words_rust(
+    text: str,
+    replacement: str,
+    rate: float,
+    merge: bool,
+    unweighted: bool,
+    seed: int,
+) -> str:
+    """Redact random words via Rust.
+
+    Args:
+        text: Input text.
+        replacement: Character to replace word characters with.
+        rate: Probability of redacting each word.
+        merge: If True, merge adjacent redactions.
+        unweighted: If True, use uniform selection; else weight by length.
+        seed: Deterministic seed.
+
+    Returns:
+        Text with words redacted.
+    """
+    fn = get_rust_operation("redact_words")
+    return cast(str, fn(text, replacement, rate, merge, unweighted, seed))
+
+
+def jargoyle_drift_rust(
+    text: str,
+    lexemes: str,
+    mode: str,
+    rate: float,
+    seed: int | None,
+) -> str:
+    """Apply Jargoyle dictionary-based word drift via Rust.
+
+    Args:
+        text: Input text.
+        lexemes: Name of the dictionary to use (colors, synonyms, corporate, academic, cyberpunk,
+            lovecraftian, or any custom dictionary discovered in the lexemes directory).
+        mode: Drift mode ("literal" or "drift").
+        rate: Probability of transforming each matching word.
+        seed: Deterministic seed (only used for "drift" mode).
+
+    Returns:
+        Text with word substitutions applied.
+    """
+    fn = get_rust_operation("jargoyle_drift")
+    return cast(str, fn(text, lexemes, mode, rate, seed))
+
+
+def list_lexeme_dictionaries_rust() -> list[str]:
+    """List available lexeme dictionaries.
+
+    Returns:
+        List of dictionary names available for Jargoyle.
+    """
+    fn = get_rust_operation("list_lexeme_dictionaries")
+    return cast(list[str], fn())
+
+
+def ekkokin_homophones_rust(
+    text: str,
+    rate: float,
+    weighting: str,
+    seed: int | None,
+) -> str:
+    """Substitute words with homophones via Rust.
+
+    Args:
+        text: Input text.
+        rate: Probability of substituting each word.
+        weighting: Weighting mode for selection.
+        seed: Deterministic seed.
+
+    Returns:
+        Text with homophone substitutions.
+    """
+    fn = get_rust_operation("ekkokin_homophones")
+    return cast(str, fn(text, rate, weighting, seed))
+
+
+# ---------------------------------------------------------------------------
+# Grammar Operations
+# ---------------------------------------------------------------------------
+
+
+def pedant_rust(
+    text: str,
+    *,
+    stone: str,
+    seed: int,
+) -> str:
+    """Apply pedant grammar transformation via Rust.
+
+    Args:
+        text: Input text.
+        stone: Pedant stone label defining transformation type.
+        seed: Deterministic seed.
+
+    Returns:
+        Text with grammar transformation applied.
+    """
+    fn = get_rust_operation("pedant")
+    return cast(str, fn(text, stone=stone, seed=seed))