Inspecting Objects

Relevant source files

• rich/__init__.py
• rich/_inspect.py
• rich/json.py
• tests/test_inspect.py
• tests/test_json.py

Rich provides an object inspection tool that lets you examine Python objects—attributes, methods, docstrings, and values—in a structured, highlighted panel. The main entry point is inspect() in rich/__init__.py, backed by the Inspect renderable in rich/_inspect.py.

For pretty printing objects without detailed inspection, see page 6.3.

Overview

The inspection flow starts with a call to rich.inspect(), which constructs an Inspect instance and passes it to a Console for rendering. The Inspect class implements __rich__(), returning a Panel.fit() wrapping a Group of generated renderables.

Data flow through inspect

Sources: rich/__init__.py120-174 rich/_inspect.py21-81

The inspect() Function

rich.inspect() rich/__init__.py120-174 is the public entry point. It creates an Inspect instance and calls _console.print(_inspect).

Special behavior: When you call inspect(inspect) (passing the function itself as obj), it automatically enables help=True, methods=True, and docs=True so that the function self-documents its own options.

Parameters

Parameter	Type	Default	Description
obj	Any	required	The Python object to inspect
console	Console	None	Console to use; falls back to global console
title	str	None	Custom panel title; defaults to object's type string
help	bool	False	Show full docstring instead of only the first paragraph
methods	bool	False	Include callable attributes in the output
docs	bool	True	Render docstrings
private	bool	False	Include single-underscore attributes
dunder	bool	False	Include double-underscore attributes
sort	bool	True	Sort attributes (non-callables first, then alphabetical ignoring underscores)
all	bool	False	Equivalent to setting methods, private, and dunder all to True
value	bool	True	Show a pretty-printed representation of the object's value

Sources: rich/__init__.py120-174

The Inspect Renderable

Inspect rich/_inspect.py21-238 is the core class. It extends JupyterMixin and implements __rich__().

How Inspect.__init__ resolves options rich/_inspect.py37-62:

• If all=True, then methods, private, and dunder are all set to True.
• If dunder=True, then private is also set to True (dunders imply private visibility).
• If help=True, then docs is also set to True.
• The title defaults to _make_title(obj): uses str(obj) for classes, callables, and modules; uses str(type(obj)) for all other values.

__rich__() output structure rich/_inspect.py74-81:

Sources: rich/_inspect.py74-81 rich/_inspect.py125-216

Attribute Rendering (_render)

The _render() method rich/_inspect.py125-216 iterates over dir(obj), filters based on options, and builds a Table.grid:

1. Key filtering: Excludes dunders unless self.dunder, excludes single-underscore keys unless self.private.
2. Attribute access: Uses safe_getattr() which catches all exceptions and returns (error, None) on failure.
3. Sorting: When self.sort is True, applies sort_items key: (callable(value), key.strip("_").lower()). This puts non-callables before callables, then sorts alphabetically ignoring leading/trailing underscores.
4. Callables: Skipped unless self.methods=True; shown with _get_signature() and optional doc text appended.
5. Non-callables: Shown with Pretty(value, highlighter=highlighter).
6. Errors: Attributes that raised an exception during access are shown with the error repr and inspect.error style.
7. Hidden count: If items were filtered out, a message like "N attribute(s) not shown. Run inspect(inspect) for options." is yielded instead of the table.

Sources: rich/_inspect.py125-216

Signature Formatting (_get_signature)

_get_signature(name, obj) rich/_inspect.py82-123:

• Calls inspect.signature(obj). On ValueError, falls back to "(...)". On TypeError, returns None (attribute shown as a value instead).
• Tries inspect.getfile(obj) and, if successful, adds a link file://... hyperlink to the callable name.
• Prefixes with "class", "async def", or "def" depending on the object type.
• Returns an assembled Text with inspect.callable, inspect.def, inspect.async_def, or inspect.class styles.

Sources: rich/_inspect.py82-123

Docstring Formatting (_get_formatted_doc)

_get_formatted_doc(object_) rich/_inspect.py218-237:

1. Calls inspect.getdoc(object_) (handles inheritance).
2. Cleans indentation with inspect.cleandoc().
3. If self.help is False, takes only the first paragraph via _first_paragraph() (splits on "\n\n").
4. Passes through escape_control_codes() to sanitize special characters (e.g., \r, \v, \a).

Sources: rich/_inspect.py15-18 rich/_inspect.py218-237

