benchpulse 1.0.0

Hardware resource benchmarking framework for Python

BenchPulse

BenchPulse is a dependency-free hardware benchmarking library for Python. Add @benchpulse to any function, method, or async callable to capture execution time, CPU utilization, memory usage, and thread activity while your code runs.

The performance-sensitive monitoring engine is implemented in C17 and exposed to Python through a thin native extension. Python is used only for the public API, validation, formatting, and export helpers.

Quick start

from benchpulse import benchpulse

@benchpulse
def train():
    return sum(range(100_000))

report = train()
print(report.return_value)
print(report.cpu_statistics.process_utilization_percent.mean)

@benchpulse is the primary decorator. @benchmark is provided as an alias.

Features

• Native C runtime with OS-level collectors
• CPU, memory, and thread metrics out of the box
• Optional GPU collector hook (vendor libraries are optional)
• Decorator, context manager, and class decorator APIs
• Async function support
• JSON, CSV, Markdown, and HTML export
• Zero runtime Python dependencies
• Windows, Linux, and macOS support

Installation

pip install benchpulse

Prebuilt wheels are published for Windows (x64), Linux (x86_64 and aarch64), and macOS (Intel and Apple Silicon) on CPython 3.11+. No compiler or extra setup is required.

Development install

pip install -e ".[dev]"

Building from source requires:

• Python 3.11+
• A C17 compiler (MSVC 2019 16.8+ on Windows, GCC 8+/Clang 7+ on Linux and macOS)

CMake is optional and only used for standalone native-library builds.

API overview

from benchpulse import benchpulse, Benchmark, BenchmarkConfiguration, OutputMode

@benchpulse(sampling_interval_ms=50, output_mode=OutputMode.SILENT)
def work():
    ...

with Benchmark() as session:
    result = compute()
report = session.report

Decorated functions return a BenchmarkReport. The original return value is available as report.return_value.

Project layout

benchpulse/          Python package
native/              C runtime and collectors
include/benchpulse/  Public C headers
tests/               Python tests
CMakeLists.txt       Native build definition

License

See LICENSE.