Decorator

Benchmark decorator utilities for easier function benchmarking.

This module provides decorators for benchmarking functions with configurable parameters and settings. It allows for easy setup and running of benchmarks.

BenchDecorator

Decorator for benchmarking functions.

Source code in easybench/decorator.py

class BenchDecorator:
    """Decorator for benchmarking functions."""

    def __init__(self) -> None:
        """Initialize BenchDecorator with storage for deferred functions."""
        self._deferred_functions: dict[str, list[BenchmarkableFunction]] = {}

    def _initialize_bench_attributes(self, func: Callable) -> BenchmarkableFunction:
        """
        Initialize benchmark attributes on a function if they don't exist.

        Args:
            func: The function to initialize benchmark attributes for

        Returns:
            The function cast as BenchmarkableFunction with all necessary attributes

        """
        func = cast("BenchmarkableFunction", func)
        if not hasattr(func, "bench"):
            func.bench = FunctionBench(func)
            func.fixtures = {}
            # Initialize last_results together with bench
            func.last_results = {}
            # Initialize defer attribute
            func.defer = False
            # Initialize params_list attribute
            func.params_list = None
            # Add the function to its global namespace to enable recursion
            self._register_in_globals(func)

        return func

    def _register_in_globals(self, func: BenchmarkableFunction) -> None:
        """
        Register the function in its global namespace to enable recursion.

        Args:
            func: The function to register in the global namespace

        """
        if hasattr(func, "__globals__") and hasattr(func, "__name__"):
            # Register the function in the module's global namespace
            # with its original name
            func.__globals__[func.__name__] = func

            # Add self-reference to the function's closure if needed
            code = getattr(func, "__code__", None)
            closure = getattr(func, "__closure__", None)
            freevars = getattr(code, "co_freevars", ()) if code else ()
            if closure is not None and func.__name__ in freevars:
                for i, var_name in enumerate(freevars):
                    if var_name == func.__name__ and isinstance(closure[i], CellType):
                        object.__setattr__(closure[i], "cell_contents", func)
                        break

    def __call__(
        self,
        *args: object,
        **kwargs: object,
    ) -> Callable:
        """
        EasyBench benchmark decorator.

        Example:
            ```python
            @bench(
                item=123,
                big_list=lambda: list(range(1_000_000)),
            )
            def add_item(item, big_list):
                big_list.append(item)
            ```

            # Using a list of BenchParams for comparison
            ```python
            params1 = BenchParams(
                name="Small", params={"lst": lambda: list(range(1000))},
            )
            params2 = BenchParams(
                name="Large", params={"lst": lambda: list(range(10000))},
            )

            @bench([params1, params2])
            def pop_first(lst):
                return lst.pop(0)
            ```

        Returns:
            A decorated function with benchmark capabilities

        """
        # Handle list of BenchParams as first argument
        if (
            len(args) == 1
            and isinstance(args[0], list)
            and not kwargs
            and all(isinstance(param, BenchParams) for param in args[0])
        ):
            return self._decorate_with_bench_param_list(args[0])

        # Handle BenchParams instance as first argument
        if len(args) == 1 and isinstance(args[0], BenchParams) and not kwargs:
            return self._decorate_with_bench_param(args[0])

        # Handle direct function decoration: @bench
        if len(args) == 1 and callable(args[0]) and not kwargs:
            return self._decorate(args[0])

        # Handle parameterized decoration: @bench(param=value)
        def decorator(func: Callable) -> Callable:
            return self._decorate(func, **kwargs)

        return decorator

    def _process_single_param_set(
        self,
        func: Callable,
        params: BenchParams,
        index: int,
        func_name: str,
    ) -> tuple[str, ResultType | None, BenchConfig | None]:
        """
        Process a single parameter set for benchmarking.

        Args:
            func: The original function to benchmark
            params: The parameter set to use
            index: The index of this parameter in the list
            func_name: Name of the function

        Returns:
            A tuple of (param_name, results_dict, config)

        """
        # Determine parameter name
        param_name = f"params_{index+1}"
        if params.name:
            param_name = params.name

        # Decorate with this parameter set (with empty reporters)
        decorated_func = self._decorate_with_bench_param(params, reporters=[])(func)

        # Extract results from the function
        bench_func = cast("BenchmarkableFunction", decorated_func)
        results_dict = None
        config = None

        if bench_func.last_results:
            results_dict = bench_func.last_results[func_name]
            config = bench_func.bench.bench_config.model_copy(deep=True)

        return param_name, results_dict, config

    def _display_comparison_results(
        self,
        all_results: ResultsType,
        first_config: BenchConfig,
        original_reporters: list[Reporter] | None,
    ) -> None:
        """
        Display comparison results.

        Args:
            all_results: Dictionary of all benchmark results
            first_config: The first benchmark configuration
            original_reporters: Original reporters from the function

        """
        comparison_config = first_config
        if original_reporters is not None:
            comparison_config.reporters = original_reporters
        elif comparison_config.reporters == []:
            comparison_config.reporters = [ConsoleReporter()]

        comparison = EasyBench(bench_config=comparison_config)
        comparison.report_results(
            results=all_results,
            config=comparison_config,
        )

    def _decorate_with_bench_param_list(
        self,
        params_list: list[BenchParams],
    ) -> Callable:
        """
        Set up the function for benchmarking using a list of BenchParams instances.

        This allows comparing different parameter configurations for the same function.

        Args:
            params_list: List of BenchParams instances with benchmark configurations

        Returns:
            A decorator function that configures the function with multiple
            BenchParams and compares results

        """

        def decorator(func: Callable) -> Callable:
            # Initialize benchmark attributes
            func = self._initialize_bench_attributes(func)

            # Store the params_list with the function for possible deferred execution
            func.params_list = params_list

            # If deferred, register in the group and return
            if func.defer:
                return func

            # Not deferred - run benchmarks immediately
            # Store original function
            orig_func = func
            func_name = func.__name__

            # Store original reporters from the function if available
            original_reporters = None
            if hasattr(func, "bench") and hasattr(func.bench, "bench_config"):
                bench_func = cast("BenchmarkableFunction", func)
                original_reporters = bench_func.bench.bench_config.reporters

            # Store results for each parameter set
            all_results: ResultsType = {}
            first_config = None

            # Run benchmarks for each parameter set
            for i, params in enumerate(params_list):
                param_name, results, config = self._process_single_param_set(
                    func,
                    params,
                    i,
                    func_name,
                )

                if results:
                    all_results[f"{func_name} ({param_name})"] = results
                    if first_config is None:
                        first_config = config

            # Display results if we have results
            if len(all_results) >= 1 and first_config:
                self._display_comparison_results(
                    all_results,
                    first_config,
                    original_reporters,
                )

            # Return the original function
            return orig_func

        return decorator

    def _decorate_with_bench_param(
        self,
        param: BenchParams,
        reporters: list[Reporter] | None = None,
    ) -> Callable:
        """
        Set up the function for benchmarking using a BenchParams instance.

        Args:
            param: BenchParams instance with benchmark configuration
            reporters: List of reporters for benchmark

        Returns:
            A decorator function that configures the function with the BenchParams

        """

        def decorator(func: Callable) -> Callable:
            # Initialize benchmark attributes
            func = self._initialize_bench_attributes(func)

            if reporters is not None:
                func.bench.bench_config.reporters = reporters

            # Apply function parameters
            if param.fn_params:
                for name, value in param.fn_params.items():
                    func.fixtures[name] = lambda v=value: v

            # Apply bench parameters
            if param.params:
                for name, value in param.params.items():
                    if callable(value) and not isinstance(value, type):
                        # For callables like lambdas, register the callable itself
                        func.fixtures[name] = value
                    else:
                        # For values, create a lambda that returns the value
                        func.fixtures[name] = lambda v=value: v

            # Run benchmark if all parameters are satisfied
            self._maybe_run_benchmark(func)

            return func

        return decorator

    def _decorate(self, func: Callable, **kwargs: object) -> Callable:
        """
        Set up the function for benchmarking.

        Args:
            func: The function to benchmark
            **kwargs: Benchmark parameters

        Returns:
            The decorated function

        """
        # Initialize benchmark attributes
        func = self._initialize_bench_attributes(func)

        # Register variables as fixtures
        for name, value in kwargs.items():
            if callable(value) and not isinstance(value, type):
                # For callables like lambdas, register the callable itself
                func.fixtures[name] = value
            else:
                # For values, create a lambda that returns the value
                func.fixtures[name] = lambda v=value: v

        # Check if all required parameters are available and run if they are
        self._maybe_run_benchmark(func)
        return func

    def _reset_bench(
        self,
        func: BenchmarkableFunction,
        *,
        reset_params: bool = True,
        reset_config: bool = True,
    ) -> None:
        """
        Reset benchmark settings.

        Args:
            func: The benchmarked function
            reset_params: Whether to reset parameters
            reset_config: Whether to reset configuration

        """
        if reset_params:
            func.fixtures = {}

        if reset_config:
            func.bench.bench_config = BenchConfig()

    def fn_params(self, **kwargs: object) -> Callable:
        """
        Configure benchmark function parameters.

        Example:
            ```python
            @bench.fn_params(op=lambda x: x + 1)
            def apply_operation(op):
                return op(12345)
            ```

        Returns:
            A decorator function that configures benchmark parameters

        """

        def decorator(func: Callable) -> Callable:
            # Initialize benchmark attributes
            func = self._initialize_bench_attributes(func)

            # Register function parameters as fixtures
            for name, value in kwargs.items():
                func.fixtures[name] = lambda v=value: v

            self._maybe_run_benchmark(func)
            return func

        return decorator

    def _maybe_run_benchmark(self, func: BenchmarkableFunction) -> None:
        """Run the benchmark if all parameters are available and not deferred."""
        # Skip if deferred
        if func.defer:
            return

        # Get function signature to determine required parameters
        sig = inspect.signature(func)

        # Get parameters that have no defaults and must be provided
        required_params = {
            name
            for name, param in sig.parameters.items()
            if param.default is inspect.Parameter.empty
        }

        # Check if all required parameters are available in fixtures
        provided_params = set(func.fixtures.keys())

        if required_params.issubset(provided_params):
            # All parameters are satisfied, run the benchmark
            fixture_registry: FixtureRegistry = {
                "trial": func.fixtures,
                "function": {},
                "class": {},
            }
            results = func.bench.bench(fixture_registry=fixture_registry)
            func.last_results = results

            # Reset bench
            self._reset_bench(func, reset_config=False)

    @overload
    def config(self, /) -> Callable: ...

    @overload
    def config(self, config: BenchConfig, /, **kwargs: object) -> Callable: ...

    @overload
    def config(
        self,
        /,
        *,
        trials: int | None = None,
        loops_per_trial: int | None = None,
        warmups: int | None = None,
        sort_by: SortType | None = None,
        reverse: bool | None = None,
        memory: bool | MemoryUnit | str | None = None,
        time: bool | TimeUnit | str | None = None,
        color: bool | None = None,
        show_output: bool | None = None,
        reporters: list[Reporter] | None = None,
        progress: bool | Callable | None = None,
        clip_outliers: float | None = None,
        defer: bool | str | None = None,
    ) -> Callable: ...

    def config(self, config: BenchConfig | None = None, /, **kwargs: Any) -> Callable:
        """
        Configure benchmark settings.

        Example:
            ```python
            # Using keyword arguments
            @bench(
                item=123,
                big_list=lambda: list(range(1_000_000)),
            )
            @bench.config(trials=5, loops_per_trial=10, memory=True)
            def add_item(item, big_list):
                big_list.append(item)

            # Using BenchConfig as positional argument
            my_config = BenchConfig(trials=10, memory=True)
            @bench.config(my_config)
            def another_function():
                pass
            ```

        Args:
            config: Optional BenchConfig instance as positional argument
            **kwargs: Configuration parameters to set

        Returns:
            A decorator function that configures benchmark settings

        """

        def decorator(func: Callable) -> Callable:
            # Initialize benchmark attributes
            func = self._initialize_bench_attributes(func)

            # Extract defer parameter (not part of BenchConfig)
            defer = kwargs.pop("defer", False)
            func.defer = defer

            # Register function in group if a group name is provided
            if isinstance(defer, str):
                if defer not in self._deferred_functions:
                    self._deferred_functions[defer] = []
                self._deferred_functions[defer].append(func)

            # Create partial config from kwargs
            partial_config = PartialBenchConfig(**kwargs)
            # Update benchmark config with merged values
            func.bench.bench_config = partial_config.merge_with(
                config or func.bench.bench_config,
            )

            # Check if all required parameters are available
            self._maybe_run_benchmark(func)
            return func

        return decorator

    def grid(
        self,
        params_lists: Iterable[Iterable[BenchParams]],
    ) -> Callable:
        """
        Create a decorator that applies a Cartesian product of parameter lists.

        This creates all combinations of the parameter sets for benchmarking.

        Example:
            ```python
            sizes = [
                BenchParams(name="Small", params={"size": 100}),
                BenchParams(name="Large", params={"size": 10000}),
            ]
            ops = [
                BenchParams(name="Append", fn_params={"op": lambda x: x.append(0)}),
                BenchParams(name="Pop", fn_params={"op": lambda x: x.pop()}),
            ]

            @bench.grid([sizes, ops])
            def operation(size, op):
                # Will run with all combinations:
                # (Small, Append), (Small, Pop), (Large, Append), (Large, Pop)
                lst = list(range(size))
                op(lst)
            ```

        Args:
            params_lists: An iterable of iterables of BenchParams to combine

        Returns:
            A decorator function that applies all parameter combinations

        """

        def decorator(func: Callable) -> Callable:
            # Convert all parameter lists to actual lists
            converted_lists = []
            for params in params_lists:
                if isinstance(params, (list, tuple)):
                    converted_lists.append(list(params))
                else:
                    # Handle iterables by converting to list
                    converted_lists.append(list(params))

            # Handle the case with no parameter lists
            if not converted_lists:
                return func

            # Handle the case with just one parameter list
            if len(converted_lists) == 1:
                return self._decorate_with_bench_param_list(converted_lists[0])(func)

            # Start with the first list
            result_params = converted_lists[0]

            # Multiply with each subsequent list to get Cartesian product
            for params_list in converted_lists[1:]:
                new_result = []
                for param1 in result_params:
                    for param2 in params_list:
                        # Use the multiplication operator defined in BenchParams
                        combined_param = param1 * param2
                        new_result.append(combined_param)
                result_params = new_result

            # Apply the combined parameters using _decorate_with_bench_param_list
            return self._decorate_with_bench_param_list(result_params)(func)

        return decorator

    def run(
        self,
        group: str,
        config: BenchConfig | None = None,
    ) -> ResultsType:
        """
        Run all benchmarks in a specified group.

        Args:
            group: The group name to run
            config: Optional BenchConfig to use for all benchmarks in the group

        Returns:
            Combined results from all benchmarks in the group

        Example:
            ```python
            @bench.config(defer="examples")
            def example1(x):
                return x * 2

            @bench.config(defer="examples")
            def example2(x):
                return x * 3

            # Run all examples
            bench.run("examples")
            ```

        """
        if group not in self._deferred_functions:
            msg = f"No functions in group '{group}'"
            raise ValueError(msg)

        # Get all functions in the group
        functions = self._deferred_functions[group]

        if not functions:
            msg = f"Group '{group}' exists but contains no functions"
            raise ValueError(msg)

        # Use the config of the last added function if no config provided
        final_config = config or functions[-1].bench.bench_config.model_copy(deep=True)

        all_results: ResultsType = {}

        # Process each function
        for func in functions:
            # Prepare config
            _config = final_config.model_copy(deep=True)
            _config.reporters = []

            # Use individual config for loops_per_trial
            _config.loops_per_trial = func.bench.bench_config.loops_per_trial

            # Check if this function has params_list for comparison benchmarking
            if func.params_list:
                # Handle parameter comparison benchmarking
                func_name = func.__name__

                # Run benchmarks for each parameter set
                org_defer = func.defer
                org_config = func.bench.bench_config
                func.defer = False
                func.bench.bench_config = _config
                for i, params in enumerate(func.params_list):
                    param_name, results, _ = self._process_single_param_set(
                        func,
                        params,
                        i,
                        func_name,
                    )

                    if results:
                        all_results[f"{func_name} ({param_name})"] = results
                func.defer = org_defer
                func.bench.bench_config = org_config
            else:
                # Standard benchmark for a single function
                fixture_registry: FixtureRegistry = {
                    "trial": func.fixtures,
                    "function": {},
                    "class": {},
                }
                _results = func.bench.bench(
                    config=_config,
                    fixture_registry=fixture_registry,
                )

                # Add results to the combined results
                if _results:
                    all_results.update(_results)

        # Display combined results using the final config
        if all_results:
            comparison = EasyBench(bench_config=final_config)
            comparison.report_results(
                results=all_results,
                config=final_config,
            )

        return all_results

