bencher.utils

Attributes

_current_job_key

_gen_path_counter

AGG_FN_MAP

UNSET

Classes

_Unset

Sentinel for distinguishing 'not provided' from 'explicitly passed the default'.

Functions

hmap_canonical_input(→ tuple)

From a dictionary of kwargs, return a hashable representation (tuple) that is always the same for the same inputs and retains the order of the input arguments. e.g, {x=1,y=2} -> (1,2) and {y=2,x=1} -> (1,2). This is used so that keywords arguments can be hashed and converted the the tuple keys that are used for holomaps

make_namedtuple(→ collections.namedtuple)

Convenience method for making a named tuple

get_nearest_coords(→ dict)

Find the nearest coordinates in an xarray dataset based on provided coordinate values.

get_nearest_coords1D(→ Any)

Find the closest coordinate to a given value in a list of coordinates.

hash_sha1(→ str)

A hash function that avoids the PYTHONHASHSEED 'feature' which returns a different hash value each time the program is run.

capitalise_words(→ str)

Given a string of lowercase words, capitalise them.

un_camel(→ str)

Given a snake_case string return a CamelCase string

mult_tuple(→ tuple[float, Ellipsis])

Multiply each element in a tuple by a scalar value.

tabs_in_markdown(→ str)

Given a string with tabs in the form convert the to   which is a double space in markdown

