Metadata-Version: 2.4
Name: pyintrospect
Version: 0.2.2
Summary: Simple Python introspection tool
Author-email: Hoàng Long <hoanglongdeptrai392@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Hoang Long
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/hoang-long2012/pyintrospect
Project-URL: Source, https://github.com/hoang-long2012/pyintrospect/src/pyintrospect
Project-URL: Repository, https://github.com/hoang-long2012/pyintrospect
Project-URL: Documentation, https://github.com/hoang-long2012/pyintrospect/README.md
Project-URL: Issues, https://github.com/hoang-long2012/pyintrospect/issues
Project-URL: Releases, https://github.com/hoang-long2012/pyintrospect/releases
Project-URL: Changelog, https://github.com/hoang-long2012/pyintrospect/releases
Keywords: inspect,introspection,reflection,debugging,analysis,introspect
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```bash
pip install pyintrospect
```

---

# Quick Start

```python
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()

```python
r.summary()
```

Returns or prints:

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

---

## submodules()

```python
r.submodules()
```

Returns or prints submodules imported in the target module.

---

## variables()

```python
r.variables()
```

Returns or prints module-level variables.

---

## constants()

```python
r.constants()
```

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

---

## functions()

```python
r.functions()
```

Returns or prints functions with:

- Name
- Signature
- Return type (if available)

---

## classes()

```python
r.classes()
```

Returns or prints class definitions with:

- Class name
- Base classes
- `__init__` signature

---

## source()

```python
r.source()
```

Returns or prints module source code (if available).

---

## path()

```python
r.path()
```

Returns or prints absolute file path of the module.

---

## all()

```python
r.all()
```

Returns or prints all available introspection data.

---

## doc(attribute=None)

```python
r.doc()
r.doc("function_name")
```

Returns documentation for:

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

---

# CLI Usage

```bash
pyintrospect <module> [options]
```

## Examples

```bash
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
