glitchlings 0.10.2__cp312-cp312-macosx_11_0_universal2.whl

glitchlings/zoo/mim1c.py

@@ -0,0 +1,148 @@
+"""Rust-backed Mim1c glitchling that swaps characters for homoglyphs."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Collection, Iterable
+from typing import Any, 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'")
+
+
+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(
+    text: str,
+    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,
+) -> str:
+    """Replace characters with visually confusable homoglyphs via the Rust engine."""
+
+    effective_rate = DEFAULT_MIM1C_RATE if rate is None else rate
+
+    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,
+        classes: list[str] | Literal["all"] | None = None,
+        banned_characters: Collection[str] | None = None,
+        seed: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        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,
+            scope=AttackWave.CHARACTER,
+            order=AttackOrder.LAST,
+            seed=seed,
+            rate=effective_rate,
+            classes=normalised_classes,
+            banned_characters=normalised_banned,
+            **kwargs,
+        )
+
+    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", "swap_homoglyphs"]

glitchlings/zoo/pedant/__init__.py

@@ -0,0 +1,109 @@
+"""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,
+        **kwargs: Any,
+    ) -> 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),
+            **kwargs,
+        )
+        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"]

glitchlings/zoo/redactyl.py

@@ -0,0 +1,97 @@
+import random
+from typing import Any, cast
+
+from glitchlings.constants import DEFAULT_REDACTYL_CHAR, DEFAULT_REDACTYL_RATE
+from glitchlings.internal.rust_ffi import redact_words_rust, resolve_seed
+
+from .core import AttackWave, Glitchling, PipelineOperationPayload
+
+# Backwards compatibility alias
+FULL_BLOCK = DEFAULT_REDACTYL_CHAR
+
+
+def redact_words(
+    text: str,
+    replacement_char: str | None = DEFAULT_REDACTYL_CHAR,
+    rate: float | None = None,
+    merge_adjacent: bool | None = False,
+    seed: int = 151,
+    rng: random.Random | None = None,
+    *,
+    unweighted: bool = False,
+) -> str:
+    """Redact random words by replacing their characters."""
+    effective_rate = DEFAULT_REDACTYL_RATE if rate is None else rate
+
+    replacement = DEFAULT_REDACTYL_CHAR if replacement_char is None else str(replacement_char)
+    merge = False if merge_adjacent is None else bool(merge_adjacent)
+
+    clamped_rate = max(0.0, min(effective_rate, 1.0))
+    unweighted_flag = bool(unweighted)
+
+    return redact_words_rust(
+        text,
+        replacement,
+        clamped_rate,
+        merge,
+        unweighted_flag,
+        resolve_seed(seed, rng),
+    )
+
+
+class Redactyl(Glitchling):
+    """Glitchling that redacts words with block characters."""
+
+    flavor = "Some things are better left ████████."
+
+    def __init__(
+        self,
+        *,
+        replacement_char: str = DEFAULT_REDACTYL_CHAR,
+        rate: float | None = None,
+        merge_adjacent: bool = False,
+        seed: int = 151,
+        unweighted: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        effective_rate = DEFAULT_REDACTYL_RATE if rate is None else rate
+        super().__init__(
+            name="Redactyl",
+            corruption_function=redact_words,
+            scope=AttackWave.WORD,
+            seed=seed,
+            replacement_char=replacement_char,
+            rate=effective_rate,
+            merge_adjacent=merge_adjacent,
+            unweighted=unweighted,
+            **kwargs,
+        )
+
+    def pipeline_operation(self) -> PipelineOperationPayload:
+        replacement_char_value = self.kwargs.get("replacement_char", DEFAULT_REDACTYL_CHAR)
+        rate_value = self.kwargs.get("rate", DEFAULT_REDACTYL_RATE)
+        merge_value = self.kwargs.get("merge_adjacent", False)
+
+        replacement_char = str(
+            DEFAULT_REDACTYL_CHAR if replacement_char_value is None else replacement_char_value
+        )
+        rate = float(DEFAULT_REDACTYL_RATE if rate_value is None else rate_value)
+        merge_adjacent = bool(merge_value)
+        unweighted = bool(self.kwargs.get("unweighted", False))
+
+        return cast(
+            PipelineOperationPayload,
+            {
+                "type": "redact",
+                "replacement_char": replacement_char,
+                "rate": rate,
+                "merge_adjacent": merge_adjacent,
+                "unweighted": unweighted,
+            },
+        )
+
+
+redactyl = Redactyl()
+
+
+__all__ = ["Redactyl", "redactyl", "redact_words"]