glitchlings 0.4.4__cp313-cp313-manylinux_2_28_x86_64.whl

glitchlings/util/__init__.py

@@ -0,0 +1,195 @@
+import difflib
+from collections.abc import Iterable
+
+__all__ = [
+    "SAMPLE_TEXT",
+    "string_diffs",
+    "KeyNeighborMap",
+    "KeyboardLayouts",
+    "KeyNeighbors",
+    "KEYNEIGHBORS",
+]
+
+SAMPLE_TEXT = (
+    "One morning, when Gregor Samsa woke from troubled dreams, he found himself "
+    "transformed in his bed into a horrible vermin. He lay on his armour-like back, and "
+    "if he lifted his head a little he could see his brown belly, slightly domed and "
+    "divided by arches into stiff sections. The bedding was hardly able to cover it and "
+    "seemed ready to slide off any moment. His many legs, pitifully thin compared with "
+    "the size of the rest of him, waved about helplessly as he looked."
+)
+
+
+def string_diffs(a: str, b: str) -> list[list[tuple[str, str, str]]]:
+    """Compare two strings using SequenceMatcher and return
+    grouped adjacent opcodes (excluding 'equal' tags).
+
+    Each element is a tuple: (tag, a_text, b_text).
+    """
+    sm = difflib.SequenceMatcher(None, a, b)
+    ops: list[list[tuple[str, str, str]]] = []
+    buffer: list[tuple[str, str, str]] = []
+
+    for tag, i1, i2, j1, j2 in sm.get_opcodes():
+        if tag == "equal":
+            # flush any buffered operations before skipping
+            if buffer:
+                ops.append(buffer)
+                buffer = []
+            continue
+
+        # append operation to buffer
+        buffer.append((tag, a[i1:i2], b[j1:j2]))
+
+    # flush trailing buffer
+    if buffer:
+        ops.append(buffer)
+
+    return ops
+
+
+KeyNeighborMap = dict[str, list[str]]
+KeyboardLayouts = dict[str, KeyNeighborMap]
+
+
+def _build_neighbor_map(rows: Iterable[str]) -> KeyNeighborMap:
+    """Derive 8-neighbour adjacency lists from keyboard layout rows."""
+    grid: dict[tuple[int, int], str] = {}
+    for y, row in enumerate(rows):
+        for x, char in enumerate(row):
+            if char == " ":
+                continue
+            grid[(x, y)] = char.lower()
+
+    neighbors: KeyNeighborMap = {}
+    for (x, y), char in grid.items():
+        seen: list[str] = []
+        for dy in (-1, 0, 1):
+            for dx in (-1, 0, 1):
+                if dx == 0 and dy == 0:
+                    continue
+                candidate = grid.get((x + dx, y + dy))
+                if candidate is None:
+                    continue
+                seen.append(candidate)
+        # Preserve encounter order but drop duplicates for determinism
+        deduped = list(dict.fromkeys(seen))
+        neighbors[char] = deduped
+
+    return neighbors
+
+
+_KEYNEIGHBORS: KeyboardLayouts = {
+    "CURATOR_QWERTY": {
+        "a": [*"qwsz"],
+        "b": [*"vghn  "],
+        "c": [*"xdfv  "],
+        "d": [*"serfcx"],
+        "e": [*"wsdrf34"],
+        "f": [*"drtgvc"],
+        "g": [*"ftyhbv"],
+        "h": [*"gyujnb"],
+        "i": [*"ujko89"],
+        "j": [*"huikmn"],
+        "k": [*"jilom,"],
+        "l": [*"kop;.,"],
+        "m": [*"njk,  "],
+        "n": [*"bhjm  "],
+        "o": [*"iklp90"],
+        "p": [*"o0-[;l"],
+        "q": [*"was 12"],
+        "r": [*"edft45"],
+        "s": [*"awedxz"],
+        "t": [*"r56ygf"],
+        "u": [*"y78ijh"],
+        "v": [*"cfgb  "],
+        "w": [*"q23esa"],
+        "x": [*"zsdc  "],
+        "y": [*"t67uhg"],
+        "z": [*"asx"],
+    }
+}
+
+
+def _register_layout(name: str, rows: Iterable[str]) -> None:
+    _KEYNEIGHBORS[name] = _build_neighbor_map(rows)
+
+
+_register_layout(
+    "DVORAK",
+    (
+        "`1234567890[]\\",
+        " ',.pyfgcrl/=\\",
+        "  aoeuidhtns-",
+        "   ;qjkxbmwvz",
+    ),
+)
+
+_register_layout(
+    "COLEMAK",
+    (
+        "`1234567890-=",
+        " qwfpgjluy;[]\\",
+        "  arstdhneio'",
+        "   zxcvbkm,./",
+    ),
+)
+
+_register_layout(
+    "QWERTY",
+    (
+        "`1234567890-=",
+        " qwertyuiop[]\\",
+        "  asdfghjkl;'",
+        "   zxcvbnm,./",
+    ),
+)
+
+_register_layout(
+    "AZERTY",
+    (
+        "²&é\"'(-è_çà)=",
+        " azertyuiop^$",
+        "  qsdfghjklmù*",
+        "   <wxcvbn,;:!",
+    ),
+)
+
+_register_layout(
+    "QWERTZ",
+    (
+        "^1234567890ß´",
+        " qwertzuiopü+",
+        "  asdfghjklöä#",
+        "   yxcvbnm,.-",
+    ),
+)
+
+_register_layout(
+    "SPANISH_QWERTY",
+    (
+        "º1234567890'¡",
+        " qwertyuiop´+",
+        "  asdfghjklñ´",
+        "   <zxcvbnm,.-",
+    ),
+)
+
+_register_layout(
+    "SWEDISH_QWERTY",
+    (
+        "§1234567890+´",
+        " qwertyuiopå¨",
+        "  asdfghjklöä'",
+        "   <zxcvbnm,.-",
+    ),
+)
+
+
+class KeyNeighbors:
+    def __init__(self) -> None:
+        for layout_name, layout in _KEYNEIGHBORS.items():
+            setattr(self, layout_name, layout)
+
+
+KEYNEIGHBORS: KeyNeighbors = KeyNeighbors()