MRO Utilities

rich/_inspect.py exports three utility functions used by other parts of Rich (particularly by the Traceback system in page 6.2) to perform type-checking against fully-qualified class names without importing those classes at runtime.

MRO utility function signatures

Function	Returns	Description
get_object_types_mro(obj)	tuple[type, ...]	Returns the MRO of obj's class. If obj itself has __mro__ (i.e., is a class), uses it directly.
get_object_types_mro_as_strings(obj)	list[str]	Returns each MRO entry as "module.qualname", e.g. ["json.decoder.JSONDecoder", "builtins.object"].
is_object_one_of_types(obj, names)	bool	Returns True if any fully-qualified name in names appears in the object's MRO string list.

Note: get_object_types_mro avoids type(obj) is type because it doesn't work for classes using abc.ABCMeta and similar metaclasses. It checks for the presence of __mro__ instead rich/_inspect.py240-246

Sources: rich/_inspect.py240-272 tests/test_inspect.py458-516

The JSON Renderable

rich/json.py provides the JSON class, a separate renderable for pretty-printing JSON with syntax highlighting. It is also exposed via rich.print_json() rich/__init__.py77-117 and Console.print_json().

Construction

Method	Input	Description
JSON(json_str, ...)	A JSON-encoded str	Parses with json.loads, reformats with json.dumps, then highlights.
JSON.from_data(data, ...)	Any JSON-serializable Python object	Skips the loads step; goes directly to json.dumps.

Both accept the same optional parameters:

Parameter	Default	Description
indent	2	Number of spaces to indent
highlight	True	Apply JSONHighlighter; set to False for plain output
skip_keys	False	Skip dict keys that aren't basic types
ensure_ascii	False	Escape all non-ASCII characters
check_circular	True	Detect circular references
allow_nan	True	Allow NaN/Infinity values
default	None	Callable for non-serializable values
sort_keys	False	Sort dictionary keys

JSON.__rich__() rich/json.py101-102 simply returns self.text, a Text object with no_wrap=True and overflow=None, processed by JSONHighlighter (or NullHighlighter when highlight=False).

JSON class structure

The module also ships a CLI entry point: python -m rich.json <path> prints a file, or - reads from stdin rich/json.py105-139

Sources: rich/json.py9-103 rich/__init__.py77-117

Component Relationships

Class-level view of the inspect subsystem

Sources: rich/_inspect.py1-272 rich/__init__.py120-174

Usage Tips

Goal	Option to set
See methods with signatures	methods=True
See everything	all=True
See full docstrings	help=True
See _private attributes	private=True
See __dunder__ attributes	dunder=True
Hide the pretty-printed value	value=False
Custom panel heading	title="My Title"
Use a specific Console	console=my_console

Calling inspect(inspect) is the built-in self-help mechanism: the function detects this case and enables help, methods, and docs automatically rich/__init__.py158-165

Style Keys Used

The Inspect renderable uses the following style keys, which can be themed:

Style Key	Applied To
scope.border	The outer Panel.fit() border
inspect.callable	Callable name in signature
inspect.def	def keyword prefix
inspect.async_def	async def keyword prefix
inspect.class	class keyword prefix
inspect.attr	Normal attribute names
inspect.attr.dunder	Dunder attribute names
inspect.equals	The = separator
inspect.help	Docstring text
inspect.doc	Inline doc appended to method signatures
inspect.error	Attribute keys that raised an error
inspect.value.border	Border of the nested value Panel

Sources: rich/_inspect.py98 rich/_inspect.py165 rich/_inspect.py178-204

Comparison with Python Built-ins

Rich's inspect() function provides several advantages over Python's built-in dir() and help():

Feature	Rich inspect()	Python dir()	Python help()
Colorization	✓	✗	✗
Syntax highlighting	✓	✗	✗
Object value display	✓	✗	✗
Method signatures	✓	✗	✓ (text only)
Selective display of attributes	✓	✗	✗
Docstring formatting	✓	✗	✓ (text only)
Attributes table	✓	List only	✓ (text only)
Filtering ability	✓	✗	✗

Debugging with inspect()

The inspect() function is particularly useful for debugging:

1. When exploring unfamiliar APIs or objects
2. When trying to understand complex object structures
3. When checking object state during debugging sessions
4. For exploring library internals without leaving the terminal

Rich's inspect functionality gives you a clear, structured view of any Python object, making it easier to understand its structure, capabilities, and current state.