__call__(*args, **kwargs)

EasyBench benchmark decorator.

Example

@bench(
    item=123,
    big_list=lambda: list(range(1_000_000)),
)
def add_item(item, big_list):
    big_list.append(item)

Using a list of BenchParams for comparison

params1 = BenchParams(
    name="Small", params={"lst": lambda: list(range(1000))},
)
params2 = BenchParams(
    name="Large", params={"lst": lambda: list(range(10000))},
)

@bench([params1, params2])
def pop_first(lst):
    return lst.pop(0)

Returns:

Type	Description
Callable	A decorated function with benchmark capabilities

Source code in easybench/decorator.py

def __call__(
    self,
    *args: object,
    **kwargs: object,
) -> Callable:
    """
    EasyBench benchmark decorator.

    Example:
        ```python
        @bench(
            item=123,
            big_list=lambda: list(range(1_000_000)),
        )
        def add_item(item, big_list):
            big_list.append(item)
        ```

        # Using a list of BenchParams for comparison
        ```python
        params1 = BenchParams(
            name="Small", params={"lst": lambda: list(range(1000))},
        )
        params2 = BenchParams(
            name="Large", params={"lst": lambda: list(range(10000))},
        )

        @bench([params1, params2])
        def pop_first(lst):
            return lst.pop(0)
        ```

    Returns:
        A decorated function with benchmark capabilities

    """
    # Handle list of BenchParams as first argument
    if (
        len(args) == 1
        and isinstance(args[0], list)
        and not kwargs
        and all(isinstance(param, BenchParams) for param in args[0])
    ):
        return self._decorate_with_bench_param_list(args[0])

    # Handle BenchParams instance as first argument
    if len(args) == 1 and isinstance(args[0], BenchParams) and not kwargs:
        return self._decorate_with_bench_param(args[0])

    # Handle direct function decoration: @bench
    if len(args) == 1 and callable(args[0]) and not kwargs:
        return self._decorate(args[0])

    # Handle parameterized decoration: @bench(param=value)
    def decorator(func: Callable) -> Callable:
        return self._decorate(func, **kwargs)

    return decorator

