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

glitchlings/dlc/_shared.py

@@ -0,0 +1,296 @@
+"""Shared utilities for DLC integrations."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, cast
+
+from ..util.transcripts import is_transcript
+from ..zoo.core import Gaggle
+
+
+def resolve_columns(dataset: Any, columns: Sequence[str] | None) -> list[str]:
+    """Identify which dataset columns should be corrupted."""
+    available = set(getattr(dataset, "column_names", ()))
+
+    if columns is not None:
+        missing = sorted(set(columns) - available)
+        if missing:
+            missing_str = ", ".join(missing)
+            raise ValueError(f"Columns not found in dataset: {missing_str}")
+        return list(columns)
+
+    for candidate in ("prompt", "question"):
+        if candidate in available:
+            return [candidate]
+
+    try:
+        dataset_length = len(dataset)
+    except TypeError:
+        preview_rows: list[dict[str, Any]]
+        take_fn = getattr(dataset, "take", None)
+        if callable(take_fn):
+            preview_rows = list(take_fn(1))
+        else:
+            iterator = iter(dataset)
+            try:
+                first_row = next(iterator)
+            except StopIteration:
+                preview_rows = []
+            else:
+                preview_rows = [first_row]
+        sample = dict(preview_rows[0]) if preview_rows else {}
+    else:
+        sample = dataset[0] if dataset_length else {}
+    inferred = [
+        name for name in getattr(dataset, "column_names", ()) if isinstance(sample.get(name), str)
+    ]
+
+    if inferred:
+        return inferred
+
+    raise ValueError("Unable to determine which dataset columns to corrupt.")
+
+
+def normalize_column_spec(
+    columns: str | int | Sequence[str | int] | None,
+) -> list[str | int] | None:
+    """Normalize a column specification into a list of keys or indices.
+
+    Args:
+        columns: Column specification as a single value, sequence of values, or None.
+
+    Returns:
+        A list of column identifiers, or None if input was None.
+
+    Raises:
+        ValueError: If an empty sequence is provided.
+    """
+    if columns is None:
+        return None
+
+    if isinstance(columns, (str, int)):
+        return [columns]
+
+    normalized = list(columns)
+    if not normalized:
+        raise ValueError("At least one column must be specified")
+    return normalized
+
+
+def is_textual_candidate(value: Any) -> bool:
+    """Return ``True`` when ``value`` looks like text that glitchlings can corrupt.
+
+    Args:
+        value: The value to check for textual content.
+
+    Returns:
+        True if the value appears to be textual content.
+    """
+    if isinstance(value, str):
+        return True
+
+    if is_transcript(value, allow_empty=False, require_all_content=True):
+        return True
+
+    if isinstance(value, Sequence) and not isinstance(value, (bytes, bytearray, str)):
+        if not value:
+            return False
+        if all(isinstance(item, str) for item in value):
+            return True
+        if is_transcript(list(value), allow_empty=False, require_all_content=True):
+            return True
+
+    return False
+
+
+def corrupt_text_value(value: Any, gaggle: Gaggle) -> Any:
+    """Return ``value`` with glitchlings applied when possible.
+
+    Args:
+        value: The value to corrupt (string, transcript, or sequence of strings).
+        gaggle: The gaggle of glitchlings to apply.
+
+    Returns:
+        The corrupted value, preserving the original type where possible.
+    """
+    if isinstance(value, str):
+        return gaggle.corrupt(value)
+
+    if is_transcript(value, allow_empty=True):
+        return gaggle.corrupt(value)
+
+    if isinstance(value, list) and value and all(isinstance(item, str) for item in value):
+        return [gaggle.corrupt(item) for item in value]
+
+    if isinstance(value, tuple) and value and all(isinstance(item, str) for item in value):
+        return tuple(gaggle.corrupt(item) for item in value)
+
+    return value
+
+
+def infer_batch_targets(batch: Any) -> list[str | int] | None:
+    """Infer which fields should be glitched from a representative batch.
+
+    Args:
+        batch: A batch from a DataLoader (mapping, sequence, or textual value).
+
+    Returns:
+        A list of column keys (strings) or indices (ints), or None if the batch
+        itself is textual content.
+
+    Raises:
+        ValueError: If unable to infer textual columns/indices.
+        TypeError: If the batch type is unsupported.
+    """
+    if isinstance(batch, Mapping):
+        inferred = [key for key, value in batch.items() if is_textual_candidate(value)]
+        if inferred:
+            return inferred
+        raise ValueError("Unable to infer which mapping columns contain text")
+
+    if isinstance(batch, Sequence) and not isinstance(batch, (bytes, bytearray, str)):
+        inferred_indices: list[str | int] = [
+            idx for idx, value in enumerate(batch) if is_textual_candidate(value)
+        ]
+        if inferred_indices:
+            return inferred_indices
+        raise ValueError("Unable to infer which sequence indices contain text")
+
+    if is_textual_candidate(batch):
+        return None
+
+    raise TypeError("Unsupported DataLoader batch type for glitching")
+
+
+def corrupt_batch(batch: Any, targets: list[str | int] | None, gaggle: Gaggle) -> Any:
+    """Return batch with glitchlings applied to the specified targets.
+
+    Args:
+        batch: The batch to corrupt (mapping, sequence, or textual value).
+        targets: List of column keys (strings) or indices (ints), or None to
+                 corrupt the entire batch as textual content.
+        gaggle: The gaggle of glitchlings to apply.
+
+    Returns:
+        The corrupted batch, preserving the original type.
+
+    Raises:
+        TypeError: If batch type is unsupported or targets are incompatible.
+        ValueError: If a specified target is not found in the batch.
+    """
+    if targets is None:
+        return corrupt_text_value(batch, gaggle)
+
+    if isinstance(batch, Mapping):
+        # Use copy() if available, otherwise dict()
+        if hasattr(batch, "copy"):
+            mutated = batch.copy()
+        else:
+            mutated = dict(batch)
+
+        for key in targets:
+            if not isinstance(key, str):
+                raise TypeError("Mapping batches require string column names")
+            if key not in mutated:
+                raise ValueError(f"Column '{key}' not found in DataLoader batch")
+            mutated[key] = corrupt_text_value(mutated[key], gaggle)
+        return mutated
+
+    if isinstance(batch, Sequence) and not isinstance(batch, (bytes, bytearray, str)):
+        mutated_sequence = list(batch)
+        for index in targets:
+            if not isinstance(index, int):
+                raise TypeError("Sequence batches require integer column indices")
+            try:
+                mutated_sequence[index] = corrupt_text_value(mutated_sequence[index], gaggle)
+            except IndexError as exc:  # pragma: no cover - defensive
+                raise IndexError("Column index out of range for DataLoader batch") from exc
+        if isinstance(batch, tuple):
+            return tuple(mutated_sequence)
+        return mutated_sequence
+
+    raise TypeError("Unsupported DataLoader batch type for glitching")
+
+
+class BaseGlitchedDataLoader:
+    """Proxy dataloader that glitches batches produced by the wrapped loader.
+
+    This class wraps a dataloader and applies glitchlings to specified columns
+    in each batch as it's yielded. It supports both mapping-based batches (dict-like)
+    and sequence-based batches (list/tuple-like).
+    """
+
+    def __init__(self, dataloader: Any, columns: list[str | int], gaggle: Gaggle) -> None:
+        """Initialize the glitched dataloader.
+
+        Args:
+            dataloader: The underlying dataloader to wrap.
+            columns: List of column names (strings) or indices (ints) to corrupt.
+            gaggle: The gaggle of glitchlings to apply.
+        """
+        self._dataloader = dataloader
+        self._columns = columns
+        self._gaggle = gaggle
+
+    def __iter__(self) -> Any:
+        """Yield corrupted batches from the underlying dataloader."""
+        for batch in self._dataloader:
+            yield corrupt_batch(batch, self._columns, self._gaggle)
+
+    def __len__(self) -> int:
+        """Return the number of batches in the dataloader."""
+        return len(self._dataloader)
+
+    def __getattr__(self, attribute: str) -> Any:
+        """Proxy attribute access to the underlying dataloader."""
+        return getattr(self._dataloader, attribute)
+
+
+def wrap_dataloader(dataloader: Any, columns: list[str | int], gaggle: Gaggle) -> Any:
+    """Wrap a dataloader (or nested structure) to apply glitchlings lazily.
+
+    This function recursively wraps dataloaders in nested structures (mappings,
+    lists, tuples, etc.) so that all dataloaders in the structure will yield
+    corrupted batches.
+
+    Args:
+        dataloader: The dataloader or nested structure to wrap.
+        columns: List of column names (strings) or indices (ints) to corrupt.
+        gaggle: The gaggle of glitchlings to apply.
+
+    Returns:
+        The wrapped dataloader or structure, with the same type as the input.
+    """
+    if dataloader is None:
+        return None
+
+    if isinstance(dataloader, Mapping):
+        mapping_type = cast(type[Any], dataloader.__class__)
+        return mapping_type(
+            {key: wrap_dataloader(value, columns, gaggle) for key, value in dataloader.items()}
+        )
+
+    if isinstance(dataloader, list):
+        return [wrap_dataloader(value, columns, gaggle) for value in dataloader]
+
+    if isinstance(dataloader, tuple):
+        return tuple(wrap_dataloader(value, columns, gaggle) for value in dataloader)
+
+    if isinstance(dataloader, Sequence) and not isinstance(dataloader, (str, bytes, bytearray)):
+        sequence_type = cast(type[Any], dataloader.__class__)
+        return sequence_type(wrap_dataloader(value, columns, gaggle) for value in dataloader)
+
+    return BaseGlitchedDataLoader(dataloader, columns, gaggle)
+
+
+__all__ = [
+    "BaseGlitchedDataLoader",
+    "corrupt_batch",
+    "corrupt_text_value",
+    "infer_batch_targets",
+    "is_textual_candidate",
+    "normalize_column_spec",
+    "resolve_columns",
+    "wrap_dataloader",
+]

glitchlings/dlc/gutenberg.py

@@ -0,0 +1,400 @@
+"""Integration helpers for the py-gutenberg library.
+
+This module provides a wrapper around the GutenbergAPI that applies
+glitchlings to book text as it's fetched.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from functools import cached_property
+from typing import Any, Protocol, TypeAlias, cast
+
+from ..util.adapters import coerce_gaggle
+from ..zoo import Gaggle, Glitchling
+from ._shared import corrupt_text_value
+
+#: Default Gutendex API instance URL (public instance hosted at gutendex.com).
+DEFAULT_GUTENDEX_URL = "https://gutendex.com"
+
+
+class PersonProtocol(Protocol):
+    """Minimal interface for py-gutenberg Person objects."""
+
+    name: str
+
+
+class BookProtocol(Protocol):
+    """Minimal interface for py-gutenberg Book objects."""
+
+    id: int
+    title: str
+    authors: list[PersonProtocol]
+    translators: list[PersonProtocol]
+    subjects: list[str]
+    bookshelves: list[str]
+    languages: list[str]
+    copyright: bool
+    media_type: str
+    formats: dict[str, str]
+    download_count: int
+
+    def get_text(self) -> str: ...
+
+
+class GutenbergAPIProtocol(Protocol):
+    """Subset of the py-gutenberg API we rely on."""
+
+    instance_url: str
+
+    def get_all_books(self) -> Iterable[BookProtocol]: ...
+
+    def get_public_domain_books(self) -> Iterable[BookProtocol]: ...
+
+    def get_copyrighted_books(self) -> Iterable[BookProtocol]: ...
+
+    def get_books_by_author(self, author: str) -> Iterable[BookProtocol]: ...
+
+    def get_books_by_ids(self, ids: list[int]) -> Iterable[BookProtocol]: ...
+
+    def get_books_by_language(self, languages: list[str]) -> Iterable[BookProtocol]: ...
+
+    def get_books_by_search(self, query: str) -> Iterable[BookProtocol]: ...
+
+    def get_books_by_mime_type(self, mime_type: str) -> Iterable[BookProtocol]: ...
+
+    def get_books_ascending(self) -> Iterable[BookProtocol]: ...
+
+    def get_oldest(self) -> Iterable[BookProtocol]: ...
+
+    def get_latest(self, topic: str = "recent") -> Iterable[BookProtocol]: ...
+
+    def get_book(self, book_id: int) -> BookProtocol: ...
+
+    def get_book_metadata(self, book_id: int) -> BookProtocol: ...
+
+    def get_book_text(self, book_id: int) -> BookProtocol: ...
+
+
+Person: TypeAlias = PersonProtocol
+Book: TypeAlias = BookProtocol
+GutenbergAPI: TypeAlias = GutenbergAPIProtocol
+
+
+@dataclass
+class GlitchedBook:
+    """A Book wrapper that corrupts text content via glitchlings.
+
+    This class wraps a py-gutenberg Book object but provides corrupted text
+    when accessed. The original Book attributes are preserved.
+
+    Attributes:
+        id: The Gutenberg book ID.
+        title: The corrupted book title.
+        original_title: The original (uncorrupted) book title.
+        authors: List of book authors.
+        translators: List of book translators.
+        subjects: List of subject categories.
+        bookshelves: List of bookshelf categories.
+        languages: List of language codes.
+        copyright: Whether the book is under copyright.
+        media_type: The media type of the book.
+        formats: Dictionary mapping MIME types to download URLs.
+        download_count: Number of times the book has been downloaded.
+    """
+
+    id: int
+    title: str
+    original_title: str
+    authors: list[Person]
+    translators: list[Person]
+    subjects: list[str]
+    bookshelves: list[str]
+    languages: list[str]
+    copyright: bool
+    media_type: str
+    formats: dict[str, str]
+    download_count: int
+    _original_book: Book = field(repr=False)
+    _gaggle: Gaggle = field(repr=False)
+
+    @classmethod
+    def from_book(cls, book: Book, gaggle: Gaggle) -> GlitchedBook:
+        """Create a GlitchedBook from a py-gutenberg Book.
+
+        Args:
+            book: The original Book object from py-gutenberg.
+            gaggle: The gaggle of glitchlings to apply to text.
+
+        Returns:
+            A GlitchedBook that corrupts text with the provided gaggle.
+        """
+        # Use shared utility for consistent corruption; cast tells mypy this is str
+        corrupted_title = cast(str, corrupt_text_value(book.title, gaggle))
+        return cls(
+            id=book.id,
+            title=corrupted_title,
+            original_title=book.title,
+            authors=book.authors,
+            translators=book.translators,
+            subjects=book.subjects,
+            bookshelves=book.bookshelves,
+            languages=book.languages,
+            copyright=book.copyright,
+            media_type=book.media_type,
+            formats=book.formats,
+            download_count=book.download_count,
+            _original_book=book,
+            _gaggle=gaggle,
+        )
+
+    @cached_property
+    def _text_content(self) -> str:
+        """Lazily fetch and corrupt the full text content of the book."""
+        original_text: str = self._original_book.get_text()
+        return cast(str, corrupt_text_value(original_text, self._gaggle))
+
+    def get_text(self) -> str:
+        """Fetch and corrupt the full text content of the book.
+
+        This method fetches the book's text from Project Gutenberg and applies
+        glitchlings corruption to it. The text is fetched fresh on the first call
+        and cached for subsequent calls.
+
+        Returns:
+            The corrupted full text of the book.
+
+        Raises:
+            AttributeError: If the underlying Book doesn't support get_text().
+        """
+        return self._text_content
+
+    def __repr__(self) -> str:
+        """Return a concise representation of the GlitchedBook."""
+        return (
+            f"GlitchedBook(id={self.id}, title={self.title!r}, "
+            f"authors={[a.name for a in self.authors]!r})"
+        )
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to the original book."""
+        return getattr(self._original_book, name)
+
+
+class GlitchenbergAPI:
+    """A wrapper around GutenbergAPI that corrupts book text with glitchlings.
+
+    This class provides the same interface as GutenbergAPI but applies
+    glitchlings to corrupt book text as it's fetched.
+
+    Example:
+        >>> from glitchlings.dlc.gutenberg import GlitchenbergAPI
+        >>> from glitchlings import Typogre
+        >>> api = GlitchenbergAPI(Typogre(rate=0.05), seed=42)
+        >>> book = api.get_book(1342)  # Pride and Prejudice
+        >>> print(book.title)  # Title will have typos applied
+    """
+
+    def __init__(
+        self,
+        glitchlings: Glitchling | Gaggle | str | Iterable[str | Glitchling],
+        *,
+        seed: int = 151,
+        instance_url: str = DEFAULT_GUTENDEX_URL,
+    ) -> None:
+        """Initialize the GlitchenbergAPI.
+
+        Args:
+            glitchlings: A glitchling, gaggle, or specification of glitchlings to apply.
+            seed: RNG seed for deterministic corruption (default: 151).
+            instance_url: The Gutendex instance URL to use for API requests.
+                Defaults to the public instance at gutendex.com. For production use,
+                consider self-hosting Gutendex.
+        """
+        self._gaggle = coerce_gaggle(glitchlings, seed=seed)
+        self._api = _get_gutenberg_api(instance_url)
+
+    @property
+    def instance_url(self) -> str:
+        """Return the Gutendex instance URL."""
+        return str(self._api.instance_url)
+
+    @property
+    def gaggle(self) -> Gaggle:
+        """Return the gaggle used for corruption."""
+        return self._gaggle
+
+    def _corrupt_book(self, book: Book) -> GlitchedBook:
+        """Apply glitchlings to a Book object."""
+        return GlitchedBook.from_book(book, self._gaggle)
+
+    def _corrupt_books(self, books: Iterable[Book]) -> list[GlitchedBook]:
+        """Apply glitchlings to a list of Book objects."""
+        return [self._corrupt_book(book) for book in books]
+
+    def corrupt_books(self, books: list[Book]) -> list[GlitchedBook]:
+        """Apply glitchlings to a list of Book objects.
+
+        This method allows batch corruption of books fetched from other sources
+        or the underlying API.
+
+        Args:
+            books: List of py-gutenberg Book objects to corrupt.
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+
+        Example:
+            >>> # Fetch from underlying API and corrupt separately
+            >>> raw_books = api._api.get_books_by_author("Austen")
+            >>> glitched = api.corrupt_books(raw_books)
+        """
+        return self._corrupt_books(books)
+
+    # Methods that return lists of books
+    def get_all_books(self) -> list[GlitchedBook]:
+        """Get all books with glitchling corruption applied."""
+        return self._corrupt_books(self._api.get_all_books())
+
+    def get_public_domain_books(self) -> list[GlitchedBook]:
+        """Get public domain books with glitchling corruption applied."""
+        return self._corrupt_books(self._api.get_public_domain_books())
+
+    def get_copyrighted_books(self) -> list[GlitchedBook]:
+        """Get copyrighted books with glitchling corruption applied."""
+        return self._corrupt_books(self._api.get_copyrighted_books())
+
+    def get_books_by_author(self, author: str) -> list[GlitchedBook]:
+        """Get books by author with glitchling corruption applied.
+
+        Args:
+            author: Author name to search for.
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+        """
+        return self._corrupt_books(self._api.get_books_by_author(author))
+
+    def get_books_by_ids(self, ids: list[int]) -> list[GlitchedBook]:
+        """Get books by IDs with glitchling corruption applied.
+
+        Args:
+            ids: List of Gutenberg book IDs to retrieve.
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+        """
+        return self._corrupt_books(self._api.get_books_by_ids(ids))
+
+    def get_books_by_language(self, languages: list[str]) -> list[GlitchedBook]:
+        """Get books by language with glitchling corruption applied.
+
+        Args:
+            languages: List of language codes (e.g., ["en", "fr"]).
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+        """
+        return self._corrupt_books(self._api.get_books_by_language(languages))
+
+    def get_books_by_search(self, query: str) -> list[GlitchedBook]:
+        """Search for books with glitchling corruption applied.
+
+        Args:
+            query: Search query string.
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+        """
+        return self._corrupt_books(self._api.get_books_by_search(query))
+
+    def get_books_by_mime_type(self, mime_type: str) -> list[GlitchedBook]:
+        """Get books by MIME type with glitchling corruption applied.
+
+        Args:
+            mime_type: MIME type filter (e.g., "text/plain").
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+        """
+        return self._corrupt_books(self._api.get_books_by_mime_type(mime_type))
+
+    def get_books_ascending(self) -> list[GlitchedBook]:
+        """Get books sorted ascending with glitchling corruption applied."""
+        return self._corrupt_books(self._api.get_books_ascending())
+
+    def get_oldest(self) -> list[GlitchedBook]:
+        """Get oldest books with glitchling corruption applied."""
+        return self._corrupt_books(self._api.get_oldest())
+
+    def get_latest(self, topic: str = "recent") -> list[GlitchedBook]:
+        """Get latest books by topic with glitchling corruption applied.
+
+        Args:
+            topic: Topic string to filter books by (e.g., "fiction", "science").
+                Defaults to "recent".
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+        """
+        return self._corrupt_books(self._api.get_latest(topic))
+
+    # Methods that return single books
+    def get_book(self, book_id: int) -> GlitchedBook:
+        """Get a book by ID with glitchling corruption applied.
+
+        Args:
+            book_id: Gutenberg book ID.
+
+        Returns:
+            GlitchedBook with corrupted text.
+        """
+        return self._corrupt_book(self._api.get_book(book_id))
+
+    def get_book_metadata(self, book_id: int) -> GlitchedBook:
+        """Get book metadata by ID with glitchling corruption applied.
+
+        Args:
+            book_id: Gutenberg book ID.
+
+        Returns:
+            GlitchedBook with corrupted metadata.
+        """
+        return self._corrupt_book(self._api.get_book_metadata(book_id))
+
+    def get_book_text(self, book_id: int) -> GlitchedBook:
+        """Get book text by ID with glitchling corruption applied.
+
+        Args:
+            book_id: Gutenberg book ID.
+
+        Returns:
+            GlitchedBook with corrupted text.
+        """
+        return self._corrupt_book(self._api.get_book_text(book_id))
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to the underlying API."""
+        return getattr(self._api, name)
+
+
+def _get_gutenberg_api(instance_url: str) -> GutenbergAPI:
+    """Import and return a GutenbergAPI instance.
+
+    Raises:
+        ImportError: If py-gutenberg is not installed.
+    """
+    try:
+        from gutenberg import GutenbergAPI
+    except ImportError as exc:
+        raise ImportError(
+            "py-gutenberg is required for the GlitchenbergAPI integration. "
+            "Install it with: pip install py-gutenberg"
+        ) from exc
+
+    api = GutenbergAPI(instance_url=instance_url)
+    return cast(GutenbergAPIProtocol, api)
+
+
+__all__ = ["DEFAULT_GUTENDEX_URL", "GlitchenbergAPI", "GlitchedBook"]