int_to_col(→ tuple[float, float, float] | tuple[float, ...)

Uses the golden angle to generate colors programmatically with minimum overlap between colors.

lerp(→ float)

Linear interpolation between two ranges.

color_tuple_to_css(→ str)

Convert a RGB color tuple to CSS rgb format string.

color_tuple_to_255(→ tuple[int, int, int])

Convert a RGB color tuple with values in range [0.0, 1.0] to values in range [0, 255].

gen_path(→ str)

Generate a path for a file in the cache directory.

gen_video_path(→ str)

Generate a unique path for a video file in the cache directory.

gen_image_path(→ str)

Generate a unique path for an image file in the cache directory.

gen_rerun_data_path(→ str)

Generate a unique path for a rerun data file in the cache directory.

resolve_aggregate(→ list[str] | None)

Resolve the aggregate convenience parameter into a list of dimension names.

callable_name(→ str)

Extract the name of a callable object, handling various callable types.

listify(→ list[Any] | None)

Convert an object to a list if it's not already a list.

get_name(→ str)

Extract the name from a variable, handling param.Parameter objects.

params_to_str(→ list[str])

Convert a list of param.Parameter objects to a list of their names.

publish_file(→ str)

Publish a file to an orphan git branch:

normalize_subsampling_divisions_kwargs(→ tuple[int, ...)

Translate deprecated level/max_level kwargs to subsampling_divisions/max_subsampling_divisions.

github_content(remote, branch_name, filename)

Module Contents

bencher.utils.hmap_canonical_input(dic: dict) → tuple

From a dictionary of kwargs, return a hashable representation (tuple) that is always the same for the same inputs and retains the order of the input arguments. e.g, {x=1,y=2} -> (1,2) and {y=2,x=1} -> (1,2). This is used so that keywords arguments can be hashed and converted the the tuple keys that are used for holomaps

Parameters:

dic (dict) – dictionary with keyword arguments and values in any order

Returns:

values of the dictionary always in the same order and hashable

Return type:

tuple

bencher.utils.make_namedtuple(class_name: str, **fields) → collections.namedtuple

Convenience method for making a named tuple

Parameters:

class_name (str) – name of the named tuple

Returns:

a named tuple with the fields as values

Return type:

namedtuple

bencher.utils.get_nearest_coords(dataset: xarray.Dataset, collapse_list: bool = False, **kwargs) → dict

Find the nearest coordinates in an xarray dataset based on provided coordinate values.

Given an xarray dataset and kwargs of key-value pairs of coordinate values, return a dictionary of the nearest coordinate name-value pair that was found in the dataset.

Parameters:

  • dataset (xr.Dataset) – The xarray dataset to search in

  • collapse_list (bool, optional) – If True, when a coordinate value is a list, only the first item is returned. Defaults to False.

  • **kwargs – Key-value pairs where keys are coordinate names and values are points to find the nearest match for

Returns:

Dictionary of coordinate name-value pairs with the nearest values found in the dataset

Return type:

dict

bencher.utils.get_nearest_coords1D(val: Any, coords: list[Any]) → Any

Find the closest coordinate to a given value in a list of coordinates.

For numeric values, finds the value in coords that is closest to val. For non-numeric values, returns the exact match if found, otherwise returns val.

Parameters:

  • val (Any) – The value to find the closest coordinate for

  • coords (list[Any]) – The list of coordinates to search in

Returns:

The closest coordinate value from the list

Return type:

Any

bencher.utils.hash_sha1(var: Any) → str

A hash function that avoids the PYTHONHASHSEED ‘feature’ which returns a different hash value each time the program is run.

Converts input to a consistent SHA1 hash string.

Parameters:

var (Any) – The variable to hash

Returns:

A hexadecimal SHA1 hash of the string representation of the variable

Return type:

str

bencher.utils.capitalise_words(message: str) → str

Given a string of lowercase words, capitalise them.

Parameters:

message (str) – lower case string

Returns:

capitalised string where each word starts with an uppercase letter

Return type:

str

bencher.utils.un_camel(camel: str) → str

Given a snake_case string return a CamelCase string

Parameters:

camel (str) – camelcase string

Returns:

uncamelcased string

Return type:

str

bencher.utils.mult_tuple(inp: tuple[float, Ellipsis], val: float) → tuple[float, Ellipsis]

Multiply each element in a tuple by a scalar value.

Parameters:

  • inp (tuple[float, ...]) – The input tuple of floats to multiply

  • val (float) – The scalar value to multiply each element by

Returns:

A new tuple with each element multiplied by val

Return type:

tuple[float, …]

bencher.utils.tabs_in_markdown(regular_str: str, spaces: int = 2) → str

Given a string with tabs in the form convert the to   which is a double space in markdown

Parameters:

  • regular_str (str) – A string with tabs in it

  • spaces (int) – the number of spaces per tab

Returns:

A string with sets of   to represent the tabs in markdown

Return type:

str

bencher.utils.int_to_col(int_val: int, sat: float = 0.5, val: float = 0.95, alpha: float = -1) → tuple[float, float, float] | tuple[float, float, float, float]

Uses the golden angle to generate colors programmatically with minimum overlap between colors. https://martin.ankerl.com/2009/12/09/how-to-create-random-colors-programmatically/

Parameters:

  • int_val (int) – index of an object you want to color, this is mapped to hue in HSV

  • sat (float, optional) – saturation in HSV. Defaults to 0.5.

  • val (float, optional) – value in HSV. Defaults to 0.95.

  • alpha (float, optional) – transparency. If -1 then only RGB is returned, if 0 or greater, RGBA is returned. Defaults to -1.

Returns:

either RGB or RGBA vector

Return type:

tuple[float, float, float] | tuple[float, float, float, float]

bencher.utils.lerp(value: float, input_low: float, input_high: float, output_low: float, output_high: float) → float

Linear interpolation between two ranges.

Maps a value from one range [input_low, input_high] to another range [output_low, output_high].

Parameters:

  • value (float) – The input value to interpolate

  • input_low (float) – The lower bound of the input range

  • input_high (float) – The upper bound of the input range

  • output_low (float) – The lower bound of the output range

  • output_high (float) – The upper bound of the output range

Returns:

The interpolated value in the output range

Return type:

float

bencher.utils.color_tuple_to_css(color: tuple[float, float, float]) → str

Convert a RGB color tuple to CSS rgb format string.

Parameters:

color (tuple[float, float, float]) – RGB color tuple with values in range [0.0, 1.0]

Returns:

CSS color string in format ‘rgb(r, g, b)’ with values in range [0, 255]

Return type:

str

bencher.utils.color_tuple_to_255(color: tuple[float, float, float]) → tuple[int, int, int]

Convert a RGB color tuple with values in range [0.0, 1.0] to values in range [0, 255].

Parameters:

color (tuple[float, float, float]) – RGB color tuple with values in range [0.0, 1.0]

Returns:

RGB color tuple with values clamped to range [0, 255]

Return type:

tuple[int, int, int]

bencher.utils._current_job_key: contextvars.ContextVar[str | None]
bencher.utils._gen_path_counter: contextvars.ContextVar[dict | None]
bencher.utils.gen_path(filename: str, folder: str = 'generic', suffix: str = '.dat') → str

Generate a path for a file in the cache directory.

When called inside a benchmark sweep, files are placed in a per-job-key subdirectory so that cache overwrites can cleanly delete old media. Outside a sweep, falls back to UUID-based naming.

Parameters:

  • filename (str) – Base name for the file

  • folder (str, optional) – Subfolder within cachedir. Defaults to “generic”.

  • suffix (str, optional) – File extension. Defaults to “.dat”.

Returns:

Absolute path to a file location

Return type:

str

bencher.utils.gen_video_path(video_name: str = 'vid', extension: str = '.mp4') → str

Generate a unique path for a video file in the cache directory.

Parameters:

  • video_name (str, optional) – Base name for the video file. Defaults to “vid”.

  • extension (str, optional) – Video file extension. Defaults to “.mp4”.

Returns:

Absolute path to a unique video file location

Return type:

str

bencher.utils.gen_image_path(image_name: str = 'img', filetype: str = '.png') → str

Generate a unique path for an image file in the cache directory.

Parameters:

  • image_name (str, optional) – Base name for the image file. Defaults to “img”.

  • filetype (str, optional) – Image file extension. Defaults to “.png”.

Returns:

Absolute path to a unique image file location

Return type:

str

bencher.utils.gen_rerun_data_path(rrd_name: str = 'rrd', filetype: str = '.rrd') → str

Generate a unique path for a rerun data file in the cache directory.

Parameters:

  • rrd_name (str, optional) – Base name for the rerun data file. Defaults to “rrd”.

  • filetype (str, optional) – File extension. Defaults to “.rrd”.

Returns:

Absolute path to a unique rerun data file location

Return type:

str

bencher.utils.resolve_aggregate(aggregate: bool | int | list[str] | None, input_var_names: list[str] | None = None) → list[str] | None

Resolve the aggregate convenience parameter into a list of dimension names.

Parameters:

  • aggregate –

    Aggregation specification. - None / False: no aggregation - True: aggregate all but the first input dim, collapsing data

    to 1-D (the minimum for meaningful plots). With 0 or 1 input vars there is nothing to aggregate and None is returned.

    • int N: aggregate last N input dims (requires input_var_names)

    • list[str]: aggregate exactly these dims (validated only when input_var_names is provided)

  • input_var_names – Names of input variables (in order). When None, list[str] values pass through without validation and True/int raise ValueError (no context to resolve against).

Returns:

List of dimension names to aggregate over, or None.

Raises:

  • ValueError – If int is out of range, list contains unknown names, or True/int used without input_var_names.

  • TypeError – If aggregate is an unsupported type.

bencher.utils.AGG_FN_MAP: dict[str, Callable]
bencher.utils.callable_name(any_callable: Callable[Ellipsis, Any]) → str

Extract the name of a callable object, handling various callable types.

This function attempts to extract the name of a callable object, including regular functions, partial functions, and other callables.

Parameters:

any_callable (Callable[..., Any]) – The callable object to get the name from

Returns:

The name of the callable

Return type:

str

bencher.utils.listify(obj: Any) → list[Any] | None

Convert an object to a list if it’s not already a list.

This function handles conversion of various object types to lists, with special handling for None values and existing list/tuple types.

Parameters:

obj (Any) – The object to convert to a list

Returns:

A list containing the object, the object itself if it was

already a list, a list from the tuple if it was a tuple, or None if the input was None

Return type:

list[Any] | None

bencher.utils.get_name(var: Any) → str

Extract the name from a variable, handling param.Parameter objects.

Parameters:

var (Any) – The variable to extract the name from

Returns:

The name of the variable

Return type:

str

bencher.utils.params_to_str(param_list: list[param.Parameter]) → list[str]

Convert a list of param.Parameter objects to a list of their names.

Parameters:

param_list (list[param.Parameter]) – List of parameter objects

Returns:

List of parameter names

Return type:

list[str]

bencher.utils.publish_file(filepath: str, remote: str, branch_name: str) → str

Publish a file to an orphan git branch:

def publish_args(branch_name) -> tuple[str, str]:
    return (
        "https://github.com/blooop/bencher.git",
        f"https://github.com/blooop/bencher/blob/{branch_name}")
Parameters:

remote (Callable) – A function the returns a tuple of the publishing urls. It must follow the signature def publish_args(branch_name) -> tuple[str, str]. The first url is the git repo name, the second url needs to match the format for viewable html pages on your git provider. The second url can use the argument branch_name to point to the file on a specified branch.

Returns:

the url of the published file

Return type:

str

class bencher.utils._Unset

Sentinel for distinguishing ‘not provided’ from ‘explicitly passed the default’.

_instance = None
__repr__()
__bool__()
bencher.utils.UNSET
bencher.utils.normalize_subsampling_divisions_kwargs(*, subsampling_divisions: int | _Unset, max_subsampling_divisions: int | None, kwargs: dict[str, Any], default_subsampling_divisions: int = 2, stacklevel: int = 2) → tuple[int, int | None, bool]

Translate deprecated level/max_level kwargs to subsampling_divisions/max_subsampling_divisions.

subsampling_divisions should be passed as UNSET when the caller did not provide it, so that run(subsampling_divisions=2, level=3) correctly raises TypeError instead of silently preferring level.

Returns (subsampling_divisions, max_subsampling_divisions, subsampling_divisions_was_set) where subsampling_divisions_was_set is True when the caller explicitly provided subsampling_divisions or level.

Raises TypeError when old and new names are both provided.

bencher.utils.github_content(remote: str, branch_name: str, filename: str)