# pyinspect: A Terminal Tool for Finding, Inspecting, and Debugging Python Code

> pyinspect is a Python library that searches modules for functions, prints source code, and enhances tracebacks with local variable details. It targets developers who prefer staying in the terminal over opening editors or browsers.

**FedeClaudi/pyinspect** — find functions when you can't remember their name

- Repository: https://github.com/FedeClaudi/pyinspect
- Stars: 100 · Forks: 4
- Language: Python
- License: MIT
- Published: 2026-08-17 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/fedeclaudi-pyinspect

## A Terminal-Centric Answer to Forgotten Function Names

pyinspect solves a specific annoyance: you know a function exists, but you cannot recall its exact name or its signature. The README pitches it as a package for lazy programmers, and the core use case is staying in the terminal instead of switching to a browser or an editor. The library provides a search function that scans a module and its submodules for names matching a query. It also prints the source code of a function directly to the terminal, so you can read the implementation without opening a file. The intended audience is Python developers who work in a REPL or a terminal-heavy workflow and want quick answers. It is not a static analysis tool or a linter; it is a convenience layer for interactive exploration.

## How search and showme Work Under the Hood

The README shows two central functions: `pi.search(pi, name='what')` and `pi.showme(pi.search)`. The search function takes a module or a class and a name string, then returns a table of matching functions and methods. The documentation notes that search traverses submodules when given a module, so `search(matplotlib, 'plot')` would scan the entire library. For classes, search also includes methods from parent classes unless you pass `include_parents=False`. Parent methods are highlighted in a different color in the output, which helps you distinguish inherited methods from those defined in the class itself. The `showme` function prints the source code of a given function, using Python's inspect module under the hood. There is no indication that search uses any indexing or caching; it likely iterates over the module's attributes at call time, which means it works on any imported module but could be slow on very large libraries.

## Getting Started: Installation and Basic Commands

Installation is a single pip command: `pip install pyinspect`. The README gives no other dependency instructions, so the package presumably pulls in whatever it needs. To list local variables, you call `pi.what()` with no arguments, which prints all variables in the local scope. You can also pass a specific variable, like `pi.what(a)`, to see its content, definition location, and some attributes. For function search, the example is `pi.search(pi, name='what')`, which returns a table. To view source, use `pi.showme(pi.search)`. The traceback installation is `pi.install_traceback()` at the start of your script. That call accepts several keyword arguments: `hide_locals=True` to suppress local variable panels, `relevant_only=True` to show only variables in the error line, `all_locals=True` to include imported modules, and `keep_frames` to control how many stack frames appear in nested tracebacks. These are all real options from the README, so you can configure the verbosity of the error output.

## Traceback Enhancement: The Most Substantial Feature

The traceback functionality is the most elaborate part of the project. When you call `pi.install_traceback()`, the library replaces the default exception hook with a custom handler. On error, it prints a summary that includes the local variables relevant to the failing line. The README demonstrates this with a NumPy example where `a + c` fails because the arrays have different sizes. The traceback highlights `a` and `c` because those are the variables in the error line, not `b`, which is defined but unused. That is a deliberate design choice: focus the developer's attention on the data that caused the failure. The `relevant_only` flag tightens this further. There is also a `keep_frames` option to decide how many frames to show in nested calls, so you can see locals from the calling function as well as the failing one. This is genuinely useful for debugging, and it goes beyond what standard Python tracebacks offer.

## The 'why' Command and Stack Overflow Integration

The README mentions a second way to get help: passing `enable_prompt=True` to `install_traceback` triggers a prompt after an error, asking if you want to search for solutions online. Typing `y` presumably opens a browser or fetches results, though the README is truncated at that point. There is also a `why` command that can be run in a terminal window, but the details are cut off. The intended behavior is to automate the copy-paste of an error message into a search engine or Stack Overflow. This is a bold feature because it requires network access and parsing external content, which can be fragile. The documentation does not specify how the lookup is performed or whether it respects network proxies. Given the project's last push in October 2020, the integration likely targets a specific Stack Overflow API that may have changed since then. This is a potential failure point for modern users.