__init__()

Initialize BenchDecorator with storage for deferred functions.

Source code in easybench/decorator.py

def __init__(self) -> None:
    """Initialize BenchDecorator with storage for deferred functions."""
    self._deferred_functions: dict[str, list[BenchmarkableFunction]] = {}

config(config=None, /, **kwargs)

config() -> Callable

config(
    config: BenchConfig, /, **kwargs: object
) -> Callable

config(
    *,
    trials: int | None = None,
    loops_per_trial: int | None = None,
    warmups: int | None = None,
    sort_by: SortType | None = None,
    reverse: bool | None = None,
    memory: bool | MemoryUnit | str | None = None,
    time: bool | TimeUnit | str | None = None,
    color: bool | None = None,
    show_output: bool | None = None,
    reporters: list[Reporter] | None = None,
    progress: bool | Callable | None = None,
    clip_outliers: float | None = None,
    defer: bool | str | None = None
) -> Callable

Configure benchmark settings.

Example

# Using keyword arguments
@bench(
    item=123,
    big_list=lambda: list(range(1_000_000)),
)
@bench.config(trials=5, loops_per_trial=10, memory=True)
def add_item(item, big_list):
    big_list.append(item)

# Using BenchConfig as positional argument
my_config = BenchConfig(trials=10, memory=True)
@bench.config(my_config)
def another_function():
    pass

