5 new features:

- Feature 1 — arguments.match() + signature validation in
  Scenario.__init__
- Feature 2 — microbenchmark CLI entry point (__main__.py), argv
  parameter on .cli()
- Feature 3 — BenchmarkResult.total_duration and functions_duration
  fields, shown as total: / fn total:
- Feature 4 — Unicode box borders ╭─╮│╰─╯ around .cli() output, nested
  borders for ScenarioGroup
- Feature 5 — --histogram flag with draw_histogram() producing ASCII █
  bar charts (8 rows fixed height)

Author: Евгений Блинов

README.md

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from typing import Union
+
+from microbenchmark.scenario import Scenario
+from microbenchmark.scenario_group import ScenarioGroup
+
+_Target = Union[Scenario, ScenarioGroup]
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = argv if argv is not None else sys.argv[1:]
+
+    if not args or ':' not in args[0]:
+        sys.stderr.write(
+            'microbenchmark: expected TARGET in the form module.path:attr\n'
+            'Usage: microbenchmark module.path:attr [OPTIONS]\n',
+        )
+        sys.exit(3)
+
+    spec, *rest = args
+    colon_pos = spec.index(':')
+    module_path = spec[:colon_pos]
+    attr_name = spec[colon_pos + 1:]
+
+    if not module_path or not attr_name:
+        sys.stderr.write(
+            f'microbenchmark: invalid target {spec!r} — '
+            'expected non-empty module and attribute\n',
+        )
+        sys.exit(3)
+
+    # Ensure CWD is importable so local (non-installed) modules can be found.
+    cwd = str(Path.cwd())
+    if cwd not in sys.path and '' not in sys.path:
+        sys.path.insert(0, cwd)  # pragma: no cover
+
+    try:
+        module = importlib.import_module(module_path)
+    except ModuleNotFoundError as exc:
+        sys.stderr.write(f'microbenchmark: cannot import module {module_path!r}: {exc}\n')
+        sys.exit(3)
+
+    sentinel = object()
+    target: object = getattr(module, attr_name, sentinel)
+    if target is sentinel:
+        sys.stderr.write(
+            f'microbenchmark: module {module_path!r} has no attribute {attr_name!r}\n',
+        )
+        sys.exit(3)
+
+    if not isinstance(target, (Scenario, ScenarioGroup)):
+        sys.stderr.write(
+            f'microbenchmark: {module_path}:{attr_name} is a '
+            f'{type(target).__name__!r}, expected Scenario or ScenarioGroup\n',
+        )
+        sys.exit(3)
+
+    target.cli(argv=rest)
+
+
+if __name__ == '__main__':
+    main()

