pytest-async-benchmark 0.1.1__py3-none-any.whl

pytest_async_benchmark/__init__.py

@@ -0,0 +1,31 @@
+"""pytest-async-benchmark: Modern pytest benchmarking for async code. 🚀"""
+
+__version__ = "0.1.1"
+__author__ = "Mihai Farcas"
+__email__ = "contact@mihai.ltd"
+
+from .analytics import benchmark_summary, compare_benchmarks, performance_grade
+from .comparison import (
+    BenchmarkComparator,
+    BenchmarkScenario,
+    a_vs_b_comparison,
+    quick_compare,
+)
+from .display import display_comparison_table, format_speedup, format_time
+from .plugin import async_benchmark
+from .runner import AsyncBenchmarkRunner
+
+__all__ = [
+    "async_benchmark",
+    "AsyncBenchmarkRunner",
+    "BenchmarkComparator",
+    "BenchmarkScenario",
+    "quick_compare",
+    "a_vs_b_comparison",
+    "display_comparison_table",
+    "format_time",
+    "format_speedup",
+    "compare_benchmarks",
+    "performance_grade",
+    "benchmark_summary",
+]

pytest_async_benchmark/analytics.py

@@ -0,0 +1,49 @@
+"""Additional utilities for pytest-async-benchmark."""
+
+import statistics
+from typing import Any
+
+
+def compare_benchmarks(
+    result1: dict[str, Any], result2: dict[str, Any]
+) -> dict[str, float]:
+    """Compare two benchmark results and return relative performance metrics."""
+    return {
+        "mean_ratio": result2["mean"] / result1["mean"],
+        "min_ratio": result2["min"] / result1["min"],
+        "max_ratio": result2["max"] / result1["max"],
+        "speedup": result1["mean"] / result2["mean"],
+        "relative_stddev": (result2["stddev"] - result1["stddev"]) / result1["stddev"],
+    }
+
+
+def benchmark_summary(results: list[dict[str, Any]]) -> dict[str, Any]:
+    """Create a summary of multiple benchmark results."""
+    all_means = [r["mean"] for r in results]
+    all_stddevs = [r["stddev"] for r in results]
+
+    return {
+        "total_tests": len(results),
+        "fastest_mean": min(all_means),
+        "slowest_mean": max(all_means),
+        "average_mean": statistics.mean(all_means),
+        "mean_variation": statistics.stdev(all_means) if len(all_means) > 1 else 0,
+        "stability_score": 1
+        - (statistics.mean(all_stddevs) / statistics.mean(all_means)),
+    }
+
+
+def performance_grade(result: dict[str, Any], thresholds: dict[str, float]) -> str:
+    """Grade performance based on configurable thresholds."""
+    mean_time = result["mean"]
+
+    if mean_time <= thresholds.get("excellent", 0.001):
+        return "A+"
+    elif mean_time <= thresholds.get("good", 0.005):
+        return "A"
+    elif mean_time <= thresholds.get("acceptable", 0.01):
+        return "B"
+    elif mean_time <= thresholds.get("slow", 0.05):
+        return "C"
+    else:
+        return "D"

pytest_async_benchmark/comparison.py

@@ -0,0 +1,241 @@
+"""
+Comparison utilities for pytest-async-benchmark.
+
+This module provides high-level utilities for comparing multiple benchmark results
+and displaying them in various formats.
+"""
+
+from collections.abc import Awaitable
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from .analytics import compare_benchmarks, performance_grade
+from .display import display_comparison_table, format_speedup, format_time
+from .runner import AsyncBenchmarkRunner
+
+
+@dataclass
+class BenchmarkScenario:
+    """Represents a single benchmark scenario."""
+
+    name: str
+    func: Callable[[], Awaitable[Any]]
+    rounds: int = 5
+    iterations: int = 10
+    description: Optional[str] = None
+
+
+class BenchmarkComparator:
+    """High-level utility for comparing multiple benchmarks."""
+
+    def __init__(self, console: Optional[Console] = None):
+        self.console = console or Console()
+        self.runner = AsyncBenchmarkRunner()
+        self.results: list[dict[str, Any]] = []
+
+    async def add_scenario(
+        self,
+        name: str,
+        func: Callable[[], Awaitable[Any]],
+        rounds: int = 5,
+        iterations: int = 10,
+        description: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Add and run a benchmark scenario."""
+        scenario = BenchmarkScenario(name, func, rounds, iterations, description)
+
+        self.console.print(f"🏃 Running scenario: [cyan]{name}[/cyan]")
+        if description:
+            self.console.print(f"   {description}")
+
+        runner = AsyncBenchmarkRunner(rounds=rounds, iterations=iterations)
+        result = await runner.run(func)
+
+        scenario_result = {
+            "name": name,
+            "result": result,
+            "description": description,
+            "scenario": scenario,
+        }
+
+        self.results.append(scenario_result)
+        return scenario_result
+
+    def display_all_results(self, title: str = "📊 Benchmark Results Summary"):
+        """Display all collected results in a summary table."""
+        if not self.results:
+            self.console.print("❌ No benchmark results to display")
+            return
+
+        display_comparison_table(self.results, title=title, console=self.console)
+
+    def display_pairwise_comparison(
+        self, name1: str, name2: str, title: Optional[str] = None
+    ):
+        """Display a detailed comparison between two specific scenarios."""
+        result1 = next((r for r in self.results if r["name"] == name1), None)
+        result2 = next((r for r in self.results if r["name"] == name2), None)
+
+        if not result1 or not result2:
+            self.console.print(f"❌ Could not find results for '{name1}' or '{name2}'")
+            return
+
+        comparison_title = title or f"⚡ {name1} vs {name2}"
+
+        display_comparison_table(
+            [result1, result2], title=comparison_title, console=self.console
+        )
+
+        comparison = compare_benchmarks(result1["result"], result2["result"])
+
+        self.console.print("\n📈 Detailed Analysis:")
+        analysis_text = Text()
+
+        speedup = comparison["speedup"]
+        if speedup > 1.2:
+            analysis_text.append(f"🚀 {name2} is significantly faster ", style="green")
+            analysis_text.append(f"({format_speedup(speedup)})", style="bold green")
+        elif speedup < 0.8:
+            analysis_text.append(f"🐌 {name1} is significantly faster ", style="red")
+            analysis_text.append(f"({format_speedup(1 / speedup)})", style="bold red")
+        else:
+            analysis_text.append(
+                "⚖️  Both scenarios have similar performance", style="yellow"
+            )
+
+        self.console.print(Panel(analysis_text, title="Performance Summary"))
+
+    def display_performance_grades(self, thresholds: Optional[dict[str, float]] = None):
+        """Display performance grades for all scenarios."""
+        if not self.results:
+            self.console.print("❌ No results to grade")
+            return
+
+        default_thresholds = {
+            "excellent": 0.001,
+            "good": 0.005,
+            "acceptable": 0.01,
+            "slow": 0.05,
+        }
+        thresholds = thresholds or default_thresholds
+
+        from rich.table import Table
+
+        table = Table(title="🏆 Performance Grades")
+        table.add_column("Scenario", style="cyan")
+        table.add_column("Mean Time", style="yellow", justify="right")
+        table.add_column("Grade", style="green", justify="center")
+        table.add_column("Status", justify="center")
+
+        for result in self.results:
+            grade = performance_grade(result["result"], thresholds)
+            mean_time = format_time(result["result"]["mean"])
+
+            status = {"A+": "🏆", "A": "🥇", "B": "🥈", "C": "🥉", "D": "🐌"}.get(
+                grade, "❓"
+            )
+
+            grade_style = {
+                "A+": "bold green",
+                "A": "green",
+                "B": "yellow",
+                "C": "orange3",
+                "D": "red",
+            }.get(grade, "white")
+
+            table.add_row(
+                result["name"],
+                mean_time,
+                f"[{grade_style}]{grade}[/{grade_style}]",
+                status,
+            )
+
+        self.console.print(table)
+
+    def get_fastest_scenario(self) -> Optional[dict[str, Any]]:
+        """Get the scenario with the fastest mean time."""
+        if not self.results:
+            return None
+
+        return min(self.results, key=lambda r: r["result"]["mean"])
+
+    def get_most_stable_scenario(self) -> Optional[dict[str, Any]]:
+        """Get the scenario with the lowest standard deviation."""
+        if not self.results:
+            return None
+
+        return min(self.results, key=lambda r: r["result"]["stddev"])
+
+    def export_results(self) -> list[dict[str, Any]]:
+        """Export all results for external analysis."""
+        return [
+            {
+                "name": r["name"],
+                "description": r["description"],
+                "mean": r["result"]["mean"],
+                "min": r["result"]["min"],
+                "max": r["result"]["max"],
+                "median": r["result"]["median"],
+                "stddev": r["result"]["stddev"],
+                "rounds": r["result"]["rounds"],
+                "iterations": r["result"]["iterations"],
+            }
+            for r in self.results
+        ]
+
+    def clear_results(self):
+        """Clear all stored results."""
+        self.results.clear()
+
+
+async def quick_compare(
+    scenarios: list[BenchmarkScenario],
+    title: str = "🚀 Quick Benchmark Comparison",
+    console: Optional[Console] = None,
+) -> BenchmarkComparator:
+    """Run a quick comparison of multiple scenarios."""
+    comparator = BenchmarkComparator(console)
+
+    comparator.console.print(f"\n[bold blue]{title}[/bold blue]")
+    comparator.console.print("=" * 50)
+
+    for scenario in scenarios:
+        await comparator.add_scenario(
+            scenario.name,
+            scenario.func,
+            scenario.rounds,
+            scenario.iterations,
+            scenario.description,
+        )
+
+    comparator.display_all_results(title)
+    comparator.display_performance_grades()
+
+    return comparator
+
+
+async def a_vs_b_comparison(
+    name_a: str,
+    func_a: Callable[[], Awaitable[Any]],
+    name_b: str,
+    func_b: Callable[[], Awaitable[Any]],
+    rounds: int = 10,
+    iterations: int = 50,
+    console: Optional[Console] = None,
+) -> BenchmarkComparator:
+    """Quick A vs B comparison utility."""
+    comparator = BenchmarkComparator(console)
+
+    comparator.console.print(f"\n[bold magenta]⚔️  {name_a} vs {name_b}[/bold magenta]")
+    comparator.console.print("=" * 50)
+
+    await comparator.add_scenario(name_a, func_a, rounds, iterations)
+    await comparator.add_scenario(name_b, func_b, rounds, iterations)
+
+    comparator.display_pairwise_comparison(name_a, name_b)
+
+    return comparator

pytest_async_benchmark/display.py

@@ -0,0 +1,169 @@
+"""Display utilities for async benchmarking."""
+
+from typing import Any, Optional
+
+from rich.console import Console
+from rich.table import Table
+
+
+def format_time(seconds: float) -> str:
+    """Format time duration in human-readable format."""
+    if seconds >= 1.0:
+        return f"{seconds:.3f}s"
+    elif seconds >= 0.001:
+        return f"{seconds * 1000:.3f}ms"
+    elif seconds >= 0.000001:
+        return f"{seconds * 1000000:.3f}μs"
+    else:
+        return f"{seconds * 1000000000:.3f}ns"
+
+
+def format_percentage(value: float) -> str:
+    """Format percentage with appropriate styling."""
+    if value > 0:
+        return f"+{value:.1f}%"
+    else:
+        return f"{value:.1f}%"
+
+
+def format_speedup(ratio: float) -> str:
+    """Format speedup ratio with descriptive text."""
+    if ratio > 1:
+        return f"{ratio:.2f}x faster"
+    elif ratio < 1:
+        return f"{1 / ratio:.2f}x slower"
+    else:
+        return "same speed"
+
+
+def display_comparison_table(
+    comparisons: list[dict[str, Any]],
+    title: str = "🚀 Async Benchmark Comparison",
+    console: Optional[Console] = None,
+) -> None:
+    """Display a comparison table for multiple benchmark results."""
+    if console is None:
+        console = Console()
+
+    table = Table(title=title)
+
+    table.add_column("Metric", style="cyan", no_wrap=True)
+
+    for comp in comparisons:
+        name = comp.get("name", "Benchmark")
+        table.add_column(name, style="green", justify="right")
+
+    if len(comparisons) == 2:
+        table.add_column("Difference", style="yellow", justify="right")
+
+    def get_metric_values(metric: str):
+        values = []
+        for comp in comparisons:
+            result = comp["result"]
+            if metric in result:
+                values.append(format_time(result[metric]))
+            else:
+                values.append("N/A")
+        return values
+
+    metrics = ["min", "max", "mean", "median", "stddev"]
+
+    for metric in metrics:
+        row = [metric.title()]
+        row.extend(get_metric_values(metric))
+
+        if len(comparisons) == 2:
+            result1 = comparisons[0]["result"]
+            result2 = comparisons[1]["result"]
+
+            if metric in result1 and metric in result2:
+                val1, val2 = result1[metric], result2[metric]
+                if val1 > 0:
+                    diff_percent = ((val2 - val1) / val1) * 100
+                    speedup = val1 / val2
+
+                    if metric == "mean":
+                        row.append(format_speedup(speedup))
+                    else:
+                        row.append(format_percentage(diff_percent))
+                else:
+                    row.append("N/A")
+            else:
+                row.append("N/A")
+
+        table.add_row(*row)
+
+    config_row = ["Rounds"]
+    config_row.extend(
+        [str(comp["result"].get("rounds", "N/A")) for comp in comparisons]
+    )
+    if len(comparisons) == 2:
+        config_row.append("")
+    table.add_row(*config_row)
+
+    iter_row = ["Iterations"]
+    iter_row.extend(
+        [str(comp["result"].get("iterations", "N/A")) for comp in comparisons]
+    )
+    if len(comparisons) == 2:
+        iter_row.append("")
+    table.add_row(*iter_row)
+
+    console.print("\n")
+    console.print(table)
+
+    if len(comparisons) == 2:
+        result1 = comparisons[0]["result"]
+        result2 = comparisons[1]["result"]
+        name1 = comparisons[0].get("name", "Version 1")
+        name2 = comparisons[1].get("name", "Version 2")
+
+        if "mean" in result1 and "mean" in result2:
+            speedup = result1["mean"] / result2["mean"]
+            if speedup > 1.1:
+                console.print(f"🏆 {name2} is {format_speedup(speedup)} than {name1}")
+            elif speedup < 0.9:
+                console.print(
+                    f"🏆 {name1} is {format_speedup(1 / speedup)} than {name2}"
+                )
+            else:
+                console.print(f"⚖️  {name1} and {name2} have similar performance")
+
+    console.print("✅ Comparison completed successfully!\n")
+
+
+def validate_async_function(func) -> bool:
+    """Validate that a function is async."""
+    import asyncio
+
+    return asyncio.iscoroutinefunction(func)
+
+
+def display_results_rich(benchmark_results, terminalreporter):
+    """Display benchmark results using rich."""
+    console = Console(file=terminalreporter._tw)
+
+    table = Table(title="Async Benchmark Results 📊")
+    table.add_column("Test Case 🧪", style="cyan", no_wrap=True)
+    table.add_column("Min (ms)", style="magenta", justify="right")
+    table.add_column("Max (ms)", style="magenta", justify="right")
+    table.add_column("Mean (ms)", style="green", justify="right")
+    table.add_column("StdDev (ms)", style="yellow", justify="right")
+    table.add_column("Median (ms)", style="blue", justify="right")
+    table.add_column("Rounds 🔁", justify="right")
+    table.add_column("Iter/Round 🔄", justify="right")
+
+    for result in benchmark_results:
+        status_emoji = "✅"
+        table.add_row(
+            f"{status_emoji} {result.name}",
+            format_time(result.min),
+            format_time(result.max),
+            format_time(result.mean),
+            format_time(result.stddev),
+            format_time(result.median),
+            str(result.rounds),
+            str(result.iterations),
+        )
+
+    console.print(table)

pytest_async_benchmark/plugin.py

@@ -0,0 +1,91 @@
+"""Core pytest plugin for async benchmarking."""
+
+import asyncio
+from typing import Any, Callable, Optional
+
+import pytest
+from rich.console import Console
+from rich.table import Table
+
+from .display import format_time
+from .runner import AsyncBenchmarkRunner
+
+
+class AsyncBenchmarkFixture:
+    """Fixture for benchmarking async functions."""
+
+    def __init__(self, request: pytest.FixtureRequest):
+        self.request = request
+        self.console = Console()
+        self.results: dict[str, Any] = {}
+
+    def __call__(
+        self,
+        func: Callable,
+        *args,
+        rounds: Optional[int] = None,
+        iterations: Optional[int] = None,
+        warmup_rounds: int = 1,
+        **kwargs,
+    ):
+        """Benchmark an async function."""
+        if not asyncio.iscoroutinefunction(func):
+            raise ValueError("Function must be async (coroutine function)")
+
+        runner = AsyncBenchmarkRunner(
+            rounds=rounds, iterations=iterations, warmup_rounds=warmup_rounds
+        )
+
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+
+        result = loop.run_until_complete(runner.run(func, *args, **kwargs))
+
+        test_name = self.request.node.name
+        self.results[test_name] = result
+
+        self._display_results(test_name, result)
+
+        return result
+
+    def _display_results(self, test_name: str, result: dict[str, Any]):
+        """Display benchmark results using rich."""
+        table = Table(title=f"🚀 Async Benchmark Results: {test_name}")
+
+        table.add_column("Metric", style="cyan")
+        table.add_column("Value", style="green")
+
+        table.add_row("Min", format_time(result["min"]))
+        table.add_row("Max", format_time(result["max"]))
+        table.add_row("Mean", format_time(result["mean"]))
+        table.add_row("Median", format_time(result["median"]))
+        table.add_row("Std Dev", format_time(result["stddev"]))
+        table.add_row("Rounds", str(result["rounds"]))
+        table.add_row("Iterations", str(result["iterations"]))
+
+        self.console.print("\n")
+        self.console.print(table)
+        self.console.print("✅ Benchmark completed successfully!\n")
+
+
+@pytest.fixture
+def async_benchmark(request: pytest.FixtureRequest) -> AsyncBenchmarkFixture:
+    """Pytest fixture for async benchmarking."""
+    return AsyncBenchmarkFixture(request)
+
+
+def pytest_configure(config):
+    """Configure pytest plugin."""
+    config.addinivalue_line(
+        "markers", "async_benchmark: mark test as an async benchmark"
+    )
+
+
+def pytest_collection_modifyitems(config, items):
+    """Modify collected test items."""
+    for item in items:
+        if "async_benchmark" in item.fixturenames:
+            item.add_marker(pytest.mark.async_benchmark)

pytest_async_benchmark/runner.py

@@ -0,0 +1,56 @@
+"""Core benchmarking logic for async functions."""
+
+import asyncio
+import statistics
+import time
+from typing import Any, Callable, Optional
+
+
+class AsyncBenchmarkRunner:
+    """Runner for async function benchmarks."""
+
+    def __init__(
+        self,
+        rounds: Optional[int] = None,
+        iterations: Optional[int] = None,
+        warmup_rounds: int = 1,
+    ):
+        self.rounds = rounds or 5
+        self.iterations = iterations or 1
+        self.warmup_rounds = warmup_rounds
+
+    async def run(self, func: Callable, *args, **kwargs) -> dict[str, Any]:
+        """Run benchmark for an async function."""
+        if not asyncio.iscoroutinefunction(func):
+            raise ValueError("Function must be async (coroutine function)")
+
+        for _ in range(self.warmup_rounds):
+            await func(*args, **kwargs)
+
+        times: list[float] = []
+
+        for _ in range(self.rounds):
+            round_times: list[float] = []
+
+            for _ in range(self.iterations):
+                start_time = time.perf_counter()
+                await func(*args, **kwargs)
+                end_time = time.perf_counter()
+                round_times.append(end_time - start_time)
+
+            times.append(statistics.mean(round_times))
+
+        return self._calculate_stats(times)
+
+    def _calculate_stats(self, times: list[float]) -> dict[str, Any]:
+        """Calculate statistics from timing data."""
+        return {
+            "min": min(times),
+            "max": max(times),
+            "mean": statistics.mean(times),
+            "median": statistics.median(times),
+            "stddev": statistics.stdev(times) if len(times) > 1 else 0.0,
+            "rounds": self.rounds,
+            "iterations": self.iterations,
+            "raw_times": times,
+        }

pytest_async_benchmark/stats.py

@@ -0,0 +1,36 @@
+"""Statistics calculation for async benchmarks."""
+
+import statistics
+from typing import Any
+
+
+class StatsContainer:
+    """Container for benchmark statistics calculation."""
+
+    def __init__(self):
+        self.measurements: list[float] = []
+
+    def add_measurement(self, duration: float):
+        """Add a timing measurement."""
+        self.measurements.append(duration)
+
+    def calculate_stats(self) -> dict[str, Any]:
+        """Calculate comprehensive statistics."""
+        if not self.measurements:
+            return {}
+
+        return {
+            "min": min(self.measurements),
+            "max": max(self.measurements),
+            "mean": statistics.mean(self.measurements),
+            "median": statistics.median(self.measurements),
+            "stddev": statistics.stdev(self.measurements)
+            if len(self.measurements) > 1
+            else 0.0,
+            "count": len(self.measurements),
+            "raw_times": self.measurements.copy(),
+        }
+
+    def reset(self):
+        """Reset all measurements."""
+        self.measurements.clear()

pytest_async_benchmark/utils.py

@@ -0,0 +1,30 @@
+"""Utility functions for async benchmarking."""
+
+import asyncio
+
+
+def format_time(seconds: float) -> str:
+    """Format time duration in human-readable format."""
+    if seconds >= 1.0:
+        return f"{seconds:.3f}s"
+    elif seconds >= 0.001:
+        return f"{seconds * 1000:.3f}ms"
+    elif seconds >= 0.000001:
+        return f"{seconds * 1000000:.3f}μs"
+    else:
+        return f"{seconds * 1000000000:.3f}ns"
+
+
+def validate_async_function(func) -> bool:
+    """Validate that a function is async."""
+    return asyncio.iscoroutinefunction(func)
+
+
+def get_event_loop():
+    """Get or create an event loop safely."""
+    try:
+        return asyncio.get_running_loop()
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        return loop

pytest_async_benchmark-0.1.1.dist-info/METADATA

@@ -0,0 +1,518 @@
+Metadata-Version: 2.4
+Name: pytest-async-benchmark
+Version: 0.1.1
+Summary: pytest-async-benchmark: Modern pytest benchmarking for async code. 🚀
+Author-email: Mihai Farcas <contact@mihai.ltd>
+License: MIT License
+        
+        Copyright (c) 2025 Mihai Farcas <contact@mihai.ltd>
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: pytest>=8.3.5
+Requires-Dist: rich>=14.0.0
+Description-Content-Type: text/markdown
+
+# pytest-async-benchmark 🚀
+
+Modern pytest benchmarking for async code with beautiful terminal output and advanced comparison tools.
+
+## ✨ Features
+
+- 🎯 **Async-First**: Designed specifically for benchmarking `async def` functions
+- 🔌 **Pytest Integration**: Seamless integration as a pytest plugin
+- 🎨 **Rich Output**: Beautiful terminal reporting!
+- 📊 **Comprehensive Stats**: Min, max, mean, median, std dev, percentiles, and more
+- ⚖️ **A vs B Comparisons**: Compare different implementations side-by-side
+- 📈 **Multi-Scenario Analysis**: Benchmark multiple scenarios with detailed comparison tables
+- 🎯 **Performance Grading**: Automatic performance scoring and analysis
+- ⚡ **Auto Calibration**: Intelligent round and iteration detection
+- 🔄 **Quick Compare**: One-line comparison utilities
+- 🏆 **Winner Detection**: Automatic identification of best-performing implementation
+- 🚀 **Easy to Use**: Simple fixture-based API
+
+## 📦 Installation
+
+```bash
+uv add pytest-async-benchmark
+# or
+pip install pytest-async-benchmark
+```
+
+## 🚀 Quick Start
+
+```python
+import asyncio
+import pytest
+
+async def slow_async_operation():
+    await asyncio.sleep(0.01)  # 10ms
+    return "result"
+
+def test_async_performance(async_benchmark):
+    result = async_benchmark(slow_async_operation, rounds=5)
+    
+    # Your assertions here
+    assert result['mean'] < 0.02  # Should complete in under 20ms
+```
+
+## 🎯 Core Usage Examples
+
+### Basic Benchmarking
+
+```python
+def test_my_async_function(async_benchmark):
+    async def my_function():
+        # Your async code here
+        await some_async_operation()
+        return result
+    
+    # Benchmark with default settings (5 rounds, 1 iteration each)
+    stats = async_benchmark(my_function)
+    
+    # Access comprehensive timing statistics
+    print(f"Mean execution time: {stats['mean']:.3f}s")
+    print(f"Standard deviation: {stats['stddev']:.3f}s")
+    print(f"95th percentile: {stats['p95']:.3f}s")
+```
+
+### Advanced Configuration
+
+```python
+def test_with_custom_settings(async_benchmark):
+    result = async_benchmark(
+        my_async_function,
+        rounds=10,        # Number of rounds to run
+        iterations=5,     # Iterations per round
+        warmup_rounds=2   # Warmup rounds before measurement
+    )
+```
+
+### With Function Arguments
+
+```python
+def test_with_args(async_benchmark):
+    async def process_data(data, multiplier=1):
+        # Process the data
+        await asyncio.sleep(0.01)
+        return len(data) * multiplier
+    
+    result = async_benchmark(
+        process_data,
+        "test_data",      # positional arg
+        multiplier=2,     # keyword arg
+        rounds=3
+    )
+```
+
+## ⚖️ A vs B Comparison Features
+
+### Quick Comparison
+
+```python
+from pytest_async_benchmark import quick_compare
+
+async def algorithm_v1():
+    await asyncio.sleep(0.002)  # 2ms
+    return "v1_result"
+
+async def algorithm_v2():
+    await asyncio.sleep(0.0015)  # 1.5ms - optimized
+    return "v2_result"
+
+# Quick one-liner comparison
+def test_algorithm_comparison():
+    winner, results = quick_compare(algorithm_v1, algorithm_v2, rounds=5)
+    assert winner == "algorithm_v2"  # v2 should be faster
+```
+
+### Detailed A vs B Analysis
+
+```python
+from pytest_async_benchmark import a_vs_b_comparison
+
+def test_detailed_comparison():
+    # Compare with beautiful terminal output
+    a_vs_b_comparison(
+        "Original Algorithm", algorithm_v1,
+        "Optimized Algorithm", algorithm_v2,
+        rounds=8, iterations=20
+    )
+```
+
+### Multi-Scenario Benchmarking
+
+```python
+from pytest_async_benchmark import BenchmarkComparator
+
+def test_multi_scenario():
+    comparator = BenchmarkComparator()
+    
+    # Add multiple scenarios
+    comparator.add_scenario(
+        "Database Query v1", db_query_v1,
+        rounds=5, iterations=10,
+        description="Original database implementation"
+    )
+    
+    comparator.add_scenario(
+        "Database Query v2", db_query_v2,
+        rounds=5, iterations=10,
+        description="Optimized with connection pooling"
+    )
+    
+    # Run comparison and get results
+    results = comparator.run_comparison()
+    
+    # Beautiful comparison table automatically displayed
+    # Access programmatic results
+    fastest = results.get_fastest_scenario()
+    assert fastest.name == "Database Query v2"
+```
+
+## 📊 Comprehensive Statistics
+
+Each benchmark returns detailed statistics:
+
+```python
+{
+    'min': 0.001234,      # Minimum execution time
+    'max': 0.005678,      # Maximum execution time  
+    'mean': 0.002456,     # Mean execution time
+    'median': 0.002123,   # Median execution time
+    'stddev': 0.000234,   # Standard deviation
+    'p50': 0.002123,      # 50th percentile (median)
+    'p90': 0.003456,      # 90th percentile
+    'p95': 0.004123,      # 95th percentile
+    'p99': 0.004789,      # 99th percentile
+    'rounds': 5,          # Number of rounds executed
+    'iterations': 1,      # Number of iterations per round
+    'raw_times': [...],   # List of raw timing measurements
+    'grade': 'A',         # Performance grade (A-F)
+    'grade_score': 87.5   # Numeric grade score (0-100)
+}
+```
+
+## 🎨 Beautiful Terminal Output
+
+### Basic Benchmark Output
+
+```
+🚀 Async Benchmark Results: test_my_function
+┏━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ Metric      ┃ Value      ┃
+┡━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ Min         │ 10.234ms   │
+│ Max         │ 15.678ms   │
+│ Mean        │ 12.456ms   │
+│ Median      │ 12.123ms   │
+│ Std Dev     │ 1.234ms    │
+│ 95th %ile   │ 14.567ms   │
+│ 99th %ile   │ 15.234ms   │
+│ Grade       │ A (87.5)   │
+│ Rounds      │ 5          │
+│ Iterations  │ 1          │
+└─────────────┴────────────┘
+✅ Benchmark completed successfully!
+```
+
+### A vs B Comparison Output
+
+```
+⚖️  A vs B Comparison Results
+┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━┓
+┃ Scenario                ┃ Algorithm A ┃ Algorithm B ┃ Winner    ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━┩
+│ Mean Time              │ 2.456ms     │ 1.789ms     │ B 🏆      │
+│ Median Time            │ 2.234ms     │ 1.678ms     │ B 🏆      │
+│ 95th Percentile        │ 3.456ms     │ 2.345ms     │ B 🏆      │
+│ Standard Deviation     │ 0.567ms     │ 0.234ms     │ B 🏆      │
+│ Performance Grade      │ B (76.2)    │ A (89.1)    │ B 🏆      │
+│ Improvement            │ -           │ 27.2%       │ -         │
+└─────────────────────────┴─────────────┴─────────────┴───────────┘
+🏆 Winner: Algorithm B (27.2% faster)
+```
+
+## 🏗️ Project Structure
+
+```
+pytest-async-benchmark/
+├── src/
+│   └── pytest_async_benchmark/
+│       ├── __init__.py          # Main exports and API
+│       ├── plugin.py            # Pytest plugin and fixtures
+│       ├── runner.py            # Core benchmarking engine
+│       ├── display.py           # Rich terminal output formatting
+│       ├── stats.py             # Statistical calculations
+│       ├── utils.py             # Utility functions
+│       ├── analytics.py         # Performance analysis tools
+│       └── comparison.py        # A vs B comparison functionality
+├── examples/
+│   ├── pytest_examples.py      # Comprehensive pytest usage examples
+│   ├── quart_api_comparison.py  # Real-world API endpoint comparison
+│   └── comparison_examples.py   # Advanced comparison features demo
+├── tests/
+│   ├── test_async_bench.py      # Core functionality tests
+│   ├── test_comparison.py       # Comparison feature tests
+│   ├── test_demo.py             # Demo test cases
+│   └── conftest.py              # Test configuration
+├── pyproject.toml               # Package configuration
+└── README.md                    # This file
+```
+
+## 📚 Example Files Guide
+
+### 🔧 [`examples/pytest_examples.py`](examples/pytest_examples.py)
+Comprehensive pytest usage examples including:
+- Basic benchmarking with the `async_benchmark` fixture
+- Advanced configuration options
+- Performance assertions and testing patterns
+- Using markers for benchmark organization
+
+### 🌐 [`examples/quart_api_comparison.py`](examples/quart_api_comparison.py)
+Real-world API endpoint comparison demo featuring:
+- Quart web framework setup
+- API v1 vs v2 endpoint benchmarking
+- Live server testing with actual HTTP requests
+- Performance regression detection
+
+### ⚖️ [`examples/comparison_examples.py`](examples/comparison_examples.py)
+Advanced comparison features showcase:
+- Multi-scenario benchmark comparisons
+- A vs B testing with detailed analysis
+- Performance grading and scoring
+- Statistical comparison utilities
+
+## 🌐 Real-World Examples
+
+### FastAPI Endpoint Benchmarking
+
+```python
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+import pytest
+
+app = FastAPI()
+
+@app.get("/api/data")
+async def get_data():
+    # Simulate database query
+    await asyncio.sleep(0.005)
+    return {"data": "example"}
+
+def test_fastapi_endpoint_performance(async_benchmark):
+    async def make_request():
+        with TestClient(app) as client:
+            response = client.get("/api/data")
+            return response.json()
+    
+    result = async_benchmark(make_request, rounds=10)
+    assert result['mean'] < 0.1  # Should respond within 100ms
+    assert result['grade'] in ['A', 'B']  # Should have good performance grade
+```
+
+### Quart API Endpoint Comparison
+
+See the complete example in [`examples/quart_api_comparison.py`](examples/quart_api_comparison.py):
+
+```python
+from pytest_async_benchmark import a_vs_b_comparison
+import asyncio
+import aiohttp
+
+async def test_api_v1():
+    async with aiohttp.ClientSession() as session:
+        async with session.get('http://localhost:5000/api/v1/data') as resp:
+            return await resp.json()
+
+async def test_api_v2():
+    async with aiohttp.ClientSession() as session:
+        async with session.get('http://localhost:5000/api/v2/data') as resp:
+            return await resp.json()
+
+# Compare API versions
+a_vs_b_comparison(
+    "API v1", test_api_v1,
+    "API v2 (Optimized)", test_api_v2,
+    rounds=10, iterations=5
+)
+```
+
+### Database Query Benchmarking
+
+```python
+async def test_database_query_performance(async_benchmark):
+    async def fetch_user_data(user_id):
+        async with database.connection() as conn:
+            return await conn.fetch_one(
+                "SELECT * FROM users WHERE id = ?", user_id
+            )
+    
+    result = async_benchmark(fetch_user_data, 123, rounds=5)
+    assert result['mean'] < 0.05  # Should complete within 50ms
+    assert result['p95'] < 0.1    # 95% of queries under 100ms
+```
+
+## 🎯 Using Markers
+
+```python
+@pytest.mark.async_benchmark
+def test_performance(async_benchmark):
+    # Your benchmark test
+    result = async_benchmark(my_async_function)
+    assert result is not None
+```
+
+## 📋 API Reference
+
+### `async_benchmark(func, *args, rounds=None, iterations=None, warmup_rounds=1, **kwargs)`
+
+**Parameters:**
+- `func`: The async function to benchmark
+- `*args`: Positional arguments to pass to the function
+- `rounds`: Number of measurement rounds (default: 5)
+- `iterations`: Number of iterations per round (default: 1)
+- `warmup_rounds`: Number of warmup rounds before measurement (default: 1)
+- `**kwargs`: Keyword arguments to pass to the function
+
+**Returns:**
+A dictionary with comprehensive statistics including min, max, mean, median, stddev, percentiles, performance grade, and raw measurements.
+
+### Comparison Functions
+
+- `quick_compare(func_a, func_b, **kwargs)`: Quick comparison returning winner and results
+- `a_vs_b_comparison(name_a, func_a, name_b, func_b, **kwargs)`: Detailed comparison with terminal output
+- `BenchmarkComparator`: Class for multi-scenario benchmarking and analysis
+
+## 📋 Requirements
+
+- Python ≥ 3.9
+- pytest ≥ 8.3.5
+
+Note: Rich (for beautiful terminal output) is automatically installed as a dependency.
+
+## 🚀 Development
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/pytest-async-benchmark.git
+cd pytest-async-benchmark
+
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest tests/ -v
+
+# Run examples
+uv run pytest examples/pytest_examples.py -v
+
+# Test real-world Quart API comparison
+uv run python examples/quart_api_comparison.py
+
+# See advanced comparison features
+uv run python examples/comparison_examples.py
+```
+
+### 🛠️ Code Quality and Formatting
+
+This project uses [Ruff](https://docs.astral.sh/ruff/) for both linting and formatting:
+
+```bash
+# Check code for linting issues
+uv run ruff check .
+
+# Fix auto-fixable linting issues
+uv run ruff check . --fix
+
+# Check code formatting
+uv run ruff format --check .
+
+# Format code automatically
+uv run ruff format .
+
+# Run both linting and formatting in one go
+uv run ruff check . --fix && uv run ruff format .
+
+# Run all quality checks at once (linting, formatting, and tests)
+uv run python scripts/quality-check.py
+```
+
+### 📋 Release Readiness Check
+
+Before creating a release, verify everything is ready:
+
+```bash
+# Run comprehensive release check
+uv run python scripts/release-check.py
+
+# This checks:
+# ✅ Git repository status
+# ✅ Version consistency 
+# ✅ Code formatting and linting
+# ✅ Test suite passes
+# ✅ Package builds successfully
+# ✅ All required files exist
+```
+
+### 🚀 Quick Quality Check
+
+Run all quality checks at once:
+
+```bash
+# Run linting, formatting, tests, and release checks
+python scripts/quality-check.py
+
+# This will:
+# 🔧 Fix linting issues automatically
+# 🎨 Format code with Ruff
+# 🧪 Run the full test suite
+# 📋 Check release readiness
+```
+
+## 🚀 Automated Releases
+
+This project uses GitHub Actions for automated testing and publishing to PyPI:
+
+- **Continuous Integration**: Tests run on every push for Python 3.9-3.13
+- **Test Publishing**: Automatic uploads to TestPyPI for testing releases
+- **Production Releases**: Secure publishing to PyPI using trusted publishing
+- **Release Validation**: Comprehensive checks ensure package quality
+
+### Creating a Release
+
+1. Update version in `pyproject.toml` and `src/pytest_async_benchmark/__init__.py`
+2. Run `uv run python scripts/release-check.py` to verify readiness
+3. Create a git tag: `git tag v1.0.0 && git push origin v1.0.0`
+4. Create a GitHub release to trigger automated PyPI publishing
+
+See [RELEASE_GUIDE.md](RELEASE_GUIDE.md) for detailed release instructions.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+*Built with ❤️ for the async Python community*

pytest_async_benchmark-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+pytest_async_benchmark/__init__.py,sha256=i_vjO6kOxhDSBXhBuVo9mgvItucMaTAne_jaVorarNg,825
+pytest_async_benchmark/analytics.py,sha256=7lR-GF0rqS8X1pVtFucmyO-GXvzYXoX0I9bOh6uzUhQ,1710
+pytest_async_benchmark/comparison.py,sha256=-TXaUSpFNKzroPRRILw_7aAOte5uARSiaDeifShUgUQ,8025
+pytest_async_benchmark/display.py,sha256=WRoiSZK03XNAtfeMzBniJeHra2YzPB4_DbWsMp30BVI,5357
+pytest_async_benchmark/plugin.py,sha256=P8TcblejlVejdDIowy4Zeame-C4pa23IEBS_rFqqIgs,2857
+pytest_async_benchmark/runner.py,sha256=HFRZ8kc9fDNGy9IorZawAKN9KnQjQv_YqdvV-qbAt_Y,1775
+pytest_async_benchmark/stats.py,sha256=I0hpi-TqcstOdXxLW03p1ZA7TX1qz9JnJNu_vSxWqWA,1074
+pytest_async_benchmark/utils.py,sha256=-oiEiuOXyiU614wkBgS67em1KVQCnaJW4z_x3lNnSKs,797
+pytest_async_benchmark-0.1.1.dist-info/METADATA,sha256=XgpF-xFS1Ndw5_juXkzRAE5s6K3YEpzLFf26q0yTV8E,16976
+pytest_async_benchmark-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pytest_async_benchmark-0.1.1.dist-info/entry_points.txt,sha256=5PoCegPmQcqj3Y5iGuiW9pGvYxnxirJ-P93NekT7aYg,55
+pytest_async_benchmark-0.1.1.dist-info/licenses/LICENSE,sha256=ZzNL_t8ZeKS3i3duN9drmwyTr5DiTTCAtpgTB8JXH1k,1088
+pytest_async_benchmark-0.1.1.dist-info/RECORD,,

pytest_async_benchmark-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_async_benchmark-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+async_bench = pytest_async_benchmark.plugin

pytest_async_benchmark-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mihai Farcas <contact@mihai.ltd>
+
+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.