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

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

glitchlings/zoo/core.py

@@ -7,18 +7,16 @@ import random
 from collections.abc import Mapping, Sequence
 from enum import IntEnum, auto
 from hashlib import blake2s
-from typing import TYPE_CHECKING, Any, Callable, Protocol, TypedDict, Union
+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__)
@@ -35,6 +33,9 @@ class PlanSpecification(TypedDict):
     order: int
 
 
+TranscriptTurn = dict[str, Any]
+Transcript = list[TranscriptTurn]
+
 PlanEntry = Union["Glitchling", Mapping[str, Any]]
 
 
@@ -132,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
 
@@ -186,7 +192,7 @@ def plan_glitchlings(
 
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
-    from datasets import Dataset  # type: ignore
+    from datasets import Dataset
 elif _DatasetsDataset is not None:
     Dataset = _DatasetsDataset
 else:
@@ -202,8 +208,8 @@ def _is_transcript(
     *,
     allow_empty: bool = True,
     require_all_content: bool = False,
-) -> bool:
-    """Return `True` when `value` appears to be a chat transcript."""
+) -> TypeGuard[Transcript]:
+    """Return ``True`` when ``value`` appears to be a chat transcript."""
     if not isinstance(value, list):
         return False
 
@@ -351,15 +357,17 @@ class Glitchling:
             corrupted = self.corruption_function(text, *args, **kwargs)
         return corrupted
 
-    def corrupt(self, text: str | list[dict[str, Any]]) -> str | list[dict[str, Any]]:
+    def corrupt(self, text: str | Transcript) -> str | Transcript:
         """Apply the corruption function to text or conversational transcripts."""
         if _is_transcript(text):
-            transcript = [dict(turn) for turn in text]
+            transcript: Transcript = [dict(turn) for turn in text]
             if transcript:
-                transcript[-1]["content"] = self.__corrupt(transcript[-1]["content"], **self.kwargs)
+                content = transcript[-1].get("content")
+                if isinstance(content, str):
+                    transcript[-1]["content"] = self.__corrupt(content, **self.kwargs)
             return transcript
 
-        return self.__corrupt(text, **self.kwargs)
+        return self.__corrupt(cast(str, text), **self.kwargs)
 
     def corrupt_dataset(self, dataset: Dataset, columns: list[str]) -> Dataset:
         """Apply corruption lazily across dataset columns."""
@@ -383,7 +391,7 @@ class Glitchling:
 
         return dataset.with_transform(__corrupt_row)
 
-    def __call__(self, text: str, *args: Any, **kwds: Any) -> str | list[dict[str, Any]]:
+    def __call__(self, text: str, *args: Any, **kwds: Any) -> str | Transcript:
         """Allow a glitchling to be invoked directly like a callable."""
         return self.corrupt(text, *args, **kwds)
 
@@ -426,7 +434,7 @@ class Gaggle(Glitchling):
             seed: Master seed used to derive per-glitchling seeds.
 
         """
-        super().__init__("Gaggle", self.corrupt, AttackWave.DOCUMENT, seed=seed)
+        super().__init__("Gaggle", self._corrupt_text, AttackWave.DOCUMENT, seed=seed)
         self._clones_by_index: list[Glitchling] = []
         for idx, glitchling in enumerate(glitchlings):
             clone = glitchling.clone()
@@ -528,17 +536,47 @@ class Gaggle(Glitchling):
 
         return descriptors
 
-    def corrupt(self, text: str) -> str:
-        """Apply each glitchling to the provided text sequentially."""
+    def _corrupt_text(self, text: str) -> str:
+        """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 _compose_glitchlings_rust(text, descriptors, master_seed)
-            except Exception:  # pragma: no cover - fall back to Python execution
+                return cast(str, _compose_glitchlings_rust(text, descriptors, master_seed))
+            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
         for glitchling in self.apply_order:
-            corrupted = glitchling(corrupted)
+            next_value = glitchling.corrupt(corrupted)
+            if not isinstance(next_value, str):
+                message = "Glitchling pipeline produced non-string output for string input"
+                raise TypeError(message)
+            corrupted = next_value
+
         return corrupted
+
+    def corrupt(self, text: str | Transcript) -> str | Transcript:
+        """Apply each glitchling to the provided text sequentially."""
+        if isinstance(text, str):
+            return self._corrupt_text(text)
+
+        if _is_transcript(text):
+            transcript: Transcript = [dict(turn) for turn in text]
+            if transcript and "content" in transcript[-1]:
+                content = transcript[-1]["content"]
+                if isinstance(content, str):
+                    transcript[-1]["content"] = self._corrupt_text(content)
+            return transcript
+
+        message = f"Unsupported text type for Gaggle corruption: {type(text)!r}"
+        raise TypeError(message)

