A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
feat: introduce better_inspect module for enhanced dir() and help() functionality for marimo-pair (#9223)
Myles Scolnickcab71a295272
diff --git a/.github/workflows/test_be.yaml b/.github/workflows/test_be.yamlindex 588dc79982..b7be17bb6a 100644--- a/.github/workflows/test_be.yaml+++ b/.github/workflows/test_be.yaml@@ -211,6 +211,7 @@ jobs:--changed-from=${{ steps.setup-flags.outputs.changed_from }} \--include-unchanged=${{ steps.setup-flags.outputs.include_unchanged }} \--picked=first \+ --inline-snapshot=disable \|| { ec=$?; [ $ec -eq 5 ] && exit 0 || exit $ec; }# Test with optional dependencies@@ -226,6 +227,7 @@ jobs:--changed-from=${{ steps.setup-flags.outputs.changed_from }} \--include-unchanged=${{ steps.setup-flags.outputs.include_unchanged }} \--picked=first \+ --inline-snapshot=disable \|| { ec=$?; [ $ec -eq 5 ] && exit 0 || exit $ec; }# Test with minimal dependencies using lowest resolution@@ -243,6 +245,7 @@ jobs:--changed-from=${{ steps.setup-flags.outputs.changed_from }} \--include-unchanged=${{ steps.setup-flags.outputs.include_unchanged }} \--picked=first \+ --inline-snapshot=disable \|| { ec=$?; [ $ec -eq 5 ] && exit 0 || exit $ec; }env:UV_RESOLUTION: lowest-direct@@ -275,6 +278,7 @@ jobs:-k "not test_cli" \--durations=10 \--picked=first \+ --inline-snapshot=disable \--cov=marimo --cov-report=xml --junitxml=junit.xml -o junit_family=legacy# Only upload coverage on `main` so it is not blockingdiff --git a/marimo/_code_mode/_better_inspect.py b/marimo/_code_mode/_better_inspect.pynew file mode 100644index 0000000000..8397f63f6c--- /dev/null+++ b/marimo/_code_mode/_better_inspect.py@@ -0,0 +1,516 @@+# Copyright 2026 Marimo. All rights reserved.+"""better_inspect -- opinionated replacements for dir() and help().++Why these exist:+Python's built-in dir() and help() were designed in a pre-AI, pre-LSP era.+They dump too much noise (dunders, inherited object methods, pager UIs) and+produce output that's hard to scan, hard to copy-paste into prompts, and hard+to feed to tools.++These two functions fix that:++``better_dir(obj)``+ Filters out all private/dunder attributes.+ Appends type annotations to data attributes (e.g. ``host: str``).+ Appends full signatures to callables (e.g. ``send(data: bytes) -> int``).+ Returns a plain ``list[str]`` so it's a drop-in ``__dir__`` return value.+ Uses ``object.__dir__(obj)`` internally to avoid infinite recursion+ when wired as ``__dir__``.++``better_help(obj)``+ Returns a compact, markdown-ish summary: class name, docstring,+ attributes with types, methods with signatures and one-line docs.+ No pager, no dunders, no self parameter, no scroll.+ Returns ``str`` so it can be wired to ``__repr__`` and will also be+ picked up by ``help()`` via pydoc's repr fallback.++``@helpable``+ Class decorator that rewrites ``__doc__`` at definition time so+ ``help()`` shows the clean summary natively via pydoc -- no need to+ touch ``__repr__``. Also wires ``__dir__`` automatically.++Usage::++ from marimo._code_mode._better_inspect import better_dir, better_help, helpable++ # Standalone+ better_dir(my_obj)+ better_help(my_obj)++ # Zero-boilerplate via decorator+ @helpable+ class MyClient:+ \"\"\"A TCP client for sending data to a remote server.\"\"\"++ def __init__(self, host: str, port: int = 8080):+ self.host = host+ self.port = port++ def connect(self, timeout: float = 5.0) -> bool:+ \"\"\"Connect to the remote server.\"\"\"+ ...++ def send(self, data: bytes, timeout: float = 5.0) -> int:+ \"\"\"Send data to the server.\"\"\"+ ...++ def disconnect(self) -> None:+ \"\"\"Disconnect from the server.\"\"\"+ ...++ # Now both work natively:+ # dir(client) -> clean list with types and signatures+ # help(client) -> pydoc shows the clean summary via __doc__+"""++from __future__ import annotations++import inspect+from enum import Enum, EnumMeta+from typing import Any+++def _public_attrs(obj: Any) -> list[str]:+ """Return sorted public attribute names using ``object.__dir__``.++ Uses ``object.__dir__(obj)`` instead of ``dir(obj)`` to avoid infinite+ recursion when this is called from inside ``__dir__`` itself.++ Args:+ obj: Any Python object.++ Returns:+ Sorted list of attribute names that don't start with ``_``.+ """+ # Enum classes: only show member names.+ if isinstance(obj, type) and issubclass(obj, Enum):+ return sorted(m.name for m in obj)+ # For classes (types), use type.__dir__ to get the class's own attributes.+ # For instances, use object.__dir__ to avoid recursion through __dir__.+ raw = type.__dir__(obj) if isinstance(obj, type) else object.__dir__(obj)+ return sorted(name for name in raw if not name.startswith("_"))+++_MISSING: Any = object()+++def _safe_getattr_static(obj: Any, name: str) -> Any:+ """Fetch an attribute without invoking descriptors or properties.++ Uses ``inspect.getattr_static`` so that ``dir()``/``help()`` never+ trigger property getters (which could raise or have side effects).+ Returns ``_MISSING`` if the attribute cannot be retrieved.+ """+ try:+ return inspect.getattr_static(obj, name)+ except AttributeError:+ return _MISSING+++def _type_label(val: Any) -> str:+ """Best-effort type label for a value.++ For property descriptors (seen when inspecting a class rather than an+ instance), extracts the return annotation from the getter.+ """+ if isinstance(val, property) and val.fget is not None:+ ret = getattr(val.fget, "__annotations__", {}).get("return")+ if ret is not None:+ return ret.__name__ if isinstance(ret, type) else str(ret)+ return type(val).__name__+++def _unwrap_callable(val: Any) -> Any:+ """Unwrap ``classmethod``/``staticmethod`` to the underlying function."""+ if isinstance(val, (classmethod, staticmethod)):+ return val.__func__+ return val+++def _format_signature(func: Any) -> str:+ """Return a string signature with ``self``/``cls`` stripped."""+ sig = inspect.signature(func)+ params = [p for n, p in sig.parameters.items() if n not in ("self", "cls")]+ return str(sig.replace(parameters=params))+++def _first_doc_line(doc: str | None) -> str:+ if not doc:+ return ""+ return doc.strip().split("\n", 1)[0]+++def better_dir(obj: Any) -> list[str]:+ """A cleaner ``dir()`` that shows only the public interface.++ Designed to be returned directly from ``__dir__``::++ def __dir__(self):+ return better_dir(self)++ Improvements over built-in ``dir()``:++ - Excludes all private and dunder attributes.+ - Data attributes show their type -> ``host: str``+ - Callables show their full signature -> ``send(data: bytes) -> int``+ - Sorted alphabetically for easy scanning.+ - Returns ``list[str]`` -- the exact type ``__dir__`` requires.+ - Safe from infinite recursion (uses ``object.__dir__`` internally).++ Args:+ obj: Any Python object (instance, class, module, ...).++ Returns:+ A sorted list of formatted public attribute descriptions.++ Example::++ >>> better_dir(my_client)+ ['connect(timeout: float = 5.0) -> bool',+ 'disconnect() -> None',+ 'host: str',+ 'port: int',+ 'send(data: bytes, timeout: float = 5.0) -> int']+ """+ result: list[str] = []++ for name in _public_attrs(obj):+ val = _safe_getattr_static(obj, name)+ if val is _MISSING:+ continue++ call_target = _unwrap_callable(val)++ if isinstance(val, property):+ result.append(f"{name}: {_type_label(val)}")+ elif isinstance(val, Enum):+ result.append(f"{name} = {val.value!r}")+ elif callable(call_target):+ try:+ sig = _format_signature(call_target)+ except (ValueError, TypeError):+ sig = "(...)"+ result.append(f"{name}{sig}")+ else:+ result.append(f"{name}: {_type_label(val)}")++ return result+++def better_help(obj: Any) -> str:+ """A compact, AI-friendly replacement for ``help()``.++ Can be used standalone, or applied automatically via the ``@helpable``+ decorator which rewrites ``__doc__`` at class definition time so that+ ``help()`` shows this output natively through pydoc.++ Improvements over built-in ``help()``:++ - Markdown-style heading with the class/module name.+ - Shows only the first line of each docstring -- enough to understand+ intent without the filler.+ - ``self`` is stripped from method signatures by ``inspect.signature``.+ - Attributes and methods are grouped into clearly labelled sections.+ - No pager, no quitting, no scrolling -- just a string.+ - Output is structured for LLMs: paste it straight into a prompt,+ a README, or a tool description.+ - Returns ``str`` instead of printing, so it composes cleanly with+ logging, f-strings, ``__repr__``, etc.++ Args:+ obj: Any Python object (instance, class, module, ...).++ Returns:+ A formatted multi-line string describing the object's public interface.++ Example::++ >>> print(better_help(my_client))+ # MyClient+ A TCP client for sending data to a remote server.++ Attributes:+ host: str+ port: int++ Methods:+ connect(timeout: float = 5.0) -> bool -- Connect to the remote server.+ disconnect() -> None -- Disconnect from the server.+ send(data: bytes, timeout: float = 5.0) -> int -- Send data to the server.+ """+ # Pick a reasonable title for any object kind (modules, functions, ...).+ title = getattr(obj, "__name__", None) or type(obj).__name__++ lines: list[str] = [f"# {title}"]++ # Prefer the original (pre-@helpable) docstring so we don't duplicate+ # the generated heading or drop the human-written description line.+ raw_doc = getattr(obj, "_original_doc__", None) or getattr(+ obj, "__doc__", None+ )+ desc = _first_doc_line(raw_doc)+ # Strip the generated `# Name` heading if _original_doc__ is unavailable.+ if desc.startswith("#"):+ desc = ""+ if desc:+ lines.append(desc)++ lines.append("")++ attrs: list[str] = []+ methods: list[str] = []++ for name in _public_attrs(obj):+ val = _safe_getattr_static(obj, name)+ if val is _MISSING:+ continue++ call_target = _unwrap_callable(val)++ if isinstance(val, property):+ attrs.append(f" {name}: {_type_label(val)}")+ continue++ if callable(call_target) and not isinstance(val, Enum):+ try:+ sig = _format_signature(call_target)+ except (ValueError, TypeError):+ sig = "(...)"+ doc = _first_doc_line(getattr(call_target, "__doc__", None))+ entry = f" {name}{sig}"+ if doc:+ entry += f" -- {doc}"+ methods.append(entry)+ elif isinstance(val, Enum):+ attrs.append(f" {name} = {val.value!r}")+ else:+ attrs.append(f" {name}: {_type_label(val)}")++ if attrs:+ lines.append("Attributes:")+ lines.extend(attrs)+ lines.append("")++ if methods:+ lines.append("Methods:")+ lines.extend(methods)++ return "\n".join(lines)+++def _build_enum_help(cls: type) -> str:+ """Build help for an Enum class, showing members with values and docs."""+ original_doc: str | None = getattr(cls, "_original_doc__", None)+ lines: list[str] = [f"# {cls.__name__}"]+ if original_doc:+ lines.append(original_doc.strip().split("\n")[0])+ lines.append("")+ lines.append("Values:")+ for member in cls: # type: ignore[attr-defined]+ doc = _enum_member_doc(cls, member.name)+ entry = f" {member.name} = {member.value!r}"+ if doc:+ entry += f" -- {doc}"+ lines.append(entry)+ return "\n".join(lines)+++def _enum_member_doc(cls: type, name: str) -> str:+ """Extract the inline docstring for an enum member, if any.++ Python 3.13+ stores the immediately-following ``\"\"\"docstring\"\"\"``+ literal as ``member.__doc__``. On older Pythons this is just the+ class docstring; we treat that as "no per-member doc" and return "".+ """+ member = cls[name] # type: ignore[index]+ member_doc = getattr(member, "__doc__", None)+ if member_doc and member_doc != cls.__doc__:+ return _first_doc_line(member_doc)+ return ""+++def _build_help(cls: type) -> str:+ """Build the help string for a class (not an instance).++ Works at decoration time with no instance available, so it inspects+ the class itself -- methods via the class dict, and type hints via+ ``__annotations__`` and ``__init__`` annotations.++ Args:+ cls: The class to document.++ Returns:+ A formatted multi-line help string.+ """+ lines: list[str] = [f"# {cls.__name__}"]++ # Preserve original docstring as the description line+ original_doc: str | None = getattr(cls, "_original_doc__", None)+ if original_doc:+ lines.append(original_doc.strip().split("\n")[0])++ lines.append("")++ # Collect type hints from __init__ and class-level annotations+ hints: dict[str, Any] = {}+ init = getattr(cls, "__init__", None)+ if init:+ hints.update(+ {+ k: v+ for k, v in getattr(init, "__annotations__", {}).items()+ if k != "return"+ }+ )+ hints.update(+ {k: v for k, v in getattr(cls, "__annotations__", {}).items()}+ )++ attrs: list[str] = []+ methods: list[str] = []++ seen: set[str] = set()+ for klass in cls.__mro__:+ for name, val in vars(klass).items():+ if name.startswith("_") or name in seen:+ continue+ seen.add(name)++ # Unwrap classmethod/staticmethod so they appear under Methods.+ call_target = _unwrap_callable(val)++ if callable(call_target) and not isinstance(val, property):+ try:+ sig = _format_signature(call_target)+ except (ValueError, TypeError):+ sig = "(...)"+ doc = _first_doc_line(getattr(call_target, "__doc__", None))+ entry = f" {name}{sig}"+ if doc:+ entry += f" -- {doc}"+ methods.append(entry)+ else:+ if name in hints:+ h = hints[name]+ type_name: str = (+ h.__name__ if isinstance(h, type) else str(h)+ )+ else:+ type_name = _type_label(val)+ attrs.append(f" {name}: {type_name}")++ # Also show __init__ params as attributes if they're in hints but not+ # already declared on the class body+ for name, hint in hints.items():+ if name not in seen and not name.startswith("_"):+ type_name = hint.__name__ if isinstance(hint, type) else str(hint)+ attrs.append(f" {name}: {type_name}")++ if attrs:+ lines.append("Attributes:")+ lines.extend(sorted(attrs))+ lines.append("")++ if methods:+ lines.append("Methods:")+ lines.extend(sorted(methods))++ return "\n".join(lines)+++class _HelpableEnumMeta(EnumMeta):+ """Metaclass for enum classes that makes ``dir(EnumClass)`` clean.++ ``EnumType`` is the default metaclass for all ``Enum`` subclasses.+ By subclassing it and overriding ``__dir__``, ``dir(MyEnum)`` returns+ only the enum member names with values.+ """++ def __dir__(cls) -> list[str]: # type: ignore[override]+ return better_dir(cls)+++class _HelpableMeta(type):+ """Metaclass that makes ``dir(ClassName)`` return ``better_dir`` output.++ Without this, ``dir(cls)`` always calls ``type.__dir__(cls)`` which+ returns the raw attribute list including dunders. By overriding+ ``__dir__`` on the metaclass, ``dir(MyClass)`` now returns the same+ clean list that ``dir(instance)`` does.+ """++ def __dir__(cls) -> list[str]: # type: ignore[override]+ return better_dir(cls)+++def helpable(cls: type) -> type:+ """Class decorator that wires ``better_dir`` and ``better_help`` automatically.++ Rewrites ``__doc__`` on the class at definition time so that ``help(obj)``+ shows a clean, AI-friendly summary through pydoc's normal machinery. Also+ installs ``__dir__`` to return ``better_dir(self)``.++ The original docstring is preserved in ``_original_doc__`` and used as the+ description line in the generated help output.++ Works on both classes and instances::++ @helpable+ class MyClient:+ \"\"\"A TCP client.\"\"\"+ ...++ dir(MyClient) # clean output (via metaclass)+ dir(MyClient()) # clean output (via __dir__)+ help(MyClient) # clean output (via __doc__)+ help(MyClient()) # clean output (via __doc__)++ Caveat:+ For classes whose metaclass is the default ``type``, the decorator+ recreates the class with ``_HelpableMeta`` so that ``dir(Class)``+ is also clean. Methods that use zero-argument ``super()`` inside+ such classes will still bind to the *original* class (via the+ ``__class__`` closure cell the compiler injects), which is not in+ the new class's MRO. In practice this is only an issue if the+ decorated class subclasses another class *and* its methods call+ ``super()``; keep ``@helpable`` for simple, leaf-level data/API+ classes, or use explicit ``super(ClassName, self)`` calls.++ Args:+ cls: The class to decorate.++ Returns:+ The decorated class with new ``__doc__`` and ``__dir__``.+ """+ original_doc = cls.__doc__++ # Stash original doc so _build_help can read it, then build help text.+ cls._original_doc__ = original_doc # type: ignore[attr-defined]+ is_enum = isinstance(cls, type) and issubclass(cls, Enum)+ help_text = _build_enum_help(cls) if is_enum else _build_help(cls)++ def _dir(self: Any) -> list[str]:+ return better_dir(self)++ # If the metaclass is plain `type`, recreate the class with+ # _HelpableMeta so that dir(ClassName) also works.+ meta = type(cls)+ if meta is type:+ skip = {"__dict__", "__weakref__"}+ slots = vars(cls).get("__slots__", ())+ if slots:+ skip |= set(slots)+ ns = {k: v for k, v in vars(cls).items() if k not in skip}+ ns["__doc__"] = help_text+ ns["__dir__"] = _dir+ ns["_original_doc__"] = original_doc+ new_cls = _HelpableMeta(cls.__name__, cls.__bases__, ns)+ new_cls.__module__ = cls.__module__+ new_cls.__qualname__ = cls.__qualname__+ return new_cls # type: ignore[return-value]++ # Fallback for classes with special metaclasses (Protocol, ABCMeta, …):+ # mutate in place — dir(instance) works, dir(Class) stays default.+ cls.__doc__ = help_text+ cls.__dir__ = _dir # type: ignore[method-assign, assignment]+ return clsdiff --git a/marimo/_code_mode/_context.py b/marimo/_code_mode/_context.pyindex b01e544223..f3da0866b0 100644--- a/marimo/_code_mode/_context.py+++ b/marimo/_code_mode/_context.py@@ -25,6 +25,7 @@ from __future__ import annotationsimport sysfrom dataclasses import dataclass+from enum import Enumfrom typing import TYPE_CHECKING, Any, Literal, Protocol, overloadfrom marimo import _loggers@@ -37,6 +38,7 @@ from marimo._ast.cell import (from marimo._ast.cell_id import CellIdGeneratorfrom marimo._ast.compiler import compile_cellfrom marimo._ast.names import SETUP_CELL_NAME+from marimo._code_mode._better_inspect import _HelpableEnumMeta, helpablefrom marimo._code_mode._packages import (Packages,_AddPackage,@@ -94,21 +96,45 @@ if TYPE_CHECKING:from marimo._runtime.dataflow import DirectedGraphfrom marimo._runtime.runtime import Kernel-CellStatusType = Literal[- "idle",- "exception",- "stale",- "cancelled",- "interrupted",- "marimo-error",- "disabled",- "queued",- "running",-]++@helpable+class CellStatusType(str, Enum, metaclass=_HelpableEnumMeta):+ """Synthesized cell execution status.++ Returned by ``NotebookCell.status``. Compares equal to plain+ strings, so ``cell.status == "idle"`` works as expected.+ """++ idle = "idle"+ """Ran successfully, up to date."""+ exception = "exception"+ """Cell raised an exception."""+ stale = "stale"+ """Needs re-run (code edited, inputs changed, or never run)."""+ cancelled = "cancelled"+ """Ancestor raised an exception."""+ interrupted = "interrupted"+ """Execution was interrupted."""+ marimo_error = "marimo-error"+ """Prevented from executing (e.g. multiply-defined name)."""+ disabled = "disabled"+ """Cell is disabled."""+ queued = "queued"+ """Waiting to run."""+ running = "running"+ """Currently executing."""++ def __str__(self) -> str:+ return self.value++ def __repr__(self) -> str:+ return repr(self.value)+CellErrorKind = Literal["graph", "runtime"]+@helpable@dataclass(frozen=True, slots=True)class CellError:"""An error affecting a notebook cell.@@ -190,6 +216,7 @@ def get_context(*, skip_validation: bool = False) -> AsyncCodeModeContext:)+@helpableclass NotebookCell:"""Read-only view of a single cell with runtime status.@@ -283,26 +310,26 @@ class NotebookCell:stale > last run result."""if self._impl is None:- return "stale" if self._cell.code else None+ return CellStatusType.stale if self._cell.code else None# Transient runtime state takes priority.rs = self._impl.runtime_stateif rs == "queued":- return "queued"+ return CellStatusType.queuedif rs == "running":- return "running"+ return CellStatusType.runningif rs == "disabled-transitively":- return "disabled"+ return CellStatusType.disabled# Stale overrides last run result.if self._is_stale():- return "stale"+ return CellStatusType.stale# Fall back to last execution result.rr = self._impl.run_result_statusif rr is None:# Registered in the graph but never executed.- return "stale" if self._cell.code else None+ return CellStatusType.stale if self._cell.code else Noneif rr == "success":- return "idle"- return rr+ return CellStatusType.idle+ return CellStatusType(rr)@propertydef errors(self) -> list[CellError]:@@ -349,6 +376,7 @@ class NotebookCell:)+@helpableclass _CellsView:"""Read-only, ordered view over notebook cells.@@ -537,6 +565,7 @@ class _CellsView:# ------------------------------------------------------------------+@helpableclass AsyncCodeModeContext:"""Async programmatic control of a running marimo notebook.diff --git a/marimo/_smoke_tests/code_mode/help_and_dir.py b/marimo/_smoke_tests/code_mode/help_and_dir.pynew file mode 100644index 0000000000..776971ee5d--- /dev/null+++ b/marimo/_smoke_tests/code_mode/help_and_dir.py@@ -0,0 +1,87 @@+import marimo++__generated_with = "0.23.1"+app = marimo.App(width="columns", auto_download=["ipynb"])++[email protected](column=0)+def _():+ import marimo._code_mode as cm+ import marimo as mo++ code_mode = cm+ return cm, mo+++def _(mo):+ def display_help(obj):+ with mo.capture_stdout() as cap:+ help(obj)+ return mo.plain_text(cap.getvalue())++ return (display_help,)++[email protected](column=1)+def _(cm, display_help):+ display_help(cm)+ return+++def _(cm, display_help):+ display_help(cm.AsyncCodeModeContext)+ return+++def _(cm, display_help):+ display_help(cm.CellStatusType)+ return+++def _(cm, display_help):+ display_help(cm.get_context)+ return+++def _(cm, display_help):+ display_help(cm.NotebookCell)+ return++[email protected](column=2)+def _(cm):+ dir(cm)+ return+++def _(cm):+ help(cm.get_context)+ return+++def _(cm):+ dir(cm.AsyncCodeModeContext)+ return+++def _(cm):+ dir(cm.CellStatusType)+ return+++def _(cm):+ dir(cm.NotebookCell)+ return+++if __name__ == "__main__":+ app.run()diff --git a/tests/_code_mode/test_better_inspect.py b/tests/_code_mode/test_better_inspect.pynew file mode 100644index 0000000000..6c5081ec48--- /dev/null+++ b/tests/_code_mode/test_better_inspect.py@@ -0,0 +1,165 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++from enum import Enum++import pytest++from marimo._code_mode._better_inspect import (+ _HelpableEnumMeta,+ better_dir,+ better_help,+ helpable,+)++# -- shared fixture class ---------------------------------------------------+++@helpable+class _Demo:+ """A demo widget."""++ x: int++ def __init__(self, x: int = 1, hidden: str = "secret"):+ self.x = x+ self._hidden = hidden++ def greet(self, name: str = "world") -> str:+ """Say hello."""+ return f"hi {name}"++ def _private(self) -> None: ...+++def demo() -> _Demo:+ return _Demo(x=42)+++# -- better_dir --------------------------------------------------------------+++class TestBetterDir:+ def test_excludes_private_and_dunder(self, demo: _Demo) -> None:+ entries = better_dir(demo)+ for e in entries:+ assert not e.startswith("_")++ def test_data_attr_shows_type(self, demo: _Demo) -> None:+ assert "x: int" in better_dir(demo)++ def test_callable_shows_signature(self, demo: _Demo) -> None:+ [match] = [e for e in better_dir(demo) if e.startswith("greet")]+ assert "name" in match+ assert "str" in match+ assert "-> " in match++ def test_returns_list_of_str(self, demo: _Demo) -> None:+ result = better_dir(demo)+ assert isinstance(result, list)+ assert all(isinstance(e, str) for e in result)++ def test_sorted(self, demo: _Demo) -> None:+ result = better_dir(demo)+ assert result == sorted(result)+++# -- better_help --------------------------------------------------------------+++class TestBetterHelp:+ def test_header_and_docstring(self, demo: _Demo) -> None:+ out = better_help(demo)+ assert out.startswith("# _Demo\n")++ def test_attributes_section(self, demo: _Demo) -> None:+ out = better_help(demo)+ assert "Attributes:" in out+ assert "x: int" in out++ def test_methods_section(self, demo: _Demo) -> None:+ out = better_help(demo)+ assert "Methods:" in out+ assert "greet(" in out+ assert "Say hello." in out++ def test_no_private(self, demo: _Demo) -> None:+ out = better_help(demo)+ assert "_private" not in out+ assert "_hidden" not in out++ def test_returns_str(self, demo: _Demo) -> None:+ assert isinstance(better_help(demo), str)+++# -- @helpable decorator ------------------------------------------------------+++class TestHelpable:+ def test_rewrites_doc(self) -> None:+ assert _Demo.__doc__ is not None+ assert _Demo.__doc__.startswith("# _Demo")++ def test_preserves_original_doc(self) -> None:+ assert _Demo._original_doc__ == "A demo widget." # type: ignore[attr-defined]++ def test_dir_uses_better_dir(self, demo: _Demo) -> None:+ assert dir(demo) == better_dir(demo)++ def test_class_still_works(self, demo: _Demo) -> None:+ assert demo.greet() == "hi world"+ assert demo.x == 42++ def test_dir_on_class_uses_better_dir(self) -> None:+ # dir(ClassName) should also use better_dir (via metaclass)+ result = dir(_Demo)+ assert all(isinstance(e, str) for e in result)+ assert not any(e.startswith("_") for e in result)+ assert any("greet" in e for e in result)++ def test_works_on_empty_class(self) -> None:+ @helpable+ class Empty:+ pass++ assert "# Empty" in (Empty.__doc__ or "")+ assert dir(Empty()) == better_dir(Empty())+ assert dir(Empty) == better_dir(Empty)+++# -- enum support --------------------------------------------------------------+++@helpable+class _Color(str, Enum, metaclass=_HelpableEnumMeta):+ """Primary colors."""++ red = "red"+ green = "green"+ blue = "blue"+++class TestHelpableEnum:+ def test_dir_shows_only_members(self) -> None:+ result = dir(_Color)+ assert sorted(result) == [+ "blue = 'blue'",+ "green = 'green'",+ "red = 'red'",+ ]++ def test_dir_excludes_str_methods(self) -> None:+ result = dir(_Color)+ assert not any("capitalize" in e for e in result)+ assert not any("upper" in e for e in result)++ def test_help_shows_values_section(self) -> None:+ assert _Color.__doc__ is not None+ assert "# _Color" in _Color.__doc__+ assert "Values:" in _Color.__doc__+ assert "red = 'red'" in _Color.__doc__++ def test_string_equality_preserved(self) -> None:+ assert _Color.red == "red"+ assert isinstance(_Color.red, str)