glitchlings 0.4.2__cp312-cp312-macosx_11_0_universal2.whl → 0.4.4__cp312-cp312-macosx_11_0_universal2.whl

glitchlings/lexicon/wordnet.py

@@ -4,49 +4,74 @@ from __future__ import annotations
 
 from importlib import import_module
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from types import ModuleType
+from typing import Any, Callable, Protocol, Sequence, cast
 
 from ..compat import nltk as _nltk_dependency
 from . import LexiconBackend
 from ._cache import CacheSnapshot
 
-nltk = _nltk_dependency.get()  # type: ignore[assignment]
-_NLTK_IMPORT_ERROR = _nltk_dependency.error
 
-if TYPE_CHECKING:  # pragma: no cover - typing aid only
-    from nltk.corpus.reader import WordNetCorpusReader  # type: ignore[import]
-else:  # pragma: no cover - runtime fallback to avoid hard dependency
-    WordNetCorpusReader = Any
+class _LemmaProtocol(Protocol):
+    def name(self) -> str:
+        ...
 
-find: Any | None = None
-_WORDNET_MODULE: Any | None = None
+
+class _SynsetProtocol(Protocol):
+    def lemmas(self) -> Sequence[_LemmaProtocol]:
+        ...
+
+
+class _WordNetResource(Protocol):
+    def synsets(self, word: str, pos: str | None = None) -> Sequence[_SynsetProtocol]:
+        ...
+
+    def ensure_loaded(self) -> None:
+        ...
+
+
+WordNetCorpusReaderFactory = Callable[[Any, Any], _WordNetResource]
+
+nltk: ModuleType | None = _nltk_dependency.get()
+_NLTK_IMPORT_ERROR: ModuleNotFoundError | None = _nltk_dependency.error
+
+WordNetCorpusReader: WordNetCorpusReaderFactory | None = None
+find: Callable[[str], Any] | None = None
+_WORDNET_MODULE: _WordNetResource | None = None
 
 if nltk is not None:  # pragma: no cover - guarded by import success
     try:
         corpus_reader_module = import_module("nltk.corpus.reader")
-        WordNetCorpusReader = corpus_reader_module.WordNetCorpusReader  # type: ignore[assignment]
     except ModuleNotFoundError as exc:  # pragma: no cover - triggered when corpus missing
         if _NLTK_IMPORT_ERROR is None:
-            _NLTK_IMPORT_ERROR = exc  # type: ignore[assignment]
+            _NLTK_IMPORT_ERROR = exc
     else:
+        reader_candidate = getattr(corpus_reader_module, "WordNetCorpusReader", None)
+        if reader_candidate is not None:
+            WordNetCorpusReader = cast(WordNetCorpusReaderFactory, reader_candidate)
+
         try:
             data_module = import_module("nltk.data")
         except ModuleNotFoundError as exc:  # pragma: no cover - triggered when data missing
             if _NLTK_IMPORT_ERROR is None:
-                _NLTK_IMPORT_ERROR = exc  # type: ignore[assignment]
+                _NLTK_IMPORT_ERROR = exc
         else:
-            find = getattr(data_module, "find", None)
+            locator = getattr(data_module, "find", None)
+            if callable(locator):
+                find = cast(Callable[[str], Any], locator)
 
     try:
-        _WORDNET_MODULE = import_module("nltk.corpus.wordnet")
+        module_candidate = import_module("nltk.corpus.wordnet")
     except ModuleNotFoundError:  # pragma: no cover - only hit on namespace packages
         _WORDNET_MODULE = None
+    else:
+        _WORDNET_MODULE = cast(_WordNetResource, module_candidate)
 else:
-    nltk = None  # type: ignore[assignment]
+    nltk = None
     find = None
     _WORDNET_MODULE = None
 
-_WORDNET_HANDLE: WordNetCorpusReader | Any | None = _WORDNET_MODULE
+_WORDNET_HANDLE: _WordNetResource | None = _WORDNET_MODULE
 _wordnet_ready = False
 
 _VALID_POS: tuple[str, ...] = ("n", "v", "a", "r")
@@ -69,15 +94,22 @@ def dependencies_available() -> bool:
     return nltk is not None and find is not None
 
 
