glitchlings 0.2.5__cp312-cp312-win_amd64.whl → 0.9.3__cp312-cp312-win_amd64.whl

glitchlings/zoo/mim1c.py

@@ -1,11 +1,55 @@
-from collections.abc import Collection
+"""Rust-backed Mim1c glitchling that swaps characters for homoglyphs."""
+
+from __future__ import annotations
+
 import random
-from typing import Literal
+from collections.abc import Collection, Iterable
+from typing import Literal, cast
+
+from glitchlings.constants import DEFAULT_MIM1C_RATE, MIM1C_DEFAULT_CLASSES
+from glitchlings.internal.rust_ffi import mim1c_rust, resolve_seed
+
+from .core import AttackOrder, AttackWave, Glitchling, PipelineOperationPayload
+
+
+def _normalise_classes(
+    value: object,
+) -> tuple[str, ...] | Literal["all"] | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        if value.lower() == "all":
+            return "all"
+        return (value,)
+    if isinstance(value, Iterable):
+        return tuple(str(item) for item in value)
+    raise TypeError("classes must be an iterable of strings or 'all'")
 
-from confusable_homoglyphs import confusables
 
-from .core import AttackOrder, AttackWave, Glitchling
-from ._rate import resolve_rate
+def _normalise_banned(value: object) -> tuple[str, ...] | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return tuple(value)
+    if isinstance(value, Iterable):
+        return tuple(str(item) for item in value)
+    raise TypeError("banned_characters must be an iterable of strings")
+
+
+def _serialise_classes(
+    value: tuple[str, ...] | Literal["all"] | None,
+) -> list[str] | Literal["all"] | None:
+    if value is None:
+        return None
+    if value == "all":
+        return "all"
+    return list(value)
+
+
+def _serialise_banned(value: tuple[str, ...] | None) -> list[str] | None:
+    if value is None:
+        return None
+    return list(value)
 
 
 def swap_homoglyphs(
@@ -15,81 +59,48 @@ def swap_homoglyphs(
     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.
-    - 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.
-    - rng: Optional RNG; overrides seed.
-
-    Notes
-    - 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",
-    )
+    """Replace characters with visually confusable homoglyphs via the Rust engine."""
+
+    effective_rate = DEFAULT_MIM1C_RATE if rate is None else rate
 
-    if rng is None:
-        rng = random.Random(seed)
-
-    if classes is None:
-        classes = ["LATIN", "GREEK", "CYRILLIC"]
-
-    target_chars = [char for char in text if char.isalnum()]
-    confusable_chars = [
-        char for char in target_chars if char in confusables.confusables_data
-    ]
-    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 ())
-    for char in confusable_chars:
-        if done >= num_replacements:
-            break
-        options = [
-            o["c"] for o in confusables.confusables_data[char] if len(o["c"]) == 1
-        ]
-        if classes != "all":
-            options = [opt for opt in options if confusables.alias(opt) in classes]
-        if banned_set:
-            options = [opt for opt in options if opt not in banned_set]
-        if not options:
-            continue
-        text = text.replace(char, rng.choice(options), 1)
-        done += 1
-    return text
+    normalised_classes = _normalise_classes(classes)
+    normalised_banned = _normalise_banned(banned_characters)
+
+    if normalised_classes is None:
+        payload_classes: list[str] | Literal["all"] | None = list(MIM1C_DEFAULT_CLASSES)
+    else:
+        payload_classes = _serialise_classes(normalised_classes)
+    payload_banned = _serialise_banned(normalised_banned)
+
+    return mim1c_rust(
+        text,
+        effective_rate,
+        payload_classes,
+        payload_banned,
+        resolve_seed(seed, rng),
+    )
 
 
 class Mim1c(Glitchling):
     """Glitchling that swaps characters for visually similar homoglyphs."""
 
+    flavor = (
+        "Breaks your parser by replacing some characters in strings with "
+        "doppelgangers. Don't worry, this text is clean. ;)"
+    )
+
     def __init__(
         self,
         *,
         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",
-        )
+        effective_rate = DEFAULT_MIM1C_RATE if rate is None else rate
+        normalised_classes = _normalise_classes(classes)
+        normalised_banned = _normalise_banned(banned_characters)
         super().__init__(
             name="Mim1c",
             corruption_function=swap_homoglyphs,
@@ -97,12 +108,39 @@ class Mim1c(Glitchling):
             order=AttackOrder.LAST,
             seed=seed,
             rate=effective_rate,
-            classes=classes,
-            banned_characters=banned_characters,
+            classes=normalised_classes,
+            banned_characters=normalised_banned,
         )
 
