feat(python/timing): export benchmark to python

Author: hakula139

binding/timing_binding.cpp

@@ -4,12 +4,13 @@
  */
 
 #include <chrono>
-#include <cstdint>
-#include <format>
+#include <cstddef>
 #include <functional>
+#include <string>
 
 #include <pybind11/pybind11.h>
 
+#include "timing/benchmark.hpp"
 #include "timing/timer.hpp"
 
 namespace py = pybind11;
@@ -22,10 +23,13 @@ auto GetElapsedWrapper(const Timer &timer) {
   return timer.GetElapsed<DurationType>();
 }
 
-auto TimeFunctionWrapper(const std::function<void()> &func) -> std::int64_t {
-  return TimeFunction(func);
+auto BenchmarkWrapper(const std::string &name, const std::function<void()> &func,
+                      std::size_t iterations = 1000) {
+  return BenchmarkRunner::Benchmark(name, func, iterations);
 }
 
+auto TimeFunctionWrapper(const std::function<void()> &func) { return TimeFunction(func); }
+
 }  // namespace
 
 void BindTiming(py::module &m) {
@@ -41,6 +45,20 @@ void BindTiming(py::module &m) {
       .def("get_elapsed_s", &GetElapsedWrapper<std::chrono::seconds>)
       .def("get_elapsed_str", &Timer::GetElapsedString);
 
+  // Bind BenchmarkResult struct
+  py::class_<BenchmarkRunner::BenchmarkResult>(m, "BenchmarkResult")
+      .def_readwrite("name", &BenchmarkRunner::BenchmarkResult::name)
+      .def_readwrite("iterations", &BenchmarkRunner::BenchmarkResult::iterations)
+      .def_readwrite("total_ns", &BenchmarkRunner::BenchmarkResult::total_ns)
+      .def_readwrite("avg_ns", &BenchmarkRunner::BenchmarkResult::avg_ns)
+      .def_readwrite("min_ns", &BenchmarkRunner::BenchmarkResult::min_ns)
+      .def_readwrite("max_ns", &BenchmarkRunner::BenchmarkResult::max_ns);
+
+  // Bind BenchmarkRunner class
+  py::class_<BenchmarkRunner>(m, "BenchmarkRunner")
+      .def_static("benchmark", &BenchmarkWrapper)
+      .def_static("print_result", &BenchmarkRunner::PrintResult);
+
   // Bind utility functions
   m.def("to_human_readable", &ToHumanReadable);
   m.def("time_function", &TimeFunctionWrapper);

python/src/demo/algorithms.py

@@ -154,6 +154,7 @@ def pipeline(*functions: Callable[[Any], Any]) -> Callable[[Any], Any]:
     ...     lambda data: [x for x in data if x > 5],
     ...     sum,
     ... )
+    ...
     >>> process([1, 2, 3, 4, 5])
     24
     """

python/src/demo/containers.py

@@ -143,6 +143,7 @@ def __iter__(self) -> Iterator[T]:
         >>> container = Container(int, [1, 2, 3])
         >>> for item in container:
         ...     print(item)
+        ...
         1
         2
         3

python/src/demo/timing.py

@@ -1,9 +1,9 @@
 """Python wrapper for the timing module."""
 
-import statistics
 from contextlib import contextmanager
+from dataclasses import dataclass
 from types import TracebackType
-from typing import Any, Callable, ContextManager, Generator
+from typing import Any, Callable, Generator
 
 import cpp_features.timing as _timing
 
@@ -152,9 +152,11 @@ def measure_time(name: str | None = None) -> Generator[Timer, None, None]:
 
     Examples
     --------
+    >>> from time import sleep
     >>> with measure_time('Scoped operation') as timer:
     ...     sleep(3)
     ...     print('Doing some work inside scoped timer...')
+    ...
     Scoped operation: 3s
     """
     timer = Timer()
@@ -206,9 +208,93 @@ def time_function(func: Callable[[], Any]) -> int:
     return _timing.time_function(func)
 
 
+@dataclass
+class BenchmarkResult:
+    """Structure containing benchmark results and statistics."""
+
+    name: str
+    iterations: int
+    total_ns: int
+    avg_ns: int
+    min_ns: int
+    max_ns: int
+
+    @staticmethod
+    def from_cpp(result: _timing.BenchmarkResult) -> 'BenchmarkResult':
+        """Create a BenchmarkResult from the C++ BenchmarkResult.
+
+        Parameters
+        ----------
+        result : _timing.BenchmarkResult
+            The C++ BenchmarkResult to convert
+
+        Returns
+        -------
+        BenchmarkResult
+            The converted BenchmarkResult
+        """
+        return BenchmarkResult(
+            name=result.name,
+            iterations=result.iterations,
+            total_ns=result.total_ns,
+            avg_ns=result.avg_ns,
+            min_ns=result.min_ns,
+            max_ns=result.max_ns,
+        )
+
+    def print(self) -> None:
+        """Print formatted benchmark results.
+
+        Prints comprehensive benchmark statistics in a human-readable format with appropriate units
+        and formatting.
+        """
+        _timing.BenchmarkRunner.print_result(self)
+
+
+def benchmark(
+    name: str, func: Callable[[], Any], iterations: int = 1000
+) -> BenchmarkResult:
+    """Utility function to benchmark a function with a given number of iterations.
+
+    Parameters
+    ----------
+    name : str
+        Descriptive name for the benchmark
+    func : Callable[[], Any]
+        Function to benchmark
+    iterations : int, default=1000
+        Number of times to execute the function
+
+    Returns
+    -------
+    BenchmarkResult
+        Structure containing timing statistics
+
+    Examples
+    --------
+    >>> from random import randint
+    >>> def sort_data() -> None:
+    ...     data = [randint(1, 100) for _ in range(1000)]
+    ...     data.sort()
+    ...
+    >>> result = benchmark('Sorting algorithm', sort_data, 1000)
+    >>> result.print()
+    Benchmark: Sorting algorithm
+    - Iterations: 1000
+    - Total time: 12.3ms
+    - Average: 12.3μs
+    - Min: 10.1μs
+    - Max: 15.7μs
+    """
+    result = _timing.BenchmarkRunner.benchmark(name, func, iterations)
+    return BenchmarkResult.from_cpp(result)
+
+
 __all__ = [
     'Timer',
     'measure_time',
     'to_human_readable',
     'time_function',
+    'BenchmarkResult',
+    'benchmark',
 ]