simplebench.reporters.rich_table package

Rich Table Reporter for SimpleBench.

This package provides a Rich Table reporter for the simplebench.reporters package. It offers functionality for generating rich table reports from benchmark results.

Public API

• RichTableConfig: Configuration class for the Rich Table reporter.

• RichTableField: Field enumeration for the Rich Table reporter.

• RichTableOptions: Options class for the Rich Table reporter.

• RichTableReporter: The Rich Table reporter class.

class simplebench.reporters.rich_table.RichTableConfig(

*,

name: str | None = None,

description: str | None = None,

sections: set[Section] | None = None,

targets: set[Target] | None = None,

default_targets: set[Target] | None = None,

formats: set[Format] | None = None,

choices: ChoicesConf | None = None,

file_suffix: str | None = None,

file_unique: bool | None = None,

file_append: bool | None = None,

subdir: str | None = None,

)

Bases: ReporterConfig

Configuration for a RichTableReporter.

This class inherits from ReporterConfig and provides a type-safe, discoverable interface for overriding the default settings of a RichTableReporter.

Initialize the RichTableReporter configuration.

Accepts keyword arguments to override any of the default configurations. All arguments are optional. If not provided, the default value for RichTableReporter will be used.

Note

The parameters of this constructor correspond directly to the parameters of the base ReporterConfig class. This design allows users to easily discover and override any configuration option available for the RichTableReporter while maintaining type safety and discoverability through IDEs and documentation tools.

To prevent future breakage, avoid using the ‘rc_’, or ‘rich_table_’ prefixes for any new parameters in subclasses as these are reserved for use by SimpleBench.

Default Values:

• name: 'rich-table'

• description: 'Displays benchmark results as a rich text table on the console.'

• sections: {Section.OPS, Section.TIMING, Section.MEMORY, Section.PEAK_MEMORY}

• targets: {Target.CONSOLE, Target.FILESYSTEM, Target.CALLBACK}

• default_targets: {Target.CONSOLE}

• formats: {Format.RICH_TEXT}

• choices: A ChoicesConf with predefined ChoiceConf objects for rich table reporting.

• file_suffix: 'txt'

• file_unique: False

• file_append: True

• subdir: 'rich'

Parameters:

• name – The name of the reporter.

• description – A brief description of the reporter.

• sections – The sections to include in the report.

• targets – The output targets for the report.

• default_targets – The default output targets if none are specified.

• formats – The output formats for the report.

• choices – The choice configurations for the reporter.

• file_suffix – The file suffix to use for filesystem outputs.

• file_unique – Whether to use unique filenames for outputs.

• file_append – Whether to append to existing files.

• subdir – The subdirectory to use for filesystem outputs.

Raises:

• SimpleBenchTypeError – If any provided argument has an invalid type.

• SimpleBenchValueError – If any provided argument has an invalid value or combination of values.

class simplebench.reporters.rich_table.RichTableField(value)

Bases: str, Enum

Fields available for Rich Table reporter output.

ELAPSED_SECONDS = 'Elapsed Seconds'

The total elapsed time in seconds.

ITERATIONS = 'Iterations'

The number of iterations performed.

MAX = 'max'

The statistical maximum value.

MEAN = 'mean'

The statistical mean value.

MEDIAN = 'median'

The statistical median value.

MIN = 'min'

The statistical minimum value.

N = 'N'

The O() complexity value.

P5 = '5th'

The statistical 5th percentile.

P95 = '95th'

The statistical 95th percentile.

ROUNDS = 'Rounds'

The number of rounds performed.

RSD_PERCENT = 'rsd%'

The relative standard deviation percentage.

STD_DEV = 'std dev'

The adjusted standard deviation of operation times.

class simplebench.reporters.rich_table.RichTableOptions(

virtual_width: int | None = None,

fields: Sequence[RichTableField] | None = None,

variation_cols_last: bool = False,

)

Bases: ReporterOptions

Class for holding Rich table reporter specific options in a Choice.

This class provides additional configuration options specific to the JSON reporter. It is accessed via the options attribute of a Choice instance.

Parameters:

• virtual_width –

  The width of the Rich table output in characters when rendered to the filesystem or via callback. Must be between 80 and 1000 characters or None. If None, no width constraint is applied.

  The virtual width is used to determine how the table should be formatted when rendered to non-console outputs, such as files or callbacks. This allows for better control over the appearance of the table in different contexts.