glitchlings/zoo/jargoyle.py

@@ -2,20 +2,29 @@ import random
 import re
 from collections.abc import Iterable
 from dataclasses import dataclass
+from types import ModuleType
 from typing import Any, Literal, cast
 
 from glitchlings.lexicon import Lexicon, get_default_lexicon
 
+from ._rate import resolve_rate
+from .core import AttackWave, Glitchling
+
+_wordnet_module: ModuleType | None
+
 try:  # pragma: no cover - optional WordNet dependency
-    from glitchlings.lexicon.wordnet import (
-        WordNetLexicon,
-    )
-    from glitchlings.lexicon.wordnet import (
-        dependencies_available as _lexicon_dependencies_available,
-    )
-    from glitchlings.lexicon.wordnet import ensure_wordnet as _lexicon_ensure_wordnet
-except Exception:  # pragma: no cover - triggered when nltk unavailable
-    WordNetLexicon = None  # type: ignore[assignment]
+    import glitchlings.lexicon.wordnet as _wordnet_module
+except (
+    ImportError,
+    ModuleNotFoundError,
+    AttributeError,
+):  # pragma: no cover - triggered when nltk unavailable
+    _wordnet_module = None
+
+_wordnet_runtime: ModuleType | None = _wordnet_module
+
+WordNetLexicon: type[Lexicon] | None
+if _wordnet_runtime is None:
 
     def _lexicon_dependencies_available() -> bool:
         return False
@@ -26,9 +35,12 @@ except Exception:  # pragma: no cover - triggered when nltk unavailable
             "and download its WordNet corpus manually if you need legacy synonyms."
         )
 
+    WordNetLexicon = None
+else:
+    WordNetLexicon = cast(type[Lexicon], _wordnet_runtime.WordNetLexicon)
+    _lexicon_dependencies_available = _wordnet_runtime.dependencies_available
+    _lexicon_ensure_wordnet = _wordnet_runtime.ensure_wordnet
 
-from ._rate import resolve_rate
-from .core import AttackWave, Glitchling
 
 ensure_wordnet = _lexicon_ensure_wordnet
 
@@ -41,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
 