-def _load_wordnet_reader() -> WordNetCorpusReader:
+def _load_wordnet_reader() -> _WordNetResource:
     """Return a WordNet corpus reader from the downloaded corpus files."""
     _require_nltk()
 
+    if WordNetCorpusReader is None:
+        raise RuntimeError("The NLTK WordNet corpus reader is unavailable.")
+
+    locator = find
+    if locator is None:
+        raise RuntimeError("The NLTK data locator is unavailable.")
+
     try:
-        root = find("corpora/wordnet")
+        root = locator("corpora/wordnet")
     except LookupError:
         try:
-            zip_root = find("corpora/wordnet.zip")
+            zip_root = locator("corpora/wordnet.zip")
         except LookupError as exc:
             raise RuntimeError(
                 "The NLTK WordNet corpus is not installed; run `nltk.download('wordnet')`."
@@ -87,18 +119,20 @@ def _load_wordnet_reader() -> WordNetCorpusReader:
     return WordNetCorpusReader(root, None)
 
 
-def _wordnet(force_refresh: bool = False) -> WordNetCorpusReader | Any:
+def _wordnet(force_refresh: bool = False) -> _WordNetResource:
     """Retrieve the active WordNet handle, rebuilding it on demand."""
     global _WORDNET_HANDLE
 
     if force_refresh:
         _WORDNET_HANDLE = _WORDNET_MODULE
 
-    if _WORDNET_HANDLE is not None:
-        return _WORDNET_HANDLE
+    cached = _WORDNET_HANDLE
+    if cached is not None:
+        return cached
 
-    _WORDNET_HANDLE = _load_wordnet_reader()
-    return _WORDNET_HANDLE
+    resource = _load_wordnet_reader()
+    _WORDNET_HANDLE = resource
+    return resource
 
 
 def ensure_wordnet() -> None:
@@ -110,11 +144,14 @@ def ensure_wordnet() -> None:
     _require_nltk()
 
     resource = _wordnet()
+    nltk_module = nltk
+    if nltk_module is None:
+        raise RuntimeError("The NLTK dependency is unexpectedly unavailable.")
 
     try:
         resource.ensure_loaded()
     except LookupError:
-        nltk.download("wordnet", quiet=True)
+        nltk_module.download("wordnet", quiet=True)
         try:
             resource = _wordnet(force_refresh=True)
             resource.ensure_loaded()
@@ -159,6 +196,7 @@ class WordNetLexicon(LexiconBackend):
     """Lexicon that retrieves synonyms from the NLTK WordNet corpus."""
 
     def get_synonyms(self, word: str, pos: str | None = None, n: int = 5) -> list[str]:
+        """Return up to ``n`` WordNet lemmas for ``word`` filtered by ``pos`` if provided."""
         ensure_wordnet()
 
         if pos is None:
@@ -173,15 +211,18 @@ class WordNetLexicon(LexiconBackend):
         return self._deterministic_sample(synonyms, limit=n, word=word, pos=pos)
 
     def supports_pos(self, pos: str | None) -> bool:
+        """Return ``True`` when ``pos`` is unset or recognised by the WordNet corpus."""
         if pos is None:
             return True
         return pos.lower() in _VALID_POS
 
     @classmethod
     def load_cache(cls, path: str | Path) -> CacheSnapshot:
+        """WordNet lexicons do not persist caches; raising keeps the contract explicit."""
         raise RuntimeError("WordNetLexicon does not persist or load caches.")
 
     def save_cache(self, path: str | Path | None = None) -> Path | None:
+        """WordNet lexicons do not persist caches; raising keeps the contract explicit."""
         raise RuntimeError("WordNetLexicon does not persist or load caches.")
 
     def __repr__(self) -> str:  # pragma: no cover - trivial representation

glitchlings/main.py

@@ -5,7 +5,9 @@ from __future__ import annotations
 import argparse
 import difflib
 import sys
+from collections.abc import Sequence
 from pathlib import Path
+from typing import cast
 
 from . import SAMPLE_TEXT
 from .config import DEFAULT_ATTACK_SEED, build_gaggle, load_attack_config
@@ -88,6 +90,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def build_lexicon_parser() -> argparse.ArgumentParser:
+    """Create the ``build-lexicon`` subcommand parser with vector cache options."""
     builder = argparse.ArgumentParser(
         prog="glitchlings build-lexicon",
         description=(
@@ -179,21 +182,23 @@ def read_text(args: argparse.Namespace, parser: argparse.ArgumentParser) -> str:
         SystemExit: Raised indirectly via ``parser.error`` on failure.
 
     """
-    if args.file is not None:
+    file_path = cast(Path | None, getattr(args, "file", None))
+    if file_path is not None:
         try:
-            return args.file.read_text(encoding="utf-8")
+            return file_path.read_text(encoding="utf-8")
         except OSError as exc:
-            filename = getattr(exc, "filename", None) or args.file
+            filename = getattr(exc, "filename", None) or file_path
             reason = exc.strerror or str(exc)
             parser.error(f"Failed to read file {filename}: {reason}")
 
-    if args.text:
-        return args.text
+    text_argument = cast(str | None, getattr(args, "text", None))
+    if text_argument:
+        return text_argument
 
     if not sys.stdin.isatty():
         return sys.stdin.read()
 
-    if args.sample:
+    if bool(getattr(args, "sample", False)):
         return SAMPLE_TEXT
 
     parser.error(
@@ -224,21 +229,23 @@ def summon_glitchlings(
 
         return build_gaggle(config, seed_override=seed)
 
+    normalized: Sequence[str | Glitchling]
     if names:
-        normalized: list[str | Glitchling] = []
+        parsed: list[str | Glitchling] = []
         for specification in names:
             try:
-                normalized.append(parse_glitchling_spec(specification))
+                parsed.append(parse_glitchling_spec(specification))
             except ValueError as exc:
                 parser.error(str(exc))
                 raise AssertionError("parser.error should exit")
+        normalized = parsed
     else:
-        normalized = DEFAULT_GLITCHLING_NAMES
+        normalized = list(DEFAULT_GLITCHLING_NAMES)
 
     effective_seed = seed if seed is not None else DEFAULT_ATTACK_SEED
 
     try:
-        return summon(normalized, seed=effective_seed)
+        return summon(list(normalized), seed=effective_seed)
     except ValueError as exc:
         parser.error(str(exc))
         raise AssertionError("parser.error should exit")
@@ -285,7 +292,10 @@ def run_cli(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
         config_path=args.config,
     )
 
-    corrupted = gaggle(text)
+    corrupted = gaggle.corrupt(text)
+    if not isinstance(corrupted, str):
+        message = "Gaggle returned non-string output for string input"
+        raise TypeError(message)
 
     if args.diff:
         show_diff(text, corrupted)

glitchlings/zoo/__init__.py

@@ -4,6 +4,7 @@ import ast
 from typing import Any
 
 from .adjax import Adjax, adjax
+from .apostrofae import Apostrofae, apostrofae
 from .core import (
     Gaggle,
     Glitchling,
@@ -30,6 +31,8 @@ __all__ = [
     "mim1c",
     "Jargoyle",
     "jargoyle",
+    "Apostrofae",
+    "apostrofae",
     "Adjax",
     "adjax",
     "Reduple",
@@ -58,7 +61,7 @@ __all__ = [
 
 _HAS_JARGOYLE = _jargoyle_available()
 
-_BUILTIN_GLITCHLING_LIST: list[Glitchling] = [typogre, mim1c]
+_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])
@@ -69,6 +72,7 @@ BUILTIN_GLITCHLINGS: dict[str, Glitchling] = {
 
 _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,

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

@@ -1,16 +1,15 @@
 from __future__ import annotations
 
 import random
-from typing import Any
+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(
@@ -83,7 +82,7 @@ def swap_adjacent_words(
         rng = random.Random(seed)
 
     if _swap_adjacent_words_rust is not None:
-        return _swap_adjacent_words_rust(text, clamped_rate, rng)
+        return cast(str, _swap_adjacent_words_rust(text, clamped_rate, rng))
 
     return _python_swap_adjacent_words(text, rate=clamped_rate, rng=rng)