glitchlings 0.4.1__tar.gz → 0.4.2__tar.gz

{glitchlings-0.4.1 → glitchlings-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glitchlings
-Version: 0.4.1
+Version: 0.4.2
 Summary: Monsters for your language games.
 Author: osoleve
 License:                                  Apache License
@@ -239,6 +239,16 @@ Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: hypothesis>=6.140.0; extra == "dev"
 Requires-Dist: numpy<=2.0,>=1.24; extra == "dev"
+Requires-Dist: mkdocs>=1.6.0; extra == "dev"
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "dev"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
+Requires-Dist: mkdocstrings-python>=1.10.0; extra == "dev"
+Requires-Dist: interrogate>=1.5.0; extra == "dev"
+Requires-Dist: black>=24.4.0; extra == "dev"
+Requires-Dist: isort>=5.13.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: pre-commit>=3.8.0; extra == "dev"
 Dynamic: license-file
 
 #
@@ -338,10 +348,66 @@ They're horrible little gremlins, but they're not _unreasonable_.
 
 Keyboard warriors can challenge them directly via the `glitchlings` command:
 
+<!-- BEGIN: CLI_USAGE -->
 ```bash
 # Discover which glitchlings are currently on the loose.
 glitchlings --list
+```
+
+```text
+   Typogre — scope: Character, order: early
+     Mim1c — scope: Character, order: last
+  Jargoyle — scope: Word, order: normal
+     Adjax — scope: Word, order: normal
+   Reduple — scope: Word, order: normal
+  Rushmore — scope: Word, order: normal
+  Redactyl — scope: Word, order: normal
+Scannequin — scope: Character, order: late
+    Zeedub — scope: Character, order: last
+```
+
+```bash
+# Review the full CLI contract.
+glitchlings --help
+```
 
+```text
+usage: glitchlings [-h] [-g SPEC] [-s SEED] [-f FILE] [--sample] [--diff]
+                   [--list] [-c CONFIG]
+                   [text]
+
+Summon glitchlings to corrupt text. Provide input text as an argument, via
+--file, or pipe it on stdin.
+
+positional arguments:
+  text                  Text to corrupt. If omitted, stdin is used or --sample
+                        provides fallback text.
+
+options:
+  -h, --help            show this help message and exit
+  -g SPEC, --glitchling SPEC
+                        Glitchling to apply, optionally with parameters like
+                        Typogre(rate=0.05). Repeat for multiples; defaults to
+                        all built-ins.
+  -s SEED, --seed SEED  Seed controlling deterministic corruption order
+                        (default: 151).
+  -f FILE, --file FILE  Read input text from a file instead of the command
+                        line argument.
+  --sample              Use the included SAMPLE_TEXT when no other input is
+                        provided.
+  --diff                Show a unified diff between the original and corrupted
+                        text.
+  --list                List available glitchlings and exit.
+  -c CONFIG, --config CONFIG
+                        Load glitchlings from a YAML configuration file.
+```
+<!-- END: CLI_USAGE -->
+
+Run `python docs/build_cli_reference.py` whenever you tweak the CLI so the README stays in sync with the actual output. The script executes the commands above and replaces the block between the markers automatically.
+
+Prefer inline tweaks? You can still configure glitchlings directly in the shell:
+
+```bash
 # Run Typogre against the contents of a file and inspect the diff.
 glitchlings -g typogre --file documents/report.txt --diff
 
@@ -355,8 +421,6 @@ echo "Beware LLM-written flavor-text" | glitchlings -g mim1c
 glitchlings --config experiments/chaos.yaml "Let slips the glitchlings of war"
 ```
 
-Use `--help` for a complete breakdown of available options, including support for parameterised glitchlings via `-g "Name(arg=value, ...)"` to mirror the Python API.
-
 Attack configurations live in plain YAML files so you can version-control experiments without touching code:
 
 ```yaml

{glitchlings-0.4.1 → glitchlings-0.4.2}/README.md

@@ -95,10 +95,66 @@ They're horrible little gremlins, but they're not _unreasonable_.
 
 Keyboard warriors can challenge them directly via the `glitchlings` command:
 
+<!-- BEGIN: CLI_USAGE -->
 ```bash
 # Discover which glitchlings are currently on the loose.
 glitchlings --list
+```
+
+```text
+   Typogre — scope: Character, order: early
+     Mim1c — scope: Character, order: last
+  Jargoyle — scope: Word, order: normal
+     Adjax — scope: Word, order: normal
+   Reduple — scope: Word, order: normal
+  Rushmore — scope: Word, order: normal
+  Redactyl — scope: Word, order: normal
+Scannequin — scope: Character, order: late
+    Zeedub — scope: Character, order: last
+```
+
+```bash
+# Review the full CLI contract.
+glitchlings --help
+```
 
+```text
+usage: glitchlings [-h] [-g SPEC] [-s SEED] [-f FILE] [--sample] [--diff]
+                   [--list] [-c CONFIG]
+                   [text]
+
+Summon glitchlings to corrupt text. Provide input text as an argument, via
+--file, or pipe it on stdin.
+
+positional arguments:
+  text                  Text to corrupt. If omitted, stdin is used or --sample
+                        provides fallback text.
+
+options:
+  -h, --help            show this help message and exit
+  -g SPEC, --glitchling SPEC
+                        Glitchling to apply, optionally with parameters like
+                        Typogre(rate=0.05). Repeat for multiples; defaults to
+                        all built-ins.
+  -s SEED, --seed SEED  Seed controlling deterministic corruption order
+                        (default: 151).
+  -f FILE, --file FILE  Read input text from a file instead of the command
+                        line argument.
+  --sample              Use the included SAMPLE_TEXT when no other input is
+                        provided.
+  --diff                Show a unified diff between the original and corrupted
+                        text.
+  --list                List available glitchlings and exit.
+  -c CONFIG, --config CONFIG
+                        Load glitchlings from a YAML configuration file.
+```
+<!-- END: CLI_USAGE -->
+
+Run `python docs/build_cli_reference.py` whenever you tweak the CLI so the README stays in sync with the actual output. The script executes the commands above and replaces the block between the markers automatically.
+
+Prefer inline tweaks? You can still configure glitchlings directly in the shell:
+
+```bash
 # Run Typogre against the contents of a file and inspect the diff.
 glitchlings -g typogre --file documents/report.txt --diff
 
@@ -112,8 +168,6 @@ echo "Beware LLM-written flavor-text" | glitchlings -g mim1c
 glitchlings --config experiments/chaos.yaml "Let slips the glitchlings of war"
 ```
 
-Use `--help` for a complete breakdown of available options, including support for parameterised glitchlings via `-g "Name(arg=value, ...)"` to mirror the Python API.
-
 Attack configurations live in plain YAML files so you can version-control experiments without touching code:
 
 ```yaml

{glitchlings-0.4.1 → glitchlings-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "glitchlings"
-version = "0.4.1"
+version = "0.4.2"
 description = "Monsters for your language games."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -56,6 +56,16 @@ dev = [
     "pytest>=8.0.0",
     "hypothesis>=6.140.0",
     "numpy>=1.24,<=2.0",
+    "mkdocs>=1.6.0",
+    "mkdocstrings[python]>=0.24.0",
+    "mkdocs-material>=9.5.0",
+    "mkdocstrings-python>=1.10.0",
+    "interrogate>=1.5.0",
+    "black>=24.4.0",
+    "isort>=5.13.0",
+    "ruff>=0.6.0",
+    "mypy>=1.8.0",
+    "pre-commit>=3.8.0",
 ]
 
 [build-system]
@@ -85,3 +95,66 @@ debug = false
 pythonpath = [
     "src",
 ]
+
+[tool.interrogate]
+config = true
+fail-under = 80
+ignore-init-module = true
+ignore-module = true
+ignore-nested-functions = true
+ignore-private = true
+ignore-semiprivate = true
+ignore-magic = true
+ignore-property-decorators = false
+color = true
+quiet = false
+exclude = [
+    "tests",
+    "docs",
+    "rust",
+    "benchmarks",
+]
+
+[tool.black]
+line-length = 100
+target-version = ["py310"]
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.mypy]
+python_version = "3.10"
+follow_imports = "skip"
+ignore_missing_imports = true
+enable_error_code = ["ignore-without-code"]
+
+[[tool.mypy.overrides]]
+module = [
+    "glitchlings.util.adapters",
+    "glitchlings.dlc._shared",
+    "glitchlings.dlc.huggingface",
+    "glitchlings.dlc.prime",
+]
+strict = true
+
+[[tool.mypy.overrides]]
+module = [
+    "glitchlings.compat",
+    "glitchlings.config",
+    "glitchlings.lexicon",
+    "glitchlings.lexicon.*",
+    "glitchlings.zoo",
+    "glitchlings.zoo.*",
+    "glitchlings.main",
+    "glitchlings.__main__",
+    "glitchlings.__init__",
+]
+ignore_errors = true

{glitchlings-0.4.1 → glitchlings-0.4.2}/rust/zoo/src/text_buffer.rs

@@ -172,10 +172,7 @@ impl TextBuffer {
     }
 
     /// Replace multiple words in a single pass, avoiding repeated reindexing.
-    pub fn replace_words_bulk<I>(
-        &mut self,
-        replacements: I,
-    ) -> Result<(), TextBufferError>
+    pub fn replace_words_bulk<I>(&mut self, replacements: I) -> Result<(), TextBufferError>
     where
         I: IntoIterator<Item = (usize, String)>,
     {
@@ -435,10 +432,7 @@ mod tests {
     fn bulk_replace_words_updates_multiple_entries() {
         let mut buffer = TextBuffer::from_str("alpha beta gamma delta");
         buffer
-            .replace_words_bulk(vec![
-                (0, "delta".to_string()),
-                (3, "alpha".to_string()),
-            ])
+            .replace_words_bulk(vec![(0, "delta".to_string()), (3, "alpha".to_string())])
             .expect("bulk replace succeeds");
         assert_eq!(buffer.to_string(), "delta beta gamma alpha");
         let spans = buffer.spans();

{glitchlings-0.4.1 → glitchlings-0.4.2}/src/glitchlings/__init__.py

@@ -1,29 +1,33 @@
+from .config import AttackConfig, build_gaggle, load_attack_config
+from .util import SAMPLE_TEXT
 from .zoo import (
-    Typogre,
-    typogre,
-    Mim1c,
-    mim1c,
-    Jargoyle,
-    jargoyle,
     Adjax,
-    adjax,
+    Gaggle,
+    Glitchling,
+    Jargoyle,
+    Mim1c,
     Redactyl,
-    redactyl,
     Reduple,
-    reduple,
     Rushmore,
-    rushmore,
     Scannequin,
-    scannequin,
+    Typogre,
     Zeedub,
-    zeedub,
-    Glitchling,
-    Gaggle,
+    adjax,
+    is_rust_pipeline_enabled,
+    is_rust_pipeline_supported,
+    jargoyle,
+    mim1c,
+    pipeline_feature_flag_enabled,
+    plan_glitchling_specs,
+    plan_glitchlings,
+    redactyl,
+    reduple,
+    rushmore,
+    scannequin,
     summon,
+    typogre,
+    zeedub,
 )
-from .config import AttackConfig, build_gaggle, load_attack_config
-from .util import SAMPLE_TEXT
-
 
 __all__ = [
     "Typogre",
@@ -47,6 +51,11 @@ __all__ = [
     "summon",
     "Glitchling",
     "Gaggle",
+    "plan_glitchlings",
+    "plan_glitchling_specs",
+    "is_rust_pipeline_enabled",
+    "is_rust_pipeline_supported",
+    "pipeline_feature_flag_enabled",
     "SAMPLE_TEXT",
     "AttackConfig",
     "build_gaggle",

{glitchlings-0.4.1 → glitchlings-0.4.2}/src/glitchlings/__main__.py

@@ -4,6 +4,5 @@ import sys
 
 from .main import main
 
-
 if __name__ == "__main__":
     sys.exit(main())

glitchlings-0.4.2/src/glitchlings/compat.py

@@ -0,0 +1,215 @@
+"""Compatibility helpers centralising optional dependency imports and extras."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from importlib import import_module, metadata
+from types import ModuleType
+from typing import Any, Iterable
+
+try:  # pragma: no cover - packaging is bundled with modern Python environments
+    from packaging.markers import default_environment
+    from packaging.requirements import Requirement
+except ModuleNotFoundError:  # pragma: no cover - fallback when packaging missing
+    Requirement = None  # type: ignore[assignment]
+    default_environment = None  # type: ignore[assignment]
+
+_MISSING = object()
+
+
+@dataclass
+class OptionalDependency:
+    """Lazily import an optional dependency and retain the import error."""
+
+    module_name: str
+    _cached: ModuleType | object = _MISSING
+    _error: ModuleNotFoundError | None = None
+
+    def _attempt_import(self) -> ModuleType | None:
+        try:
+            module = import_module(self.module_name)
+        except ModuleNotFoundError as exc:
+            self._cached = None
+            self._error = exc
+            return None
+        else:
+            self._cached = module
+            self._error = None
+            return module
+
+    def get(self) -> ModuleType | None:
+        """Return the imported module or ``None`` when unavailable."""
+        if self._cached is _MISSING:
+            return self._attempt_import()
+        if self._cached is None:
+            return None
+        return self._cached
+
+    def load(self) -> ModuleType:
+        """Return the dependency, raising the original import error when absent."""
+        module = self.get()
+        if module is None:
+            error = self._error
+            if error is not None:
+                raise error
+            message = f"{self.module_name} is not installed"
+            raise ModuleNotFoundError(message)
+        return module
+
+    def require(self, message: str) -> ModuleType:
+        """Return the dependency or raise ``ModuleNotFoundError`` with ``message``."""
+        try:
+            return self.load()
+        except ModuleNotFoundError as exc:
+            raise ModuleNotFoundError(message) from exc
+
+    def available(self) -> bool:
+        """Return ``True`` when the dependency can be imported."""
+        return self.get() is not None
+
+    def reset(self) -> None:
+        """Forget any cached import result."""
+        self._cached = _MISSING
+        self._error = None
+
+    def attr(self, attribute: str) -> Any | None:
+        """Return ``attribute`` from the dependency when available."""
+        module = self.get()
+        if module is None:
+            return None
+        return getattr(module, attribute, None)
+
+    @property
+    def error(self) -> ModuleNotFoundError | None:
+        """Return the most recent ``ModuleNotFoundError`` (if any)."""
+        self.get()
+        return self._error
+
+
+datasets = OptionalDependency("datasets")
+verifiers = OptionalDependency("verifiers")
+jellyfish = OptionalDependency("jellyfish")
+jsonschema = OptionalDependency("jsonschema")
+nltk = OptionalDependency("nltk")
+
+
+def reset_optional_dependencies() -> None:
+    """Clear cached optional dependency imports (used by tests)."""
+    for dependency in (datasets, verifiers, jellyfish, jsonschema, nltk):
+        dependency.reset()
+
+
+def get_datasets_dataset() -> Any | None:
+    """Return Hugging Face ``Dataset`` class when the dependency is installed."""
+    return datasets.attr("Dataset")
+
+
+def require_datasets(message: str = "datasets is not installed") -> ModuleType:
+    """Ensure the Hugging Face datasets dependency is present."""
+    return datasets.require(message)
+
+
+def require_verifiers(message: str = "verifiers is not installed") -> ModuleType:
+    """Ensure the verifiers dependency is present."""
+    return verifiers.require(message)
+
+
+def require_jellyfish(message: str = "jellyfish is not installed") -> ModuleType:
+    """Ensure the jellyfish dependency is present."""
+    return jellyfish.require(message)
+
+
+def get_installed_extras(
+    extras: Iterable[str] | None = None,
+    *,
+    distribution: str = "glitchlings",
+) -> dict[str, bool]:
+    """Return a mapping of optional extras to installation availability."""
+    try:
+        dist = metadata.distribution(distribution)
+    except metadata.PackageNotFoundError:
+        return {}
+
+    provided = {extra.lower() for extra in dist.metadata.get_all("Provides-Extra") or []}
+    targets = {extra.lower() for extra in extras} if extras is not None else provided
+    requirements = dist.requires or []
+    mapping: dict[str, set[str]] = {extra: set() for extra in provided}
+
+    for requirement in requirements:
+        names = _extras_from_requirement(requirement, provided)
+        if not names:
+            continue
+        req_name = _requirement_name(requirement)
+        for extra in names:
+            mapping.setdefault(extra, set()).add(req_name)
+
+    status: dict[str, bool] = {}
+    for extra in targets:
+        deps = mapping.get(extra)
+        if not deps:
+            status[extra] = False
+            continue
+        status[extra] = all(_distribution_installed(dep) for dep in deps)
+    return status
+
+
+def _distribution_installed(name: str) -> bool:
+    try:
+        metadata.distribution(name)
+    except metadata.PackageNotFoundError:
+        return False
+    return True
+
+
+_EXTRA_PATTERN = re.compile(r'extra\\s*==\\s*"(?P<extra>[^"]+)"')
+
+
+def _extras_from_requirement(requirement: str, candidates: set[str]) -> set[str]:
+    if Requirement is not None and default_environment is not None:
+        req = Requirement(requirement)
+        if req.marker is None:
+            return set()
+        extras: set[str] = set()
+        for extra in candidates:
+            environment = default_environment()
+            environment["extra"] = extra
+            if req.marker.evaluate(environment):
+                extras.add(extra)
+        return extras
+
+    matches = set()
+    for match in _EXTRA_PATTERN.finditer(requirement):
+        extra = match.group("extra").lower()
+        if extra in candidates:
+            matches.add(extra)
+    return matches
+
+
+def _requirement_name(requirement: str) -> str:
+    if Requirement is not None:
+        req = Requirement(requirement)
+        return req.name
+
+    candidate = requirement.split(";", 1)[0].strip()
+    for delimiter in ("[", "(", " ", "<", ">", "=", "!", "~"):
+        index = candidate.find(delimiter)
+        if index != -1:
+            return candidate[:index]
+    return candidate
+
+
+__all__ = [
+    "OptionalDependency",
+    "datasets",
+    "verifiers",
+    "jellyfish",
+    "jsonschema",
+    "nltk",
+    "get_datasets_dataset",
+    "require_datasets",
+    "require_verifiers",
+    "require_jellyfish",
+    "get_installed_extras",
+    "reset_optional_dependencies",
+]