+    def pipeline_operation(self) -> PipelineOperationPayload:
+        rate_value = self.kwargs.get("rate")
+        rate = DEFAULT_MIM1C_RATE if rate_value is None else float(rate_value)
+
+        descriptor: dict[str, object] = {"type": "mimic", "rate": rate}
+
+        classes = self.kwargs.get("classes")
+        serialised_classes = _serialise_classes(classes)
+        if serialised_classes is not None:
+            descriptor["classes"] = serialised_classes
+
+        banned = self.kwargs.get("banned_characters")
+        serialised_banned = _serialise_banned(banned)
+        if serialised_banned:
+            descriptor["banned_characters"] = serialised_banned
+
+        return cast(PipelineOperationPayload, descriptor)
+
+    def set_param(self, key: str, value: object) -> None:
+        if key == "classes":
+            super().set_param(key, _normalise_classes(value))
+            return
+        if key == "banned_characters":
+            super().set_param(key, _normalise_banned(value))
+            return
+        super().set_param(key, value)
+
 
 mim1c = Mim1c()
 
 
-__all__ = ["Mim1c", "mim1c"]
+__all__ = ["Mim1c", "mim1c", "swap_homoglyphs"]

glitchlings/zoo/pedant/__init__.py

@@ -0,0 +1,107 @@
+"""Pedant glitchling integrating grammar evolutions with Rust acceleration."""
+
+from __future__ import annotations
+
+import random
+from typing import Any, cast
+
+from glitchlings.internal.rust_ffi import resolve_seed
+
+from ..core import AttackOrder, AttackWave, Glitchling, PipelineOperationPayload
+from .core import EVOLUTIONS, PedantBase, apply_pedant
+from .stones import STONES, PedantStone
+
+
+def _coerce_stone(value: Any) -> PedantStone:
+    """Return a :class:`PedantStone` enum member for ``value``."""
+
+    return PedantStone.from_value(value)
+
+
+def pedant_transform(
+    text: str,
+    *,
+    stone: PedantStone | str = PedantStone.COEURITE,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+) -> str:
+    """Apply a pedant evolution to text."""
+
+    pedant_stone = _coerce_stone(stone)
+    if pedant_stone not in EVOLUTIONS:
+        raise ValueError(f"Unknown pedant stone: {stone!r}")
+
+    effective_seed = resolve_seed(seed, rng)
+
+    return apply_pedant(
+        text,
+        stone=pedant_stone,
+        seed=effective_seed,
+    )
+
+
+def _build_pipeline_descriptor(glitch: Glitchling) -> PipelineOperationPayload:
+    stone_value = glitch.kwargs.get("stone")
+    if stone_value is None:
+        message = "Pedant requires a stone to build the pipeline descriptor"
+        raise RuntimeError(message)
+
+    pedant_stone = _coerce_stone(stone_value)
+
+    return cast(
+        PipelineOperationPayload,
+        {"type": "pedant", "stone": pedant_stone.label},
+    )
+
+
+class Pedant(Glitchling):
+    """Glitchling that deterministically applies pedant evolutions."""
+
+    _param_aliases = {
+        "form": "stone",
+        "stone_name": "stone",
+    }
+
+    def __init__(
+        self,
+        *,
+        stone: PedantStone | str = PedantStone.COEURITE,
+        seed: int | None = None,
+    ) -> None:
+        super().__init__(
+            name="Pedant",
+            corruption_function=pedant_transform,
+            scope=AttackWave.WORD,
+            order=AttackOrder.LATE,
+            seed=seed,
+            pipeline_operation=_build_pipeline_descriptor,
+            stone=_coerce_stone(stone),
+        )
+        if seed is not None:
+            self.set_param("seed", int(seed))
+
+    def set_param(self, key: str, value: object) -> None:
+        if key in {"stone", "form", "stone_name"}:
+            super().set_param(key, _coerce_stone(value))
+            return
+        super().set_param(key, value)
+
+    def reset_rng(self, seed: int | None = None) -> None:
+        super().reset_rng(seed)
+        if self.seed is None:
+            self.kwargs.pop("seed", None)
+            return
+        self.kwargs["seed"] = int(self.seed)
+
+
+pedant = Pedant()
+
+__all__ = [
+    "PedantBase",
+    "Pedant",
+    "pedant",
+    "pedant_transform",
+    "EVOLUTIONS",
+    "STONES",
+    "PedantStone",
+]

