glitchlings 0.4.1__cp312-cp312-macosx_11_0_universal2.whl → 0.4.3__cp312-cp312-macosx_11_0_universal2.whl

glitchlings/main.py

@@ -4,16 +4,18 @@ from __future__ import annotations
 
 import argparse
 import difflib
-from pathlib import Path
 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
 from .zoo import (
-    Glitchling,
-    Gaggle,
     BUILTIN_GLITCHLINGS,
     DEFAULT_GLITCHLING_NAMES,
+    Gaggle,
+    Glitchling,
     parse_glitchling_spec,
     summon,
 )
@@ -26,8 +28,8 @@ def build_parser() -> argparse.ArgumentParser:
 
     Returns:
         argparse.ArgumentParser: The configured argument parser instance.
-    """
 
+    """
     parser = argparse.ArgumentParser(
         description=(
             "Summon glitchlings to corrupt text. Provide input text as an argument, "
@@ -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=(
@@ -157,7 +160,6 @@ def build_lexicon_parser() -> argparse.ArgumentParser:
 
 def list_glitchlings() -> None:
     """Print information about the available built-in glitchlings."""
-
     for key in DEFAULT_GLITCHLING_NAMES:
         glitchling = BUILTIN_GLITCHLINGS[key]
         display_name = glitchling.name
@@ -178,27 +180,30 @@ def read_text(args: argparse.Namespace, parser: argparse.ArgumentParser) -> str:
 
     Raises:
         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(
-        "No input text provided. Supply text as an argument, use --file, pipe input, or pass --sample."
+        "No input text provided. Supply text as an argument, use --file, pipe input, or "
+        "pass --sample."
     )
     raise AssertionError("parser.error should exit")
 
@@ -211,7 +216,6 @@ def summon_glitchlings(
     config_path: Path | None = None,
 ) -> Gaggle:
     """Instantiate the requested glitchlings and bundle them in a ``Gaggle``."""
-
     if config_path is not None:
         if names:
             parser.error("Cannot combine --config with --glitchling.")
@@ -225,30 +229,30 @@ 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")
 
 
-
 def show_diff(original: str, corrupted: str) -> None:
     """Display a unified diff between the original and corrupted text."""
-
     diff_lines = list(
         difflib.unified_diff(
             original.splitlines(keepends=True),
@@ -274,8 +278,8 @@ def run_cli(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
 
     Returns:
         int: Exit code for the process (``0`` on success).
-    """
 
+    """
     if args.list:
         list_glitchlings()
         return 0
@@ -288,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)
@@ -300,7 +307,6 @@ def run_cli(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
 
 def run_build_lexicon(args: argparse.Namespace) -> int:
     """Delegate to the vector lexicon cache builder using CLI arguments."""
-
     from glitchlings.lexicon.vector import main as vector_main
 
     vector_args = [
@@ -337,8 +343,8 @@ def main(argv: list[str] | None = None) -> int:
 
     Returns:
         int: Exit code suitable for use with ``sys.exit``.
-    """
 
+    """
     if argv is None:
         raw_args = sys.argv[1:]
     else:

glitchlings/util/__init__.py

@@ -1,12 +1,27 @@
 import difflib
 from collections.abc import Iterable
 
-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."
+__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
+    """Compare two strings using SequenceMatcher and return
     grouped adjacent opcodes (excluding 'equal' tags).
 
     Each element is a tuple: (tag, a_text, b_text).
@@ -39,7 +54,6 @@ 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):

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

@@ -3,16 +3,26 @@ from __future__ import annotations
 import ast
 from typing import Any
 
-from .typogre import Typogre, typogre
-from .mim1c import Mim1c, mim1c
-from .jargoyle import Jargoyle, jargoyle, dependencies_available as _jargoyle_available
 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 .redactyl import Redactyl, redactyl
 from .scannequin import Scannequin, scannequin
+from .typogre import Typogre, typogre
 from .zeedub import Zeedub, zeedub
-from .core import Glitchling, Gaggle
 
 __all__ = [
     "Typogre",
@@ -21,6 +31,8 @@ __all__ = [
     "mim1c",
     "Jargoyle",
     "jargoyle",
+    "Apostrofae",
+    "apostrofae",
     "Adjax",
     "adjax",
     "Reduple",
@@ -35,6 +47,11 @@ __all__ = [
     "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",
@@ -44,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])
@@ -55,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,
@@ -71,7 +89,6 @@ 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.")
@@ -98,14 +115,10 @@ def parse_glitchling_spec(specification: str) -> Glitchling:
     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
+        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."
-        )
+        raise ValueError(f"Glitchling '{name}' parameters must be provided as keyword arguments.")
 
     kwargs: dict[str, Any] = {}
     for keyword in call_expr.keywords:
@@ -128,7 +141,6 @@ def parse_glitchling_spec(specification: str) -> Glitchling:
 
 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.")
@@ -142,7 +154,6 @@ def get_glitchling_class(name: str) -> type[Glitchling]:
 
 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):

glitchlings/zoo/_ocr_confusions.py

@@ -26,9 +26,7 @@ def load_confusion_table() -> list[tuple[str, list[str]]]:
 
     # 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])
-    )
+    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

@@ -9,11 +9,8 @@ def resolve_rate(
     legacy_name: str,
 ) -> float:
     """Return the effective rate while enforcing mutual exclusivity."""
-
     if rate is not None and legacy_value is not None:
-        raise ValueError(
-            f"Specify either 'rate' or '{legacy_name}', not both."
-        )
+        raise ValueError(f"Specify either 'rate' or '{legacy_name}', not both.")
     if rate is not None:
         return rate
     if legacy_value is not None:

glitchlings/zoo/_sampling.py

@@ -17,7 +17,6 @@ def weighted_sample_without_replacement(
     handling and RNG interactions so the Python and Rust implementations remain
     aligned.
     """
-
     if k < 0:
         raise ValueError("Sample size cannot be negative")
 

glitchlings/zoo/_text_utils.py

@@ -10,13 +10,11 @@ _TOKEN_EDGES_PATTERN = re.compile(r"^(\W*)(.*?)(\W*)$")
 
 def split_preserving_whitespace(text: str) -> list[str]:
     """Split text while keeping whitespace tokens for stable reconstruction."""
-
     return _WORD_SPLIT_PATTERN.split(text)
 
 
 def split_token_edges(token: str) -> tuple[str, str, str]:
     """Return leading, core, and trailing segments for a token."""
-
     match = _TOKEN_EDGES_PATTERN.match(token)
     if match is None:
         return "", token, ""
@@ -25,7 +23,6 @@ def split_token_edges(token: str) -> tuple[str, str, str]:
 
 def token_core_length(token: str) -> int:
     """Return the length of the main word characters for weighting heuristics."""
-
     _, core, _ = split_token_edges(token)
     candidate = core if core else token
     length = len(candidate)
@@ -50,7 +47,6 @@ class WordToken:
     @property
     def has_core(self) -> bool:
         """Return ``True`` when the token contains at least one core character."""
-
         return bool(self.core)
 
 
@@ -65,8 +61,8 @@ def collect_word_tokens(
         tokens: Token sequence produced by :func:`split_preserving_whitespace`.
         skip_first_word: Exclude the first candidate token (used by Rushmore to
             preserve leading words).
-    """
 
+    """
     start = 2 if skip_first_word else 0
     collected: list[WordToken] = []
     for index in range(start, len(tokens), 2):

glitchlings/zoo/adjax.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import random
-from typing import Any
+from typing import Any, cast
 
 from ._rate import resolve_rate
 from ._text_utils import split_preserving_whitespace, split_token_edges
@@ -20,7 +20,6 @@ def _python_swap_adjacent_words(
     rng: random.Random,
 ) -> str:
     """Swap the cores of adjacent words while keeping affixes and spacing intact."""
-
     tokens = split_preserving_whitespace(text)
     if len(tokens) < 2:
         return text
@@ -72,7 +71,6 @@ def swap_adjacent_words(
     swap_rate: float | None = None,
 ) -> str:
     """Swap adjacent word cores while preserving spacing and punctuation."""
-
     effective_rate = resolve_rate(
         rate=rate,
         legacy_value=swap_rate,
@@ -85,7 +83,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)
 

glitchlings/zoo/apostrofae.py

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