Parameters:

Name	Type	Description	Default
config	BenchConfig | None	Optional BenchConfig instance as positional argument	None
**kwargs	Any	Configuration parameters to set	{}

Returns:

Type	Description
Callable	A decorator function that configures benchmark settings

Source code in easybench/decorator.py

def config(self, config: BenchConfig | None = None, /, **kwargs: Any) -> Callable:
    """
    Configure benchmark settings.

    Example:
        ```python
        # Using keyword arguments
        @bench(
            item=123,
            big_list=lambda: list(range(1_000_000)),
        )
        @bench.config(trials=5, loops_per_trial=10, memory=True)
        def add_item(item, big_list):
            big_list.append(item)

        # Using BenchConfig as positional argument
        my_config = BenchConfig(trials=10, memory=True)
        @bench.config(my_config)
        def another_function():
            pass
        ```

    Args:
        config: Optional BenchConfig instance as positional argument
        **kwargs: Configuration parameters to set

    Returns:
        A decorator function that configures benchmark settings

    """

    def decorator(func: Callable) -> Callable:
        # Initialize benchmark attributes
        func = self._initialize_bench_attributes(func)

        # Extract defer parameter (not part of BenchConfig)
        defer = kwargs.pop("defer", False)
        func.defer = defer

        # Register function in group if a group name is provided
        if isinstance(defer, str):
            if defer not in self._deferred_functions:
                self._deferred_functions[defer] = []
            self._deferred_functions[defer].append(func)

        # Create partial config from kwargs
        partial_config = PartialBenchConfig(**kwargs)
        # Update benchmark config with merged values
        func.bench.bench_config = partial_config.merge_with(
            config or func.bench.bench_config,
        )

        # Check if all required parameters are available
        self._maybe_run_benchmark(func)
        return func

    return decorator