glitchlings/zoo/pedant/core.py

@@ -0,0 +1,105 @@
+"""Core classes for the pedant evolution chain backed by the Rust pipeline."""
+
+from __future__ import annotations
+
+from typing import Dict, Type
+
+from glitchlings.internal.rust_ffi import pedant_rust
+
+from ..core import Gaggle
+from .stones import PedantStone
+
+
+def apply_pedant(
+    text: str,
+    *,
+    stone: PedantStone,
+    seed: int,
+) -> str:
+    """Apply a pedant transformation via the Rust extension."""
+
+    return pedant_rust(
+        text,
+        stone=stone.label,
+        seed=int(seed),
+    )
+
+
+class PedantEvolution:
+    """Concrete pedant form that delegates to the Rust implementation."""
+
+    stone: PedantStone
+
+    def __init__(
+        self,
+        seed: int,
+        *,
+        stone: PedantStone | None = None,
+    ) -> None:
+        resolved_stone = stone or getattr(self, "stone", None)
+        if resolved_stone is None:  # pragma: no cover - defensive guard
+            raise ValueError("PedantEvolution requires a PedantStone")
+        self.seed = int(seed)
+        self.stone = resolved_stone
+
+    def move(self, text: str) -> str:
+        result = apply_pedant(text, stone=self.stone, seed=self.seed)
+        return result
+
+
+class PedantBase:
+    """Base pedant capable of evolving into specialised grammar forms."""
+
+    name: str = "Pedant"
+    type: str = "Normal"
+    flavor: str = "A novice grammarian waiting to evolve."
+
+    def __init__(self, seed: int, *, root_seed: int | None = None) -> None:
+        self.seed = int(seed)
+        self.root_seed = int(seed if root_seed is None else root_seed)
+
+    def evolve(self, stone: PedantStone | str) -> PedantEvolution:
+        pedant_stone = PedantStone.from_value(stone)
+        form_cls = EVOLUTIONS.get(pedant_stone)
+        if form_cls is None:  # pragma: no cover - sanity guard
+            raise KeyError(f"Unknown stone: {stone}")
+        derived_seed = Gaggle.derive_seed(self.root_seed, pedant_stone.label, 0)
+        return form_cls(seed=int(derived_seed))
+
+    def move(self, text: str) -> str:
+        return text
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging helper
+        return f"<{self.__class__.__name__} seed={self.seed} type={self.type}>"
+
+
+EVOLUTIONS: Dict[PedantStone, Type[PedantEvolution]] = {}
+
+
+try:  # pragma: no cover - import resolution occurs at runtime
+    from .forms import (
+        Aetheria,
+        Apostrofae,
+        Commama,
+        Correctopus,
+        Fewerling,
+        Kiloa,
+        Subjunic,
+        Whomst,
+    )
+except ImportError:  # pragma: no cover - partial imports during type checking
+    pass
+else:
+    EVOLUTIONS = {
+        PedantStone.WHOM: Whomst,
+        PedantStone.FEWERITE: Fewerling,
+        PedantStone.COEURITE: Aetheria,
+        PedantStone.CURLITE: Apostrofae,
+        PedantStone.SUBJUNCTITE: Subjunic,
+        PedantStone.OXFORDIUM: Commama,
+        PedantStone.ORTHOGONITE: Correctopus,
+        PedantStone.METRICITE: Kiloa,
+    }
+
+
+__all__ = ["PedantBase", "PedantEvolution", "EVOLUTIONS", "apply_pedant"]

glitchlings/zoo/pedant/forms.py

