pyvitals-profiler 1.0.0__tar.gz

pyvitals_profiler-1.0.0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antoine
+
+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.

pyvitals_profiler-1.0.0/PKG-INFO

@@ -0,0 +1,126 @@
+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.

pyvitals_profiler-1.0.0/README.md

@@ -0,0 +1,110 @@
+# 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.

pyvitals_profiler-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+# pyproject.toml
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyvitals-profiler"  # Choose a unique name on PyPI
+version = "1.0.0"
+authors = [
+  { name="Antoine M", email="projet24.apprentissage@gmail.com" },
+]
+description = "An intelligent, lightweight Wall/CPU time and memory profiler with beautiful terminal reports."
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Debuggers",
+]
+dependencies = [
+    "rich>=10.0.0",
+]
+
+[project.scripts]
+# This creates a global terminal command automatically when the package is installed!
+pyvitals = "pyvitals.analyzer:main"
+
+[tool.ruff]
+line-length = 88
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = []

pyvitals_profiler-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyvitals_profiler-1.0.0/src/pyvitals/__init__.py

@@ -0,0 +1,6 @@
+# src/pyvitals/__init__.py
+"""PyVitals: An intelligent lightweight performance profiler."""
+
+from .profiler import track
+
+__all__ = ["track"]

pyvitals_profiler-1.0.0/src/pyvitals/analyzer.py

@@ -0,0 +1,133 @@
+import argparse
+import json
+import os
+
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def load_vitals_data(filepath: str) -> list:
+    """Loads and parses the JSON vitals data file."""
+    if not os.path.exists(filepath):
+        console.print(f"[bold red]Error:[/] File '{filepath}' not found.")
+        return []
+
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except json.JSONDecodeError:
+        console.print(
+            f"[bold red]Error:[/] File '{filepath}' is not a valid JSON file."
+        )
+        return []
+
+
+def analyze_and_display(data: list):
+    """
+    Analyzes the raw profiling data, groups it by function name,
+    calculates Wall/CPU statistics, and renders a rich terminal table.
+    """
+    if not data:
+        return
+
+    # Group data by function name
+    grouped_data = {}
+    for entry in data:
+        name = entry.get("name", "Unknown")
+        if name not in grouped_data:
+            grouped_data[name] = {"wall_times": [], "cpu_times": [], "peaks": []}
+
+        # Handle backward compatibility with Phase 2 data
+        wall = entry.get("wall_time_s", entry.get("execution_time_s", 0))
+        # If cpu_time_s is missing (old data), default to 0
+        cpu = entry.get("cpu_time_s", 0)
+
+        grouped_data[name]["wall_times"].append(wall)
+        grouped_data[name]["cpu_times"].append(cpu)
+        grouped_data[name]["peaks"].append(entry.get("peak_memory_mb", 0))
+
+    # Prepare the Rich Table
+    table = Table(title="Performance Analysis", border_style="blue")
+    table.add_column("Function Name", style="bold yellow")
+    table.add_column("Runs", justify="right", style="cyan")
+    table.add_column("Avg Wall Time", justify="right")
+    table.add_column("Avg CPU Time", justify="right", style="magenta")
+    table.add_column("Workload Profile", justify="center")
+    table.add_column("Trend (Wall)", justify="right")
+    table.add_column("Max Peak Mem", justify="right", style="green")
+
+    for name, metrics in grouped_data.items():
+        wall_times = metrics["wall_times"]
+        cpu_times = metrics["cpu_times"]
+        peaks = metrics["peaks"]
+
+        runs = len(wall_times)
+        avg_wall = sum(wall_times) / runs if runs else 0
+        avg_cpu = sum(cpu_times) / runs if runs else 0
+        last_wall = wall_times[-1]
+        max_peak = max(peaks) if peaks else 0
+
+        # Calculate performance trend percentage (based on Wall Time)
+        if avg_wall > 0:
+            diff_pct = ((last_wall - avg_wall) / avg_wall) * 100
+        else:
+            diff_pct = 0.0
+
+        # Format trend coloring
+        if diff_pct > 5.0:
+            trend_str = f"[bold red]▲ +{diff_pct:.1f}%[/bold red]"
+        elif diff_pct < -5.0:
+            trend_str = f"[bold green]▼ {diff_pct:.1f}%[/bold green]"
+        else:
+            trend_str = f"[dim]~ {diff_pct:.1f}%[/dim]"
+
+        # Determine Workload Profile based on averages
+        if avg_wall > 0 and avg_cpu > 0:
+            utilization = (avg_cpu / avg_wall) * 100
+            if utilization > 80:
+                workload = "[bold red]CPU Bound[/bold red]"
+            elif utilization < 20:
+                workload = "[bold blue]I/O Bound[/bold blue]"
+            else:
+                workload = "[bold yellow]Mixed[/bold yellow]"
+        elif avg_wall > 0 and avg_cpu == 0:
+            # Catch strict I/O bounds where CPU time might round to exactly 0
+            workload = "[bold blue]I/O Bound[/bold blue]"
+        else:
+            workload = "[dim]Unknown[/dim]"
+
+        table.add_row(
+            name,
+            str(runs),
+            f"{avg_wall:.4f} s",
+            f"{avg_cpu:.4f} s",
+            workload,
+            trend_str,
+            f"{max_peak:.4f} MB",
+        )
+
+    console.print(table)
+    console.print(
+        "[dim]Trend compares the last Wall Time to the historical average.[/dim]"
+    )
+
+
+def main():
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(description="Analyze PyVitals JSON export files.")
+    parser.add_argument(
+        "filepath",
+        type=str,
+        help="Path to the JSON vitals file (e.g., vitals_history.json)",
+    )
+
+    args = parser.parse_args()
+
+    data = load_vitals_data(args.filepath)
+    analyze_and_display(data)
+
+
+if __name__ == "__main__":
+    main()