microbenchmark/__main__.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import shutil
+from collections.abc import Sequence
+
+
+def terminal_width() -> int:
+    """Return the current terminal width, clamped to a minimum of 20."""
+    cols = shutil.get_terminal_size((80, 24)).columns
+    return max(cols, 20)
+
+
+def draw_box(lines: list[str], width: int) -> list[str]:
+    """Draw a Unicode border box around *lines*.
+
+    Each output line is exactly *width* characters wide.  Content lines are
+    padded with spaces or truncated to ``width - 4`` characters (2 chars for
+    the border + space on each side).
+
+    Box drawing uses ASCII + box-drawing characters (``╭╮╰╯│─``).  Width is
+    measured by ``len()``, which counts every character as 1 column.  Emoji or
+    CJK characters may cause visual misalignment.
+
+    Args:
+        lines: Content lines to render inside the box.
+        width: Total width of each output line, including borders.
+    """
+    inner_width = width - 4  # 2 for │ and 1 space on each side
+    top = '╭' + '─' * (width - 2) + '╮'
+    bottom = '╰' + '─' * (width - 2) + '╯'
+    result = [top]
+    for line in lines:
+        if len(line) > inner_width:
+            content = line[:inner_width]
+        else:
+            content = line.ljust(inner_width)
+        result.append('│ ' + content + ' │')
+    result.append(bottom)
+    return result
+
+
+def draw_nested(
+    inner_blocks: list[list[str]],
+    extras: list[str],
+    width: int,
+) -> list[str]:
+    """Draw an outer border box wrapping pre-rendered *inner_blocks*.
+
+    Each inner block is already a list of strings (e.g. from :func:`draw_box`).
+    They are placed inside the outer border with 1-space padding on each side.
+    *extras* are additional plain-text lines rendered after the inner blocks,
+    also padded.
+
+    Args:
+        inner_blocks: List of already-rendered blocks (each a list of strings).
+        extras: Extra plain-text lines appended after the inner blocks.
+        width: Total width of the outer box.
+    """
+    inner_width = width - 4  # space for │ + space on each side
+
+    def pad_inner_line(line: str) -> str:
+        if len(line) > inner_width:
+            content = line[:inner_width]
+        else:
+            content = line.ljust(inner_width)
+        return '│ ' + content + ' │'
+
+    top = '╭' + '─' * (width - 2) + '╮'
+    bottom = '╰' + '─' * (width - 2) + '╯'
+    result = [top]
+    for block in inner_blocks:
+        for line in block:
+            result.append(pad_inner_line(line))
+    for line in extras:
+        result.append(pad_inner_line(line))
+    result.append(bottom)
+    return result
+
+
+def draw_histogram(durations: Sequence[float], width: int, height: int) -> list[str]:
+    """Render an ASCII bar chart of *durations* as a ``height`` x ``width`` grid.
+
+    Each column is one bucket; each row is one unit of height.  Filled cells
+    use ``'█'``; empty cells use ``' '``.  Returns an empty list when any
+    dimension is zero/negative or when *durations* is empty.
+
+    When all values are identical (``hi == lo``), the middle column is drawn
+    full-height and all other columns are left empty.
+
+    Args:
+        durations: Sequence of per-call timings in seconds.
+        width: Number of columns (buckets) in the chart.
+        height: Number of rows in the chart.
+    """
+    if width < 1 or height < 1 or len(durations) == 0:
+        return []
+
+    lo = min(durations)
+    hi = max(durations)
+
+    counts = [0] * width
+
+    if hi == lo:
+        counts[width // 2] = 1
+    else:
+        span = hi - lo
+        for d in durations:
+            idx = min(width - 1, int((d - lo) / span * width))
+            counts[idx] += 1
+
+    max_count = max(counts)
+    bar_heights = [
+        (max(1, round(c / max_count * height)) if c > 0 else 0)
+        for c in counts
+    ]
+
+    rows: list[str] = []
+    for row in range(height - 1, -1, -1):
+        line = ''.join('█' if bar_heights[col] > row else ' ' for col in range(width))
+        rows.append(line)
+    return rows

microbenchmark/_render.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 from printo import describe_data_object
+from sigmatch import PossibleCallMatcher
+from sigmatch.errors import SignatureNotFoundError, UnsupportedSignatureError
 
 
 class arguments:  # noqa: N801
@@ -28,3 +30,25 @@ def __eq__(self, other: object) -> bool:
 
     def __hash__(self) -> int:
         return hash((self.args, tuple(sorted(self.kwargs.items()))))
+
+    def match(self, function: object) -> bool:
+        """Check whether *function* can be called with these arguments.
+
+        Returns ``True`` if the call is compatible with the function's
+        signature, ``False`` if not.
+
+        **Limitation:** if Python cannot introspect the signature of
+        *function* (e.g. built-in / C-extension functions such as ``len``),
+        the check is silently skipped and ``True`` is returned.  The function
+        will be validated at runtime when the benchmark actually runs.
+        """
+        from sigmatch import SignatureMismatchError  # noqa: PLC0415
+        shape = ('.',) * len(self.args) + tuple(self.kwargs)
+        matcher: PossibleCallMatcher = PossibleCallMatcher(*shape)
+        try:
+            matcher.match(function, raise_exception=True)  # type: ignore[arg-type]
+            return True
+        except SignatureMismatchError:
+            return False
+        except (SignatureNotFoundError, UnsupportedSignatureError):
+            return True

microbenchmark/arguments.py

@@ -19,6 +19,7 @@ class _ScenarioMeta(TypedDict):
 
 class _ResultJson(TypedDict):
     durations: list[float]
+    total_duration: float
     is_primary: bool
     scenario: _ScenarioMeta | None
 
@@ -27,16 +28,19 @@ class _ResultJson(TypedDict):
 class BenchmarkResult:
     scenario: Scenario | None
     durations: tuple[float, ...]
+    total_duration: float
     is_primary: bool = True
 
     mean: float = field(init=False)
     best: float = field(init=False)
     worst: float = field(init=False)
+    functions_duration: float = field(init=False)
 
     def __post_init__(self) -> None:
         self.mean = math.fsum(self.durations) / len(self.durations)
         self.best = min(self.durations)
         self.worst = max(self.durations)
+        self.functions_duration = math.fsum(self.durations)
 
     def percentile(self, p: float) -> BenchmarkResult:
         if not (0 < p <= 100):
@@ -46,6 +50,7 @@ def percentile(self, p: float) -> BenchmarkResult:
         return BenchmarkResult(
             scenario=self.scenario,
             durations=trimmed,
+            total_duration=0.0,
             is_primary=False,
         )
 
@@ -73,6 +78,7 @@ def to_json(self) -> str:
             scenario_meta = None
         data: _ResultJson = _ResultJson(
             durations=list(self.durations),
+            total_duration=self.total_duration,
             is_primary=self.is_primary,
             scenario=scenario_meta,
         )
@@ -91,8 +97,14 @@ def from_json(cls, data: str) -> BenchmarkResult:
             raise ValueError('durations must be a list')
         if not isinstance(raw_is_primary, bool):
             raise ValueError('is_primary must be a bool')
+        raw_total: object = raw.get('total_duration')
+        if raw_total is None:
+            total_duration = math.fsum(float(d) for d in raw_durations)
+        else:
+            total_duration = float(raw_total)  # type: ignore[arg-type]
         return cls(
             scenario=None,
             durations=tuple(float(d) for d in raw_durations),
+            total_duration=total_duration,
             is_primary=raw_is_primary,
         )

microbenchmark/benchmark_result.py

@@ -7,7 +7,9 @@
 
 from printo import describe_data_object
 from printo.reprs import superrepr
+from sigmatch import SignatureMismatchError
 
+from microbenchmark._render import draw_box, draw_histogram, terminal_width
 from microbenchmark.arguments import arguments as Arguments  # noqa: N812
 from microbenchmark.benchmark_result import BenchmarkResult
 
@@ -19,6 +21,7 @@ class _CliArgs:
     def __init__(self) -> None:
         self.number: int | None = None
         self.max_mean: float | None = None
+        self.histogram: bool = False
 
 
 class Scenario:
@@ -34,6 +37,13 @@ def __init__(  # noqa: PLR0913
     ) -> None:
         if number < 1:
             raise ValueError(f'number must be at least 1, got {number}')
+        checker: Arguments = arguments if isinstance(arguments, Arguments) else Arguments()
+        if not checker.match(function):
+            fn_name: object = getattr(function, '__name__', repr(function))
+            raise SignatureMismatchError(
+                f'Scenario arguments {checker!r} are incompatible with the '
+                f'signature of {fn_name}',
+            )
         self.function: object = function
         self._arguments: Arguments | None = arguments
         if name is None and hasattr(function, '__name__'):
@@ -56,24 +66,29 @@ def run(self, warmup: int = 0) -> BenchmarkResult:
             self._call_once()
             timer()
         durations: list[float] = []
+        loop_start = timer()
         for _ in range(self.number):
             start = timer()
             self._call_once()
             end = timer()
             durations.append(end - start)
+        loop_end = timer()
         return BenchmarkResult(
             scenario=self,
             durations=tuple(durations),
+            total_duration=loop_end - loop_start,
             is_primary=True,
         )
 
-    def cli(self) -> None:
+    def cli(self, argv: list[str] | None = None) -> None:
         parser = argparse.ArgumentParser(description=self.doc or f'Benchmark: {self.name}')
         parser.add_argument('--number', type=int, default=None, help='Number of iterations')
         parser.add_argument('--max-mean', type=float, default=None, dest='max_mean',
                             help='Fail if mean time (seconds) exceeds this threshold')
+        parser.add_argument('--histogram', action='store_true', default=False,
+                            help='Append an ASCII histogram of per-call timings')
         cli_args = _CliArgs()
-        parser.parse_args(namespace=cli_args)
+        parser.parse_args(argv, namespace=cli_args)
 
         scenario = self
         if cli_args.number is not None:
@@ -87,7 +102,13 @@ def cli(self) -> None:
             )
 
         result = scenario.run()