@@ -0,0 +1,74 @@
+"""Pedant evolution forms delegating to the Rust-backed core."""
+
+from __future__ import annotations
+
+from .core import PedantEvolution
+from .stones import PedantStone
+
+
+class Whomst(PedantEvolution):
+    stone = PedantStone.WHOM
+    name = "Whomst"
+    type = "Ghost"
+    flavor = "Insists upon objective-case precision."
+
+
+class Fewerling(PedantEvolution):
+    stone = PedantStone.FEWERITE
+    name = "Fewerling"
+    type = "Fairy"
+    flavor = "Counts only countable nouns."
+
+
+class Aetheria(PedantEvolution):
+    stone = PedantStone.COEURITE
+    name = "Aetheria"
+    type = "Psychic"
+    flavor = "Resurrects archaic ligatures and diacritics."
+
+
+class Apostrofae(PedantEvolution):
+    stone = PedantStone.CURLITE
+    name = "Apostrofae"
+    type = "Fairy"
+    flavor = "Curves quotes into typeset perfection."
+
+
+class Subjunic(PedantEvolution):
+    stone = PedantStone.SUBJUNCTITE
+    name = "Subjunic"
+    type = "Psychic"
+    flavor = "Corrects the subjunctive wherever it can."
+
+
+class Commama(PedantEvolution):
+    stone = PedantStone.OXFORDIUM
+    name = "Commama"
+    type = "Steel"
+    flavor = "Oxonian hero of the list."
+
+
+class Kiloa(PedantEvolution):
+    stone = PedantStone.METRICITE
+    name = "Kiloa"
+    type = "Electric"
+    flavor = "Measures the world in rational units."
+
+
+class Correctopus(PedantEvolution):
+    stone = PedantStone.ORTHOGONITE
+    name = "Correctopus"
+    type = "Dragon"
+    flavor = "The final editor, breathing blue ink."
+
+
+__all__ = [
+    "Whomst",
+    "Fewerling",
+    "Aetheria",
+    "Apostrofae",
+    "Subjunic",
+    "Commama",
+    "Kiloa",
+    "Correctopus",
+]

glitchlings/zoo/pedant/stones.py

@@ -0,0 +1,74 @@
+"""Evolution stones recognised by the pedant."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+@dataclass(frozen=True)
+class Stone:
+    """Descriptor for an evolution stone."""
+
+    name: str
+    type: str
+    effect: str
+
+
+class PedantStone(Enum):
+    """Enumeration of evolution stones available to the pedant."""
+
+    WHOM = Stone("Whom Stone", "Ghost", "Encourages object-pronoun precision.")
+    FEWERITE = Stone("Fewerite", "Fairy", "Obsesses over countable quantities.")
+    COEURITE = Stone("Coeurite", "Psychic", "Restores archaic ligatures to modern words.")
+    CURLITE = Stone(
+        "Curlite",
+        "Fairy",
+        "Coaches punctuation to embrace typographic curls.",
+    )
+    SUBJUNCTITE = Stone("Subjunctite", "Psychic", "Demands contrary-to-fact phrasing.")
+    OXFORDIUM = Stone("Oxfordium", "Steel", "Polishes serial comma usage.")
+    ORTHOGONITE = Stone("Orthogonite", "Dragon", "Unlocks the legendary Correctopus.")
+    METRICITE = Stone("Metricite", "Electric", "Compels metrication of measures.")
+
+    @property
+    def descriptor(self) -> Stone:
+        """Return the metadata describing this stone."""
+
+        return self.value
+
+    @property
+    def label(self) -> str:
+        """Return the display name for this stone."""
+
+        return self.value.name
+
+    def __str__(self) -> str:  # pragma: no cover - convenience for reprs/CLI echo
+        return self.label
+
+    @classmethod
+    def from_value(cls, value: object) -> "PedantStone":
+        """Normalise ``value`` into a :class:`PedantStone` member."""
+
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, Stone):
+            for member in cls:
+                if member.value == value:
+                    return member
+            msg = f"Unknown pedant stone descriptor: {value!r}"
+            raise ValueError(msg)
+
+        try:
+            return _STONE_BY_NAME[str(value)]
+        except KeyError as exc:
+            raise ValueError(f"Unknown pedant stone: {value!r}") from exc
+
+
+_STONE_BY_NAME: dict[str, PedantStone] = {stone.value.name: stone for stone in PedantStone}
+
+
+STONES: dict[str, Stone] = {stone.label: stone.descriptor for stone in PedantStone}
+
+
+__all__ = ["Stone", "PedantStone", "STONES"]