pyvitals-profiler 1.0.0

An intelligent, lightweight Wall/CPU time and memory profiler with beautiful terminal reports.

PyVitals

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:

pip install pyvitals-profiler

Quickstart

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

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.

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.

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:

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.

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.