Metadata-Version: 2.4
Name: inspectlab
Version: 0.1.0
Summary: A CLI tool for inspecting Python source code using AST
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer

<p align="center">
  <img src="logo.png" alt="InspectLab Logo" width="220">
</p>

# InspectLab

InspectLab is a lightweight Python CLI for inspecting Python source code directly from the terminal.

It uses Python's built-in `ast` module to analyze source files without executing them. InspectLab can quickly show functions, classes, imports, and the full AST structure of a file.

## Features

* Inspect functions and async functions
* Detect generators and return/yield expressions
* Inspect classes, inheritance, metaclasses, and methods
* Show imports and aliases
* Show arguments and type annotations
* Show decorators and docstrings
* Show source line ranges
* Print the complete Python AST

## Why InspectLab?

InspectLab is useful when you want a fast structural overview of a Python file without opening it manually or running its code.

### Advantages

* **Safe static inspection** — analyzes source code without executing the target file.
* **Fast CLI workflow** — inspect a file with one command.
* **No parser setup** — built on Python's standard `ast` module.
* **Useful for debugging and review** — quickly understand unfamiliar Python code.
* **Detailed output** — includes annotations, decorators, docstrings, return values, line numbers, and more.

## Installation

Install InspectLab from PyPI:

```bash
pip install inspectlab
```

Then verify that the CLI is available:

```bash
inspectlab --help
```

> InspectLab relies on modern Python AST features such as `ast.unparse`, so Python 3.9 or newer is recommended.

## Basic Usage

InspectLab provides four commands:

```bash
inspectlab functions FILE
inspectlab classes FILE
inspectlab imports FILE
inspectlab tree FILE
```

`FILE` is the Python filename you want to inspect.

InspectLab searches for that filename recursively from your current working directory.

Example:

```bash
inspectlab functions app.py
```

---

## 1. `functions`

Inspect all functions found in a Python file.

### Usage

```bash
inspectlab functions FILE
```

Example:

```bash
inspectlab functions app.py
```

### What it outputs

For each function, InspectLab shows:

* Function name
* Function type
* Arguments and argument kinds
* Argument type annotations
* Return and yield expressions
* Return type annotation
* Decorators
* Docstring
* Start and end line numbers

It recognizes normal functions, async functions, generators, and async generators.

Example output:

```text
Name: add
Type: Function with Return
Arguments:
  - a: int [Normal]
  - b: int [Normal]
Returns: [{'Return': 'a + b'}]
Return Data Type: int
Decorators: []
Docstring: Add two integers.
Lines: {'Start': 9, 'End': 11}
```

---

## 2. `classes`

Inspect classes and their methods.

### Usage

```bash
inspectlab classes FILE
```

Example:

```bash
inspectlab classes models.py
```

### What it outputs

For each class, InspectLab shows:

* Class name
* Inherited classes
* Metaclass
* Class decorators
* Docstring
* Start and end line numbers
* Methods defined directly inside the class
* Detailed function information for each method

Example output:

```text
Class: Admin
Inherits: User
Metaclass: None
Decorators: None
Docstring: Represents an administrator.
Lines: 54 - 65
Methods:
  Name: validate
  Type: Function with Return
  Arguments:
    - value: int [Normal]
  Returns: [{'Return': 'value > 0'}]
  Return Data Type: bool
  Decorators: ['staticmethod']
  Docstring: None
  Lines: {'Start': 64, 'End': 65}
```

---

## 3. `imports`

List imports used by a Python file.

### Usage

```bash
inspectlab imports FILE
```

Example:

```bash
inspectlab imports app.py
```

### What it outputs

The command shows:

* Import type: `import` or `from ... import ...`
* Imported module or name
* Import aliases
* Source line number

Example output:

```text
Type: Import
Line: 2
Imports:
  - sys as system

Type: ImportFrom
Line: 6
Module: collections
Imports:
  - defaultdict as dd
```

---

## 4. `tree`

Print the complete Abstract Syntax Tree of a Python file.

### Usage

```bash
inspectlab tree FILE
```

Example:

```bash
inspectlab tree app.py
```

### What it outputs

This command prints Python's AST representation using an indented tree. It is useful when you need to see the exact syntax nodes generated from the source code.

Example output:

```text
Module(
    body=[
        Import(
            names=[
                alias(name='os')]),
        FunctionDef(
            name='add',
            args=arguments(...),
            body=[...])
    ])
```

## Example Workflow

```bash
# See the functions in a file
inspectlab functions main.py

# Inspect its classes
inspectlab classes main.py

# Check its dependencies/imports
inspectlab imports main.py

# View the raw AST
inspectlab tree main.py
```

## Error Handling

If InspectLab cannot find or parse the requested file, the CLI currently prints:

```text
Wrong file name or typed out command
```

Make sure you run the command from a directory where InspectLab can find the requested filename.

## License

Add your project license here.