-        _print_result(result)
+        width = terminal_width()
+        lines = _render_result(result)
+        if cli_args.histogram:
+            lines.append('')
+            lines.extend(draw_histogram(list(result.durations), width - 4, 8))
+        box = draw_box(lines, width)
+        sys.stdout.write('\n'.join(box) + '\n')
 
         if cli_args.max_mean is not None and result.mean > cli_args.max_mean:
             sys.stdout.write(
@@ -128,19 +149,23 @@ def _fn_call_str(function: object, arguments: Arguments | None) -> str:
     return describe_data_object(fn_name, args, kwargs)
 
 
-def _print_result(result: BenchmarkResult) -> None:
+def _render_result(result: BenchmarkResult) -> list[str]:
     scenario = result.scenario
     assert scenario is not None
     call_str = _fn_call_str(scenario.function, scenario._arguments)
     label_width = len('p95 mean:')
-    sys.stdout.write(f'benchmark: {scenario.name}\n')
-    sys.stdout.write(f'{"call:".ljust(label_width)} {call_str}\n')
+    lines: list[str] = []
+    lines.append(f'benchmark: {scenario.name}')
+    lines.append(f'{"call:".ljust(label_width)} {call_str}')
     if scenario.doc:
-        sys.stdout.write(f'{"doc:".ljust(label_width)} {scenario.doc}\n')
-    sys.stdout.write(f'{"runs:".ljust(label_width)} {scenario.number}\n')
-    sys.stdout.write(f'{"mean:".ljust(label_width)} {result.mean:.6f}s\n')
-    sys.stdout.write(f'{"median:".ljust(label_width)} {result.median:.6f}s\n')
-    sys.stdout.write(f'{"best:".ljust(label_width)} {result.best:.6f}s\n')
-    sys.stdout.write(f'{"worst:".ljust(label_width)} {result.worst:.6f}s\n')
-    sys.stdout.write(f'{"p95 mean:".ljust(label_width)} {result.p95.mean:.6f}s\n')
-    sys.stdout.write(f'{"p99 mean:".ljust(label_width)} {result.p99.mean:.6f}s\n')
+        lines.append(f'{"doc:".ljust(label_width)} {scenario.doc}')
+    lines.append(f'{"runs:".ljust(label_width)} {scenario.number}')
+    lines.append(f'{"mean:".ljust(label_width)} {result.mean:.6f}s')
+    lines.append(f'{"median:".ljust(label_width)} {result.median:.6f}s')
+    lines.append(f'{"best:".ljust(label_width)} {result.best:.6f}s')
+    lines.append(f'{"worst:".ljust(label_width)} {result.worst:.6f}s')
+    lines.append(f'{"p95 mean:".ljust(label_width)} {result.p95.mean:.6f}s')
+    lines.append(f'{"p99 mean:".ljust(label_width)} {result.p99.mean:.6f}s')
+    lines.append(f'{"total:".ljust(label_width)} {result.total_duration:.6f}s')
+    lines.append(f'{"fn total:".ljust(label_width)} {result.functions_duration:.6f}s')
+    return lines