glitchlings 0.2.1__cp312-cp312-win_amd64.whl → 0.2.3__cp312-cp312-win_amd64.whl

glitchlings/zoo/jargoyle.py

@@ -2,27 +2,68 @@ import random
 import re
 from collections.abc import Iterable
 from dataclasses import dataclass
-from typing import Any, Literal, cast
-
-import nltk
-from nltk.corpus.reader import WordNetCorpusReader
-from nltk.data import find
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+try:  # pragma: no cover - exercised in environments with NLTK installed
+    import nltk  # type: ignore[import]
+except ModuleNotFoundError as exc:  # pragma: no cover - triggered when NLTK missing
+    nltk = None  # type: ignore[assignment]
+    find = None  # type: ignore[assignment]
+    _NLTK_IMPORT_ERROR = exc
+else:  # pragma: no cover - executed when NLTK is available
+    from nltk.corpus.reader import WordNetCorpusReader as _WordNetCorpusReader  # type: ignore[import]
+    from nltk.data import find as _nltk_find  # type: ignore[import]
+
+    find = _nltk_find
+    _NLTK_IMPORT_ERROR = None
+
+if TYPE_CHECKING:  # pragma: no cover - typing aid only
+    from nltk.corpus.reader import WordNetCorpusReader  # type: ignore[import]
+else:  # Use ``Any`` at runtime to avoid hard dependency when NLTK missing
+    WordNetCorpusReader = Any
+
+if nltk is not None:  # pragma: no cover - guarded by import success
+    try:
+        from nltk.corpus import wordnet as _WORDNET_MODULE  # type: ignore[import]
+    except ModuleNotFoundError:  # pragma: no cover - only hit on namespace packages
+        _WORDNET_MODULE = None
+    else:
+        WordNetCorpusReader = _WordNetCorpusReader  # type: ignore[assignment]
+else:
+    _WORDNET_MODULE = None
 
 from .core import AttackWave, Glitchling
-
-try:  # pragma: no cover - exercised when the namespace package is present
-    from nltk.corpus import wordnet as _WORDNET_MODULE
-except ModuleNotFoundError:  # pragma: no cover - triggered on modern NLTK installs
-    _WORDNET_MODULE = None
+from ._rate import resolve_rate
 
 _WORDNET_HANDLE: WordNetCorpusReader | Any | None = _WORDNET_MODULE
 
 _wordnet_ready = False
 
 
+def _require_nltk() -> None:
+    """Ensure the NLTK dependency is present before continuing."""
+
+    if nltk is None or find is None:
+        message = (
+            "The NLTK package is required for the jargoyle glitchling; install "
+            "the 'wordnet' extra via `pip install glitchlings[wordnet]`."
+        )
+        if '_NLTK_IMPORT_ERROR' in globals() and _NLTK_IMPORT_ERROR is not None:
+            raise RuntimeError(message) from _NLTK_IMPORT_ERROR
+        raise RuntimeError(message)
+
+
+def dependencies_available() -> bool:
+    """Return ``True`` when the runtime NLTK dependency is present."""
+
+    return nltk is not None and find is not None
+
+
 def _load_wordnet_reader() -> WordNetCorpusReader:
     """Return a WordNet corpus reader from the downloaded corpus files."""
 
+    _require_nltk()
+
     try:
         root = find("corpora/wordnet")
     except LookupError:
@@ -59,6 +100,8 @@ def ensure_wordnet() -> None:
     if _wordnet_ready:
         return
 
+    _require_nltk()
+
     resource = _wordnet()
 
     try:
@@ -169,16 +212,18 @@ def _collect_synonyms(
 
 def substitute_random_synonyms(
     text: str,
-    replacement_rate: float = 0.1,
+    rate: float | None = None,
     part_of_speech: PartOfSpeechInput = "n",
     seed: int | None = None,
     rng: random.Random | None = None,
+    *,
+    replacement_rate: float | None = None,
 ) -> str:
     """Replace words with random WordNet synonyms.
 
     Parameters
     - text: Input text.
-    - replacement_rate: Max proportion of candidate words to replace (default 0.1).
+    - rate: Max proportion of candidate words to replace (default 0.1).
     - part_of_speech: WordNet POS tag(s) to target. Accepts "n", "v", "a", "r",
       any iterable of those tags, or "any" to include all four.
     - rng: Optional RNG instance used for deterministic sampling.
@@ -190,6 +235,13 @@ def substitute_random_synonyms(
     - Synonyms sorted before rng.choice to fix ordering.
     - For each POS, the first synset containing alternate lemmas is used for stability.
     """
+    effective_rate = resolve_rate(
+        rate=rate,
+        legacy_value=replacement_rate,
+        default=0.1,
+        legacy_name="replacement_rate",
+    )
+
     ensure_wordnet()
     wordnet = _wordnet()
 
@@ -228,7 +280,8 @@ def substitute_random_synonyms(
     if not candidate_indices:
         return text
 
-    max_replacements = int(len(candidate_indices) * replacement_rate)
+    clamped_rate = max(0.0, effective_rate)
+    max_replacements = int(len(candidate_indices) * clamped_rate)
     if max_replacements <= 0:
         return text
 
@@ -255,16 +308,24 @@ class Jargoyle(Glitchling):
     def __init__(
         self,
         *,
-        replacement_rate: float = 0.1,
+        rate: float | None = None,
+        replacement_rate: float | None = None,
         part_of_speech: PartOfSpeechInput = "n",
         seed: int | None = None,
     ) -> None:
+        self._param_aliases = {"replacement_rate": "rate"}
+        effective_rate = resolve_rate(
+            rate=rate,
+            legacy_value=replacement_rate,
+            default=0.1,
+            legacy_name="replacement_rate",
+        )
         super().__init__(
             name="Jargoyle",
             corruption_function=substitute_random_synonyms,
             scope=AttackWave.WORD,
             seed=seed,
-            replacement_rate=replacement_rate,
+            rate=effective_rate,
             part_of_speech=part_of_speech,
         )
 
@@ -272,4 +333,4 @@ class Jargoyle(Glitchling):
 jargoyle = Jargoyle()
 
 
-__all__ = ["Jargoyle", "ensure_wordnet", "jargoyle"]
+__all__ = ["Jargoyle", "dependencies_available", "ensure_wordnet", "jargoyle"]

glitchlings/zoo/mim1c.py

@@ -5,21 +5,24 @@ from typing import Literal
 from confusable_homoglyphs import confusables
 
 from .core import AttackOrder, AttackWave, Glitchling
+from ._rate import resolve_rate
 
 
 def swap_homoglyphs(
     text: str,
-    replacement_rate: float = 0.02,
+    rate: float | None = None,
     classes: list[str] | Literal["all"] | None = None,
     banned_characters: Collection[str] | None = None,
     seed: int | None = None,
     rng: random.Random | None = None,
+    *,
+    replacement_rate: float | None = None,
 ) -> str:
     """Replace characters with visually confusable homoglyphs.
 
     Parameters
     - text: Input text.
-    - replacement_rate: Max proportion of eligible characters to replace (default 0.02).
+    - rate: Max proportion of eligible characters to replace (default 0.02).
     - classes: Restrict replacements to these Unicode script classes (default ["LATIN","GREEK","CYRILLIC"]). Use "all" to allow any.
     - banned_characters: Characters that must never appear as replacements.
     - seed: Optional seed if `rng` not provided.
@@ -29,6 +32,13 @@ def swap_homoglyphs(
     - Only replaces characters present in confusables.confusables_data with single-codepoint alternatives.
     - Maintains determinism by shuffling candidates and sampling via the provided RNG.
     """
+    effective_rate = resolve_rate(
+        rate=rate,
+        legacy_value=replacement_rate,
+        default=0.02,
+        legacy_name="replacement_rate",
+    )
+
     if rng is None:
         rng = random.Random(seed)
 
@@ -39,7 +49,8 @@ def swap_homoglyphs(
     confusable_chars = [
         char for char in target_chars if char in confusables.confusables_data
     ]
-    num_replacements = int(len(confusable_chars) * replacement_rate)
+    clamped_rate = max(0.0, effective_rate)
+    num_replacements = int(len(confusable_chars) * clamped_rate)
     done = 0
     rng.shuffle(confusable_chars)
     banned_set = set(banned_characters or ())
@@ -66,18 +77,26 @@ class Mim1c(Glitchling):
     def __init__(
         self,
         *,
-        replacement_rate: float = 0.02,
+        rate: float | None = None,
+        replacement_rate: float | None = None,
         classes: list[str] | Literal["all"] | None = None,
         banned_characters: Collection[str] | None = None,
         seed: int | None = None,
     ) -> None:
+        self._param_aliases = {"replacement_rate": "rate"}
+        effective_rate = resolve_rate(
+            rate=rate,
+            legacy_value=replacement_rate,
+            default=0.02,
+            legacy_name="replacement_rate",
+        )
         super().__init__(
             name="Mim1c",
             corruption_function=swap_homoglyphs,
             scope=AttackWave.CHARACTER,
             order=AttackOrder.LAST,
             seed=seed,
-            replacement_rate=replacement_rate,
+            rate=effective_rate,
             classes=classes,
             banned_characters=banned_characters,
         )

glitchlings/zoo/ocr_confusions.tsv

@@ -0,0 +1,30 @@
+# Source  Replacements (space-separated)
+li h
+h li
+rn m
+m rn
+cl d
+d cl
+I l
+l I 1
+1 l I
+0 O
+O 0
+B 8
+8 B
+S 5
+5 S
+Z 2
+2 Z
+G 6
+6 G
+“ "
+” "
+‘ '
+’ '
+— -
+– -
+vv w
+w vv
+ri n
+n ri

glitchlings/zoo/redactyl.py

@@ -1,7 +1,9 @@
 import re
 import random
+from typing import Any
 
 from .core import Glitchling, AttackWave
+from ._rate import resolve_rate
 
 FULL_BLOCK = "█"
 
@@ -16,7 +18,7 @@ def _python_redact_words(
     text: str,
     *,
     replacement_char: str,
-    redaction_rate: float,
+    rate: float,
     merge_adjacent: bool,
     rng: random.Random,
 ) -> str:
@@ -25,7 +27,7 @@ def _python_redact_words(
     Parameters
     - text: Input text.
     - replacement_char: The character to use for redaction (default FULL_BLOCK).
-    - redaction_rate: Max proportion of words to redact (default 0.05).
+    - rate: Max proportion of words to redact (default 0.05).
     - merge_adjacent: If True, merges adjacent redactions across intervening non-word chars.
     - seed: Seed used if `rng` not provided (default 151).
     - rng: Optional RNG; overrides seed.
@@ -35,7 +37,7 @@ def _python_redact_words(
     word_indices = [i for i, token in enumerate(tokens) if i % 2 == 0 and token.strip()]
     if not word_indices:
         raise ValueError("Cannot redact words because the input text contains no redactable words.")
-    num_to_redact = max(1, int(len(word_indices) * redaction_rate))
+    num_to_redact = max(1, int(len(word_indices) * rate))
 
     # Sample from the indices of actual words
     indices_to_redact = rng.sample(word_indices, k=num_to_redact)
@@ -72,21 +74,34 @@ def _python_redact_words(
 def redact_words(
     text: str,
     replacement_char: str = FULL_BLOCK,
-    redaction_rate: float = 0.05,
+    rate: float | None = None,
     merge_adjacent: bool = False,
     seed: int = 151,
     rng: random.Random | None = None,
+    *,
+    redaction_rate: float | None = None,
 ) -> str:
     """Redact random words by replacing their characters."""
 
+    effective_rate = resolve_rate(
+        rate=rate,
+        legacy_value=redaction_rate,
+        default=0.05,
+        legacy_name="redaction_rate",
+    )
+
     if rng is None:
         rng = random.Random(seed)
 
-    if _redact_words_rust is not None:
+    clamped_rate = max(0.0, effective_rate)
+
+    use_rust = _redact_words_rust is not None and isinstance(merge_adjacent, bool)
+
+    if use_rust:
         return _redact_words_rust(
             text,
             replacement_char,
-            redaction_rate,
+            clamped_rate,
             merge_adjacent,
             rng,
         )
@@ -94,7 +109,7 @@ def redact_words(
     return _python_redact_words(
         text,
         replacement_char=replacement_char,
-        redaction_rate=redaction_rate,
+        rate=clamped_rate,
         merge_adjacent=merge_adjacent,
         rng=rng,
     )
@@ -107,20 +122,42 @@ class Redactyl(Glitchling):
         self,
         *,
         replacement_char: str = FULL_BLOCK,
-        redaction_rate: float = 0.05,
+        rate: float | None = None,
+        redaction_rate: float | None = None,
         merge_adjacent: bool = False,
         seed: int = 151,
     ) -> None:
+        self._param_aliases = {"redaction_rate": "rate"}
+        effective_rate = resolve_rate(
+            rate=rate,
+            legacy_value=redaction_rate,
+            default=0.05,
+            legacy_name="redaction_rate",
+        )
         super().__init__(
             name="Redactyl",
             corruption_function=redact_words,
             scope=AttackWave.WORD,
             seed=seed,
             replacement_char=replacement_char,
-            redaction_rate=redaction_rate,
+            rate=effective_rate,
             merge_adjacent=merge_adjacent,
         )
 
+    def pipeline_operation(self) -> dict[str, Any] | None:
+        replacement_char = self.kwargs.get("replacement_char")
+        rate = self.kwargs.get("rate")
+        merge_adjacent = self.kwargs.get("merge_adjacent")
+        if replacement_char is None or rate is None or merge_adjacent is None:
+            return None
+        return {
+            "type": "redact",
+            "replacement_char": str(replacement_char),
+            "redaction_rate": float(rate),
+            "merge_adjacent": bool(merge_adjacent),
+        }
+
+
 
 redactyl = Redactyl()
 

glitchlings/zoo/reduple.py

@@ -1,7 +1,9 @@
 import re
 import random
+from typing import Any
 
 from .core import Glitchling, AttackWave
+from ._rate import resolve_rate
 
 try:
     from glitchlings._zoo_rust import reduplicate_words as _reduplicate_words_rust
@@ -12,14 +14,14 @@ except ImportError:  # pragma: no cover - compiled extension not present
 def _python_reduplicate_words(
     text: str,
     *,
-    reduplication_rate: float,
+    rate: float,
     rng: random.Random,
 ) -> str:
     """Randomly reduplicate words in the text.
 
     Parameters
     - text: Input text.
-    - reduplication_rate: Max proportion of words to reduplicate (default 0.05).
+    - rate: Max proportion of words to reduplicate (default 0.05).
     - seed: Optional seed if `rng` not provided.
     - rng: Optional RNG; overrides seed.
 
@@ -39,7 +41,7 @@ def _python_reduplicate_words(
             continue
 
         # Only consider actual words for reduplication
-        if rng.random() < reduplication_rate:
+        if rng.random() < rate:
             # Check if word has trailing punctuation
             match = re.match(r"^(\W*)(.*?)(\W*)$", word)
             if match:
@@ -53,9 +55,11 @@ def _python_reduplicate_words(
 
 def reduplicate_words(
     text: str,
-    reduplication_rate: float = 0.05,
+    rate: float | None = None,
     seed: int | None = None,
     rng: random.Random | None = None,
+    *,
+    reduplication_rate: float | None = None,
 ) -> str:
     """Randomly reduplicate words in the text.
 
@@ -63,15 +67,24 @@ def reduplicate_words(
     extension is unavailable.
     """
 
+    effective_rate = resolve_rate(
+        rate=rate,
+        legacy_value=reduplication_rate,
+        default=0.05,
+        legacy_name="reduplication_rate",
+    )
+
     if rng is None:
         rng = random.Random(seed)
 
+    clamped_rate = max(0.0, effective_rate)
+
     if _reduplicate_words_rust is not None:
-        return _reduplicate_words_rust(text, reduplication_rate, rng)
+        return _reduplicate_words_rust(text, clamped_rate, rng)
 
     return _python_reduplicate_words(
         text,
-        reduplication_rate=reduplication_rate,
+        rate=clamped_rate,
         rng=rng,
     )
 
@@ -82,17 +95,32 @@ class Reduple(Glitchling):
     def __init__(
         self,
         *,
-        reduplication_rate: float = 0.05,
+        rate: float | None = None,
+        reduplication_rate: float | None = None,
         seed: int | None = None,
     ) -> None:
+        self._param_aliases = {"reduplication_rate": "rate"}
+        effective_rate = resolve_rate(
+            rate=rate,
+            legacy_value=reduplication_rate,
+            default=0.05,
+            legacy_name="reduplication_rate",
+        )
         super().__init__(
             name="Reduple",
             corruption_function=reduplicate_words,
             scope=AttackWave.WORD,
             seed=seed,
-            reduplication_rate=reduplication_rate,
+            rate=effective_rate,
         )
 
+    def pipeline_operation(self) -> dict[str, Any] | None:
+        rate = self.kwargs.get("rate")
+        if rate is None:
+            return None
+        return {"type": "reduplicate", "reduplication_rate": float(rate)}
+
+
 
 reduple = Reduple()
 

glitchlings/zoo/rushmore.py

@@ -1,8 +1,10 @@
 import math
 import random
 import re
+from typing import Any
 
 from .core import Glitchling, AttackWave
+from ._rate import resolve_rate
 
 try:
     from glitchlings._zoo_rust import delete_random_words as _delete_random_words_rust
@@ -13,11 +15,14 @@ except ImportError:  # pragma: no cover - compiled extension not present
 def _python_delete_random_words(
     text: str,
     *,
-    max_deletion_rate: float,
+    rate: float,
     rng: random.Random,
 ) -> str:
     """Delete random words from the input text while preserving whitespace."""
 
+    if rate <= 0.0:
+        return text
+
     tokens = re.split(r"(\s+)", text)  # Split but keep separators for later rejoin
 
     candidate_indices: list[int] = []
@@ -29,14 +34,14 @@ def _python_delete_random_words(
         candidate_indices.append(i)
 
     allowed_deletions = min(
-        len(candidate_indices), math.floor(len(candidate_indices) * max_deletion_rate)
+        len(candidate_indices), math.floor(len(candidate_indices) * rate)
     )
     if allowed_deletions <= 0:
         return text
 
     deletions = 0
     for i in candidate_indices:
-        if rng.random() < max_deletion_rate:
+        if rng.random() < rate:
             word = tokens[i]
             match = re.match(r"^(\W*)(.*?)(\W*)$", word)
             if match:
@@ -58,24 +63,35 @@ def _python_delete_random_words(
 
 def delete_random_words(
     text: str,
-    max_deletion_rate: float = 0.01,
+    rate: float | None = None,
     seed: int | None = None,
     rng: random.Random | None = None,
+    *,
+    max_deletion_rate: float | None = None,
 ) -> str:
     """Delete random words from the input text.
 
     Uses the optional Rust implementation when available.
     """
 
+    effective_rate = resolve_rate(
+        rate=rate,
+        legacy_value=max_deletion_rate,
+        default=0.01,
+        legacy_name="max_deletion_rate",
+    )
+
     if rng is None:
         rng = random.Random(seed)
 
+    clamped_rate = max(0.0, effective_rate)
+
     if _delete_random_words_rust is not None:
-        return _delete_random_words_rust(text, max_deletion_rate, rng)
+        return _delete_random_words_rust(text, clamped_rate, rng)
 
     return _python_delete_random_words(
         text,
-        max_deletion_rate=max_deletion_rate,
+        rate=clamped_rate,
         rng=rng,
     )
 
@@ -86,17 +102,33 @@ class Rushmore(Glitchling):
     def __init__(
         self,
         *,
-        max_deletion_rate: float = 0.01,
+        rate: float | None = None,
+        max_deletion_rate: float | None = None,
         seed: int | None = None,
     ) -> None:
+        self._param_aliases = {"max_deletion_rate": "rate"}
+        effective_rate = resolve_rate(
+            rate=rate,
+            legacy_value=max_deletion_rate,
+            default=0.01,
+            legacy_name="max_deletion_rate",
+        )
         super().__init__(
             name="Rushmore",
             corruption_function=delete_random_words,
             scope=AttackWave.WORD,
             seed=seed,
-            max_deletion_rate=max_deletion_rate,
+            rate=effective_rate,
         )
 
+    def pipeline_operation(self) -> dict[str, Any] | None:
+        rate = self.kwargs.get("rate")
+        if rate is None:
+            rate = self.kwargs.get("max_deletion_rate")
+        if rate is None:
+            return None
+        return {"type": "delete", "max_deletion_rate": float(rate)}
+
 
 rushmore = Rushmore()