What is pypeek?

pypeek is a minimal Python command-line tool that lets you inspect objects, modules, or files with one command. It’s built to be fast, lightweight, and useful for debugging or code exploration.

🔗 View pypeek on GitHub

Features

  • Quickly preview attributes and docstrings of any Python object
  • Peek inside .py files or modules without running them
  • Pretty, readable output for both shell and IDE use
  • Makes sense of unfamiliar codebases in seconds

Why did i write this?

I was finding it difficult to visualize my longer and multi-file programs and wanted a quick view like this. I looked for an existing tool but nothing worked the way I wanted. I decided to take the caveman approach and create the tool I wanted. It’s a work in progress but a useful one.

usage

pypeek myscript.py              # Show classes, functions, entry point
pypeek myscript.py:SomeClass    # Inspect a specific class or object
pypeek myscript.py --verbose    # Show all return paths with conditions

Sample Output

$ python cavepeek.py my_script.py

📄 my_script.py
──────────────────────────────

📘 Module:
Does awesome things.

🏩 Classes:
──────────────────────────────

🧱 class Ninja
  • stealth(self)
    📘 Move silently.
    ↪ return 'shadow'
  • attack(self, target)
    ↪ (no return)

🔧 Top-Level Functions:
──────────────────────────────

• helper()
  ↪ return True

🚀 Entry Point:
──────────────────────────────

• main()
  ↪ return 0

🚀 Executable:
Yes (has __main__ block)

Cool bits

I learned some useful tricks creating this script. Here are a few highlights:

  • AST (Abstract Syntax Tree)

Pypeek uses the ast module to map out top-level functions, classes, docstrings and more–no code execution required. We use a custom CodeSummary class to walk the AST for a given file to peek at its structure and introspect interesting details.

class CodeSummary(ast.NodeVisitor):
    ...
    def visit_ClassDef(self, node):
        # Finds all classes and their methods
    def visit_FunctionDef(self, node):
        # Gathers all functions, their arguments, docstrings, returns

Again a caveman approach but it has the benefit of working on structure and not requiring running code.

  • Context-Aware return tracking

Finds the conditional associated with a return that lives inside nested logic or an if statement. It prints the return and the condition that wraps it. It’s a great technique for understanding your outputs as well as your inputs.

  • Main Function Special Treatment

If there is a main() function, it gets highlighted separately. Iif the file has an if __name__=="__main__" block, you’ll know if it’s callable from the CLI.

  • Pretty Print Helpers

Functions and methods are shown with names, arguments, docstring line and each return’s code/conditions in a compact, quick-to-read and CLI friendly way.

  • Graceful Fallbacks

Non-Python file? Syntax errors? Missing docstrings? Everything gets handled gently with clear CLI feedback. No ugly tracebacks.