pyvitals_profiler-1.0.0/src/pyvitals/profiler.py

@@ -0,0 +1,202 @@
+import functools
+import inspect
+import json
+import os
+import time
+import tracemalloc
+import warnings
+from datetime import datetime
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+console = Console()
+
+
+class track:
+    """
+    Intelligent profiler for execution time (Wall/CPU) and memory usage.
+    Can be used as a decorator (@track) or a context manager (with track()).
+    """
+
+    def __init__(
+        self, name=None, max_time_s=None, max_mem_mb=None, export_to=None, quiet=False
+    ):
+        """
+        Initializes the tracker with optional thresholds, data export, and verbosity control.
+
+        Args:
+            name (str, optional): Custom name for the display panel.
+            max_time_s (float, optional): Maximum allowed Wall Time in seconds.
+            max_mem_mb (float, optional): Maximum allowed peak memory in megabytes.
+            export_to (str, optional): File path to export the results in JSON format.
+            quiet (bool, optional): If True, suppresses the terminal output.
+        """
+        self.name = name
+        self.max_time_s = max_time_s
+        self.max_mem_mb = max_mem_mb
+        self.export_to = export_to
+        self.quiet = quiet
+        self._start_time = None
+        self._start_cpu_time = None
+        self._is_enabled = os.getenv("PYVITALS_ENABLED", "1") != "0"
+
+    def _render_vitals(self, exec_time, cpu_time, current_mem, peak_mem, display_name):
+        """Generates and prints the visual terminal interface with threshold checks."""
+        peak_mb = peak_mem / (1024 * 1024)
+        current_mb = current_mem / (1024 * 1024)
+
+        time_color = "bold cyan"
+        mem_color = "bold yellow"
+        panel_border = "blue"
+
+        # Check execution time threshold
+        if self.max_time_s and exec_time > self.max_time_s:
+            time_color = "bold red"
+            panel_border = "red"
+            warnings.warn(
+                f"[{display_name}] Wall Time ({exec_time:.4f}s) exceeded limit ({self.max_time_s}s)!",
+                RuntimeWarning,
+            )
+
+        # Check peak memory threshold
+        if self.max_mem_mb and peak_mb > self.max_mem_mb:
+            mem_color = "bold red"
+            panel_border = "red"
+            warnings.warn(
+                f"[{display_name}] Peak memory ({peak_mb:.4f}MB) exceeded limit ({self.max_mem_mb}MB)!",
+                RuntimeWarning,
+            )
+
+        # Calculate CPU Utilization to determine the bottleneck type
+        cpu_utilization = (cpu_time / exec_time) * 100 if exec_time > 0 else 0
+        if cpu_utilization > 80:
+            bottleneck = "[bold red]CPU Bound (Heavy Math/Loops)[/bold red]"
+        elif cpu_utilization < 20:
+            bottleneck = "[bold blue]I/O Bound (Waiting/Network/Sleep)[/bold blue]"
+        else:
+            bottleneck = "[bold yellow]Mixed Workload[/bold yellow]"
+
+        # Table Construction (Using explicit spacing to avoid emoji-width bugs)
+        table = Table(show_header=False, box=None)
+        table.add_column(width=24)
+        table.add_column(justify="right")
+
+        table.add_row(
+            "Wall Time (Total)", f"[{time_color}]{exec_time:.4f} s[/{time_color}]"
+        )
+        table.add_row(
+            "CPU Time (Active)", f"[bold magenta]{cpu_time:.4f} s[/bold magenta]"
+        )
+        table.add_row("Workload Profile", bottleneck)
+        table.add_row("", "")  # Blank row for visual spacing
+        table.add_row(
+            "Max Memory (Peak)", f"[{mem_color}]{peak_mb:.4f} MB[/{mem_color}]"
+        )
+        table.add_row(
+            "Remaining Memory", f"[bold green]{current_mb:.4f} MB[/bold green]"
+        )
+
+        # Panel Display
+        panel = Panel(
+            table,
+            title=f"Results : [bold yellow]{display_name}[/bold yellow]",
+            expand=False,
+            border_style=panel_border,
+        )
+        console.print(panel)
+
+    def _export_to_json(self, exec_time, cpu_time, current_mem, peak_mem, display_name):
+        """Appends the profiling metrics to a JSON file."""
+        if not self.export_to:
+            return
+
+        peak_mb = peak_mem / (1024 * 1024)
+        current_mb = current_mem / (1024 * 1024)
+
+        payload = {
+            "timestamp": datetime.now().isoformat(),
+            "name": display_name,
+            "wall_time_s": round(exec_time, 4),
+            "cpu_time_s": round(cpu_time, 4),
+            "peak_memory_mb": round(peak_mb, 4),
+            "remaining_memory_mb": round(current_mb, 4),
+        }
+
+        data = []
+        if os.path.exists(self.export_to):
+            try:
+                with open(self.export_to, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+            except (json.JSONDecodeError, IOError):
+                pass
+
+        data.append(payload)
+
+        with open(self.export_to, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=4)
+
+    # ---------------------------------------------------------
+    # CONTEXT MANAGER IMPLEMENTATION
+    # ---------------------------------------------------------
+    def __enter__(self):
+        """Triggered when entering a 'with' block."""
+        if not self._is_enabled:
+            return self
+
+        tracemalloc.start()
+        # Track both Wall Time and CPU Time
+        self._start_time = time.perf_counter()
+        self._start_cpu_time = time.process_time()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Triggered when exiting a 'with' block."""
+        if not self._is_enabled:
+            return False
+
+        # Stop trackers
+        end_time = time.perf_counter()
+        end_cpu_time = time.process_time()
+        current_mem, peak_mem = tracemalloc.get_traced_memory()
+        tracemalloc.stop()
+
+        exec_time = end_time - self._start_time
+        cpu_time = end_cpu_time - self._start_cpu_time
+        display_name = self.name or "Code Block"
+
+        if not self.quiet:
+            self._render_vitals(
+                exec_time, cpu_time, current_mem, peak_mem, display_name
+            )
+
+        self._export_to_json(exec_time, cpu_time, current_mem, peak_mem, display_name)
+
+        return False
+
+    # ---------------------------------------------------------
+    # DECORATOR IMPLEMENTATION
+    # ---------------------------------------------------------
+    def __call__(self, func):
+        """Triggered when used as a decorator (@track)."""
+        if not self._is_enabled:
+            return func
+
+        display_name = self.name or f"{func.__name__}()"
+
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            self.name = display_name
+            with self:
+                return func(*args, **kwargs)
+
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            self.name = display_name
+            with self:
+                return await func(*args, **kwargs)
+
+        if inspect.iscoroutinefunction(func):
+            return async_wrapper
+        return sync_wrapper

pyvitals_profiler-1.0.0/src/pyvitals_profiler.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+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.

pyvitals_profiler-1.0.0/src/pyvitals_profiler.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENCE
+README.md
+pyproject.toml
+src/pyvitals/__init__.py
+src/pyvitals/analyzer.py
+src/pyvitals/profiler.py
+src/pyvitals_profiler.egg-info/PKG-INFO
+src/pyvitals_profiler.egg-info/SOURCES.txt
+src/pyvitals_profiler.egg-info/dependency_links.txt
+src/pyvitals_profiler.egg-info/entry_points.txt
+src/pyvitals_profiler.egg-info/requires.txt
+src/pyvitals_profiler.egg-info/top_level.txt
+tests/test_profiler.py

pyvitals_profiler-1.0.0/src/pyvitals_profiler.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyvitals_profiler-1.0.0/src/pyvitals_profiler.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyvitals = pyvitals.analyzer:main

pyvitals_profiler-1.0.0/src/pyvitals_profiler.egg-info/requires.txt

@@ -0,0 +1 @@
+rich>=10.0.0

pyvitals_profiler-1.0.0/src/pyvitals_profiler.egg-info/top_level.txt

@@ -0,0 +1 @@
+pyvitals

pyvitals_profiler-1.0.0/tests/test_profiler.py

@@ -0,0 +1,85 @@
+import asyncio
+import json
+
+import pytest
+
+from pyvitals import track
+
+
+# ---------------------------------------------------------
+# 1. Test Synchronous Decorator
+# ---------------------------------------------------------
+def test_sync_decorator_returns_correct_value():
+    @track(quiet=True)
+    def compute(a, b):
+        return a + b
+
+    result = compute(5, 7)
+    assert result == 12, "The decorator modified the function's return value!"
+
+
+# ---------------------------------------------------------
+# 2. Test Asynchronous Decorator
+# ---------------------------------------------------------
+@pytest.mark.asyncio
+async def test_async_decorator_returns_correct_value():
+    @track(quiet=True)
+    async def fetch_data():
+        await asyncio.sleep(0.01)
+        return {"status": "ok"}
+
+    result = await fetch_data()
+    assert result["status"] == "ok", "The async decorator failed to return the value!"
+
+
+# ---------------------------------------------------------
+# 3. Test Context Manager
+# ---------------------------------------------------------
+def test_context_manager_executes_without_error():
+    data = []
+    with track(name="Test Loop", quiet=True):
+        for i in range(10):
+            data.append(i)
+
+    assert len(data) == 10, "Context manager blocked code execution!"
+
+
+# ---------------------------------------------------------
+# 4. Test JSON Export
+# ---------------------------------------------------------
+def test_json_export_appends_data(tmp_path):
+    # tmp_path is a built-in pytest fixture for temporary directories
+    export_file = tmp_path / "test_vitals.json"
+
+    @track(export_to=str(export_file), quiet=True)
+    def dummy_task():
+        pass
+
+    # Run twice
+    dummy_task()
+    dummy_task()
+
+    # Verify the file was created and contains exactly 2 records
+    assert export_file.exists(), "JSON export file was not created!"
+
+    with open(export_file, "r") as f:
+        data = json.load(f)
+
+    assert len(data) == 2, f"Expected 2 records in JSON, found {len(data)}"
+    assert "wall_time_s" in data[0], "Missing keys in JSON payload"
+
+
+# ---------------------------------------------------------
+# 5. Test Global Kill-Switch
+# ---------------------------------------------------------
+def test_kill_switch_disables_profiler(monkeypatch):
+    # Simulate setting the environment variable in production
+    monkeypatch.setenv("PYVITALS_ENABLED", "0")
+
+    @track(quiet=True)
+    def simple_func():
+        return "alive"
+
+    assert simple_func() == "alive"
+    # If the kill-switch works, tracemalloc won't crash if called outside,
+    # and the function should behave exactly as if undecorated.