@@ -169,34 +181,36 @@ def substitute_random_synonyms(
         candidate_indices: list[int] = []
         candidate_metadata: dict[int, CandidateInfo] = {}
         for idx, tok in enumerate(tokens):
-            if idx % 2 == 0 and tok and not tok.isspace():
-                prefix, core_word, suffix = _split_token(tok)
-                if not core_word:
-                    continue
-
-                chosen_pos: str | None = None
-                synonyms: list[str] = []
+            if idx % 2 != 0 or not tok or tok.isspace():
+                continue
 
-                for pos in target_pos:
-                    if not active_lexicon.supports_pos(pos):
-                        continue
-                    synonyms = active_lexicon.get_synonyms(core_word, pos=pos)
-                    if synonyms:
-                        chosen_pos = pos
-                        break
+            prefix, core_word, suffix = _split_token(tok)
+            if not core_word:
+                continue
 
-                if not synonyms and active_lexicon.supports_pos(None):
-                    synonyms = active_lexicon.get_synonyms(core_word, pos=None)
+            chosen_pos: str | None = None
+            synonyms: list[str] = []
 
+            for tag in target_pos:
+                if not active_lexicon.supports_pos(tag):
+                    continue
+                synonyms = active_lexicon.get_synonyms(core_word, pos=tag)
                 if synonyms:
-                    candidate_indices.append(idx)
-                    candidate_metadata[idx] = CandidateInfo(
-                        prefix=prefix,
-                        core_word=core_word,
-                        suffix=suffix,
-                        part_of_speech=chosen_pos,
-                        synonyms=synonyms,
-                    )
+                    chosen_pos = tag
+                    break
+
+            if not synonyms and active_lexicon.supports_pos(None):
+                synonyms = active_lexicon.get_synonyms(core_word, pos=None)
+
+            if synonyms:
+                candidate_indices.append(idx)
+                candidate_metadata[idx] = CandidateInfo(
+                    prefix=prefix,
+                    core_word=core_word,
+                    suffix=suffix,
+                    part_of_speech=chosen_pos,
+                    synonyms=synonyms,
+                )
 
         if not candidate_indices:
             return text

glitchlings/zoo/redactyl.py

@@ -1,8 +1,9 @@
 import random
 import re
-from typing import Any
+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,13 +117,17 @@ def redact_words(
     use_rust = _redact_words_rust is not None and isinstance(merge_adjacent, bool)
 
     if use_rust:
-        return _redact_words_rust(
-            text,
-            replacement_char,
-            clamped_rate,
-            merge_adjacent,
-            unweighted_flag,
-            rng,
+        assert _redact_words_rust is not None  # Type narrowing for mypy
+        return cast(
+            str,
+            _redact_words_rust(
+                text,
+                replacement_char,
+                clamped_rate,
+                merge_adjacent,
+                unweighted_flag,
+                rng,
+            ),
         )
 
     return _python_redact_words(

glitchlings/zoo/reduple.py

@@ -1,14 +1,13 @@
 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 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(
@@ -94,7 +93,7 @@ def reduplicate_words(
     unweighted_flag = bool(unweighted)
 
     if _reduplicate_words_rust is not None:
-        return _reduplicate_words_rust(text, clamped_rate, unweighted_flag, rng)
+        return cast(str, _reduplicate_words_rust(text, clamped_rate, unweighted_flag, rng))
 
     return _python_reduplicate_words(
         text,

glitchlings/zoo/rushmore.py

@@ -1,16 +1,15 @@
 import math
 import random
 import re
-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 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(
@@ -97,7 +96,7 @@ def delete_random_words(
     unweighted_flag = bool(unweighted)
 
     if _delete_random_words_rust is not None:
-        return _delete_random_words_rust(text, clamped_rate, unweighted_flag, rng)
+        return cast(str, _delete_random_words_rust(text, clamped_rate, unweighted_flag, rng))
 
     return _python_delete_random_words(
         text,

glitchlings/zoo/scannequin.py

@@ -1,15 +1,14 @@
 import random
 import re
-from typing import Any
+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(
@@ -126,7 +125,7 @@ def ocr_artifacts(
     clamped_rate = max(0.0, effective_rate)
 
     if _ocr_artifacts_rust is not None:
-        return _ocr_artifacts_rust(text, clamped_rate, rng)
+        return cast(str, _ocr_artifacts_rust(text, clamped_rate, rng))
 
     return _python_ocr_artifacts(text, rate=clamped_rate, rng=rng)
 

glitchlings/zoo/typogre.py

@@ -2,16 +2,15 @@ from __future__ import annotations
 
 import math
 import random
-from typing import Any, Optional
+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:
@@ -168,7 +167,10 @@ def fatfinger(
     layout = getattr(KEYNEIGHBORS, keyboard)
 
     if _fatfinger_rust is not None:
-        return _fatfinger_rust(text, max_change_rate=clamped_rate, layout=layout, rng=rng)
+        return cast(
+            str,
+            _fatfinger_rust(text, max_change_rate=clamped_rate, layout=layout, rng=rng),
+        )
 
     return _fatfinger_python(text, rate=clamped_rate, layout=layout, rng=rng)
 

glitchlings/zoo/zeedub.py

@@ -3,15 +3,14 @@ from __future__ import annotations
 import math
 import random
 from collections.abc import Sequence
-from typing import Any
+from typing import Any, cast
 
 from ._rate import resolve_rate
+from ._rust_extensions import get_rust_operation
 from .core import AttackOrder, AttackWave, Glitchling
 
-try:
-    from glitchlings._zoo_rust import inject_zero_widths as _inject_zero_widths_rust
-except ImportError:  # pragma: no cover - compiled extension not present
-    _inject_zero_widths_rust = None
+# Load Rust-accelerated operation if available
+_inject_zero_widths_rust = get_rust_operation("inject_zero_widths")
 
 _DEFAULT_ZERO_WIDTH_CHARACTERS: tuple[str, ...] = (
     "\u200b",  # ZERO WIDTH SPACE
@@ -115,7 +114,10 @@ def insert_zero_widths(
             if hasattr(rng, "getstate"):
                 python_state = rng.getstate()
             rng.setstate(state)
-        rust_result = _inject_zero_widths_rust(text, clamped_rate, list(cleaned_palette), rng)
+        rust_result = cast(
+            str,
+            _inject_zero_widths_rust(text, clamped_rate, list(cleaned_palette), rng),
+        )
         if rust_result == python_result:
             return rust_result
         if python_state is not None and hasattr(rng, "setstate"):