fn_params(**kwargs)

Configure benchmark function parameters.

Example

@bench.fn_params(op=lambda x: x + 1)
def apply_operation(op):
    return op(12345)

Returns:

Type	Description
Callable	A decorator function that configures benchmark parameters

Source code in easybench/decorator.py

def fn_params(self, **kwargs: object) -> Callable:
    """
    Configure benchmark function parameters.

    Example:
        ```python
        @bench.fn_params(op=lambda x: x + 1)
        def apply_operation(op):
            return op(12345)
        ```

    Returns:
        A decorator function that configures benchmark parameters

    """

    def decorator(func: Callable) -> Callable:
        # Initialize benchmark attributes
        func = self._initialize_bench_attributes(func)

        # Register function parameters as fixtures
        for name, value in kwargs.items():
            func.fixtures[name] = lambda v=value: v

        self._maybe_run_benchmark(func)
        return func

    return decorator

grid(params_lists)

Create a decorator that applies a Cartesian product of parameter lists.

This creates all combinations of the parameter sets for benchmarking.

Example

sizes = [
    BenchParams(name="Small", params={"size": 100}),
    BenchParams(name="Large", params={"size": 10000}),
]
ops = [
    BenchParams(name="Append", fn_params={"op": lambda x: x.append(0)}),
    BenchParams(name="Pop", fn_params={"op": lambda x: x.pop()}),
]