• fields –

  A tuple of Rich Table fields to include in the output. If none is specifically set, a predefined set of fields is used. The fields appear in the order specified in the sequence.

  If specified, all fields must be from the RichTableField enum.

  The default fields, in order, are:

  • N

  • ITERATIONS

  • ROUNDS

  • ELAPSED_SECONDS

  • MEAN

  • MEDIAN

  • MIN

  • MAX

  • P5

  • P95

  • STD_DEV

  • RSD_PERCENT

• variation_cols_last – Whether to place the variation columns (if any) at the end of the rows. Defaults to False - which places the variation columns at the start of the rows.

Raises:

• SimpleBenchTypeError – If any parameter is of an invalid type.

• SimpleBenchValueError – If virtual_width is not between 80 and 10000 characters when specified or if fields is an empty sequence.

Initialize RichTableOptions instance.

property fields: tuple[RichTableField, ...]

Return the fields, in order, to include in the Rich table when rendering.

Returns:

A tuple of RichTableField enums representing the default fields.

property variation_cols_last: bool

Return whether variation columns are placed at the end of the rows.

Returns:

True if variation columns are placed at the end, False if at the start.

property virtual_width: int | None

Return the virtual width of the Rich table output.

The virtual width is used when rendered to the filesystem or via callback.

Returns:

The virtual width of the Rich table output in characters.

class simplebench.reporters.rich_table.RichTableReporter(

config: RichTableConfig | None = None,

)

Bases: Reporter

Class for outputting benchmark results as Rich Tables.

It supports reporting operations per second and per round timing results, either separately or together, to the console, to files, and/or via a callback function.

Defined command-line flags:

• --rich-table: Outputs all results as rich text tables on the console.

• --rich-table.ops: Outputs only operations per second results.

• --rich-table.timings: Outputs only per round timing results.

• --rich-table.memory: Outputs only memory usage results.

• --rich-table.peak-memory: Outputs only peak memory usage results.

Each flag supports multiple targets: console, filesystem, and callback with the default target being console.

Variables:

• name (str) – The unique identifying name of the reporter.

• description (str) – A brief description of the reporter.

• choices (Choices) – A collection of Choices instances defining the reporter instance, CLI flags, Choice name, supported Section objects, supported output Target objects, and supported output Format objects for the reporter.

Initialize the RichTableReporter.

Note

The exception documentation below refers to validation of subclass configuration class variables _OPTIONS_TYPE and _OPTIONS_KWARGS. These must be correctly defined in any subclass of RichTableReporter to ensure proper functionality.

In simple use, these exceptions should never be raised, as RichTableReporter provides valid implementations. They are documented here for completeness.

Parameters:

config (RichTableConfig | None) – An optional configuration object to override default reporter settings. If not provided, default settings will be used.

Raises:

• SimpleBenchTypeError – If the subclass configuration types are invalid.

• SimpleBenchValueError – If the subclass configuration values are invalid.

render(

*,

case: Case,

section: Section,

options: ReporterOptions,

) → Table

Prints the benchmark results in a rich table format if available.

It creates a Table instance containing the benchmark results for the specified section.

The table includes the fields specified in the options argument, formatted appropriately based on the results data.

Depending on the options, variation columns can be placed at the start or end of the rows.

Parameters:

• case – The Case instance representing the benchmarked code.

• options – The options specifying the report configuration. (RichTableOptions is a subclass of ReporterOptions.)

• section – The Section enum value specifying the type of results to display.

Returns:

The Table instance.

Subpackages

• simplebench.reporters.rich_table.reporter package
  • RichTableConfig
  • RichTableField
    • RichTableField.ELAPSED_SECONDS
    • RichTableField.ITERATIONS
    • RichTableField.MAX
    • RichTableField.MEAN
    • RichTableField.MEDIAN
    • RichTableField.MIN
    • RichTableField.N
    • RichTableField.P5
    • RichTableField.P95
    • RichTableField.ROUNDS
    • RichTableField.RSD_PERCENT
    • RichTableField.STD_DEV
  • RichTableOptions
    • RichTableOptions.fields
    • RichTableOptions.variation_cols_last
    • RichTableOptions.virtual_width
  • RichTableReporter
    • RichTableReporter.render()
  • Subpackages
    • simplebench.reporters.rich_table.reporter.options package
      • RichTableField
      • RichTableOptions
      • Submodules
  • Submodules
    • simplebench.reporters.rich_table.reporter.config module
      • RichTableConfig
    • simplebench.reporters.rich_table.reporter.exceptions module
    • simplebench.reporters.rich_table.reporter.reporter module
      • RichTableReporter