simplebench.utils package🔗

Utility functions for simplebench.

class simplebench.utils.MachineInfo[source]🔗

Bases: TypedDict

TypedDict for machine info returned by get_machine_info().

Variables:

processor (str) – Processor name.
machine (str) – Machine type.
python_compiler (str) – Python compiler used.
python_implementation (str) – Python implementation name.
python_implementation_version (str) – Python implementation version.
python_version (str) – Python version.
python_build (tuple[str, str]) – Python build information.
release (str) – Operating system release.
system (str) – Operating system name.
cpu (dict[str, str]) – CPU information.

cpu: dict[str, str]🔗

machine: str🔗

processor: str🔗

python_build: tuple[str, str]🔗

python_compiler: str🔗

python_implementation: str🔗

python_implementation_version: str🔗

python_version: str🔗

release: str🔗

system: str🔗

simplebench.utils.arg_to_flag(arg: str) → str[source]🔗

Convert a Python argument name to a command-line flag.

This function takes a Python argument name (e.g., ‘my_flag’) and converts it to a command-line flag (e.g., ‘–my-flag’) by adding leading dashes and replacing underscores with hyphens.

Parameters:

arg (str) – The Python argument name to convert.

Raises:

SimpleBenchTypeError – If the arg argument is not a str.
SimpleBenchValueError – If the arg argument is an empty string.

Returns:

The corresponding command-line flag.

Return type:

str

simplebench.utils.collect_arg_list( *, args: Namespace, flag: str, ) → list[str][source]🔗

Collects a list of argument values from a Namespace for a given flag.

This function retrieves the values associated with the specified flag from the provided Namespace object. If the value is a sequence (excluding str and bytes), it returns the values as a list. If the value is a single item, it returns a list containing that single item. If the flag does not exist in the Namespace, it returns an empty list.

argparse lists consist of lists of lists of strings and so they have to be flattened to be processed.

Parameters:

args (Namespace) – The Namespace object containing argument values.
flag (str) – The command-line flag whose value is to be collected.

Raises:

SimpleBenchTypeError – If the args argument is not a Namespace or if the retrieved argument value is of an unexpected type.

Returns:

A list of unique argument values associated with the specified flag.

Return type:

list[str]

simplebench.utils.flag_to_arg(flag: str) → str[source]🔗

Convert a command-line flag to a valid Python argument name.

This function takes a command-line flag (e.g., ‘–my-flag’) and converts it to a valid Python argument name (e.g., ‘my_flag’) as expected in a Namespace result by removing leading dashes and replacing hyphens with underscores.

Parameters:

flag (str) – The command-line flag to convert.

Raises:

SimpleBenchTypeError – If the flag arg is not a str.
SimpleBenchValueError – If the flag arg is an empty string or does not start with ‘–‘.

Returns:

The corresponding Python argument name.

Return type:

str

simplebench.utils.get_machine_info() → MachineInfo[source]🔗: Return a dictionary of information about the current machine and Python version.

simplebench.utils.kwargs_variations( kwargs: dict[str, Sequence[Any]], ) → list[dict[str, Any]][source]🔗

Variations of keyword arguments for the benchmark.

This function takes a dictionary where each key is a keyword argument name and the value is a Sequence of possible values for that argument. It returns a list of dictionaries, each dictionary representing a unique combination of keyword arguments and their values.

Example:

kwargs_variations({
    'arg1': [1, 2],
    'arg2': ['a', 'b']
})
# output:
# [
#     {'arg1': 1, 'arg2': 'a'},
#     {'arg1': 1, 'arg2': 'b'},
#     {'arg1': 2, 'arg2': 'a'},
#     {'arg1': 2, 'arg2': 'b'}
# ]

Parameters:: kwargs (dict[str, Sequence[Any]]) – A dictionary of keyword arguments and their possible values. The value must be a Sequence (e.g., list, tuple, set), but not a str or bytes instance.
Returns:: A list of dictionaries, each representing a unique combination of keyword arguments and values.
Return type:: list[dict[str, Any]]

simplebench.utils.platform_architecture() → str[source]🔗

Return the current architecture.

Returns:: The architecture.
Return type:: str

simplebench.utils.platform_id() → str[source]🔗

Return a string that uniquely identifies the current machine and Python version.

The platform ID is a lowercase string that combines the operating system, Python implementation, Python version, and architecture.

Returns:: The platform ID.
Return type:: str

simplebench.utils.platform_implementation() → str[source]🔗

Return the current Python implementation name.

See platform.python_implementation() for details.

Returns:: The Python implementation name.
Return type:: str

simplebench.utils.platform_machine() → str[source]🔗

Return the current machine type.

Returns:: The machine type.
Return type:: str

simplebench.utils.platform_processor() → str[source]🔗

Return the current processor name.

Returns:: The processor name.
Return type:: str

simplebench.utils.platform_system() → str[source]🔗

Return the current operating system name.

Returns:: The operating system name.
Return type:: str

simplebench.utils.platform_version() → str[source]🔗

Return the current Python version.

Returns:: The Python version.
Return type:: str

simplebench.utils.python_implementation_version() → str[source]🔗

Return the Python implementation version.

For CPython, this is the same as platform.python_version(). For PyPy, this is the PyPy version (e.g., ‘7.3.5’).

Returns:: The Python implementation version.
Return type:: str

simplebench.utils.sanitize_filename(name: str) → str[source]🔗

Sanitizes a filename by replacing invalid characters with _ (underline).

Only a-z, A-Z, 0-9, _ (underline), and - (dash) characters are allowed. All other characters are replaced with _ and multiple sequential _ characters are then collapsed to single _ characters. Leading and trailing _ and - characters are removed.

Examples:

sanitize_filename("My File-Name.txt")  # returns "My_File-Name_txt"
sanitize_filename("Invalid/Chars\In:Name*?")  # returns "Invalid_Chars_In_Name"
sanitize_filename("   Leading and Trailing   ")  # returns "Leading_and_Trailing"
sanitize_filename("!!!")  # returns "_"

Note

This function does not check for reserved filenames on any operating system.

It is the caller’s responsibility to ensure the sanitized filename is valid for the target filesystem.

If a filename becomes completely empty after sanitization, the function will return a single underscore (‘_’) character. This is the one exception to the rule that leading and trailing _ and - characters are removed.

Parameters:

name (str) – The filename to sanitize.

Returns:

The sanitized filename.

Return type:

str

Raises:

SimpleBenchTypeError – If the name arg is not a str.
SimpleBenchValueError – If the name arg is an empty string.

simplebench.utils.sigfigs(number: float, figures: int = 3) → float[source]🔗

Rounds a floating point number to the specified number of significant figures.

If the number of significant figures is not specified, it defaults to DEFAULT_SIGNIFICANT_FIGURES.

14.2 to 2 digits of significant figures becomes 14
0.234 to 2 digits of significant figures becomes 0.23
0.0234 to 2 digits of significant figures becomes 0.023
14.5 to 2 digits of significant figures becomes 15
0.235 to 2 digits of significant figures becomes 0.24

Parameters:

number (float) – The number to round.
figures (int) – The number of significant figures to round to.

Raises:

TypeError – If the number arg is not a float or the figures arg is not an int.
ValueError – If the figures arg is not at least 1.

Returns:

The rounded number as a float.

Return type:

float

simplebench.utils package🔗

Submodules🔗