algo-analyze 0.1.0
Mini Profiler & Analyzer for Python Functions
Requires Python: >=3.7

# algo_analyze

**Mini Profiler & Analyzer for Python Functions**

`algo_analyze` is a Python package and command-line tool that helps developers analyze their Python functions and scripts. It measures **execution time**, **memory usage**, **function call counts**, and **exceptions**, providing a clean, readable report. Perfect for debugging, performance profiling, and algorithm analysis.

----------

## Features 

-   Measure execution time of Python functions (seconds or milliseconds)
-   Track memory usage (current and peak)
-   Count how many times a function is called
-   Log exceptions with full traceback
-   Command-line interface (CLI) for profiling functions or scripts
-   Supports single or multiple scripts/functions
-   Tabular summary for multiple scripts
-   Lightweight and easy to integrate

----------

## Installation 

### Using pip:
```bash
pip install algo_analyze
```

### Install from source:
```bash
git clone https://github.com/prachi-33/algo_analyze.git
cd algo_analyze
pip install -e .
```

----------

## Usage 

### 1. Python Decorator

Use `@inspect` to profile a function:
```python
from algo_analyze import inspect

@inspect
def add(a, b):
    return a + b

report = add(5, 10)
print(report)
```

**Sample Output:**
```
Function: add
----------------------------------------
Execution Time : 0.000123 sec
Memory Used    : 3.12 KB
Peak Memory    : 5.45 KB
Call Count     : 1
Exception      : None
----------------------------------------
Return Value   : 15
```

### 2. Command-Line Interface (CLI)

Profile any Python function or script from the terminal:
```bash
algo_analyze <script.py> [function_name] [args...]
```

#### Examples:

**Profile a specific function:**
```bash
algo_analyze my_script.py my_function arg1 arg2
```

**Profile an entire script:**
```bash
algo_analyze my_script.py
```

**Profile multiple scripts:**
```bash
algo_analyze script1.py script2.py script3.py
```

**Sample CLI Output:**
```
Analyzing: my_script.py::my_function
========================================
Function: my_function
----------------------------------------
Execution Time : 1.234 sec
Memory Used    : 15.67 KB
Peak Memory    : 23.45 KB
Call Count     : 1
Exception      : None
----------------------------------------
```

### 3. Advanced Usage

#### Profile with custom time units:
```python
from algo_analyze import inspect

@inspect(time_unit='ms')
def complex_calculation():
    return sum(range(1000000))

report = complex_calculation()
print(report)
```

#### Profile recursive functions:
```python
from algo_analyze import inspect

@inspect
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

report = fibonacci(10)
print(report)
# Call count will show total recursive calls
```

#### Context manager usage:
```python
from algo_analyze import Profiler

with Profiler() as prof:
    # Your code here
    result = some_function()
    
print(prof.report())
```

----------

## Configuration 

### Decorator Options
```python
@inspect(
    time_unit='sec',    # 'sec' or 'ms'
    memory_unit='KB',   # 'KB', 'MB', or 'GB'
    show_traceback=True # Show full traceback on exception
)
def my_function():
    pass
```

### CLI Options
```bash
algo_analyze --help                    # Show help
algo_analyze --version                 # Show version
algo_nalyze script.py --json          # Output as JSON
algo_analyze script.py --csv           # Output as CSV
algo_analyze script.py --verbose       # Detailed output
```

----------

## Examples 

### Example 1: Analyzing Algorithm Performance
```python
from algo_analyze import inspect

@inspect
def bubble_sort(arr):
    n = len(arr)
    for i in range(n):
        for j in range(0, n-i-1):
            if arr[j] > arr[j+1]:
                arr[j], arr[j+1] = arr[j+1], arr[j]
    return arr

data = [64, 34, 25, 12, 22, 11, 90]
report = bubble_sort(data.copy())
print(report)
```

### Example 2: Memory-Intensive Operations
```python
from algo_analyze import inspect

@inspect
def create_large_list():
    return [i**2 for i in range(1000000)]

report = create_large_list()
print(report)
```

### Example 3: Exception Handling
```python
from algo_analyze import inspect

@inspect
def divide(a, b):
    return a / b

report = divide(10, 0)  # Will catch and report ZeroDivisionError
print(report)
```

----------

## API Reference 

### `@inspect` Decorator

Decorator to profile a function.

**Parameters:**
- `time_unit` (str): Time unit for display ('sec' or 'ms')
- `memory_unit` (str): Memory unit for display ('KB', 'MB', 'GB')
- `show_traceback` (bool): Show exception traceback

**Returns:** Function wrapper that returns profiling report

### `Profiler` Class

Context manager for profiling code blocks.

**Methods:**
- `report()`: Get profiling report as string
- `stats()`: Get raw statistics as dictionary

----------

## Roadmap 

- [ ] Add visualization support (graphs/charts)
- [ ] Support for async functions
- [ ] Integration with popular testing frameworks
- [ ] Web dashboard for real-time monitoring
- [ ] Comparative analysis between runs
- [ ] Export to multiple formats (HTML, PDF)

----------

## Contributing 

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

Please ensure your PR:
- Follows PEP 8 style guidelines
- Includes tests for new features
- Updates documentation as needed

----------

## Support 

- **Issues**: [GitHub Issues](https://github.com/yourusername/algo_analyze/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/algo_analyze/discussions)
- **Email**: your.email@example.com

----------

## Acknowledgments 

- Inspired by Python's built-in `timeit` and `tracemalloc` modules
- Thanks to all contributors and users

----------

## Author 

**[Prachi](https://github.com/prachi-33)**

----------

**Star this repo if you find it useful!**