## Limitations and When It Is the Wrong Tool

The most obvious limitation is the project's inactivity. The last release, v0.0.8, came out on October 13, 2020. Python itself has moved on, with newer versions and changes to the inspect module and exception handling. There is no indication that pyinspect supports Python 3.11 or later, and the traceback hook may conflict with other libraries that also install custom excepthooks, such as IPython or rich. The search function's method of scanning submodules could be slow on large packages like pandas or torch, and the README does not mention any caching. The tool is also not a replacement for a debugger: it shows locals but does not let you step through code or set breakpoints. If you need interactive debugging, you are better off with pdb or an IDE. Finally, the Stack Overflow lookup depends on the exact error message format, which varies widely, so it may often return irrelevant results.

## Alternatives: The Built-in inspect Module and IDE Features

The closest alternative is Python's standard library `inspect` module, which provides `getsource`, `getdoc`, and `getmembers`. With `inspect.getmembers(module, inspect.isfunction)` you can list all functions, and `inspect.getsource(func)` prints the source code. The difference is that `inspect` does not filter by name substring or present results in a formatted table; you have to write a loop yourself. pyinspect is a convenience wrapper around these capabilities. For tracebacks, the built-in `traceback` module gives you formatted exception information, but it does not automatically show local variables. IDEs like PyCharm or VS Code offer hover-to-see-docstrings and jump-to-definition, which solve the 'forgot the name' problem without any search command. The trade-off is that an IDE is a heavier environment, whereas pyinspect works in a plain terminal. If you already live in an IDE, pyinspect adds little; if you are in a REPL or SSH session, it might save a few keystrokes.

## Maintenance, License, and Upgrade Cost

The project is licensed under MIT, which means you can freely use, modify, and redistribute it, including in commercial projects. There is no corporate backing or community governance visible in the repository. The last push was in October 2020, and there have been no commits since then, so the maintenance cost is effectively zero: there is nothing to upgrade to. The flip side is that you inherit any bugs that exist in v0.0.8. The README does not list dependencies, but the traceback feature likely relies on internal Python APIs that could break with a new Python release. If you adopt pyinspect, you should pin the version in your requirements file and test it with your Python version. The upgrade cost is minimal because there are no newer versions, but the risk is that you will eventually need to fork the project if you hit a compatibility issue. The MIT license permits that, but it means you take on the maintenance burden yourself.

## Conclusion

Adopt pyinspect if you spend long sessions in the terminal and frequently forget function names or want error context without a debugger. Skip it if you rely on IDE features like jump-to-definition or need support for Python versions beyond what the 2020 release notes cover. Before adopting, verify that the traceback handler works with your Python version and that the Stack Overflow lookup integrates with your network environment, since the project has not been updated since October 2020.

## FAQ

### How to inspect a Python object with pyinspect?

Call pi.what() with no argument to print every variable in your local scope, or pass a variable, for example pi.what(a), to see its content, where it has been defined, and some of its attributes and methods.

### What does inspect do in Python, and is pyinspect related?

They are different things. This repository is pyinspect, a separate package that finds functions by name across modules, prints their source, and installs richer tracebacks. It does not describe the standard library's inspect module.

### How do I install pyinspect?

Run pip install pyinspect. It requires Python 3.6 or later, and pulls in rich, numpy, google, bs4, click, and requests.

### How does the pyinspect traceback feature work?

Call pi.install_traceback() at the start of your script. On an error you get a traceback with the local variables, with the variables on the failing line highlighted. relevant_only=True narrows it to that line, hide_locals=True removes the panels, all_locals=True includes imported modules, and keep_frames controls nested traceback depth.

### What console commands does pyinspect install?

Two: why, mapped to pyinspect.answers: cli_get_answers, and ask, mapped to pyinspect.answers: cli_ask. The README also describes enable_prompt=True on install_traceback, which offers to look the error up online after a traceback.

## Sources

- [Official README](https://github.com/FedeClaudi/pyinspect#readme)
- [Project repository](https://github.com/FedeClaudi/pyinspect)
- [Release notes](https://github.com/FedeClaudi/pyinspect/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/fedeclaudi-pyinspect