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)

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