glitchlings/util/adapters.py

@@ -0,0 +1,27 @@
+"""Adapter helpers shared across Python and DLC integrations."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from ..zoo import Gaggle, Glitchling, summon
+
+
+def coerce_gaggle(
+    glitchlings: Glitchling | Gaggle | str | Iterable[str | Glitchling],
+    *,
+    seed: int,
+) -> Gaggle:
+    """Return a :class:`Gaggle` built from any supported glitchling specifier."""
+    if isinstance(glitchlings, Gaggle):
+        return glitchlings
+
+    if isinstance(glitchlings, (Glitchling, str)):
+        resolved: Iterable[str | Glitchling] = [glitchlings]
+    else:
+        resolved = glitchlings
+
+    return summon(list(resolved), seed=seed)
+
+
+__all__ = ["coerce_gaggle"]

glitchlings/zoo/__init__.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import ast
+from typing import Any
+
+from .adjax import Adjax, adjax
+from .apostrofae import Apostrofae, apostrofae
+from .core import (
+    Gaggle,
+    Glitchling,
+    is_rust_pipeline_enabled,
+    is_rust_pipeline_supported,
+    pipeline_feature_flag_enabled,
+    plan_glitchling_specs,
+    plan_glitchlings,
+)
+from .jargoyle import Jargoyle, jargoyle
+from .jargoyle import dependencies_available as _jargoyle_available
+from .mim1c import Mim1c, mim1c
+from .redactyl import Redactyl, redactyl
+from .reduple import Reduple, reduple
+from .rushmore import Rushmore, rushmore
+from .scannequin import Scannequin, scannequin
+from .typogre import Typogre, typogre
+from .zeedub import Zeedub, zeedub
+
+__all__ = [
+    "Typogre",
+    "typogre",
+    "Mim1c",
+    "mim1c",
+    "Jargoyle",
+    "jargoyle",
+    "Apostrofae",
+    "apostrofae",
+    "Adjax",
+    "adjax",
+    "Reduple",
+    "reduple",
+    "Rushmore",
+    "rushmore",
+    "Redactyl",
+    "redactyl",
+    "Scannequin",
+    "scannequin",
+    "Zeedub",
+    "zeedub",
+    "Glitchling",
+    "Gaggle",
+    "plan_glitchlings",
+    "plan_glitchling_specs",
+    "is_rust_pipeline_enabled",
+    "is_rust_pipeline_supported",
+    "pipeline_feature_flag_enabled",
+    "summon",
+    "BUILTIN_GLITCHLINGS",
+    "DEFAULT_GLITCHLING_NAMES",
+    "parse_glitchling_spec",
+    "get_glitchling_class",
+]
+
+_HAS_JARGOYLE = _jargoyle_available()
+
+_BUILTIN_GLITCHLING_LIST: list[Glitchling] = [typogre, apostrofae, mim1c]
+if _HAS_JARGOYLE:
+    _BUILTIN_GLITCHLING_LIST.append(jargoyle)
+_BUILTIN_GLITCHLING_LIST.extend([adjax, reduple, rushmore, redactyl, scannequin, zeedub])
+
+BUILTIN_GLITCHLINGS: dict[str, Glitchling] = {
+    glitchling.name.lower(): glitchling for glitchling in _BUILTIN_GLITCHLING_LIST
+}
+
+_BUILTIN_GLITCHLING_TYPES: dict[str, type[Glitchling]] = {
+    typogre.name.lower(): Typogre,
+    apostrofae.name.lower(): Apostrofae,
+    mim1c.name.lower(): Mim1c,
+    adjax.name.lower(): Adjax,
+    reduple.name.lower(): Reduple,
+    rushmore.name.lower(): Rushmore,
+    redactyl.name.lower(): Redactyl,
+    scannequin.name.lower(): Scannequin,
+    zeedub.name.lower(): Zeedub,
+}
+if _HAS_JARGOYLE:
+    _BUILTIN_GLITCHLING_TYPES[jargoyle.name.lower()] = Jargoyle
+
+DEFAULT_GLITCHLING_NAMES: list[str] = list(BUILTIN_GLITCHLINGS.keys())
+
+
+def parse_glitchling_spec(specification: str) -> Glitchling:
+    """Return a glitchling instance configured according to ``specification``."""
+    text = specification.strip()
+    if not text:
+        raise ValueError("Glitchling specification cannot be empty.")
+
+    if "(" not in text:
+        glitchling = BUILTIN_GLITCHLINGS.get(text.lower())
+        if glitchling is None:
+            raise ValueError(f"Glitchling '{text}' not found.")
+        return glitchling
+
+    if not text.endswith(")"):
+        raise ValueError(f"Invalid parameter syntax for glitchling '{text}'.")
+
+    name_part, arg_source = text[:-1].split("(", 1)
+    name = name_part.strip()
+    if not name:
+        raise ValueError(f"Invalid glitchling specification '{text}'.")
+
+    lower_name = name.lower()
+    glitchling_type = _BUILTIN_GLITCHLING_TYPES.get(lower_name)
+    if glitchling_type is None:
+        raise ValueError(f"Glitchling '{name}' not found.")
+
+    try:
+        call_expr = ast.parse(f"_({arg_source})", mode="eval").body
+    except SyntaxError as exc:
+        raise ValueError(f"Invalid parameter syntax for glitchling '{name}': {exc.msg}") from exc
+
+    if not isinstance(call_expr, ast.Call) or call_expr.args:
+        raise ValueError(f"Glitchling '{name}' parameters must be provided as keyword arguments.")
+
+    kwargs: dict[str, Any] = {}
+    for keyword in call_expr.keywords:
+        if keyword.arg is None:
+            raise ValueError(
+                f"Glitchling '{name}' does not support unpacking arbitrary keyword arguments."
+            )
+        try:
+            kwargs[keyword.arg] = ast.literal_eval(keyword.value)
+        except (ValueError, SyntaxError) as exc:
+            raise ValueError(
+                f"Failed to parse value for parameter '{keyword.arg}' on glitchling '{name}': {exc}"
+            ) from exc
+
+    try:
+        return glitchling_type(**kwargs)
+    except TypeError as exc:
+        raise ValueError(f"Failed to instantiate glitchling '{name}': {exc}") from exc
+
+
+def get_glitchling_class(name: str) -> type[Glitchling]:
+    """Look up the glitchling class registered under ``name``."""
+    key = name.strip().lower()
+    if not key:
+        raise ValueError("Glitchling name cannot be empty.")
+
+    glitchling_type = _BUILTIN_GLITCHLING_TYPES.get(key)
+    if glitchling_type is None:
+        raise ValueError(f"Glitchling '{name}' not found.")
+
+    return glitchling_type
+
+
+def summon(glitchlings: list[str | Glitchling], seed: int = 151) -> Gaggle:
+    """Summon glitchlings by name (using defaults) or instance (to change parameters)."""
+    summoned: list[Glitchling] = []
+    for entry in glitchlings:
+        if isinstance(entry, Glitchling):
+            summoned.append(entry)
+            continue
+
+        try:
+            summoned.append(parse_glitchling_spec(entry))
+        except ValueError as exc:
+            raise ValueError(str(exc)) from exc
+
+    return Gaggle(summoned, seed=seed)

glitchlings/zoo/_ocr_confusions.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from importlib import resources
+
+_CONFUSION_TABLE: list[tuple[str, list[str]]] | None = None
+
+
+def load_confusion_table() -> list[tuple[str, list[str]]]:
+    """Load the OCR confusion table shared by Python and Rust implementations."""
+    global _CONFUSION_TABLE
+    if _CONFUSION_TABLE is not None:
+        return _CONFUSION_TABLE
+
+    data = resources.files(__package__) / "ocr_confusions.tsv"
+    text = data.read_text(encoding="utf-8")
+    indexed_entries: list[tuple[int, tuple[str, list[str]]]] = []
+    for line_number, line in enumerate(text.splitlines()):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        parts = stripped.split()
+        if len(parts) < 2:
+            continue
+        source, *replacements = parts
+        indexed_entries.append((line_number, (source, replacements)))
+
+    # Sort longer patterns first to avoid overlapping matches, mirroring the
+    # behaviour of the Rust `confusion_table` helper.
+    indexed_entries.sort(key=lambda item: (-len(item[1][0]), item[0]))
+    entries = [entry for _, entry in indexed_entries]
+    _CONFUSION_TABLE = entries
+    return entries

glitchlings/zoo/_rate.py

@@ -0,0 +1,131 @@
+"""Utilities for handling legacy parameter names across glitchling classes."""
+
+from __future__ import annotations
+
+import warnings
+
+
+def resolve_rate(
+    *,
+    rate: float | None,
+    legacy_value: float | None,
+    default: float,
+    legacy_name: str,
+) -> float:
+    """Return the effective rate while enforcing mutual exclusivity.
+
+    This function centralizes the handling of legacy parameter names, allowing
+    glitchlings to maintain backwards compatibility while encouraging migration
+    to the standardized 'rate' parameter.
+
+    Parameters
+    ----------
+    rate : float | None
+        The preferred parameter value.
+    legacy_value : float | None
+        The deprecated legacy parameter value.
+    default : float
+        Default value if neither parameter is specified.
+    legacy_name : str
+        Name of the legacy parameter for error/warning messages.
+
+    Returns
+    -------
+    float
+        The resolved rate value.
+
+    Raises
+    ------
+    ValueError
+        If both rate and legacy_value are specified simultaneously.
+
+    Warnings
+    --------
+    DeprecationWarning
+        If the legacy parameter is used, a deprecation warning is issued.
+
+    Examples
+    --------
+    >>> resolve_rate(rate=0.5, legacy_value=None, default=0.1, legacy_name="old_rate")
+    0.5
+    >>> resolve_rate(rate=None, legacy_value=0.3, default=0.1, legacy_name="old_rate")
+    0.3  # Issues deprecation warning
+    >>> resolve_rate(rate=None, legacy_value=None, default=0.1, legacy_name="old_rate")
+    0.1
+
+    """
+    if rate is not None and legacy_value is not None:
+        raise ValueError(f"Specify either 'rate' or '{legacy_name}', not both.")
+
+    if rate is not None:
+        return rate
+
+    if legacy_value is not None:
+        warnings.warn(
+            f"The '{legacy_name}' parameter is deprecated and will be removed in version 0.6.0. "
+            f"Use 'rate' instead.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        return legacy_value
+
+    return default
+
+
+def resolve_legacy_param(
+    *,
+    preferred_value: object,
+    legacy_value: object,
+    default: object,
+    preferred_name: str,
+    legacy_name: str,
+) -> object:
+    """Resolve a parameter that has both preferred and legacy names.
+
+    This is a generalized version of resolve_rate() that works with any type.
+
+    Parameters
+    ----------
+    preferred_value : object
+        The value from the preferred parameter name.
+    legacy_value : object
+        The value from the legacy parameter name.
+    default : object
+        Default value if neither parameter is specified.
+    preferred_name : str
+        Name of the preferred parameter.
+    legacy_name : str
+        Name of the legacy parameter for warning messages.
+
+    Returns
+    -------
+    object
+        The resolved parameter value.
+
+    Raises
+    ------
+    ValueError
+        If both preferred and legacy values are specified simultaneously.
+
+    Warnings
+    --------
+    DeprecationWarning
+        If the legacy parameter is used.
+
+    """
+    if preferred_value is not None and legacy_value is not None:
+        raise ValueError(f"Specify either '{preferred_name}' or '{legacy_name}', not both.")
+
+    if preferred_value is not None:
+        return preferred_value
+
+    if legacy_value is not None:
+        warnings.warn(
+            f"The '{legacy_name}' parameter is deprecated and will be removed in version 0.6.0. "
+            f"Use '{preferred_name}' instead.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        return legacy_value
+
+    return default

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",
+]