reprobate 0.1.0__py3-none-any.whl

reprobate/__init__.py

@@ -0,0 +1,22 @@
+"""reprobate: Budget-controlled repr for Python objects."""
+
+from .core import Policy, render, render_attrs, render_child
+from .registry import register
+
+__all__ = [
+    "Policy",
+    "register",
+    "render",
+    "render_attrs",
+    "render_child",
+]
+
+# Auto-register optional type renderers when their deps are available.
+from . import (
+    ext_arrow,  # noqa: F401
+    ext_numpy,  # noqa: F401
+    ext_pandas,  # noqa: F401
+    ext_pil,  # noqa: F401
+    ext_polars,  # noqa: F401
+    ext_pydantic,  # noqa: F401
+)

reprobate/core.py

@@ -0,0 +1,458 @@
+"""Core rendering engine: recursive budget-allocated repr."""
+
+import collections
+import contextvars
+import dataclasses
+from typing import Literal
+
+from .registry import get_renderer
+
+MIN_BUDGET = 5
+MIN_CHILD_BUDGET = 15
+
+PROTOCOL_METHOD = "__budget_repr__"
+
+Policy = Literal["greedy", "even"]
+_policy: contextvars.ContextVar[Policy] = contextvars.ContextVar(
+    "budget_policy", default="greedy"
+)
+_seen: contextvars.ContextVar[set[int]] = contextvars.ContextVar("seen")
+
+CIRCULAR = "<...>"
+
+
+def render(obj: object, budget: int = 200, policy: Policy = "greedy") -> str:
+    """Render a Python object within a character budget.
+
+    Priority order:
+    1. ``__budget_repr__`` protocol method on the object
+    2. Type-specific renderer from the registry
+    3. Generic fallback (primitives, containers, attribute decomposition)
+
+    Args:
+        obj: Any Python object.
+        budget: Maximum characters in the output.
+        policy: Budget allocation for object attributes.
+            ``"greedy"`` (default) gives each attr as much budget as
+            remains — first attrs get the most detail.
+            ``"even"`` divides budget equally across attrs so all
+            fields get comparable detail.
+
+    Returns:
+        A string of length <= budget representing the object.
+    """
+    policy_token = _policy.set(policy)
+    seen_token = _seen.set(set())
+    try:
+        return render_child(obj, budget)
+    finally:
+        _seen.reset(seen_token)
+        _policy.reset(policy_token)
+
+
+def render_child(obj: object, budget: int) -> str:
+    """Render a child object within an ongoing render call.
+
+    Use this instead of ``render()`` inside custom renderers to avoid
+    resetting the policy and cycle-detection state.
+    """
+    if budget < MIN_BUDGET:
+        return "..."[:budget]
+
+    # Cycle detection for mutable containers/objects.
+    # Primitives (None, bool, int, float, str, bytes) are immutable
+    # and can't form cycles, so we skip them.
+    if not isinstance(obj, (type(None), bool, int, float, str, bytes)):
+        seen = _seen.get()
+        obj_id = id(obj)
+        if obj_id in seen:
+            return CIRCULAR[:budget]
+        seen.add(obj_id)
+
+    # 1. Protocol method
+    method = getattr(type(obj), PROTOCOL_METHOD, None)
+    if method is not None:
+        return method(obj, budget)[:budget]
+
+    # 2. Registry
+    renderer = get_renderer(type(obj))
+    if renderer is not None:
+        return renderer(obj, budget)[:budget]
+
+    # 3. Generic fallback
+    return _render_generic(obj, budget)
+
+
+def _render_generic(obj: object, budget: int) -> str:
+    """Fallback renderer for unregistered types."""
+    if obj is None or isinstance(obj, (bool, int, float)):
+        return _render_primitive(obj, budget)
+
+    if isinstance(obj, str):
+        return _render_str(obj, budget)
+
+    if isinstance(obj, bytes):
+        return _render_bytes(obj, budget)
+
+    if isinstance(obj, collections.defaultdict):
+        return _render_defaultdict(obj, budget)
+
+    if isinstance(obj, collections.Counter):
+        return _render_counter(obj, budget)
+
+    if isinstance(obj, dict):
+        return _render_dict(obj, budget)
+
+    # namedtuple before plain tuple
+    if isinstance(obj, tuple) and hasattr(type(obj), "_fields"):
+        return _render_namedtuple(obj, budget)
+
+    if isinstance(obj, (list, tuple)):
+        return _render_sequence(obj, budget)
+
+    if isinstance(obj, (set, frozenset)):
+        return _render_set(obj, budget)
+
+    if isinstance(obj, collections.deque):
+        return _render_deque(obj, budget)
+
+    return _render_object(obj, budget)
+
+
+def _render_primitive(obj: object, budget: int) -> str:
+    r = repr(obj)
+    if len(r) <= budget:
+        return r
+    return r[: budget - 1] + "\u2026"
+
+
+def _render_str(obj: str, budget: int) -> str:
+    r = repr(obj)
+    if len(r) <= budget:
+        return r
+    # budget must fit: opening quote + chars + ... + closing quote = 1 + inner + 3 + 1
+    if budget < 6:
+        return r[:budget]
+    quote = r[0]
+    inner = budget - 5  # quote(1) + chars(inner) + ...(3) + quote(1)
+    return f"{quote}{obj[:inner]}...{quote}"
+
+
+def _render_bytes(obj: bytes, budget: int) -> str:
+    r = repr(obj)
+    if len(r) <= budget:
+        return r
+    if budget < 6:
+        return r[:budget]
+    inner = budget - 5  # b' + chars + ... + '
+    return f"b'{obj[:inner].decode('ascii', errors='replace')}...'"
+
+
+def _render_dict(obj: dict, budget: int) -> str:
+    if not obj:
+        return "{}"
+    n = len(obj)
+    tag = f"{{...{n} items}}"
+    if budget < len(tag):
+        return ("{...}"[:budget]) if budget >= 2 else "{"[:budget]
+    if budget <= len(tag):
+        return tag
+
+    remaining = budget - 2  # { and }
+    parts: list[str] = []
+    shown = 0
+
+    for key, value in obj.items():
+        sep_cost = 2 if parts else 0  # ", "
+        omitted = n - shown
+        reserve = len(f", ...{omitted - 1} more") if omitted > 1 else 0
+        available = remaining - sep_cost - reserve
+
+        key_r = render_child(key, min(available // 2, 40))
+        prefix = f"{key_r}: "
+        val_budget = available - len(prefix)
+
+        if val_budget < MIN_CHILD_BUDGET:
+            break
+
+        val_r = render_child(value, val_budget)
+        part = f"{prefix}{val_r}"
+        parts.append(part)
+        remaining -= len(part) + sep_cost
+        shown += 1
+
+    omitted = n - shown
+    if omitted > 0:
+        parts.append(f"...{omitted} more")
+
+    return "{" + ", ".join(parts) + "}"
+
+
+def _render_sequence(obj: list | tuple | collections.deque, budget: int) -> str:
+    open_b, close_b = ("(", ")") if isinstance(obj, tuple) else ("[", "]")
+    if not obj:
+        return open_b + close_b
+    n = len(obj)
+
+    tag = f"{open_b}...{n} items{close_b}"
+    if budget <= len(tag):
+        return tag[:budget]
+
+    remaining = budget - 2  # brackets
+    head_parts: list[str] = []
+    tail_parts: list[str] = []
+
+    # Head items
+    head_idx = 0
+    while head_idx < n:
+        sep_cost = 2 if head_parts else 0
+        omitted = n - head_idx - len(tail_parts)
+        reserve = len(f", ...{omitted - 1} more") if omitted > 1 else 0
+        available = remaining - sep_cost - reserve
+
+        if available < MIN_CHILD_BUDGET:
+            break
+
+        part = render_child(obj[head_idx], available)
+        head_parts.append(part)
+        remaining -= len(part) + sep_cost
+        head_idx += 1
+
+    # Tail item if budget allows and we skipped items
+    omitted = n - head_idx
+    if omitted > 1 and remaining > MIN_CHILD_BUDGET + 15:
+        tail_budget = min(remaining - len(f", ...{omitted - 1} more, "), remaining // 3)
+        if tail_budget >= MIN_CHILD_BUDGET:
+            tail_r = render_child(obj[-1], tail_budget)
+            tail_parts.append(tail_r)
+            remaining -= len(tail_r) + 2
+            omitted -= 1
+
+    mid = f"...{omitted} more" if omitted > 0 else None
+    all_parts = head_parts + ([mid] if mid else []) + tail_parts
+    return open_b + ", ".join(all_parts) + close_b
+
+
+def _render_set(obj: set | frozenset, budget: int) -> str:
+    prefix = "frozenset(" if isinstance(obj, frozenset) else ""
+    suffix = ")" if isinstance(obj, frozenset) else ""
+    open_b = prefix + "{"
+    close_b = "}" + suffix
+
+    if not obj:
+        if isinstance(obj, frozenset):
+            return ("frozenset()")[:budget]
+        return "set()"[:budget]
+
+    n = len(obj)
+    tag = f"{open_b}...{n} items{close_b}"
+    if budget <= len(tag):
+        return tag[:budget]
+
+    remaining = budget - len(open_b) - len(close_b)
+    parts: list[str] = []
+    shown = 0
+
+    for item in obj:
+        sep_cost = 2 if parts else 0
+        omitted = n - shown
+        reserve = len(f", ...{omitted - 1} more") if omitted > 1 else 0
+        available = remaining - sep_cost - reserve
+
+        if available < MIN_CHILD_BUDGET:
+            break
+
+        part = render_child(item, available)
+        parts.append(part)
+        remaining -= len(part) + sep_cost
+        shown += 1
+
+    omitted = n - shown
+    if omitted > 0:
+        parts.append(f"...{omitted} more")
+
+    return open_b + ", ".join(parts) + close_b
+
+
+def _type_stub(val: object) -> str:
+    """Minimal type representation: <type> or <type(len)> for sized types."""
+    type_name = type(val).__name__
+    if hasattr(val, "__len__"):
+        try:
+            return f"<{type_name}({len(val)})>"
+        except Exception:
+            pass
+    return f"<{type_name}>"
+
+
+def render_attrs(attrs: dict[str, object], type_name: str, budget: int) -> str:
+    """Render as TypeName(key=val, ...) with three-phase budget degradation.
+
+    Phase 1: Full render of values (greedy).
+    Phase 2: Stub remaining attrs as name=<type> or name=<type(len)>.
+    Phase 3: Count any remaining as ...N more.
+    """
+    tag = f"<{type_name}>"
+    n = len(attrs)
+
+    if not attrs:
+        return tag[:budget]
+
+    shell = f"{type_name}()"
+    if budget <= len(shell):
+        return tag[:budget]
+
+    remaining = budget - len(type_name) - 2  # Name( and )
+    parts: list[str] = []
+    attr_items = list(attrs.items())
+    idx = 0
+    even = _policy.get() == "even"
+
+    # Phase 1: Full render
+    while idx < n:
+        sep_cost = 2 if parts else 0
+        rest = n - idx
+        reserve = len(f", ...{rest - 1} more") if rest > 1 else 0
+        available = remaining - sep_cost - reserve
+
+        if even and rest > 1:
+            # Equal share of remaining budget per unrendered attr,
+            # accounting for separators between them.
+            per_attr = (remaining - (rest - 1) * 2) // rest
+            available = min(available, per_attr)
+
+        prefix = f"{attr_items[idx][0]}="
+        val_budget = available - len(prefix)
+
+        if val_budget < MIN_CHILD_BUDGET:
+            break
+
+        val_r = render_child(attr_items[idx][1], val_budget)
+        part = f"{prefix}{val_r}"
+        parts.append(part)
+        remaining -= len(part) + sep_cost
+        idx += 1
+
+    # Phase 2: Stub remaining with type info
+    while idx < n:
+        attr_name, attr_val = attr_items[idx]
+        stub = _type_stub(attr_val)
+        part = f"{attr_name}={stub}"
+        sep_cost = 2 if parts else 0
+        rest = n - idx - 1
+        reserve = len(f", ...{rest} more") if rest > 0 else 0
+
+        if len(part) + sep_cost + reserve > remaining:
+            break
+
+        parts.append(part)
+        remaining -= len(part) + sep_cost
+        idx += 1
+
+    # Phase 3: Count remaining
+    omitted = n - idx
+    if omitted > 0:
+        parts.append(f"...{omitted} more")
+
+    result = f"{type_name}(" + ", ".join(parts) + ")"
+    if len(result) > budget:
+        return tag[:budget]
+    return result
+
+
+def _render_namedtuple(obj: tuple, budget: int) -> str:
+    type_name = type(obj).__name__
+    fields = type(obj)._fields
+    attrs = dict(zip(fields, obj))
+    return render_attrs(attrs, type_name, budget)
+
+
+def _render_defaultdict(obj: collections.defaultdict, budget: int) -> str:
+    factory = obj.default_factory
+    factory_name = factory.__name__ if factory is not None else "None"
+    prefix = f"defaultdict({factory_name}, "
+    suffix = ")"
+
+    shell = f"defaultdict({factory_name})"
+    if budget <= len(shell):
+        return shell[:budget]
+
+    inner_budget = budget - len(prefix) - len(suffix)
+    if inner_budget < MIN_BUDGET:
+        return shell[:budget]
+
+    inner = _render_dict(dict(obj), inner_budget)
+    return prefix + inner + suffix
+
+
+def _render_counter(obj: collections.Counter, budget: int) -> str:
+    prefix = "Counter("
+    suffix = ")"
+
+    if not obj:
+        return "Counter()"[:budget]
+
+    shell = "Counter()"
+    if budget <= len(shell):
+        return shell[:budget]
+
+    inner_budget = budget - len(prefix) - len(suffix)
+    if inner_budget < MIN_BUDGET:
+        return shell[:budget]
+
+    inner = _render_dict(dict(obj.most_common()), inner_budget)
+    return prefix + inner + suffix
+
+
+def _render_deque(obj: collections.deque, budget: int) -> str:
+    if not obj:
+        return "deque()"[:budget]
+
+    prefix = "deque("
+    suffix = ")"
+    shell = prefix + suffix
+
+    if budget <= len(shell):
+        return shell[:budget]
+
+    inner_budget = budget - len(prefix) - len(suffix)
+    if inner_budget < MIN_BUDGET:
+        return shell[:budget]
+
+    inner = _render_sequence(obj, inner_budget)
+    return prefix + inner + suffix
+
+
+def _render_object(obj: object, budget: int) -> str:
+    """Generic object renderer via attribute decomposition."""
+    type_name = type(obj).__name__
+
+    # Try custom __repr__ first — but only if it fits entirely.
+    # Skip default "<Foo object at 0x...>" and dataclasses (decomposition
+    # is always better since it budgets each field individually).
+    if not dataclasses.is_dataclass(obj):
+        try:
+            r = repr(obj)
+            is_default = r.startswith("<") and " object at 0x" in r
+            if not is_default and len(r) <= budget:
+                return r
+        except Exception:
+            pass
+
+    # Discover attributes
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        attrs = {
+            f.name: getattr(obj, f.name) for f in dataclasses.fields(obj) if f.repr
+        }
+    elif hasattr(obj, "__dict__"):
+        attrs = {k: v for k, v in vars(obj).items() if not k.startswith("_")}
+    elif hasattr(obj, "__slots__"):
+        attrs = {
+            s: getattr(obj, s)
+            for s in obj.__slots__
+            if not s.startswith("_") and hasattr(obj, s)
+        }
+    else:
+        attrs = {}
+
+    return render_attrs(attrs, type_name, budget)

reprobate/ext_arrow.py

@@ -0,0 +1,104 @@
+"""Optional renderer for PyArrow objects."""
+
+try:
+    import pyarrow as pa
+except ImportError:
+    pa = None
+
+from .core import render_child
+from .registry import register
+
+if pa is not None:
+
+    @register(pa.Table)
+    def render_table(obj: "pa.Table", budget: int) -> str:
+        try:
+            r = repr(obj)
+            if len(r) <= budget:
+                return r
+        except Exception:
+            pass
+
+        rows, cols = obj.shape
+        col_names = obj.column_names
+        header = f"Table({rows}x{cols}"
+
+        if budget <= len(header) + 1:
+            return f"Table({rows}x{cols})"[:budget]
+
+        remaining = budget - len(header) - 5  # ", [" before cols, "])" at end
+        if remaining < 5:
+            return (header + ")")[:budget]
+
+        # Show column names
+        col_parts: list[str] = []
+        used = 0
+
+        for i, name in enumerate(col_names):
+            sep = 2 if col_parts else 0
+            omitted = len(col_names) - i - 1
+            reserve = len(f", ...{omitted} more") if omitted > 0 else 0
+            avail = remaining - used - sep - reserve
+
+            r = render_child(name, avail)
+            if len(r) > avail or avail < 3:
+                break
+            col_parts.append(r)
+            used += len(r) + sep
+
+        omitted = len(col_names) - len(col_parts)
+        if omitted > 0:
+            col_parts.append(f"...{omitted} more")
+
+        return header + ", [" + ", ".join(col_parts) + "])"
+
+    @register(pa.ChunkedArray)
+    def render_chunked_array(obj: "pa.ChunkedArray", budget: int) -> str:
+        try:
+            r = repr(obj)
+            if len(r) <= budget:
+                return r
+        except Exception:
+            pass
+
+        dtype = str(obj.type)
+        n = len(obj)
+        header = f"ChunkedArray({n}, {dtype})"
+        return header[:budget]
+
+    @register(pa.Array)
+    def render_array(obj: "pa.Array", budget: int) -> str:
+        dtype = str(obj.type)
+        n = len(obj)
+        header = f"Array({n}, {dtype}"
+
+        if budget <= len(header) + 1:
+            return f"Array({n}, {dtype})"[:budget]
+
+        remaining = budget - len(header) - 5  # ", [" before data, "])" at end
+        if remaining < 5:
+            return (header + ")")[:budget]
+
+        # Peek at values
+        peek_parts: list[str] = []
+        used = 0
+        limit = min(n, 20)
+
+        for i in range(limit):
+            sep = 2 if peek_parts else 0
+            omitted = n - i - 1
+            reserve = len(f", ...{omitted} more") if omitted > 0 else 0
+            avail = remaining - used - sep - reserve
+
+            val = obj[i].as_py()
+            r = render_child(val, avail)
+            if len(r) > avail or avail < 5:
+                break
+            peek_parts.append(r)
+            used += len(r) + sep
+
+        omitted = n - len(peek_parts)
+        if omitted > 0:
+            peek_parts.append(f"...{omitted} more")
+
+        return header + ", [" + ", ".join(peek_parts) + "])"

reprobate/ext_numpy.py

@@ -0,0 +1,50 @@
+"""Optional renderer for numpy arrays."""
+
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
+from .core import render_child
+from .registry import register
+
+if np is not None:
+
+    @register(np.ndarray)
+    def render_ndarray(obj: "np.ndarray", budget: int) -> str:
+        shape = "x".join(str(d) for d in obj.shape)
+        dtype = str(obj.dtype)
+        header = f"ndarray({shape}, {dtype}"
+
+        # header + ")" is the minimum useful output
+        if budget <= len(header) + 1:
+            return f"ndarray({shape})"[:budget]
+
+        remaining = budget - len(header) - 5  # ", [" before data, "])" at end
+        if remaining < 5:
+            return (header + ")")[:budget]
+
+        # Peek at flattened values
+        flat = obj.flat
+        n = obj.size
+        peek_parts: list[str] = []
+        used = 0
+
+        limit = min(n, 20)
+        for i in range(limit):
+            sep = 2 if peek_parts else 0  # ", "
+            omitted = n - i - 1
+            reserve = len(f", ...{omitted} more") if omitted > 0 else 0
+            avail = remaining - used - sep - reserve
+
+            r = render_child(flat[i], avail)
+            if len(r) > avail or avail < 5:
+                break
+            peek_parts.append(r)
+            used += len(r) + sep
+
+        omitted = n - len(peek_parts)
+        if omitted > 0:
+            peek_parts.append(f"...{omitted} more")
+
+        return header + ", [" + ", ".join(peek_parts) + "])"

reprobate/ext_pandas.py

@@ -0,0 +1,70 @@
+"""Optional renderer for pandas objects."""
+
+try:
+    import pandas as pd
+except ImportError:
+    pd = None
+
+from .core import render_child
+from .registry import register
+
+if pd is not None:
+
+    @register(pd.DataFrame)
+    def render_dataframe(obj: "pd.DataFrame", budget: int) -> str:
+        # Let pandas repr handle it if it fits
+        try:
+            r = repr(obj)
+            if len(r) <= budget:
+                return r
+        except Exception:
+            pass
+
+        rows, cols = obj.shape
+        col_names = list(obj.columns)
+        header = f"DataFrame({rows}x{cols}"
+
+        if budget <= len(header) + 1:
+            return f"DataFrame({rows}x{cols})"[:budget]
+
+        remaining = budget - len(header) - 5  # ", [" before cols, "])" at end
+        if remaining < 5:
+            return (header + ")")[:budget]
+
+        # Show column names
+        col_parts: list[str] = []
+        used = 0
+
+        for i, name in enumerate(col_names):
+            sep = 2 if col_parts else 0
+            omitted = len(col_names) - i - 1
+            reserve = len(f", ...{omitted} more") if omitted > 0 else 0
+            avail = remaining - used - sep - reserve
+
+            r = render_child(name, avail)
+            if len(r) > avail or avail < 3:
+                break
+            col_parts.append(r)
+            used += len(r) + sep
+
+        omitted = len(col_names) - len(col_parts)
+        if omitted > 0:
+            col_parts.append(f"...{omitted} more")
+
+        return header + ", [" + ", ".join(col_parts) + "])"
+
+    @register(pd.Series)
+    def render_series(obj: "pd.Series", budget: int) -> str:
+        try:
+            r = repr(obj)
+            if len(r) <= budget:
+                return r
+        except Exception:
+            pass
+
+        dtype = str(obj.dtype)
+        n = len(obj)
+        name_part = f", name={obj.name!r}" if obj.name is not None else ""
+        header = f"Series({n}, {dtype}{name_part})"
+
+        return header[:budget]

reprobate/ext_pil.py

@@ -0,0 +1,20 @@
+"""Optional renderer for PIL/Pillow images."""
+
+try:
+    from PIL import Image
+except ImportError:
+    Image = None
+
+from .registry import register
+
+if Image is not None:
+
+    @register(Image.Image)
+    def render_image(obj: "Image.Image", budget: int) -> str:
+        w, h = obj.size
+        mode = obj.mode
+        fmt = obj.format
+        fmt_part = f", format={fmt}" if fmt else ""
+        header = f"Image({w}x{h}, {mode}{fmt_part})"
+
+        return header[:budget]

reprobate/ext_polars.py

@@ -0,0 +1,69 @@
+"""Optional renderer for polars objects."""
+
+try:
+    import polars as pl
+except ImportError:
+    pl = None
+
+from .core import render_child
+from .registry import register
+
+if pl is not None:
+
+    @register(pl.DataFrame)
+    def render_dataframe(obj: "pl.DataFrame", budget: int) -> str:
+        try:
+            r = repr(obj)
+            if len(r) <= budget:
+                return r
+        except Exception:
+            pass
+
+        rows, cols = obj.shape
+        col_names = obj.columns
+        header = f"DataFrame({rows}x{cols}"
+
+        if budget <= len(header) + 1:
+            return f"DataFrame({rows}x{cols})"[:budget]
+
+        remaining = budget - len(header) - 5  # ", [" before cols, "])" at end
+        if remaining < 5:
+            return (header + ")")[:budget]
+
+        # Show column names
+        col_parts: list[str] = []
+        used = 0
+
+        for i, name in enumerate(col_names):
+            sep = 2 if col_parts else 0
+            omitted = len(col_names) - i - 1
+            reserve = len(f", ...{omitted} more") if omitted > 0 else 0
+            avail = remaining - used - sep - reserve
+
+            r = render_child(name, avail)
+            if len(r) > avail or avail < 3:
+                break
+            col_parts.append(r)
+            used += len(r) + sep
+
+        omitted = len(col_names) - len(col_parts)
+        if omitted > 0:
+            col_parts.append(f"...{omitted} more")
+
+        return header + ", [" + ", ".join(col_parts) + "])"
+
+    @register(pl.Series)
+    def render_series(obj: "pl.Series", budget: int) -> str:
+        try:
+            r = repr(obj)
+            if len(r) <= budget:
+                return r
+        except Exception:
+            pass
+
+        dtype = str(obj.dtype)
+        n = len(obj)
+        name_part = f", name={obj.name!r}" if obj.name else ""
+        header = f"Series({n}, {dtype}{name_part})"
+
+        return header[:budget]

reprobate/ext_pydantic.py

@@ -0,0 +1,17 @@
+"""Optional renderer for pydantic models."""
+
+try:
+    import pydantic
+except ImportError:
+    pydantic = None
+
+from .core import render_attrs
+from .registry import register
+
+if pydantic is not None:
+
+    @register(pydantic.BaseModel)
+    def render_basemodel(obj: "pydantic.BaseModel", budget: int) -> str:
+        type_name = type(obj).__name__
+        attrs = {name: getattr(obj, name) for name in type(obj).model_fields}
+        return render_attrs(attrs, type_name, budget)

reprobate/registry.py

@@ -0,0 +1,32 @@
+"""Type-specific renderer registry."""
+
+from typing import Any, Callable
+
+Renderer = Callable[[Any, int], str]
+
+_registry: dict[type, Renderer] = {}
+
+
+def register(cls: type) -> Callable[[Renderer], Renderer]:
+    """Register a budget renderer for a type.
+
+    Usage::
+
+        @register(MyClass)
+        def render_my_class(obj: MyClass, budget: int) -> str:
+            ...
+    """
+
+    def decorator(fn: Renderer) -> Renderer:
+        _registry[cls] = fn
+        return fn
+
+    return decorator
+
+
+def get_renderer(cls: type) -> Renderer | None:
+    """Look up a renderer for a type, checking MRO."""
+    for klass in cls.__mro__:
+        if klass in _registry:
+            return _registry[klass]
+    return None

reprobate-0.1.0.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: reprobate
+Version: 0.1.0
+Summary: Budget-controlled repr for Python objects.
+Author: ashenfad
+License-Expression: MIT
+Keywords: repr,pretty-print,budget,truncation,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
+Requires-Dist: numpy; extra == "test"
+Requires-Dist: pandas; extra == "test"
+Requires-Dist: Pillow; extra == "test"
+Requires-Dist: polars; extra == "test"
+Requires-Dist: pyarrow; extra == "test"
+Requires-Dist: pydantic; extra == "test"
+Dynamic: license-file
+
+# reprobate 🖨️
+
+Budget-controlled repr for Python objects.
+
+Renders any Python object into a string that fits within a character budget. Nested structures degrade gracefully: full values, then type stubs, then counts. Zero dependencies. Pluggable via a type registry and a `__budget_repr__` protocol.
+
+## Features
+
+- **Hard budget guarantee** -- output is always `<= budget` characters
+- **Three-phase degradation** -- full render, then `name=<type(len)>` stubs, then `...N more` counts
+- **Greedy and even policies** -- prioritize depth (first fields in detail) or breadth (all fields equally)
+- **Cycle detection** -- circular references render as `<...>` instead of stack overflows
+- **Type registry** -- `@register(MyType)` for custom budget-aware renderers
+- **Protocol method** -- `__budget_repr__(self, budget)` on any class
+- **Optional extensions** -- arrow, numpy, pandas, pil, polars, pydantic renderers (guarded imports, zero cost if absent)
+
+## Install
+
+```bash
+pip install reprobate
+```
+
+Zero dependencies. Optional renderers activate automatically when their libraries are already installed (numpy, pandas, polars, pyarrow, Pillow, pydantic).
+
+## Quick example
+
+```python
+import reprobate
+
+reprobate.render({"name": "alice", "scores": [98, 87, 95, 72, 88]}, 60)
+# "{'name': 'alice', 'scores': [98, 87, 95, 72, 88]}"
+
+reprobate.render({"name": "alice", "scores": [98, 87, 95, 72, 88]}, 30)
+# "{'name': 'alice', ...1 more}"
+
+reprobate.render(list(range(1000)), 40)
+# "[0, 1, 2, 3, ...996 more]"
+```
+
+## Policies
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class Agent:
+    desc: str = "A very long description that eats the budget"
+    important_note: str = "critical info here"
+    status: str = "running"
+    config: dict = None
+    history: list = None
+
+# Greedy: first fields get full detail
+reprobate.render(agent, 100, policy="greedy")
+# "Agent(desc='A very long description that eats the budget', important_note=<str(18)>, ...3 more)"
+
+# Even: all fields get comparable detail
+reprobate.render(agent, 100, policy="even")
+# "Agent(desc='A very long...', important_note='critical info...', status='running', ...2 more)"
+```
+
+## Custom renderers
+
+Register a renderer for any type:
+
+```python
+@reprobate.register(MyType)
+def render_my_type(obj: MyType, budget: int) -> str:
+    return f"MyType({obj.key})"[:budget]
+```
+
+Or implement the protocol directly:
+
+```python
+class MyType:
+    def __budget_repr__(self, budget: int) -> str:
+        return f"MyType({self.key})"[:budget]
+```
+
+For renderers that recurse into child objects, use `render_child` (inherits policy and cycle detection) and `render_attrs` (standard `TypeName(key=val, ...)` pattern):
+
+```python
+from reprobate import register, render_child, render_attrs
+
+@register(MyContainer)
+def render_my_container(obj: MyContainer, budget: int) -> str:
+    # render_child for recursive rendering
+    inner = render_child(obj.value, budget - 10)
+    return f"MyContainer({inner})"
+
+@register(MyModel)
+def render_my_model(obj: MyModel, budget: int) -> str:
+    # render_attrs for the standard object pattern
+    attrs = {"name": obj.name, "data": obj.data}
+    return render_attrs(attrs, "MyModel", budget)
+```
+
+## Supported types
+
+| Category | Types | Behavior |
+|----------|-------|----------|
+| Primitives | `None`, `bool`, `int`, `float` | `repr()`, truncated with `...` if needed |
+| Strings | `str`, `bytes` | Quoted, truncated with `...` preserving quotes |
+| Containers | `list`, `tuple`, `set`, `frozenset` | Head items + `...N more`, tail peek when budget allows |
+| Dicts | `dict` | Key-value pairs + `...N more` |
+| Collections | `deque`, `defaultdict`, `Counter` | Type-aware wrappers (factory name, most-common order) |
+| Structured | `dataclass`, `namedtuple` | Field-aware decomposition, respects `repr=False` |
+| Objects | anything with `__dict__` | Attribute decomposition, public attrs only |
+| Optional | numpy, pandas, polars, pyarrow, Pillow, pydantic | Shape/dtype/columns summary (auto-activates when lib is installed) |
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+```

reprobate-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+reprobate/__init__.py,sha256=3WQY1A9TaZ_i_KlKsAN7RX4d-lEJS2c4jcNqalz89GM,519
+reprobate/core.py,sha256=6iR3P8s1nZ4j3b4zgpUNQB4M_q5DUox8on7r0LifsZM,13526
+reprobate/ext_arrow.py,sha256=rSyigOPlhv7I0tbsF0aqUh0y_Aed9zE5Y-NA3poL1WA,2971
+reprobate/ext_numpy.py,sha256=WMQRCadF8b5VRDFFrEVmdRbAPUWNQq35qwiQywY1fa4,1447
+reprobate/ext_pandas.py,sha256=gPlkrFyGUOQnCC-SZskcLlhnf9ZWdd4JFNUSs49iMHA,1968
+reprobate/ext_pil.py,sha256=YZlhasGSfZLkhe1fj_0-EtC6nxbq3QFKUDfMSAZxoUE,471
+reprobate/ext_polars.py,sha256=l5Zk7qge4Jti-KH2faL5ahk2rUbMfgLibowjqh9dKAA,1903
+reprobate/ext_pydantic.py,sha256=ls9WoqyJQQC_86qg-NEjTaCAtHvJrIwHr0_6c_8LCUo,479
+reprobate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+reprobate/registry.py,sha256=IeiAXy7PKAGWK_-tYH9VKT6LBjNc30A3XHushLqdQMc,716
+reprobate-0.1.0.dist-info/licenses/LICENSE,sha256=mkczgS_OETNm2hMlJwDscbMGpBgyLheu2UhM2-ERWHo,1073
+reprobate-0.1.0.dist-info/METADATA,sha256=c661-KBncceSKUOFL8iW_-domyBk_i-iFUvLd1dkLfI,5389
+reprobate-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+reprobate-0.1.0.dist-info/top_level.txt,sha256=AIoXDTC_2KQz-cXvSnBSYWOaTKCATTYlbKrsolvDSjM,10
+reprobate-0.1.0.dist-info/RECORD,,

reprobate-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

reprobate-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Ashenfelter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

reprobate-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+reprobate