wsg 0.1.0__tar.gz

wsg-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.3
+Name: wsg
+Version: 0.1.0
+Summary: API load testing tool that produces latency/throughput graphs
+Author: Owen Zeng
+Author-email: Owen Zeng <owenzeng315@gmail.com>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: matplotlib>=3.11.1
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# wsg
+
+API load testing tool designed for performance visualization. Sends concurrent
+requests to an endpoint and produces a latency/throughput graph from the
+results.
+
+## Install
+
+```bash
+uv tool install wsg
+```
+
+Or, without a permanent install:
+
+```bash
+uvx wsg <url> [options]
+```
+
+`pipx install wsg` / `pip install wsg` also work if you don't use `uv`.
+
+## Usage
+
+```bash
+wsg <url> [options]
+```
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-X`, `--method` | HTTP method to use | `GET` |
+| `-n`, `--total_requests` | Total number of requests to send | `100` |
+| `-c`, `--concurrency` | Number of concurrent requests | `10` |
+| `-H`, `--headers` | HTTP headers, e.g. `-H "Authorization: Bearer xyz"` | none |
+| `-d`, `--body` | Request body for POST/PUT requests | none |
+| `--timeout` | Timeout per request in seconds | `10.0` |
+| `-o`, `--output_path` | Path to save the output graph | `results.png` |
+
+### Example
+
+```bash
+wsg https://api.example.com/ping -n 500 -c 20 -o load_test.png
+```
+
+This sends 500 requests at a concurrency of 20 and saves a latency
+distribution + throughput-over-time chart to `load_test.png` in the current
+directory.

wsg-0.1.0/README.md

@@ -0,0 +1,47 @@
+# wsg
+
+API load testing tool designed for performance visualization. Sends concurrent
+requests to an endpoint and produces a latency/throughput graph from the
+results.
+
+## Install
+
+```bash
+uv tool install wsg
+```
+
+Or, without a permanent install:
+
+```bash
+uvx wsg <url> [options]
+```
+
+`pipx install wsg` / `pip install wsg` also work if you don't use `uv`.
+
+## Usage
+
+```bash
+wsg <url> [options]
+```
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-X`, `--method` | HTTP method to use | `GET` |
+| `-n`, `--total_requests` | Total number of requests to send | `100` |
+| `-c`, `--concurrency` | Number of concurrent requests | `10` |
+| `-H`, `--headers` | HTTP headers, e.g. `-H "Authorization: Bearer xyz"` | none |
+| `-d`, `--body` | Request body for POST/PUT requests | none |
+| `--timeout` | Timeout per request in seconds | `10.0` |
+| `-o`, `--output_path` | Path to save the output graph | `results.png` |
+
+### Example
+
+```bash
+wsg https://api.example.com/ping -n 500 -c 20 -o load_test.png
+```
+
+This sends 500 requests at a concurrency of 20 and saves a latency
+distribution + throughput-over-time chart to `load_test.png` in the current
+directory.

wsg-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "wsg"
+version = "0.1.0"
+description = "API load testing tool that produces latency/throughput graphs"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "httpx>=0.28.1",
+    "matplotlib>=3.11.1",
+]
+
+[[project.authors]]
+name = "Owen Zeng"
+email = "owenzeng315@gmail.com"
+
+[project.scripts]
+wsg = "wsg:main"
+
+[build-system]
+requires = ["uv_build>=0.12.10,<0.13.0"]
+build-backend = "uv_build"

wsg-0.1.0/pyproject.toml.orig