@bench.grid([sizes, ops])
def operation(size, op):
    # Will run with all combinations:
    # (Small, Append), (Small, Pop), (Large, Append), (Large, Pop)
    lst = list(range(size))
    op(lst)

Parameters:

Name	Type	Description	Default
params_lists	Iterable[Iterable[BenchParams]]	An iterable of iterables of BenchParams to combine	required

Returns:

Type	Description
Callable	A decorator function that applies all parameter combinations

Source code in easybench/decorator.py

def grid(
    self,
    params_lists: Iterable[Iterable[BenchParams]],
) -> Callable:
    """
    Create a decorator that applies a Cartesian product of parameter lists.

    This creates all combinations of the parameter sets for benchmarking.

    Example:
        ```python
        sizes = [
            BenchParams(name="Small", params={"size": 100}),
            BenchParams(name="Large", params={"size": 10000}),
        ]
        ops = [
            BenchParams(name="Append", fn_params={"op": lambda x: x.append(0)}),
            BenchParams(name="Pop", fn_params={"op": lambda x: x.pop()}),
        ]

        @bench.grid([sizes, ops])
        def operation(size, op):
            # Will run with all combinations:
            # (Small, Append), (Small, Pop), (Large, Append), (Large, Pop)
            lst = list(range(size))
            op(lst)
        ```

    Args:
        params_lists: An iterable of iterables of BenchParams to combine

    Returns:
        A decorator function that applies all parameter combinations

    """

    def decorator(func: Callable) -> Callable:
        # Convert all parameter lists to actual lists
        converted_lists = []
        for params in params_lists:
            if isinstance(params, (list, tuple)):
                converted_lists.append(list(params))
            else:
                # Handle iterables by converting to list
                converted_lists.append(list(params))

        # Handle the case with no parameter lists
        if not converted_lists:
            return func

        # Handle the case with just one parameter list
        if len(converted_lists) == 1:
            return self._decorate_with_bench_param_list(converted_lists[0])(func)

        # Start with the first list
        result_params = converted_lists[0]

        # Multiply with each subsequent list to get Cartesian product
        for params_list in converted_lists[1:]:
            new_result = []
            for param1 in result_params:
                for param2 in params_list:
                    # Use the multiplication operator defined in BenchParams
                    combined_param = param1 * param2
                    new_result.append(combined_param)
            result_params = new_result

        # Apply the combined parameters using _decorate_with_bench_param_list
        return self._decorate_with_bench_param_list(result_params)(func)

    return decorator

