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

glitchlings/zoo/core.py

@@ -4,24 +4,18 @@ import inspect
 import logging
 import os
 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
+from typing import TYPE_CHECKING, Any, Callable, Protocol, TypedDict, TypeGuard, Union, cast
 
-_datasets_error: ModuleNotFoundError | None = None
-try:  # pragma: no cover - optional dependency
-    from datasets import Dataset as _DatasetsDataset
-except ModuleNotFoundError as error:  # pragma: no cover - optional dependency
-    _DatasetsDataset = None  # type: ignore[assignment]
-    _datasets_error = error
-else:
-    _datasets_error = None
+from ..compat import get_datasets_dataset, require_datasets
+
+_DatasetsDataset = get_datasets_dataset()
 
 try:  # pragma: no cover - optional dependency
-    from glitchlings._zoo_rust import (
-        compose_glitchlings as _compose_glitchlings_rust,
-        plan_glitchlings as _plan_glitchlings_rust,
-    )
+    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
@@ -35,9 +29,20 @@ _PIPELINE_ENABLE_VALUES = {"1", "true", "yes", "on"}
 _PIPELINE_DISABLE_VALUES = {"0", "false", "no", "off"}
 
 
-def _pipeline_feature_flag_enabled() -> bool:
-    """Return ``True`` when the environment does not explicitly disable the Rust pipeline."""
+class PlanSpecification(TypedDict):
+    name: str
+    scope: int
+    order: int
 
+
+TranscriptTurn = dict[str, Any]
+Transcript = list[TranscriptTurn]
+
+PlanEntry = Union["Glitchling", Mapping[str, Any]]
+
+
+def pipeline_feature_flag_enabled() -> bool:
+    """Return ``True`` when the environment does not explicitly disable the Rust pipeline."""
     value = os.environ.get(_PIPELINE_FEATURE_FLAG_ENV)
     if value is None:
         return True
@@ -51,12 +56,62 @@ def _pipeline_feature_flag_enabled() -> bool:
 
     return True
 
+
+def _pipeline_feature_flag_enabled() -> bool:
+    """Compatibility shim for legacy callers."""
+    return pipeline_feature_flag_enabled()
+
+
+def is_rust_pipeline_supported() -> bool:
+    """Return ``True`` when the optional Rust extension is importable."""
+    return _compose_glitchlings_rust is not None
+
+
+def is_rust_pipeline_enabled() -> bool:
+    """Return ``True`` when the Rust pipeline is available and not explicitly disabled."""
+    return is_rust_pipeline_supported() and pipeline_feature_flag_enabled()
+
+
+def _spec_from_glitchling(glitchling: "Glitchling") -> PlanSpecification:
+    """Create a plan specification mapping from a glitchling instance."""
+    return {
+        "name": glitchling.name,
+        "scope": int(glitchling.level),
+        "order": int(glitchling.order),
+    }
+
+
+def _normalize_plan_entry(entry: PlanEntry) -> PlanSpecification:
+    """Convert a plan entry (glitchling or mapping) into a normalized specification."""
+    if isinstance(entry, Glitchling):
+        return _spec_from_glitchling(entry)
+
+    if not isinstance(entry, Mapping):
+        message = "plan_glitchlings expects Glitchling instances or mapping specifications"
+        raise TypeError(message)
+
+    try:
+        name = str(entry["name"])
+        scope_value = int(entry["scope"])
+        order_value = int(entry["order"])
+    except KeyError as exc:  # pragma: no cover - defensive guard
+        raise ValueError(f"Plan specification missing required field: {exc.args[0]}") from exc
+    except (TypeError, ValueError) as exc:
+        raise ValueError("Plan specification fields must be coercible to integers") from exc
+
+    return {"name": name, "scope": scope_value, "order": order_value}
+
+
+def _normalize_plan_entries(entries: Sequence[PlanEntry]) -> list[PlanSpecification]:
+    """Normalize a collection of orchestration plan entries."""
+    return [_normalize_plan_entry(entry) for entry in entries]
+
+
 def _plan_glitchlings_python(
-    specs: list[dict[str, Any]],
+    specs: Sequence[Mapping[str, Any]],
     master_seed: int,
 ) -> list[tuple[int, int]]:
     """Pure-Python fallback for orchestrating glitchlings in deterministic order."""