@@ -0,0 +1,20 @@
+[project]
+name = "wsg"
+version = "0.1.0"
+description = "API load testing tool that produces latency/throughput graphs"
+readme = "README.md"
+authors = [
+    { name = "Owen Zeng", email = "owenzeng315@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "httpx>=0.28.1",
+    "matplotlib>=3.11.1",
+]
+
+[project.scripts]
+wsg = "wsg:main"
+
+[build-system]
+requires = ["uv_build>=0.12.10,<0.13.0"]
+build-backend = "uv_build"

wsg-0.1.0/src/wsg/__init__.py

@@ -0,0 +1,15 @@
+import asyncio
+
+from wsg.cli import parse_args
+from wsg.runner import run
+from wsg.stats import summarize
+from wsg.reports import print_report
+from wsg.graph import render
+
+def main():
+    config = parse_args()
+    results, _ = asyncio.run(run(config))
+    summary = summarize(results)
+    print_report(summary, config.url, config.method)
+    render(results, config.output_path)
+    print(f'Graph saved to {config.output_path}')

wsg-0.1.0/src/wsg/cli.py

@@ -0,0 +1,40 @@
+import argparse
+
+from wsg.config import Config
+
+def parse_args():
+    '''
+    Parse the command-line arguments for the API load-testing tool.
+    '''
+    parser = argparse.ArgumentParser(description="A simple API load-testing tool")
+    parser.add_argument("url", type=str, help="The URL of the API endpoint to test")
+    parser.add_argument("-X", "--method", type=str, default="GET", help="HTTP method to use (default: GET)")
+    parser.add_argument("-n", "--total_requests", type=int, default=100, help="Total number of requests to send (default: 100)")
+    parser.add_argument("-c", "--concurrency", type=int, default=10, help="Number of concurrent requests to send (default: 10)")
+    parser.add_argument("-H", "--headers", type=str, nargs='*', help="HTTP headers to include in the requests (format: 'Header-Name: Header-Value')")
+    parser.add_argument("-d", "--body", type=str, help="Request body for POST/PUT requests")
+    parser.add_argument("--timeout", type=float, default=10.0, help="Timeout for each request in seconds (default: 10.0)")
+    parser.add_argument("-o", "--output_path", type=str, default="results.png", help="Path to save the output results (default: results.png)")
+
+    args = parser.parse_args()
+
+    if args.total_requests <= 0:
+        parser.error("--requests must be a positive integer")
+    if args.concurrency <= 0:
+        parser.error("--concurrency must be a positive integer")
+    if args.timeout <= 0:
+        parser.error("--timeout must be a positive number")
+
+    return Config(
+        url=args.url,
+        method=args.method,
+        total_requests=args.total_requests,
+        concurrency=args.concurrency,
+        headers={header.split(":", 1)[0].strip(): header.split(":", 1)[1].strip() for header in args.headers} if args.headers else {},
+        body=args.body,
+        timeout=args.timeout,
+        output_path=args.output_path
+    )
+
+
+

wsg-0.1.0/src/wsg/config.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass, field
+
+@dataclass
+class Config:
+    '''
+    Configuration class for the WSG application.
+    '''
+    url: str
+    method: str = "GET"
+    total_requests: int = 100
+    concurrency: int = 10
+    headers: dict[str, str] = field(default_factory=dict)
+    body: str | None = None
+    timeout: float = 10.0
+    output_path: str = "results.png"

wsg-0.1.0/src/wsg/graph.py

@@ -0,0 +1,44 @@
+import statistics
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+from wsg.worker import Result
+from wsg.stats import bucket_throughputs
+
+
+def render(results: list[Result], output_path: str) -> None:
+    '''
+    Render a latency histogram and a throughput-over-time chart from the
+    results, side by side in one figure, and save it to output_path.
+    '''
+    latencies_ms = [r.elapsed * 1000 for r in results if r.status_code is not None]
+    throughputs = bucket_throughputs(results)
+
+    fig, (hist_ax, throughput_ax) = plt.subplots(1, 2, figsize=(12, 5))
+
+    bin_count = min(50, max(10, len(latencies_ms) // 2)) if latencies_ms else 10
+    hist_ax.hist(latencies_ms, bins=bin_count, color="#1f77b4", edgecolor="white")
+    if latencies_ms:
+        mean_ms = statistics.mean(latencies_ms)
+        hist_ax.axvline(mean_ms, color="black", linestyle="--", linewidth=1, label=f"Mean: {mean_ms:.0f} ms")
+        hist_ax.legend()
+    hist_ax.set_xlabel("Latency (ms)")
+    hist_ax.set_ylabel("Number of requests")
+    hist_ax.set_title("Latency Distribution")
+    hist_ax.grid(axis="y", alpha=0.3)
+
+    bucket_centers = [i + 0.5 for i in range(len(throughputs))]
+    bars = throughput_ax.bar(bucket_centers, throughputs, width=0.6, color="#ff7f0e", edgecolor="black", linewidth=0.5)
+    throughput_ax.bar_label(bars, fmt="%.0f")
+    throughput_ax.set_xticks(range(len(throughputs) + 1))
+    throughput_ax.set_ylim(0, max(throughputs, default=0) * 1.15)
+    throughput_ax.set_xlabel("Time since start (s)")
+    throughput_ax.set_ylabel("Requests/sec")
+    throughput_ax.set_title("Throughput Over Time")
+    throughput_ax.grid(axis="y", alpha=0.3)
+
+    fig.tight_layout()
+    fig.savefig(output_path, dpi=120)
+    plt.close(fig)

wsg-0.1.0/src/wsg/reports.py

@@ -0,0 +1,27 @@
+from wsg.stats import Summary
+
+def print_report(summary: Summary, url: str, method: str) -> None:
+    '''
+    Print the summary report of the WSG application.
+    '''
+    print(f'Target: {method} {url}')
+    print("=== Load Test Results ===")
+    print(f'Total requests: {summary.count}')
+    print(f'Successful requests: {summary.success_count}')
+    print(f'Failed requests: {summary.error_count}')
+    print(f'Error rate: {summary.error_rate:.2%}')
+    print("=== Load Test Latency Metrics ===")
+    print(f'Min latency: {summary.latency_min * 1000:.2f} ms')
+    print(f'Max latency: {summary.latency_max * 1000:.2f} ms')
+    print(f'Mean latency: {summary.latency_mean * 1000:.2f} ms')
+    print(f'50th percentile latency: {summary.p50 * 1000:.2f} ms')
+    print(f'90th percentile latency: {summary.p90 * 1000:.2f} ms')
+    print(f'95th percentile latency: {summary.p95 * 1000:.2f} ms')
+    print(f'99th percentile latency: {summary.p99 * 1000:.2f} ms')
+    print("=== Load Test Throughput ===")
+    print(f'Throughput Min: {summary.throughput_min:.2f} requests/sec')
+    print(f'Throughput Max: {summary.throughput_max:.2f} requests/sec')
+    print(f'Throughput Mean: {summary.throughput_mean:.2f} requests/sec')
+    print("=== Status Codes ===")
+    for code, count in summary.status_codes.items():
+        print(f'  {code}: {count}')

wsg-0.1.0/src/wsg/runner.py

@@ -0,0 +1,26 @@
+import asyncio
+import httpx
+import sys
+import time
+
+from wsg.config import Config
+from wsg.worker import Result, send_request
+
+async def run(config: Config) -> tuple[list[Result], float]:
+    '''
+    Run the load test using the provided configuration.
+    '''
+    async with httpx.AsyncClient() as client:
+        semaphore = asyncio.Semaphore(config.concurrency)
+        run_start = time.perf_counter()
+        tasks = [send_request(client, semaphore, config) for _ in range(config.total_requests)]
+
+        results = []
+        for coro in asyncio.as_completed(tasks):
+            results.append(await coro)
+            print(f"\rProgress: {len(results)}/{len(tasks)} ({len(results) / len(tasks):.0%})", end="", file=sys.stderr, flush=True)
+        print(file=sys.stderr)
+
+        for result in results:
+            result.start_time -= run_start
+        return (results, total_time := time.perf_counter() - run_start)

wsg-0.1.0/src/wsg/stats.py

@@ -0,0 +1,105 @@
+from dataclasses import dataclass
+from wsg.worker import Result
+from collections import Counter
+
+import statistics
+
+
+StatusCode = int
+
+@dataclass
+class Summary:
+    '''
+    Summary class to hold the results of the WSG application.
+    '''
+    count: int
+    success_count: int
+    error_count: int
+    error_rate: float
+    latency_min: float
+    latency_max: float
+    latency_mean: float
+    p50: float
+    p90: float
+    p95: float
+    p99: float
+    throughput_min: float
+    throughput_max: float
+    throughput_mean: float
+    status_codes: dict[StatusCode, int]
+
+def bucket_throughputs(results: list[Result], bucket_size: float = 1.0) -> list[float]:
+    '''
+    Split successful results into fixed-size time buckets by completion
+    time (start_time + elapsed) and return the throughput (requests/sec)
+    measured in each bucket. The last bucket is dropped whenever there is
+    more than one, since it may cover only a partial slice of real time
+    and would understate its rate.
+    '''
+    completions = [r.start_time + r.elapsed for r in results if r.status_code is not None]
+    if not completions:
+        return []
+
+    bucket_counts = Counter(int(t // bucket_size) for t in completions)
+    buckets = [bucket_counts[i] / bucket_size for i in sorted(bucket_counts)]
+
+    if len(buckets) > 1:
+        buckets = buckets[:-1]
+
+    return buckets
+
+def summarize(results: list[Result]) -> 'Summary':
+    '''
+    Summarize the results of the WSG application.
+    '''
+    success = []
+    failure = []
+
+    for i in results:
+        if i.status_code != None:
+            success.append(i)
+        else:
+            failure.append(i)
+
+    count = len(results)
+    success_count = len(success)
+    error_count = len(failure)
+    error_rate = error_count / count if count > 0 else 0.0
+
+    latency_list = []
+    for i in success:
+        latency_list.append(i.elapsed)
+
+    latency_min = min(latency_list) if latency_list else 0.0
+    latency_max = max(latency_list) if latency_list else 0.0
+    latency_mean = statistics.mean(latency_list) if latency_list else 0.0
+
+    p50 = statistics.median(latency_list) if latency_list else 0.0
+    p90 = statistics.quantiles(latency_list, n=10)[8] if latency_list else 0.0
+    p95 = statistics.quantiles(latency_list, n=20)[18] if latency_list else 0.0
+    p99 = statistics.quantiles(latency_list, n=100)[98] if latency_list else 0.0
+
+    throughput_buckets = bucket_throughputs(results)
+    throughput_min = min(throughput_buckets) if throughput_buckets else 0.0
+    throughput_max = max(throughput_buckets) if throughput_buckets else 0.0
+    throughput_mean = statistics.mean(throughput_buckets) if throughput_buckets else 0.0
+
+    status_codes = Counter(i.status_code for i in results if i.status_code is not None)
+
+    return Summary(
+        count=count,
+        success_count=success_count,
+        error_count=error_count,
+        error_rate=error_rate,
+        latency_min=latency_min,
+        latency_max=latency_max,
+        latency_mean=latency_mean,
+        p50=p50,
+        p90=p90,
+        p95=p95,
+        p99=p99,
+        throughput_min=throughput_min,
+        throughput_max=throughput_max,
+        throughput_mean=throughput_mean,
+        status_codes=dict(status_codes)
+    )

wsg-0.1.0/src/wsg/worker.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+from wsg.config import Config
+import time
+import httpx
+import asyncio
+
+@dataclass
+class Result:
+    '''
+    Result class to store the outcome of each request.
+    '''
+    status_code: int | None
+    elapsed: float
+    error: str | None
+    start_time: float
+
+async def send_request(client: httpx.AsyncClient, semaphore: asyncio.Semaphore, config: Config) -> Result:
+    '''
+    Send a single HTTP request using the provided client and configuration.
+    '''
+    start = time.perf_counter()
+    try:
+        async with semaphore:
+            response = await client.request(
+                config.method, config.url,
+                headers=config.headers,
+                content=config.body,
+                timeout=config.timeout,
+            )
+        elapsed = time.perf_counter() - start
+        return Result(status_code=response.status_code, elapsed=elapsed, error=None, start_time=start)
+    except Exception as e:
+        elapsed = time.perf_counter() - start
+        return Result(status_code=None, elapsed=elapsed, error=str(e), start_time=start)