Metadata-Version: 2.4
Name: pyvitals-profiler
Version: 1.0.0
Summary: An intelligent, lightweight Wall/CPU time and memory profiler with beautiful terminal reports.
Author-email: Antoine M <projet24.apprentissage@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: rich>=10.0.0
Dynamic: license-file

# PyVitals

[![PyPI version](https://img.shields.io/pypi/v/pyvitals-profiler.svg)](https://pypi.org/project/pyvitals-profiler/)
[![Python versions](https://img.shields.io/pypi/pyversions/pyvitals-profiler.svg)](https://pypi.org/project/pyvitals-profiler/)
[![CI Status](https://github.com/yourusername/pyvitals/actions/workflows/tests.yml/badge.svg)](https://github.com/yourusername/pyvitals/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**PyVitals** is an intelligent, lightweight performance profiler for Python. 
It tracks **Wall Time**, **CPU Time**, and **Peak Memory** usage with surgical precision, generating beautiful terminal reports and JSON history logs. 

Whether you are debugging a slow API or hunting down a memory leak, PyVitals tells you exactly if your code is *CPU Bound* or *I/O Bound*.

---

## Features

- **Universal:** Works seamlessly with both synchronous (`def`) and asynchronous (`async def`) functions.
- **Flexible:** Use it as a `@decorator` or as a `with` context manager for specific code blocks.
- **Smart Diagnostics:** Automatically calculates CPU vs. Wall Time to detect I/O or CPU bottlenecks.
- **Threshold Alerts:** Set limits for execution time or memory and get visual warnings if exceeded.
- **Zero-Overhead Production:** Built-in Kill-Switch environment variable to disable tracking instantly in production.
- **CLI Analyzer:** Export your metrics to JSON and use the built-in CLI tool to track performance regressions over time.

---

## Installation

Install via `pip`:

```bash
pip install pyvitals-profiler
```

## Quickstart
1. As a Decorator (Sync & Async)
Simply add @track() to any function you want to profile.

```Python
import asyncio
from pyvitals import track

@track(name="Database Query", max_time_s=1.5)
async def fetch_users():
    await asyncio.sleep(1.0) # Simulating I/O Wait
    return {"status": "success"}

asyncio.run(fetch_users())
```

2. As a Context Manager
If you only want to profile a specific loop without decorating the whole function, use the with statement.

```Python
from pyvitals import track

def process_heavy_data():
    print("Initializing...")
    
    # Only profile this specific block
    with track(name="Matrix Math", max_mem_mb=50):
        data = [x**2 for x in range(1_000_000)]
        
    print("Done!")
    
process_heavy_data()
```

## Exporting & Analyzing Data (CLI)
PyVitals allows you to save your performance history to detect regressions.

Step 1: Export to JSON
Use the export_to parameter. You can also use quiet=True to hide the terminal output if you are running the function thousands of times.

```Python
from pyvitals import track

@track(export_to="vitals_history.json", quiet=True)
def background_task():
    # ... task logic ...
    pass
```

Step 2: Use the CLI Analyzer
PyVitals comes with a built-in command-line tool. Point it to your JSON file to generate a rich historical trend analysis table:

```Bash
pyvitals vitals_history.json
```

The CLI will display the average Wall/CPU time, the maximum peak memory, the workload profile (I/O vs CPU), and highlight performance regressions (e.g., ▲ +12.5% slower).

## Production Kill-Switch
You don't need to remove all your @track decorators before deploying to production.
Set the following environment variable to 0 to instantly disable PyVitals. It will bypass the tracking logic entirely, ensuring 0ms performance overhead.

```Bash
export PYVITALS_ENABLED=0
```

## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.

Clone the repository.

Install dependencies: pip install -e .

Run tests: pytest

## License
This project is licensed under the MIT License - see the LICENSE file for details.