-
     master_seed_int = int(master_seed)
     planned: list[tuple[int, int, int, int, str]] = []
     for index, spec in enumerate(specs):
@@ -71,11 +126,10 @@ def _plan_glitchlings_python(
 
 
 def _plan_glitchlings_with_rust(
-    specs: list[dict[str, Any]],
+    specs: Sequence[Mapping[str, Any]],
     master_seed: int,
 ) -> list[tuple[int, int]] | None:
     """Attempt to obtain the orchestration plan from the compiled Rust module."""
-
     if _plan_glitchlings_rust is None:
         return None
 
@@ -88,41 +142,54 @@ def _plan_glitchlings_with_rust(
     return [(int(index), int(seed)) for index, seed in plan]
 
 
-def _plan_glitchling_specs(
-    specs: list[dict[str, Any]],
+def _resolve_orchestration_plan(
+    specs: Sequence[PlanSpecification],
+    master_seed: int,
+    prefer_rust: bool,
+) -> list[tuple[int, int]]:
+    """Dispatch to the Rust planner when available, otherwise fall back to Python."""
+    if prefer_rust:
+        plan = _plan_glitchlings_with_rust(list(specs), master_seed)
+        if plan is not None:
+            return plan
+
+    return _plan_glitchlings_python(list(specs), master_seed)
+
+
+def plan_glitchling_specs(
+    specs: Sequence[Mapping[str, Any]],
     master_seed: int | None,
+    *,
+    prefer_rust: bool = True,
 ) -> list[tuple[int, int]]:
     """Resolve orchestration order and seeds from glitchling specifications."""
-
     if master_seed is None:
         message = "Gaggle orchestration requires a master seed"
         raise ValueError(message)
 
+    normalized_specs = [_normalize_plan_entry(spec) for spec in specs]
     master_seed_int = int(master_seed)
-    plan = _plan_glitchlings_with_rust(specs, master_seed_int)
-    if plan is not None:
-        return plan
-
-    return _plan_glitchlings_python(specs, master_seed_int)
+    return _resolve_orchestration_plan(normalized_specs, master_seed_int, prefer_rust)
 
 
-def _plan_glitchling_sequence(
-    glitchlings: list["Glitchling"], master_seed: int | None
+def plan_glitchlings(
+    entries: Sequence[PlanEntry],
+    master_seed: int | None,
+    *,
+    prefer_rust: bool = True,
 ) -> list[tuple[int, int]]:
-    """Derive orchestration plan for concrete glitchling instances."""
-
-    specs = [
-        {
-            "name": glitchling.name,
-            "scope": int(glitchling.level),
-            "order": int(glitchling.order),
-        }
-        for glitchling in glitchlings
-    ]
-    return _plan_glitchling_specs(specs, master_seed)
+    """Normalize glitchling instances or specs and compute an orchestration plan."""
+    if master_seed is None:
+        message = "Gaggle orchestration requires a master seed"
+        raise ValueError(message)
+
+    normalized_specs = _normalize_plan_entries(entries)
+    master_seed_int = int(master_seed)
+    return _resolve_orchestration_plan(normalized_specs, master_seed_int, prefer_rust)
+
 
 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:
@@ -138,9 +205,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
 
@@ -209,8 +275,8 @@ class Glitchling:
             order: Relative ordering within the same scope.
             seed: Optional seed for deterministic random behaviour.
             **kwargs: Additional parameters forwarded to the corruption callable.
-        """
 
+        """
         # Each Glitchling maintains its own RNG for deterministic yet isolated behavior.
         # If no seed is supplied, we fall back to Python's default entropy.
         self.seed = seed
@@ -228,7 +294,6 @@ class Glitchling:
 
     def set_param(self, key: str, value: Any) -> None:
         """Persist a parameter for use by the corruption callable."""
-
         aliases = getattr(self, "_param_aliases", {})
         canonical = aliases.get(key, key)
 
@@ -250,7 +315,6 @@ class Glitchling:
 
     def pipeline_operation(self) -> dict[str, Any] | None:
         """Return the Rust pipeline operation descriptor for this glitchling."""
-
         factory = self._pipeline_descriptor_factory
         if factory is None:
             return None
@@ -259,15 +323,11 @@ class Glitchling:
 
     def _corruption_expects_rng(self) -> bool:
         """Return `True` when the corruption function accepts an rng keyword."""
-
         cached_callable = self._cached_rng_callable
         cached_expectation = self._cached_rng_expectation
         corruption_function = self.corruption_function
 
-        if (
-            cached_callable is corruption_function
-            and cached_expectation is not None
-        ):
+        if cached_callable is corruption_function and cached_expectation is not None:
             return cached_expectation
 
         expects_rng = False
@@ -285,7 +345,6 @@ class Glitchling:
 
     def __corrupt(self, text: str, *args: Any, **kwargs: Any) -> str:
         """Execute the corruption callable, injecting the RNG when required."""
-
         # Pass rng to underlying corruption function if it expects it.
         expects_rng = self._corruption_expects_rng()
 
@@ -295,25 +354,21 @@ 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."""
-
-        if _DatasetsDataset is None:
-            message = "datasets is not installed"
-            raise ModuleNotFoundError(message) from _datasets_error
+        require_datasets("datasets is not installed")
 
         def __corrupt_row(row: dict[str, Any]) -> dict[str, Any]:
             row = dict(row)
@@ -333,14 +388,12 @@ 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)
 
     def reset_rng(self, seed: int | None = None) -> None:
         """Reset the glitchling's RNG to its initial seed."""
-
         if seed is not None:
             self.seed = seed
         if self.seed is not None:
@@ -348,7 +401,6 @@ class Glitchling:
 
     def clone(self, seed: int | None = None) -> "Glitchling":
         """Create a copy of this glitchling, optionally with a new seed."""
-
         cls = self.__class__
         filtered_kwargs = {k: v for k, v in self.kwargs.items() if k != "seed"}
         clone_seed = seed if seed is not None else self.seed
@@ -368,9 +420,6 @@ class Glitchling:
         return cls(**filtered_kwargs)
 
 
-
-
-
 class Gaggle(Glitchling):
     """A collection of glitchlings executed in a deterministic order."""
 
@@ -380,18 +429,16 @@ class Gaggle(Glitchling):
         Args:
             glitchlings: Glitchlings to orchestrate.
             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()
             setattr(clone, "_gaggle_index", idx)
             self._clones_by_index.append(clone)
 
-        self.glitchlings: dict[AttackWave, list[Glitchling]] = {
-            level: [] for level in AttackWave
-        }
+        self.glitchlings: dict[AttackWave, list[Glitchling]] = {level: [] for level in AttackWave}
         self.apply_order: list[Glitchling] = []
         self._plan: list[tuple[int, int]] = []
         self.sort_glitchlings()
@@ -399,6 +446,7 @@ class Gaggle(Glitchling):
     @staticmethod
     def derive_seed(master_seed: int, glitchling_name: str, index: int) -> int:
         """Derive a deterministic seed for a glitchling based on the master seed."""
+
         def _int_to_bytes(value: int) -> bytes:
             if value == 0:
                 return b"\x00"
@@ -425,8 +473,7 @@ class Gaggle(Glitchling):
 
     def sort_glitchlings(self) -> None:
         """Sort glitchlings by wave then order to produce application order."""
-
-        plan = _plan_glitchling_sequence(self._clones_by_index, self.seed)
+        plan = plan_glitchlings(self._clones_by_index, self.seed)
         self._plan = plan
 
         self.glitchlings = {level: [] for level in AttackWave}
@@ -451,14 +498,12 @@ class Gaggle(Glitchling):
     @staticmethod
     def rust_pipeline_supported() -> bool:
         """Return ``True`` when the compiled Rust pipeline is importable."""
-
-        return _compose_glitchlings_rust is not None
+        return is_rust_pipeline_supported()
 
     @staticmethod
     def rust_pipeline_enabled() -> bool:
         """Return ``True`` when the Rust pipeline is available and not explicitly disabled."""
-
-        return Gaggle.rust_pipeline_supported() and _pipeline_feature_flag_enabled()
+        return is_rust_pipeline_enabled()
 
     def _pipeline_descriptors(self) -> list[dict[str, Any]] | None:
         if not self.rust_pipeline_enabled():
@@ -488,18 +533,38 @@ 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:
             try:
-                return _compose_glitchlings_rust(text, descriptors, master_seed)
+                return cast(str, _compose_glitchlings_rust(text, descriptors, master_seed))
             except Exception:  # 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,18 +2,25 @@ 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,
-        dependencies_available as _lexicon_dependencies_available,
-        ensure_wordnet as _lexicon_ensure_wordnet,
-    )
+    import glitchlings.lexicon.wordnet as _wordnet_module
 except Exception:  # pragma: no cover - triggered when nltk unavailable
-    WordNetLexicon = None  # type: ignore[assignment]
+    _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
@@ -24,16 +31,18 @@ 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
 
 
 def dependencies_available() -> bool:
     """Return ``True`` when a synonym backend is accessible."""
-
     if _lexicon_dependencies_available():
         return True
 
@@ -58,7 +67,6 @@ _VALID_POS: tuple[PartOfSpeech, ...] = ("n", "v", "a", "r")
 
 def _split_token(token: str) -> tuple[str, str, str]:
     """Split a token into leading punctuation, core word, and trailing punctuation."""
-
     match = re.match(r"^(\W*)(.*?)(\W*)$", token)
     if not match:
         return "", token, ""
@@ -70,23 +78,18 @@ def _normalize_parts_of_speech(
     part_of_speech: PartOfSpeechInput,
 ) -> NormalizedPartsOfSpeech:
     """Coerce user input into a tuple of valid WordNet POS tags."""
-
     if isinstance(part_of_speech, str):
         lowered = part_of_speech.lower()
         if lowered == "any":
             return _VALID_POS
         if lowered not in _VALID_POS:
-            raise ValueError(
-                "part_of_speech must be one of 'n', 'v', 'a', 'r', or 'any'"
-            )
+            raise ValueError("part_of_speech must be one of 'n', 'v', 'a', 'r', or 'any'")
         return (cast(PartOfSpeech, lowered),)
 
     normalized: list[PartOfSpeech] = []
     for pos in part_of_speech:
         if pos not in _VALID_POS:
-            raise ValueError(
-                "part_of_speech entries must be one of 'n', 'v', 'a', or 'r'"
-            )
+            raise ValueError("part_of_speech entries must be one of 'n', 'v', 'a', or 'r'")
         if pos not in normalized:
             normalized.append(pos)
     if not normalized:
@@ -118,6 +121,7 @@ def substitute_random_synonyms(
     """Replace words with random lexicon-driven synonyms.
 
     Parameters
+    ----------
     - text: Input text.
     - rate: Max proportion of candidate words to replace (default 0.01).
     - part_of_speech: WordNet POS tag(s) to target. Accepts "n", "v", "a", "r",
@@ -134,6 +138,7 @@ def substitute_random_synonyms(
     - Replacement positions chosen via rng.sample.
     - Synonyms sourced through the lexicon; the default backend derives
       deterministic subsets per word and part-of-speech using the active seed.
+
     """
     effective_rate = resolve_rate(
         rate=rate,
@@ -168,38 +173,40 @@ def substitute_random_synonyms(
         # Split but keep whitespace separators so we can rebuild easily
         tokens = re.split(r"(\s+)", text)
 
-        # Collect indices of candidate tokens (even positions 0,2,.. are words given our split design)
+        # Collect candidate word indices (even positions are words because separators are kept)
         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
@@ -296,9 +303,7 @@ class Jargoyle(Glitchling):
                         current_lexicon.reseed(self.seed)
                     else:
                         if hasattr(self, "_external_lexicon_original_seed"):
-                            original_seed = getattr(
-                                self, "_external_lexicon_original_seed", None
-                            )
+                            original_seed = getattr(self, "_external_lexicon_original_seed", None)
                             current_lexicon.reseed(original_seed)
         elif canonical == "lexicon" and isinstance(value, Lexicon):
             if getattr(self, "_initializing", False):

glitchlings/zoo/mim1c.py

@@ -1,11 +1,11 @@
-from collections.abc import Collection
 import random
+from collections.abc import Collection
 from typing import Literal
 
 from confusable_homoglyphs import confusables
 
-from .core import AttackOrder, AttackWave, Glitchling
 from ._rate import resolve_rate
+from .core import AttackOrder, AttackWave, Glitchling
 
 
 def swap_homoglyphs(
@@ -21,16 +21,21 @@ def swap_homoglyphs(
     """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.
+    - 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.
+    -----
+    - 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,
@@ -46,9 +51,7 @@ def swap_homoglyphs(
         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
-    ]
+    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
@@ -57,9 +60,7 @@ def swap_homoglyphs(
     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
-        ]
+        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: