simplebench.enums package

Public API for enums.

Enumarations used throughout SimpleBench.

Provides

• Color

• ExitCode

• FlagType

• Format

• Section

• Target

• Verbosity

• enum_docstrings()

class simplebench.enums.Color(value)

Bases: str, Enum

Colors for console output.

Defined Colors are:

• BLACK: Black color.

• RED: Red color.

• GREEN: Green color.

• YELLOW: Yellow color.

• BLUE: Blue color.

• MAGENTA: Magenta color.

• CYAN: Cyan color.

• WHITE: White color.

BLACK = 'black'

Black color.

BLUE = 'blue'

Blue color.

CYAN = 'cyan'

Cyan color.

GREEN = 'green'

Green color.

MAGENTA = 'magenta'

Magenta color.

RED = 'red'

Red color.

WHITE = 'white'

White color.

YELLOW = 'yellow'

Yellow color.

class simplebench.enums.ExitCode(value)

Bases: int, Enum

Exit codes for SimpleBench CLI.

Defined Exit Codes are:

• SUCCESS: Successful execution.

• RUNTIME_ERROR: General runtime error during execution.

• CLI_ARGUMENTS_ERROR: Error while processing command line arguments.

• KEYBOARD_INTERRUPT: Keyboard interrupt occurred.

• BENCHMARK_TIMED_OUT: Benchmark execution timed out.

BENCHMARK_ERROR = 5

An error occurred during benchmark execution.

BENCHMARK_TIMED_OUT = 4

Benchmark execution timed out.

CLI_ARGUMENTS_ERROR = 2

Error while processing command line arguments.

KEYBOARD_INTERRUPT = 3

Keyboard interrupt occurred.

RUNTIME_ERROR = 1

Runtime error during execution.

SUCCESS = 0

Successful execution.

class simplebench.enums.FlagType(value)

Bases: str, Enum

Types of command-line flags for reporters.

Available FlagTypes are:

• BOOLEAN: Boolean flag type.

• TARGET_LIST: List of output targets

• INVALID: Invalid flag type. This is a testing placeholder and should not be used.

BOOLEAN = 'boolean'

Boolean flag type.

This flag type represents a simple on/off or true/false option.

Example: –verbose / –no-verbose

INVALID = 'invalid'

Invalid flag type.

This is a testing placeholder and should not be used. It is included to test error handling for unsupported flag types.

TARGET_LIST = 'target_list'

List of output targets

This flag type represents a list of output targets for the reporter.

This allows specifying multiple targets for the reporter to output to.

The targets are specified as a list of strings and validated against the allowed Target enum values. It support passing NO targets as well, in which case the reporter will use the default targets.

Example: –json console filesystem callback

class simplebench.enums.Format(value)

Bases: str, Enum

Categories for different output formats.

Defined Formats are:

• PLAIN_TEXT: Plain text format.

• RICH_TEXT: Rich text format.

• CSV: CSV format.

• JSON: JSON format.

• GRAPH: Graphical format.

• CUSTOM: Custom format.

CSV = 'csv'

CSV format

CUSTOM = 'custom'

Custom format

GRAPH = 'graph'

Graphical format

JSON = 'json'

JSON format

PLAIN_TEXT = 'plain text'

Plain text format

RICH_TEXT = 'rich text'

Rich text format

class simplebench.enums.Section(value)

Bases: str, Enum

Categories for case results sections in reporters.

This is used by reporters to specify which sections of benchmark results to include in their output.

Defined Sections are:

• OPS: Operations per second section.

• TIMING: Time per round section.

• MEMORY: Memory usage section.

• PEAK_MEMORY: Peak memory usage section.

• NULL: No section. This is used when a reporter does not specify a section.

MEMORY = 'memory usage'

Memory usage section.

NULL = 'null section'

No section. This is used when a reporter does not specify a section.

OPS = 'operations per second'

Operations per second section.

PEAK_MEMORY = 'peak memory usage'

Peak memory usage section.

TIMING = 'per round timings'

Time per round section.

class simplebench.enums.Target(value)

Bases: str, Enum

Categories for different output targets.

The enums are used in generating calling parameters for the report() methods in the Reporter subclasses.

Defined Targets are:

• CONSOLE: Output to console.

• FILESYSTEM: Output to filesystem.

• CALLBACK: Pass generated output to a callback function.

• CUSTOM: Output to a custom target.

• NULL: No output.

CALLBACK = 'callback'

Pass generated output to a callback function.

CONSOLE = 'console'

Output to console.

CUSTOM = 'custom'

Output to a custom target.

FILESYSTEM = 'filesystem'

Output to filesystem.

INVALID = 'invalid'

Invalid target. This is a testing placeholder and should not be used.

NULL = 'null'

No output.

class simplebench.enums.Verbosity(value)

Bases: int, Enum

Verbosity level enums for console output.

Defined levels are:

• QUIET: Only requested output, errors, warnings and critical messages are shown.

• NORMAL: Normal messages are shown, including status displays during runs.

• VERBOSE: All messages are shown and status displays during runs.

• DEBUG: All messages are shown, including debug messages and status displays during runs.

DEBUG = 5

All messages are shown, including debug messages and status displays during runs.

This is incompatible with quiet.

NORMAL = 1

Normal messages are shown, including status displays during runs.

This is the default verbosity level and is incompatible with quiet.

QUIET = 0

Only requested output, errors, warnings and critical messages are shown. Status displays are not shown during runs.

This is incompatible with all other output levels.

VERBOSE = 2

All messages are shown and status displays during runs.

This is incompatible with quiet.

simplebench.enums.enum_docstrings(

enum: type[E],

) → type[E]

Attach docstrings to enum members.

Docstrings are string literals that appear directly below the enum member assignment expression within triple-quotes.

This decorator parses the source code of the enum class to find docstrings for each member and attaches them to the respective enum members.

This allows for more detailed documentation of enum members and in tools that can extract and display these docstrings.

This code is adapted from: https://stackoverflow.com/questions/19330460/how-do-i-put-docstrings-on-enums

Example usage of enum_docstrings decorator

@enum_docstrings
class SomeEnum(Enum):
    '''Docstring for the SomeEnum enum'''

    foo_member = "foo_value"
    '''Docstring for the foo_member enum member'''

SomeEnum.foo_member.__doc__  # 'Docstring for the foo_member enum member'

Parameters:

enum – The enum class to process.

Returns:

The same enum class with member docstrings attached.

Submodules

• simplebench.enums.color module
  • Color
    • Color.BLACK
    • Color.BLUE
    • Color.CYAN
    • Color.GREEN
    • Color.MAGENTA
    • Color.RED
    • Color.WHITE
    • Color.YELLOW
• simplebench.enums.decorators module
  • enum_docstrings()
• simplebench.enums.exit_code module
  • ExitCode
    • ExitCode.BENCHMARK_ERROR
    • ExitCode.BENCHMARK_TIMED_OUT
    • ExitCode.CLI_ARGUMENTS_ERROR
    • ExitCode.KEYBOARD_INTERRUPT
    • ExitCode.RUNTIME_ERROR
    • ExitCode.SUCCESS
• simplebench.enums.flag_type module
  • FlagType
    • FlagType.BOOLEAN
    • FlagType.INVALID
    • FlagType.TARGET_LIST
• simplebench.enums.format module
  • Format
    • Format.CSV
    • Format.CUSTOM
    • Format.GRAPH
    • Format.JSON
    • Format.PLAIN_TEXT
    • Format.RICH_TEXT
• simplebench.enums.section module
  • Section
    • Section.MEMORY
    • Section.NULL
    • Section.OPS
    • Section.PEAK_MEMORY
    • Section.TIMING
• simplebench.enums.target module
  • Target
    • Target.CALLBACK
    • Target.CONSOLE
    • Target.CUSTOM
    • Target.FILESYSTEM
    • Target.INVALID
    • Target.NULL
• simplebench.enums.verbosity module
  • Verbosity
    • Verbosity.DEBUG
    • Verbosity.NORMAL
    • Verbosity.QUIET
    • Verbosity.VERBOSE