glitchlings 0.4.5__cp311-cp311-win_amd64.whl

glitchlings/zoo/_rust_extensions.py

@@ -0,0 +1,143 @@
+"""Centralized loading and fallback management for optional Rust extensions.
+
+This module provides a single source of truth for importing Rust-accelerated
+operations, eliminating duplicated try/except blocks across the codebase.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable
+
+log = logging.getLogger(__name__)
+
+
+# Cache of loaded Rust operations to avoid repeated import attempts
+_rust_operation_cache: dict[str, Callable[..., Any] | None] = {}
+_rust_module_available: bool | None = None
+
+
+def is_rust_module_available() -> bool:
+    """Check if the Rust extension module can be imported.
+
+    Returns
+    -------
+    bool
+        True if glitchlings._zoo_rust can be imported successfully.
+
+    Notes
+    -----
+    The result is cached after the first check to avoid repeated import attempts.
+    """
+    global _rust_module_available
+
+    if _rust_module_available is not None:
+        return _rust_module_available
+
+    try:
+        import glitchlings._zoo_rust  # noqa: F401
+
+        _rust_module_available = True
+        log.debug("Rust extension module successfully loaded")
+    except (ImportError, ModuleNotFoundError):
+        _rust_module_available = False
+        log.debug("Rust extension module not available; using Python fallbacks")
+
+    return _rust_module_available
+
+
+def get_rust_operation(operation_name: str) -> Callable[..., Any] | None:
+    """Load a specific Rust operation by name with caching.
+
+    Parameters
+    ----------
+    operation_name : str
+        The name of the operation to import from glitchlings._zoo_rust.
+
+    Returns
+    -------
+    Callable | None
+        The Rust operation callable if available, None otherwise.
+
+    Examples
+    --------
+    >>> fatfinger = get_rust_operation("fatfinger")
+    >>> if fatfinger is not None:
+    ...     result = fatfinger(text, ...)
+    ... else:
+    ...     result = python_fallback(text, ...)
+
+    Notes
+    -----
+    - Results are cached to avoid repeated imports
+    - Returns None if the Rust module is unavailable or the operation doesn't exist
+    - All import errors are logged at debug level
+    """
+    # Check cache first
+    if operation_name in _rust_operation_cache:
+        return _rust_operation_cache[operation_name]
+
+    # If the module isn't available, don't try to import individual operations
+    if not is_rust_module_available():
+        _rust_operation_cache[operation_name] = None
+        return None
+
+    try:
+        from glitchlings import _zoo_rust
+
+        operation = getattr(_zoo_rust, operation_name, None)
+        _rust_operation_cache[operation_name] = operation
+
+        if operation is None:
+            log.debug(f"Rust operation '{operation_name}' not found in extension module")
+        else:
+            log.debug(f"Rust operation '{operation_name}' loaded successfully")
+
+        return operation
+
+    except (ImportError, ModuleNotFoundError, AttributeError) as exc:
+        log.debug(f"Failed to load Rust operation '{operation_name}': {exc}")
+        _rust_operation_cache[operation_name] = None
+        return None
+
+
+def clear_cache() -> None:
+    """Clear the operation cache, forcing re-import on next access.
+
+    This is primarily useful for testing scenarios where the Rust module
+    availability might change during runtime.
+    """
+    global _rust_module_available, _rust_operation_cache
+
+    _rust_module_available = None
+    _rust_operation_cache.clear()
+    log.debug("Rust extension cache cleared")
+
+
+def preload_operations(*operation_names: str) -> dict[str, Callable[..., Any] | None]:
+    """Eagerly load multiple Rust operations at once.
+
+    Parameters
+    ----------
+    *operation_names : str
+        Names of operations to preload.
+
+    Returns
+    -------
+    dict[str, Callable | None]
+        Mapping of operation names to their callables (or None if unavailable).
+
+    Examples
+    --------
+    >>> ops = preload_operations("fatfinger", "reduplicate_words", "delete_random_words")
+    >>> fatfinger = ops["fatfinger"]
+    """
+    return {name: get_rust_operation(name) for name in operation_names}
+
+
+__all__ = [
+    "is_rust_module_available",
+    "get_rust_operation",
+    "clear_cache",
+    "preload_operations",
+]

glitchlings/zoo/_sampling.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import random
+from typing import Sequence
+
+
+def weighted_sample_without_replacement(
+    population: Sequence[int],
+    weights: Sequence[float],
+    *,
+    k: int,
+    rng: random.Random,
+) -> list[int]:
+    """Sample ``k`` unique indices from ``population`` using ``weights``.
+
+    Mirrors the behaviour used by several glitchlings while centralising error
+    handling and RNG interactions so the Python and Rust implementations remain
+    aligned.
+    """
+    if k < 0:
+        raise ValueError("Sample size cannot be negative")
+
+    if len(population) != len(weights):
+        raise ValueError("Population and weight sequences must be the same length")
+
+    items = list(zip(population, weights))
+    count = len(items)
+    if k == 0 or count == 0:
+        return []
+
+    if k > count:
+        raise ValueError("Sample larger than population or is negative")
+
+    selections: list[int] = []
+    for _ in range(k):
+        total_weight = sum(weight for _, weight in items)
+        if total_weight <= 0.0:
+            chosen_index = rng.randrange(len(items))
+        else:
+            threshold = rng.random() * total_weight
+            cumulative = 0.0
+            chosen_index = len(items) - 1
+            for idx, (_, weight) in enumerate(items):
+                cumulative += weight
+                if cumulative >= threshold:
+                    chosen_index = idx
+                    break
+        value, _ = items.pop(chosen_index)
+        selections.append(value)
+
+    return selections
+
+
+__all__ = ["weighted_sample_without_replacement"]

glitchlings/zoo/_text_utils.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Sequence
+
+_WORD_SPLIT_PATTERN = re.compile(r"(\s+)")
+_TOKEN_EDGES_PATTERN = re.compile(r"^(\W*)(.*?)(\W*)$")
+
+
+def split_preserving_whitespace(text: str) -> list[str]:
+    """Split text while keeping whitespace tokens for stable reconstruction."""
+    return _WORD_SPLIT_PATTERN.split(text)
+
+
+def split_token_edges(token: str) -> tuple[str, str, str]:
+    """Return leading, core, and trailing segments for a token."""
+    match = _TOKEN_EDGES_PATTERN.match(token)
+    if match is None:
+        return "", token, ""
+    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)
+    candidate = core if core else token
+    length = len(candidate)
+    if length <= 0:
+        stripped = token.strip()
+        length = len(stripped) if stripped else len(token)
+    if length <= 0:
+        length = 1
+    return length
+
+
+@dataclass(frozen=True)
+class WordToken:
+    """Metadata describing a non-whitespace token yielded by word splitters."""
+
+    index: int
+    prefix: str
+    core: str
+    suffix: str
+    core_length: int
+
+    @property
+    def has_core(self) -> bool:
+        """Return ``True`` when the token contains at least one core character."""
+        return bool(self.core)
+
+
+def collect_word_tokens(
+    tokens: Sequence[str],
+    *,
+    skip_first_word: bool = False,
+) -> list[WordToken]:
+    """Return structured metadata for non-whitespace tokens within ``tokens``.
+
+    Args:
+        tokens: Token sequence produced by :func:`split_preserving_whitespace`.
+        skip_first_word: Exclude the first candidate token (used by Rushmore to
+            preserve leading words).
+
+    """
+    start = 2 if skip_first_word else 0
+    collected: list[WordToken] = []
+    for index in range(start, len(tokens), 2):
+        token = tokens[index]
+        if not token or token.isspace():
+            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
+
+        collected.append(
+            WordToken(
+                index=index,
+                prefix=prefix,
+                core=core,
+                suffix=suffix,
+                core_length=core_length,
+            )
+        )
+
+    return collected
+
+
+__all__ = [
+    "split_preserving_whitespace",
+    "split_token_edges",
+    "token_core_length",
+    "WordToken",
+    "collect_word_tokens",
+]

glitchlings/zoo/adjax.py

@@ -0,0 +1,128 @@
+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
+
+# Load Rust-accelerated operation if available
+_swap_adjacent_words_rust = get_rust_operation("swap_adjacent_words")
+
+
+def _python_swap_adjacent_words(
+    text: str,
+    *,
+    rate: float,
+    rng: random.Random,
+) -> str:
+    """Swap the cores of adjacent words while keeping affixes and spacing intact."""
+    tokens = split_preserving_whitespace(text)
+    if len(tokens) < 2:
+        return text
+
+    word_indices: list[int] = []
+    for index in range(len(tokens)):
+        token = tokens[index]
+        if not token or token.isspace():
+            continue
+        if index % 2 == 0:
+            word_indices.append(index)
+
+    if len(word_indices) < 2:
+        return text
+
+    clamped = max(0.0, min(rate, 1.0))
+    if clamped <= 0.0:
+        return text
+
+    for cursor in range(0, len(word_indices) - 1, 2):
+        left_index = word_indices[cursor]
+        right_index = word_indices[cursor + 1]
+
+        left_token = tokens[left_index]
+        right_token = tokens[right_index]
+
+        left_prefix, left_core, left_suffix = split_token_edges(left_token)
+        right_prefix, right_core, right_suffix = split_token_edges(right_token)
+
+        if not left_core or not right_core:
+            continue
+
+        should_swap = clamped >= 1.0 or rng.random() < clamped
+        if not should_swap:
+            continue
+
+        tokens[left_index] = f"{left_prefix}{right_core}{left_suffix}"
+        tokens[right_index] = f"{right_prefix}{left_core}{right_suffix}"
+
+    return "".join(tokens)
+
+
+def swap_adjacent_words(
+    text: str,
+    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",
+    )
+    clamped_rate = max(0.0, min(effective_rate, 1.0))
+
+    if rng is None:
+        rng = random.Random(seed)
+
+    if _swap_adjacent_words_rust is not None:
+        return cast(str, _swap_adjacent_words_rust(text, clamped_rate, rng))
+
+    return _python_swap_adjacent_words(text, rate=clamped_rate, rng=rng)
+
+
+class Adjax(Glitchling):
+    """Glitchling that swaps adjacent words to scramble local semantics."""
+
+    def __init__(
+        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",
+        )
+        super().__init__(
+            name="Adjax",
+            corruption_function=swap_adjacent_words,
+            scope=AttackWave.WORD,
+            seed=seed,
+            rate=effective_rate,
+        )
+
+    def pipeline_operation(self) -> dict[str, Any] | None:
+        rate = self.kwargs.get("rate")
+        if rate is None:
+            return None
+        return {
+            "type": "swap_adjacent",
+            "swap_rate": float(rate),
+        }
+
+
+adjax = Adjax()
+
+
+__all__ = ["Adjax", "adjax", "swap_adjacent_words"]

glitchlings/zoo/apostrofae.py

@@ -0,0 +1,127 @@
+"""Smart-quote glitchling that swaps straight quotes for fancy counterparts."""
+
+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 .core import AttackOrder, AttackWave, Gaggle, Glitchling
+
+# Load Rust-accelerated operation if available
+_apostrofae_rust = get_rust_operation("apostrofae")
+
+
+@cache
+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)
+
+    parsed: dict[str, list[tuple[str, str]]] = {}
+    for straight, replacements in data.items():
+        parsed[straight] = [(pair[0], pair[1]) for pair in replacements if len(pair) == 2]
+    return parsed
+
+
+def _find_quote_pairs(text: str) -> list[tuple[int, int, str]]:
+    """Return all balanced pairs of straight quotes in ``text``.
+
+    The search walks the string once, pairing sequential occurrences of each quote
+    glyph. Unmatched openers remain untouched so contractions (e.g. ``it's``)
+    survive unmodified.
+    """
+
+    stacks: dict[str, int | None] = {'"': None, "'": None, "`": None}
+    pairs: list[tuple[int, int, str]] = []
+
+    for index, ch in enumerate(text):
+        if ch not in stacks:
+            continue
+        start = stacks[ch]
+        if start is None:
+            stacks[ch] = index
+        else:
+            pairs.append((start, index, ch))
+            stacks[ch] = None
+
+    return pairs
+
+
+def _apostrofae_python(text: str, *, rng: random.Random) -> str:
+    """Python fallback that replaces paired straight quotes with fancy glyphs."""
+
+    pairs = _load_replacement_pairs()
+    candidates = _find_quote_pairs(text)
+    if not candidates:
+        return text
+
+    chars = list(text)
+    for start, end, glyph in candidates:
+        options = pairs.get(glyph)
+        if not options:
+            continue
+        left, right = rng.choice(options)
+        chars[start] = left
+        chars[end] = right
+    return "".join(chars)
+
+
+def smart_quotes(
+    text: str,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+) -> str:
+    """Replace straight quotes, apostrophes, and backticks with fancy pairs."""
+
+    if not text:
+        return text
+
+    if rng is None:
+        rng = random.Random(seed)
+
+    if _apostrofae_rust is not None:
+        return cast(str, _apostrofae_rust(text, rng))
+
+    return _apostrofae_python(text, rng=rng)
+
+
+class Apostrofae(Glitchling):
+    """Glitchling that swaps straight quotes for decorative Unicode pairs."""
+
+    def __init__(self, *, seed: int | None = None) -> None:
+        self._master_seed: int | None = seed
+        super().__init__(
+            name="Apostrofae",
+            corruption_function=smart_quotes,
+            scope=AttackWave.CHARACTER,
+            order=AttackOrder.NORMAL,
+            seed=seed,
+        )
+
+    def pipeline_operation(self) -> dict[str, Any] | None:
+        return {"type": "apostrofae"}
+
+    def reset_rng(self, seed: int | None = None) -> None:  # pragma: no cover - exercised indirectly
+        if seed is not None:
+            self._master_seed = seed
+            super().reset_rng(seed)
+            if self.seed is None:
+                return
+            derived = Gaggle.derive_seed(int(seed), self.name, 0)
+            self.seed = int(derived)
+            self.rng = random.Random(self.seed)
+            self.kwargs["seed"] = self.seed
+        else:
+            super().reset_rng(None)
+
+
+apostrofae = Apostrofae()
+
+
+__all__ = ["Apostrofae", "apostrofae", "smart_quotes"]

glitchlings/zoo/assets/apostrofae_pairs.json

@@ -0,0 +1,32 @@
+{
+  "\"": [
+    ["“", "”"],
+    ["„", "“"],
+    ["«", "»"],
+    ["‹", "›"],
+    ["『", "』"],
+    ["「", "」"],
+    ["﹁", "﹂"],
+    ["﹃", "﹄"],
+    ["〝", "〞"],
+    ["❝", "❞"]
+  ],
+  "'": [
+    ["‘", "’"],
+    ["‚", "‘"],
+    ["‹", "›"],
+    ["❮", "❯"],
+    ["❛", "❜"],
+    ["﹇", "﹈"]
+  ],
+  "`": [
+    ["‵", "′"],
+    ["﹁", "﹂"],
+    ["﹃", "﹄"],
+    ["⌈", "⌉"],
+    ["⌊", "⌋"],
+    ["⎡", "⎤"],
+    ["⎣", "⎦"],
+    ["〝", "〞"]
+  ]
+}