PyIntrospect

PyIntrospect is a lightweight Python introspection toolkit that provides structured, human-readable analysis of Python modules at runtime.

It builds on top of Python’s inspect module and organizes raw metadata into a consistent, categorized format for easier debugging, exploration, and tooling.

---

Features

PyIntrospect extracts and structures module information including:

• Submodules
• Variables
• Constants
• Functions (with signatures and return types when available)
• Classes (with base classes and constructor signatures)
• Module source code (when accessible)
• Module file path
• Summary statistics

---

Installation

pip install pyintrospect

---

Quick Start

import pyintrospect
import os

r = pyintrospect.Reflect(os)
r.summary()

---

Core Idea

Python provides powerful introspection tools such as dir() and inspect, but:

• dir() is unstructured and noisy
• inspect is low-level and requires manual processing

PyIntrospect adds a semantic layer on top of inspect, producing structured and categorized output suitable for analysis and tooling.

---

API

Reflect(module, HideDunder=True, pretty=True)

Parameter	Type	Description
module	Module	Target Python module
HideDunder	bool	Hide private and dunder members
pretty	bool	Print formatted output instead of returning raw data

---

Methods

summary()

r.summary()

Returns or prints:

• Module name
• File path
• Version (if available)
• Member counts by type
• Total members

---

submodules()

r.submodules()

Returns or prints submodules imported in the target module.

---

variables()

r.variables()

Returns or prints module-level variables.

---

constants()

r.constants()

Returns or prints module-level constants (uppercase identifiers).

---

functions()

r.functions()

Returns or prints functions with:

• Name
• Signature
• Return type (if available)

---

classes()

r.classes()

Returns or prints class definitions with:

• Class name
• Base classes
• __init__ signature

---

source()

r.source()

Returns or prints module source code (if available).

---

path()

r.path()

Returns or prints absolute file path of the module.

---

all()

r.all()

Returns or prints all available introspection data.

---

doc(attribute=None)

r.doc()
r.doc("function_name")

Returns documentation for:

• Entire module (default)
• Specific attribute (function/class/variable if applicable)

---

CLI Usage

pyintrospect <module> [options]

Examples

pyintrospect os
pyintrospect os --functions
pyintrospect requests --classes --raw

---

CLI Options

Core

• -a, --all Show all information (default if no filter is provided)
• -h, --help Show help
• -V, --version Show version

Inspection

• -f, --functions Show functions
• -c, --classes Show classes
• -v, --variables Show variables
• -C, --constants Show constants
• -m, --submodules Show submodules

Detail

• -s, --source Show source code
• -p, --path Show module path
• -d, --doc Show documentation

Formatting

• -r, --raw Disable pretty print (return raw data)
• -D, --dunder Include dunder/private members

---

Behavior Notes

• Built-in or compiled modules may not expose source code
• Some functions may not provide signature metadata
• Private members are filtered by default unless HideDunder=False

---

Design Philosophy

PyIntrospect is designed with three principles:

• Structure over noise
• Readability over raw inspection
• Practical output over raw metadata

The goal is to make Python introspection usable in real tooling workflows, not just debugging sessions.

---

Version

Current version: 0.2.2

---

License

MIT License

Copyright (c) 2026 Hoàng Long