Utilities

grafanarmadillo.types

Type hints for Grafana interaction.

class grafanarmadillo.types.AlertSearchResult(*args, **kwargs)

Relevant keys returned for an alert.

class grafanarmadillo.types.AnySearchResult(*args, **kwargs)

Metadata for both Grafana dashboards and alerts.

class grafanarmadillo.types.Dashboard(*args, **kwargs)

Relevant keys returned by GET of a Grafana dashboard.

class grafanarmadillo.types.DashboardSearchResult(*args, **kwargs)

Relevant keys returned by a Grafana search.

class grafanarmadillo.types.GrafanaPath(name: str, folder: str, org: str | None = None)

Path of an object in Grafana.

grafanarmadillo.paths

Tools for manipulating path-like objects into references to Grafana objects or file-safe paths.

class grafanarmadillo.paths.PathCodec

Safely encode paths which may contain invalid characters, such as forward slashes.

static decode(path: Path) → List[str]

Decode a path to segments.

static decode_segment(segment: str) → str

Decode a single segment.

static encode(segments: List[str]) → Path

Encode segments to a path.

static encode_grafana(path: GrafanaPath) → Path

Encode a GrafanaPath.

static encode_segment(segment: str) → str

Encode a single segment.

static parse_grafana(parts: Sequence[str]) → GrafanaPath

Assemble segments into an orderly GrafanaPath.

static try_parse(o: GrafanaPath | str | Path | List[str]) → GrafanaPath

Try to decode a pathlike object.

grafanarmadillo.util

Helpers and generic functions.

class grafanarmadillo.util.Cache

Cache values.

get(k)

Get a cached value, if it exists.

getor(k, f: Callable[[], T]) → T

Get a cached item or generate it.

set(k, v)

Set a cached value.

unset(k)

Unset a cached value.

unset_method(k_start)

Unset all keys whose first subkey (the method name) matches.

class grafanarmadillo.util.CacheMode(value)

Caching mode for interacting with Grafana.

None: no caching Session: lifetime of the Finder object Global: all Finders share the same cache

You can disable caching globally by setting grafanarmadillo.util.global_cache = grafanarmadillo.util.NoneCache()

static select(cache_mode: CacheMode | Cache) → Cache

Create or use a cache. Pass a cache to reuse it.

class grafanarmadillo.util.NoneCache

A Cache-interface-compatible which never caches.

get(k)

Never caches a value.

getor(k, f: Callable[[], T]) → T

Always generate the cached item.

set(k, v)

Never caches a value.

unset(k)

No keys are ever set.

grafanarmadillo.util.erase_alert_rule_identity(alertlike) → Dict

Delete the fields of an alert_rule which are used for determining identity.

grafanarmadillo.util.erase_dashboard_identity(dashboardlike: DashboardSearchResult | DashboardContent) → Dict

Delete the fields of a dashboard which are used for determining identity.

grafanarmadillo.util.exactly_one(items: List[A], message: str | None = None) → A

Throws if list does not contain exactly 1 item.

>>> exactly_one([1])
1

>>> exactly_one([1,2])
Traceback (most recent call last):
ValueError: expected exactly 1 item, found=2 message=None

>>> exactly_one([])
Traceback (most recent call last):
ValueError: expected exactly 1 item, found=0 message=None

grafanarmadillo.util.flat_map(f, xs)

Flatmap: Map on a list and then merge the results.

>>> and_reversed = lambda s: [s,s[::-1]]

>>> flat_map(and_reversed, [])
[]

>>> flat_map(and_reversed, ['hi'])
['hi', 'ih']

>>> flat_map(and_reversed, ['hi', 'hello'])
['hi', 'ih', 'hello', 'olleh']

grafanarmadillo.util.load_data(data_str: str)

Attempt to load data.

grafanarmadillo.util.map_json_strings(f: Callable[[str], str], obj: JSON) → JSON

Transform all strings in an object made of JSON primitives.

>>> f = lambda s: s.upper()
>>> map_json_strings(f, 's')
'S'
>>> map_json_strings(f, 1)
1
>>> map_json_strings(f, ['s'])
['S']
>>> map_json_strings(f, ['s', 1])
['S', 1]
>>> map_json_strings(f, {'a': 's'})
{'a': 'S'}
>>> map_json_strings(f, {'a': ['s', 1]})
{'a': ['S', 1]}

grafanarmadillo.util.project_dashboard_identity(dashboardlike: DashboardSearchResult | DashboardContent) → Dict

Project only the fields of a dashboard which are used for determining identity.

grafanarmadillo.util.project_dict(d: Dict, keys: set, inverse: bool = False) → Dict

Select the given fields from a dictionary.

>>> project_dict({'a': 1, 'b': 2}, {'a'})
{'a': 1}

>>> project_dict({'a': 1, 'b': 2}, {'a'}, inverse=True)
{'b': 2}

grafanarmadillo.util.read_from_file(file_path: Path) → dict

Read JSON from a file.

grafanarmadillo.util.resolve_filepath_to_object(base_path: Path, path: Path) → GrafanaPath

Extract the “/folder/object” format from the file on disk that contains the template.

grafanarmadillo.util.resolve_object_to_filepath(base_path: Path, name: GrafanaPath | str | Path | List[str])

Transform the “/folder/object” format to the path on disk that contains the template.

grafanarmadillo.util.write_to_file(out_path: Path, obj: dict)

Write an object to file as JSON.