run(group, config=None)

Run all benchmarks in a specified group.

Parameters:

Name	Type	Description	Default
group	str	The group name to run	required
config	BenchConfig | None	Optional BenchConfig to use for all benchmarks in the group	None

Returns:

Type	Description
ResultsType	Combined results from all benchmarks in the group

Example

@bench.config(defer="examples")
def example1(x):
    return x * 2

@bench.config(defer="examples")
def example2(x):
    return x * 3

# Run all examples
bench.run("examples")

Source code in easybench/decorator.py

def run(
    self,
    group: str,
    config: BenchConfig | None = None,
) -> ResultsType:
    """
    Run all benchmarks in a specified group.

    Args:
        group: The group name to run
        config: Optional BenchConfig to use for all benchmarks in the group

    Returns:
        Combined results from all benchmarks in the group

    Example:
        ```python
        @bench.config(defer="examples")
        def example1(x):
            return x * 2

        @bench.config(defer="examples")
        def example2(x):
            return x * 3

        # Run all examples
        bench.run("examples")
        ```

    """
    if group not in self._deferred_functions:
        msg = f"No functions in group '{group}'"
        raise ValueError(msg)

    # Get all functions in the group
    functions = self._deferred_functions[group]

    if not functions:
        msg = f"Group '{group}' exists but contains no functions"
        raise ValueError(msg)

    # Use the config of the last added function if no config provided
    final_config = config or functions[-1].bench.bench_config.model_copy(deep=True)

    all_results: ResultsType = {}

    # Process each function
    for func in functions:
        # Prepare config
        _config = final_config.model_copy(deep=True)
        _config.reporters = []

        # Use individual config for loops_per_trial
        _config.loops_per_trial = func.bench.bench_config.loops_per_trial

        # Check if this function has params_list for comparison benchmarking
        if func.params_list:
            # Handle parameter comparison benchmarking
            func_name = func.__name__

            # Run benchmarks for each parameter set
            org_defer = func.defer
            org_config = func.bench.bench_config
            func.defer = False
            func.bench.bench_config = _config
            for i, params in enumerate(func.params_list):
                param_name, results, _ = self._process_single_param_set(
                    func,
                    params,
                    i,
                    func_name,
                )

                if results:
                    all_results[f"{func_name} ({param_name})"] = results
            func.defer = org_defer
            func.bench.bench_config = org_config
        else:
            # Standard benchmark for a single function
            fixture_registry: FixtureRegistry = {
                "trial": func.fixtures,
                "function": {},
                "class": {},
            }
            _results = func.bench.bench(
                config=_config,
                fixture_registry=fixture_registry,
            )

            # Add results to the combined results
            if _results:
                all_results.update(_results)

    # Display combined results using the final config
    if all_results:
        comparison = EasyBench(bench_config=final_config)
        comparison.report_results(
            results=all_results,
            config=final_config,
        )

    return all_results

BenchmarkableFunction

Bases: Protocol[P, R_co]

Function with bench.

Source code in easybench/decorator.py

class BenchmarkableFunction(Protocol[P, R_co]):
    """Function with bench."""

    def __call__(self, *args: P.args, **kwds: P.kwargs) -> R_co:
        """Call method."""
        ...

    @property
    def __name__(self) -> str:
        """Name of the function."""
        ...

    bench: FunctionBench
    fixtures: dict[str, object]
    last_results: ResultsType
    defer: bool | str
    params_list: list[BenchParams] | None

__name__ property

Name of the function.

__call__(*args, **kwds)

Call method.

Source code in easybench/decorator.py

def __call__(self, *args: P.args, **kwds: P.kwargs) -> R_co:
    """Call method."""
    ...