glitchlings 0.4.3__cp311-cp311-macosx_11_0_universal2.whl → 0.4.5__cp311-cp311-macosx_11_0_universal2.whl

glitchlings/zoo/__init__.py

@@ -14,6 +14,7 @@ from .core import (
     plan_glitchling_specs,
     plan_glitchlings,
 )
+from .hokey import Hokey, hokey
 from .jargoyle import Jargoyle, jargoyle
 from .jargoyle import dependencies_available as _jargoyle_available
 from .mim1c import Mim1c, mim1c
@@ -33,6 +34,8 @@ __all__ = [
     "jargoyle",
     "Apostrofae",
     "apostrofae",
+    "Hokey",
+    "hokey",
     "Adjax",
     "adjax",
     "Reduple",
@@ -61,7 +64,7 @@ __all__ = [
 
 _HAS_JARGOYLE = _jargoyle_available()
 
-_BUILTIN_GLITCHLING_LIST: list[Glitchling] = [typogre, apostrofae, mim1c]
+_BUILTIN_GLITCHLING_LIST: list[Glitchling] = [typogre, apostrofae, hokey, mim1c]
 if _HAS_JARGOYLE:
     _BUILTIN_GLITCHLING_LIST.append(jargoyle)
 _BUILTIN_GLITCHLING_LIST.extend([adjax, reduple, rushmore, redactyl, scannequin, zeedub])
@@ -73,6 +76,7 @@ BUILTIN_GLITCHLINGS: dict[str, Glitchling] = {
 _BUILTIN_GLITCHLING_TYPES: dict[str, type[Glitchling]] = {
     typogre.name.lower(): Typogre,
     apostrofae.name.lower(): Apostrofae,
+    hokey.name.lower(): Hokey,
     mim1c.name.lower(): Mim1c,
     adjax.name.lower(): Adjax,
     reduple.name.lower(): Reduple,

glitchlings/zoo/_rate.py

@@ -1,5 +1,9 @@
+"""Utilities for handling legacy parameter names across glitchling classes."""
+
 from __future__ import annotations
 
+import warnings
+
 
 def resolve_rate(
     *,
@@ -8,11 +12,120 @@ def resolve_rate(
     default: float,
     legacy_name: str,
 ) -> float:
-    """Return the effective rate while enforcing mutual exclusivity."""
+    """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",
+]

glitchlings/zoo/adjax.py

@@ -4,13 +4,12 @@ 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
 
-try:
-    from glitchlings._zoo_rust import swap_adjacent_words as _swap_adjacent_words_rust
-except ImportError:  # pragma: no cover - optional acceleration
-    _swap_adjacent_words_rust = None
+# Load Rust-accelerated operation if available
+_swap_adjacent_words_rust = get_rust_operation("swap_adjacent_words")
 
 
 def _python_swap_adjacent_words(

glitchlings/zoo/apostrofae.py

@@ -8,12 +8,11 @@ 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
 
-try:  # pragma: no cover - compiled extension not present in pure-Python envs
-    from glitchlings._zoo_rust import apostrofae as _apostrofae_rust
-except ImportError:  # pragma: no cover - compiled extension not present
-    _apostrofae_rust = None
+# Load Rust-accelerated operation if available
+_apostrofae_rust = get_rust_operation("apostrofae")
 
 
 @cache

glitchlings/zoo/core.py

@@ -10,15 +10,13 @@ from hashlib import blake2s
 from typing import TYPE_CHECKING, Any, Callable, Protocol, TypedDict, TypeGuard, Union, cast
 
 from ..compat import get_datasets_dataset, require_datasets
+from ._rust_extensions import get_rust_operation
 
 _DatasetsDataset = get_datasets_dataset()
 
-try:  # pragma: no cover - optional dependency
-    from glitchlings._zoo_rust import compose_glitchlings as _compose_glitchlings_rust
-    from glitchlings._zoo_rust import plan_glitchlings as _plan_glitchlings_rust
-except ImportError:  # pragma: no cover - compiled extension not present
-    _compose_glitchlings_rust = None
-    _plan_glitchlings_rust = None
+# Load Rust-accelerated orchestration operations if available
+_compose_glitchlings_rust = get_rust_operation("compose_glitchlings")
+_plan_glitchlings_rust = get_rust_operation("plan_glitchlings")
 
 
 log = logging.getLogger(__name__)
@@ -135,7 +133,12 @@ def _plan_glitchlings_with_rust(
 
     try:
         plan = _plan_glitchlings_rust(specs, int(master_seed))
-    except Exception:  # pragma: no cover - defer to Python fallback on failure
+    except (
+        TypeError,
+        ValueError,
+        RuntimeError,
+        AttributeError,
+    ):  # pragma: no cover - defer to Python fallback on failure
         log.debug("Rust orchestration planning failed; falling back to Python plan", exc_info=True)
         return None
 
@@ -537,10 +540,19 @@ class Gaggle(Glitchling):
         """Apply each glitchling to string input sequentially."""
         master_seed = self.seed
         descriptors = self._pipeline_descriptors()
-        if master_seed is not None and descriptors is not None:
+        if (
+            master_seed is not None
+            and descriptors is not None
+            and _compose_glitchlings_rust is not None
+        ):
             try:
                 return cast(str, _compose_glitchlings_rust(text, descriptors, master_seed))
-            except Exception:  # pragma: no cover - fall back to Python execution
+            except (
+                TypeError,
+                ValueError,
+                RuntimeError,
+                AttributeError,
+            ):  # pragma: no cover - fall back to Python execution
                 log.debug("Rust pipeline failed; falling back", exc_info=True)
 
         corrupted = text

glitchlings/zoo/hokey.py

@@ -0,0 +1,173 @@
+"""Hokey glitchling that performs expressive lengthening."""
+
+from __future__ import annotations
+
+import random
+from typing import Any, cast
+
+from ..util.hokey_generator import HokeyConfig, HokeyGenerator, StretchEvent
+from ..util.stretchability import StretchabilityAnalyzer
+from ._rust_extensions import get_rust_operation
+from .core import AttackOrder, AttackWave, Gaggle
+from .core import Glitchling as GlitchlingBase
+
+_hokey_rust = get_rust_operation("hokey")
+_ANALYZER = StretchabilityAnalyzer()
+_GENERATOR = HokeyGenerator(analyzer=_ANALYZER)
+
+
+def _python_extend_vowels(
+    text: str,
+    *,
+    rate: float,
+    extension_min: int,
+    extension_max: int,
+    word_length_threshold: int,
+    base_p: float,
+    rng: random.Random,
+    return_trace: bool = False,
+) -> str | tuple[str, list[StretchEvent]]:
+    config = HokeyConfig(
+        rate=rate,
+        extension_min=extension_min,
+        extension_max=extension_max,
+        word_length_threshold=word_length_threshold,
+        base_p=base_p,
+    )
+    result, events = _GENERATOR.generate(text, rng=rng, config=config)
+    return (result, events) if return_trace else result
+
+
+def extend_vowels(
+    text: str,
+    rate: float = 0.3,
+    extension_min: int = 2,
+    extension_max: int = 5,
+    word_length_threshold: int = 6,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+    *,
+    return_trace: bool = False,
+    base_p: float | None = None,
+) -> str | tuple[str, list[StretchEvent]]:
+    """Extend expressive segments of words for emphasis.
+
+    Parameters
+    ----------
+    text : str
+        Input text to transform.
+    rate : float, optional
+        Global selection rate for candidate words.
+    extension_min : int, optional
+        Minimum number of extra repetitions for the stretch unit.
+    extension_max : int, optional
+        Maximum number of extra repetitions for the stretch unit.
+    word_length_threshold : int, optional
+        Preferred maximum alphabetic length; longer words are de-emphasised but not
+        excluded.
+    seed : int, optional
+        Deterministic seed when ``rng`` is not supplied.
+    rng : random.Random, optional
+        Random number generator to drive sampling.
+    return_trace : bool, optional
+        When ``True`` also return the stretch events for introspection.
+    base_p : float, optional
+        Base probability for the negative-binomial sampler (heavier tails for smaller
+        values). Defaults to ``0.45``.
+    """
+    if not text:
+        empty_trace: list[StretchEvent] = []
+        return (text, empty_trace) if return_trace else text
+
+    if rng is None:
+        rng = random.Random(seed)
+    base_probability = base_p if base_p is not None else 0.45
+
+    if return_trace or _hokey_rust is None:
+        return _python_extend_vowels(
+            text,
+            rate=rate,
+            extension_min=extension_min,
+            extension_max=extension_max,
+            word_length_threshold=word_length_threshold,
+            base_p=base_probability,
+            rng=rng,
+            return_trace=return_trace,
+        )
+
+    return cast(
+        str,
+        _hokey_rust(
+            text,
+            rate,
+            extension_min,
+            extension_max,
+            word_length_threshold,
+            base_probability,
+            rng,
+        ),
+    )
+
+
+class Hokey(GlitchlingBase):
+    """Glitchling that stretches words using linguistic heuristics."""
+
+    seed: int | None
+
+    def __init__(
+        self,
+        *,
+        rate: float = 0.3,
+        extension_min: int = 2,
+        extension_max: int = 5,
+        word_length_threshold: int = 6,
+        base_p: float = 0.45,
+        seed: int | None = None,
+    ) -> None:
+        self._master_seed: int | None = seed
+
+        def _corruption_wrapper(text: str, **kwargs: Any) -> str:
+            result = extend_vowels(text, **kwargs)
+            return result if isinstance(result, str) else result[0]
+
+        super().__init__(
+            name="Hokey",
+            corruption_function=_corruption_wrapper,
+            scope=AttackWave.CHARACTER,
+            order=AttackOrder.FIRST,
+            seed=seed,
+            rate=rate,
+            extension_min=extension_min,
+            extension_max=extension_max,
+            word_length_threshold=word_length_threshold,
+            base_p=base_p,
+        )
+
+    def pipeline_operation(self) -> dict[str, Any] | None:
+        return {
+            "type": "hokey",
+            "rate": self.kwargs.get("rate", 0.3),
+            "extension_min": self.kwargs.get("extension_min", 2),
+            "extension_max": self.kwargs.get("extension_max", 5),
+            "word_length_threshold": self.kwargs.get("word_length_threshold", 6),
+            "base_p": self.kwargs.get("base_p", 0.45),
+        }
+
+    def reset_rng(self, seed: int | None = None) -> None:
+        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)
+
+
+hokey = Hokey()
+
+
+__all__ = ["Hokey", "hokey", "extend_vowels"]

glitchlings/zoo/jargoyle.py

@@ -14,7 +14,11 @@ _wordnet_module: ModuleType | None
 
 try:  # pragma: no cover - optional WordNet dependency
     import glitchlings.lexicon.wordnet as _wordnet_module
-except Exception:  # pragma: no cover - triggered when nltk unavailable
+except (
+    ImportError,
+    ModuleNotFoundError,
+    AttributeError,
+):  # pragma: no cover - triggered when nltk unavailable
     _wordnet_module = None
 
 _wordnet_runtime: ModuleType | None = _wordnet_module
@@ -49,7 +53,7 @@ def dependencies_available() -> bool:
     try:
         # Fall back to the configured default lexicon (typically the bundled vector cache).
         get_default_lexicon(seed=None)
-    except Exception:
+    except (RuntimeError, ImportError, ModuleNotFoundError, AttributeError):
         return False
     return True
 

glitchlings/zoo/redactyl.py

@@ -3,6 +3,7 @@ import re
 from typing import Any, cast
 
 from ._rate import resolve_rate
+from ._rust_extensions import get_rust_operation
 from ._sampling import weighted_sample_without_replacement
 from ._text_utils import (
     WordToken,
@@ -13,11 +14,8 @@ from .core import AttackWave, Glitchling
 
 FULL_BLOCK = "█"
 
-
-try:
-    from glitchlings._zoo_rust import redact_words as _redact_words_rust
-except ImportError:  # pragma: no cover - compiled extension not present
-    _redact_words_rust = None
+# Load Rust-accelerated operation if available
+_redact_words_rust = get_rust_operation("redact_words")
 
 
 def _python_redact_words(
@@ -119,6 +117,7 @@ def redact_words(
     use_rust = _redact_words_rust is not None and isinstance(merge_adjacent, bool)
 
     if use_rust:
+        assert _redact_words_rust is not None  # Type narrowing for mypy
         return cast(
             str,
             _redact_words_rust(

glitchlings/zoo/reduple.py

@@ -2,13 +2,12 @@ import random
 from typing import Any, cast
 
 from ._rate import resolve_rate
+from ._rust_extensions import get_rust_operation
 from ._text_utils import WordToken, collect_word_tokens, split_preserving_whitespace
 from .core import AttackWave, Glitchling
 
-try:
-    from glitchlings._zoo_rust import reduplicate_words as _reduplicate_words_rust
-except ImportError:  # pragma: no cover - compiled extension not present
-    _reduplicate_words_rust = None
+# Load Rust-accelerated operation if available
+_reduplicate_words_rust = get_rust_operation("reduplicate_words")
 
 
 def _python_reduplicate_words(

glitchlings/zoo/rushmore.py

@@ -4,13 +4,12 @@ import re
 from typing import Any, cast
 
 from ._rate import resolve_rate
+from ._rust_extensions import get_rust_operation
 from ._text_utils import WordToken, collect_word_tokens, split_preserving_whitespace
 from .core import AttackWave, Glitchling
 
-try:
-    from glitchlings._zoo_rust import delete_random_words as _delete_random_words_rust
-except ImportError:  # pragma: no cover - compiled extension not present
-    _delete_random_words_rust = None
+# Load Rust-accelerated operation if available
+_delete_random_words_rust = get_rust_operation("delete_random_words")
 
 
 def _python_delete_random_words(

glitchlings/zoo/scannequin.py

@@ -4,12 +4,11 @@ from typing import Any, cast
 
 from ._ocr_confusions import load_confusion_table
 from ._rate import resolve_rate
+from ._rust_extensions import get_rust_operation
 from .core import AttackOrder, AttackWave, Glitchling
 
-try:
-    from glitchlings._zoo_rust import ocr_artifacts as _ocr_artifacts_rust
-except ImportError:  # pragma: no cover - compiled extension not present
-    _ocr_artifacts_rust = None
+# Load Rust-accelerated operation if available
+_ocr_artifacts_rust = get_rust_operation("ocr_artifacts")
 
 
 def _python_ocr_artifacts(

glitchlings/zoo/typogre.py

@@ -6,12 +6,11 @@ from typing import Any, Optional, cast
 
 from ..util import KEYNEIGHBORS
 from ._rate import resolve_rate
+from ._rust_extensions import get_rust_operation
 from .core import AttackOrder, AttackWave, Glitchling
 
-try:
-    from glitchlings._zoo_rust import fatfinger as _fatfinger_rust
-except ImportError:  # pragma: no cover - compiled extension not present
-    _fatfinger_rust = None
+# Load Rust-accelerated operation if available
+_fatfinger_rust = get_rust_operation("fatfinger")
 
 
 def _python_unichar(text: str, rng: random.Random) -> str: