4.7.5.6. Utilities

Utilities and tools.

axonius_api_client.tools.type_str(value, max_len=60, join=', ')[source]

Pass.

Parameters
Return type

typing.Union[str, typing.List[str]]

axonius_api_client.tools.pathify(path, path_strict=True, path_encoding='utf-8', resolve=True, expanduser=True, as_file=False, as_dir=False, exts=None)[source]

Convert a str into a fully resolved & expanded Path object.

Parameters
Return type

pathlib.Path

axonius_api_client.tools.is_existing_file(path, **kwargs)[source]

Check if the supplied value refers to an existing file.

Parameters

path (typing.Any) –

Return type

bool

axonius_api_client.tools.listify(obj=None, split=False, split_max=-1, split_sep=re.compile(','), strip=True, strip_chars=None, encoding='utf-8', errors='replace', dictkeys=False, **kwargs)[source]

Force an object into a list.

Notes

  • list: returns as is

  • tuple: convert to list

  • None: returns as an empty list

  • any of axonius_api_client.constants.general.SIMPLE: return as a list of obj

  • dict: if dictkeys is True, return as list of keys of obj, otherwise return as a list of obj

Parameters
Return type

list

axonius_api_client.tools.grouper(iterable, n, fillvalue=None)[source]

Split an iterable into chunks.

Parameters
Return type

typing.Iterator

axonius_api_client.tools.coerce_int(obj, max_value=None, min_value=None, allow_none=False, valid_values=None, errmsg=None)[source]

Convert an object into int.

Parameters
Raises

ToolsError – if obj is not able to be converted to int

Return type

int

axonius_api_client.tools.coerce_int_float(value, as_float=False, error=True, ret_value=False)[source]

Coerce a value into int or float.

Parameters
  • value (t.Union[int, float, str, bytes]) – value to coerce

  • as_float (bool, optional) – if value is an integer, coerce to float

  • error (bool) –

  • ret_value (bool) –

Returns

float or int if value is int, float, int as str, or float as str; else None

Return type

t.Optional[t.Union[int, float]]

axonius_api_client.tools.coerce_bool(obj, errmsg=None, error=True)[source]

Convert an object into bool.

Parameters
Raises

ToolsError – obj is not able to be converted to bool

Return type

bool

axonius_api_client.tools.is_str(value, not_empty=True)[source]

Check if value is non empty string.

Parameters
Return type

bool

axonius_api_client.tools.is_email(value)[source]

Check if a value is a valid email.

Parameters

value (typing.Any) –

Return type

bool

axonius_api_client.tools.is_int(obj, digit=False)[source]

Check if obj is int typeable.

Parameters
  • obj (typing.Any) – object to check

  • digit (bool) – allow checking str/bytes

Return type

bool

axonius_api_client.tools.join_url(url, *parts)[source]

Join a URL to any number of parts.

Parameters
  • url (str) – str to add parts to

  • *parts – str(s) to append to url

Return type

str

axonius_api_client.tools.strip_right(obj, fix)[source]

Strip text from the right side of obj.

Parameters
Return type

typing.Union[typing.List[str], str]

axonius_api_client.tools.strip_left(obj, fix)[source]

Strip text from the left side of obj.

Parameters
Return type

typing.Union[typing.List[str], str]

class axonius_api_client.tools.AxJSONEncoder(*args, **kwargs)[source]

Bases: JSONEncoder

Pass.

__init__(*args, **kwargs)[source]

Pass.

default(obj)[source]

Pass.

encode(o)

Return a JSON string representation of a Python data structure.

>>> from json.encoder import JSONEncoder
>>> JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'
item_separator = ', '
iterencode(o, _one_shot=False)

Encode the given object and yield each string representation as available.

For example:

for chunk in JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)
key_separator = ': '
axonius_api_client.tools.has_to_dict(obj)[source]

Pass.

Parameters

obj (typing.Any) –

Return type

bool

axonius_api_client.tools.json_dump(obj, indent=2, sort_keys=False, error=True, fallback=<class 'str'>, to_dict=True, cls=<class 'axonius_api_client.tools.AxJSONEncoder'>, **kwargs)[source]

Serialize an object into json str.

Parameters
Return type

typing.Any

axonius_api_client.tools.lens(value)[source]

Pass.

Parameters

value (typing.Any) –

Return type

typing.Optional[int]

axonius_api_client.tools.tlens(value)[source]

Pass.

Parameters

value (typing.Any) –

Return type

typing.Optional[int]

axonius_api_client.tools.json_load(obj, error=True, load_file=True, close_fh=True, **kwargs)[source]

Deserialize a json str into an object.

Parameters
Return type

typing.Any

axonius_api_client.tools.is_file_like(value)[source]

Pass.

Parameters

value (typing.Any) –

Return type

bool

axonius_api_client.tools.csv_load(value, encoding='utf-8-sig', restkey='extra_columns', close_fh=True, **kwargs)[source]

Pass.

Parameters
Return type

csv.DictReader

axonius_api_client.tools.jsonl_loader(item, idx, error=True, **kwargs)[source]

Pass.

Parameters
Return type

typing.Any

axonius_api_client.tools.jsonl_load(obj, error=True, close_fh=True, **kwargs)[source]

Deserialize a jsonl str into an object.

Parameters
Return type

typing.List[typing.Any]

axonius_api_client.tools.json_log(obj, error=False, trim=100, trim_lines=True, trim_msg='\\nTrimmed {value_len} {trim_type} down to {trim}', **kwargs)[source]

Pass.

Parameters
Return type

str

axonius_api_client.tools.json_reload(obj, error=False, trim=None, trim_lines=False, trim_msg='\\nTrimmed {value_len} {trim_type} down to {trim}', **kwargs)[source]

Re-serialize a json str into a pretty json str.

Parameters
Return type

str

axonius_api_client.tools.text_load(value, close_fh=True)[source]

Pass.

Parameters
Return type

typing.Generator[str, None, None]

axonius_api_client.tools.dt_parse(obj, default_tz_utc=False)[source]

Parse a str, datetime, or timedelta into a datetime object.

Notes

Parameters
Return type

datetime.datetime

axonius_api_client.tools.dt_parse_tmpl(obj, tmpl='%Y-%m-%d')[source]

Parse a string into the format used by the REST API.

Parameters
Return type

str

axonius_api_client.tools.dt_now(delta=None, tz=tzutc())[source]

Get the current datetime in for a specific tz.

Parameters
Return type

datetime.datetime

axonius_api_client.tools.dt_now_file(fmt='%Y-%m-%dT%H-%M-%S', **kwargs)[source]

Pass.

Parameters

fmt (str) –

axonius_api_client.tools.dt_sec_ago(obj, exact=False)[source]

Get number of seconds ago a given datetime was.

Parameters
Return type

int

axonius_api_client.tools.dt_min_ago(obj)[source]

Get number of minutes ago a given datetime was.

Parameters

obj (typing.Union[str, datetime.timedelta, datetime.datetime]) – parsed by dt_sec_ago() into seconds ago

Return type

int

axonius_api_client.tools.dt_days_left(obj)[source]

Get number of days left until a given datetime.

Parameters

obj (typing.Union[str, datetime.timedelta, datetime.datetime, None]) – parsed by dt_sec_ago() into days left

Return type

typing.Optional[int]

axonius_api_client.tools.dt_within_min(obj, n=None)[source]

Check if given datetime is within the past n minutes.

Parameters
Return type

bool

axonius_api_client.tools.get_path(obj)[source]

Convert a str into a fully resolved & expanded Path object.

Parameters

obj (typing.TypeVar(PathLike, pathlib.Path, str, bytes)) – obj to convert into expanded and resolved absolute Path obj

Return type

pathlib.Path

axonius_api_client.tools.path_read(obj, binary=False, is_json=False, **kwargs)[source]

Read data from a file.

Notes

  • if path filename ends with “.json”, data will be deserialized using json_load()

Parameters
Raises

ToolsError – path does not exist as file

Return type

typing.Union[bytes, str]

axonius_api_client.tools.get_backup_filename(path)[source]

Pass.

Parameters

path (typing.TypeVar(PathLike, pathlib.Path, str, bytes)) –

Return type

str

axonius_api_client.tools.get_backup_path(path)[source]

Pass.

Parameters

path (typing.TypeVar(PathLike, pathlib.Path, str, bytes)) –

Return type

pathlib.Path

axonius_api_client.tools.check_path_is_not_dir(path)[source]

Pass.

Parameters

path (typing.TypeVar(PathLike, pathlib.Path, str, bytes)) –

Return type

pathlib.Path

axonius_api_client.tools.path_create_parent_dir(path, make_parent=True, protect_parent=448)[source]

Pass.

Parameters
Return type

pathlib.Path

axonius_api_client.tools.path_backup_file(path, backup_path=None, make_parent=True, protect_parent=448, **kwargs)[source]

Pass.

Parameters
Return type

pathlib.Path

axonius_api_client.tools.auto_suffix(path, data, error=False, **kwargs)[source]

Pass.

Parameters
Return type

typing.Union[bytes, str]

axonius_api_client.tools.path_write(obj, data, overwrite=False, backup=False, backup_path=None, binary=False, binary_encoding='utf-8', is_json=False, make_parent=True, protect_file=384, protect_parent=448, suffix_auto=True, **kwargs)[source]

Write data to a file.

Notes

  • if obj filename ends with “.json”, serializes data using json_dump().

Parameters
Raises
  • ToolsError – path exists as file and overwrite is False

  • ToolsError – if parent path does not exist and make_parent is False

Return type

typing.Tuple[pathlib.Path, typing.Tuple[int, typing.Optional[pathlib.Path]]]

axonius_api_client.tools.longest_str(obj)[source]

Determine the length of the longest string in a list of strings.

Parameters

obj (typing.List[str]) – list of strings to calculate length of

Return type

int

axonius_api_client.tools.split_str(obj, split=',', strip=None, do_strip=True, lower=True, empty=False)[source]

Split a string or list of strings into a list of strings.

Parameters
  • obj (typing.Union[typing.List[str], str]) – string or list of strings to split

  • split (str) – character to split on

  • strip (typing.Optional[str]) – characters to strip

  • do_strip (bool) – strip each item from the split

  • lower (bool) – lowercase each item from the split

  • empty (bool) – remove empty items post split

Return type

typing.List[str]

axonius_api_client.tools.echo_debug(msg, **kwargs)[source]

Echo a message to console.

Parameters
  • msg (str) – message to echo

  • kwargs – passed to echo

axonius_api_client.tools.echo_ok(msg, **kwargs)[source]

Echo a message to console.

Parameters
  • msg (str) – message to echo

  • kwargs – passed to echo

axonius_api_client.tools.echo_warn(msg, **kwargs)[source]

Echo a warning message to console.

Parameters
  • msg (str) – message to echo

  • kwargs – passed to echo

axonius_api_client.tools.echo_error(msg, abort=True, **kwargs)[source]

Echo an error message to console.

Parameters
  • msg (str) – message to echo

  • abort – call sys.exit(1) after echoing message

  • kwargs – passed to echo

axonius_api_client.tools.echo(msg=None, abort=False, tmpl=True, log=None, log_level='debug', log_method=None, log_args=None, log_fallback=<bound method Logger.debug of <Logger axonius_api_client.tools (DEBUG)>>, style_tmpl=None, style_args=None, joiner='\\n', do_log=True, do_echo=True, abort_code=0, **kwargs)[source]

Pass.

Parameters
axonius_api_client.tools.sysinfo()[source]

Gather system information.

Return type

dict

axonius_api_client.tools.calc_percent(part, whole, places=2)[source]

Calculate the percentage of part out of whole.

Parameters
Return type

float

axonius_api_client.tools.trim_float(value, places=2)[source]

Trim a float to N places.

Parameters
  • value (float) – float to trim

  • places (int) – decimal places to trim value to

Return type

float

axonius_api_client.tools.join_kv(obj, listjoin=', ', tmpl='{k}: {v!r}')[source]

Join a dictionary into key value strings.

Parameters
  • obj (typing.Union[typing.List[dict], dict]) – dict or list of dicts to stringify

  • listjoin (str) – string to use for joining

  • tmpl (str) – template to format key value pairs of dict

Return type

typing.List[str]

axonius_api_client.tools.get_type_str(obj)[source]

Get the type name of a class.

Parameters

obj (typing.Any) – class or tuple of classes to get type name(s) of

axonius_api_client.tools.check_type(value, exp, name='', exp_items=None)[source]

Check that a value is the appropriate type.

Parameters
  • value (typing.Any) – value to check type of

  • exp (typing.Any) – type(s) that value should be

  • name (str) – identifier of what value is for

  • exp_items (typing.Optional[typing.Any]) – if value is a list, type(s) that list items should be

axonius_api_client.tools.check_empty(value, name='')[source]

Check if a value is empty.

Parameters
  • value (typing.Any) – value to check type of

  • name (str) – identifier of what value is for

axonius_api_client.tools.get_raw_version(value)[source]

Caclulate the raw bits of a version str.

Parameters

value (str) – version to calculate

Return type

str

axonius_api_client.tools.coerce_str_to_csv(value, coerce_list=False, errmsg=None)[source]

Coerce a string into a list of strings.

Parameters
Return type

typing.List[str]

axonius_api_client.tools.parse_ip_address(value)[source]

Parse a string into an IP address.

Parameters

value (str) – ip address

Return type

typing.Union[ipaddress.IPv4Address, ipaddress.IPv6Address]

axonius_api_client.tools.parse_ip_network(value)[source]

Parse a string into an IP network.

Parameters

value (str) – ip network

Return type

typing.Union[ipaddress.IPv4Network, ipaddress.IPv6Network]

axonius_api_client.tools.kv_dump(obj)[source]

Get a string representation of a dictionaries key value pairs.

Parameters

obj (dict) – dictionary to get string of

Return type

str

axonius_api_client.tools.bom_strip(content, strip=True, bom=b'\\xef\\xbb\\xbf')[source]

Remove the UTF-8 BOM marker from the beginning of a string.

Parameters
  • content (typing.Union[str, bytes]) – string to remove BOM marker from if found

  • strip – remove whitespace before & after removing BOM marker

  • bom (bytes) –

Return type

str

axonius_api_client.tools.read_stream(stream)[source]

Try to read input from a stream.

Parameters

stream – stdin or a file descriptor to read input from

Return type

str

axonius_api_client.tools.check_gui_page_size(size=None)[source]

Check page size to see if it one of the valid GUI page sizes.

Parameters

size (typing.Optional[int]) – page size to check

Raises

ApiError – if size is not one of axonius_api_client.constants.api.GUI_PAGE_SIZES

Return type

int

axonius_api_client.tools.calc_gb(value, places=2, is_kb=True)[source]

Convert bytes into GB.

Parameters
  • value (typing.Union[str, int]) – bytes

  • places (int) – decimal places to trim value to

  • is_kb (bool) – values are in kb or bytes

Return type

float

axonius_api_client.tools.calc_perc_gb(obj, whole_key, part_key, perc_key=None, places=2, update=True, is_kb=True)[source]

Calculate the GB and percent from a dict.

Parameters
  • obj (dict) – dict to get whole_key and part_key from

  • whole_key (str) – key to get whole value from and convert to GB and set as whole_key_gb

  • part_key (str) – key to get part value from and convert to GB and set as part_key_gb

  • perc_key (typing.Optional[str]) – key to set percent in

  • is_kb (bool) – values are in kb or bytes

  • places (int) –

  • update (bool) –

Return type

dict

axonius_api_client.tools.get_subcls(cls, excludes=None)[source]

Get all subclasses of a class.

Parameters
Return type

list

axonius_api_client.tools.prettify_obj(obj, indent=0)[source]

Pass.

Parameters
Return type

typing.List[str]

axonius_api_client.tools.token_parse(obj)[source]

Pass.

Parameters

obj (str) –

Return type

str

axonius_api_client.tools.combo_dicts(*args, **kwargs)[source]

Pass.

Return type

dict

axonius_api_client.tools.is_url(value)[source]

Pass.

Parameters

value (str) –

Return type

bool

axonius_api_client.tools.bytes_to_str(value, encoding='utf-8', errors='replace')[source]

Convert value to str if value is bytes.

Parameters
  • value (t.Any) – value to convert to str

  • encoding (str, optional) – encoding to use

  • errors (str, optional) – how to handle errors

Returns

str if value is bytes, else orginal value

Return type

t.Any

axonius_api_client.tools.strip_str(value)[source]

Strip a value if it is a string.

Parameters

value (typing.Any) –

Return type

typing.Union[str, typing.Any]

axonius_api_client.tools.coerce_str(value, strip=True, none='', trim=None, trim_lines=False, trim_msg='\\nTrimmed {value_len} {trim_type} down to {trim}')[source]

Coerce a value to a string.

Parameters
Return type

typing.Union[str, typing.Any]

axonius_api_client.tools.str_trim(value, trim=None, trim_lines=False, trim_msg='\\nTrimmed {value_len} {trim_type} down to {trim}')[source]

Pass.

Parameters
Return type

str

axonius_api_client.tools.get_cls_path(value)[source]

Pass.

Parameters

value (typing.Any) –

Return type

str

axonius_api_client.tools.csv_writer(rows, columns=None, quotes='nonnumeric', dialect='excel', line_ending='\\n', stream=None, key_extra_error=False, key_missing_value=None)[source]

Pass.

Parameters
Return type

str

axonius_api_client.tools.parse_int_min_max(value, default=0, min_value=None, max_value=None)[source]

Pass.

axonius_api_client.tools.safe_replace(obj, value)[source]

Pass.

Parameters
Return type

str

axonius_api_client.tools.safe_format(value, mapping=None, as_path=False, **kwargs)[source]

Pass.

Parameters
Return type

typing.TypeVar(PathLike, pathlib.Path, str, bytes)

axonius_api_client.tools.get_paths_format(*args, mapping=None)[source]

Pass.

Parameters

mapping (typing.Optional[typing.Dict[str, str]]) –

Return type

typing.Optional[pathlib.Path]

axonius_api_client.tools.int_days_map(value, names=False)[source]

Pass.

Parameters
Return type

typing.List[str]

axonius_api_client.tools.lowish(value)[source]

Pass.

Parameters

value (typing.Any) –

Return type

typing.Any

axonius_api_client.tools.log_or_exc(msg, error=True, log=<Logger axonius_api_client.tools (DEBUG)>, log_level='exception', log_join='\\n', exc_cls=<class 'axonius_api_client.exceptions.ToolsError'>, exc_args=None, **kwargs)[source]

Pass.

Parameters
axonius_api_client.tools.coerce_io(value)[source]

Pass.

Parameters

value (typing.Union[str, bytes, typing.IO]) –

Return type

typing.IO

axonius_api_client.tools.is_json_dict(value)[source]

Pass.

Return type

bool

axonius_api_client.tools.extract_kvs_auto(value, **kwargs)[source]

Pass.

Parameters

value (typing.Union[str, bytes, typing.IO]) –

Return type

dict

axonius_api_client.tools.trype(value)[source]

Pass.

axonius_api_client.tools.extract_kvs_json(value, **kwargs)[source]

Pass.

Parameters

value (typing.Union[str, bytes, typing.IO]) –

Return type

dict

axonius_api_client.tools.is_callable(value, attr=None, default=None)[source]

Pass.

Parameters
Return type

bool

axonius_api_client.tools.extract_kvs_csv(value=None, has_headers=False, split_kv='=', delimiter=',', **kwargs)[source]

Pass.

Parameters
Return type

dict

axonius_api_client.tools.tilde_re(value)[source]

Pass.

Parameters

value (typing.Any) –

Return type

typing.Union[str, typing.Pattern, None]

axonius_api_client.tools.coerce_str_re(value, prefix='~')[source]

Convert a str into a pattern if value is str and starts with prefix.

Parameters
  • value (t.Any) – value to convert to pattern

  • prefix (str, optional) – prefix to use to indicate value should be converted to a pattern

Returns

t.Pattern if value is str or bytes and starts with prefix, else original value

Return type

t.Any

axonius_api_client.tools.human_size(value, decimals=2, error=True)[source]

Convert bytes to human readable.

Parameters
  • value (t.Union[int, str, bytes, float]) – value to coerce into int/float

  • decimals (int, optional) – number of decimal places to include in str output

  • error (bool) –

Returns

human readable size of value if value is int, float, int as str, or float as str

else empty str

Return type

str

axonius_api_client.tools.is_pattern(value)[source]

Check if value is a pattern.

Parameters

value (t.Any) – value to check

Returns

True if value is a re.Pattern; else False

Return type

bool

axonius_api_client.tools.is_tty(value)[source]

Pass.

Parameters

value (typing.Any) –

Return type

bool

axonius_api_client.tools.check_tty(value, errmsg='unable to prompt')[source]

Pass.

Parameters
axonius_api_client.tools.check_tty_stdin()[source]

Pass.

axonius_api_client.tools.get_secho_args(kwargs=None, key=None, **sargs)[source]

Pass.

Parameters
axonius_api_client.tools.confirm(msgs=None, text=None, abort=False, default=False, text_confirm='Please confirm', join='\\n', check_stdin=True, **kwargs)[source]

Pass.

Parameters
axonius_api_client.tools.coerce_prompt_confirm(value=None, prompt=False, **kwargs)[source]

Pass.

Parameters
Return type

bool

axonius_api_client.tools.check_confirm_prompt(reason, src, msgs=None, value=None, prompt=False, **kwargs)[source]

Pass.

Parameters
axonius_api_client.tools.csv_able(value, sep=',')[source]

Pass.

Parameters
Return type

typing.List[str]

axonius_api_client.tools.is_list(value)[source]

Pass.

Parameters

value (typing.Any) –

Return type

bool

axonius_api_client.tools.style_switch(text, switch=False, args_true={'bold': True, 'fg': 'green'}, args_false={'bold': True, 'fg': 'red'})[source]

Pass.

Parameters
  • text (str) –

  • switch (bool) –

  • args_true (dict) –

  • args_false (str) –

axonius_api_client.tools.add_source(source, kwargs)[source]

Pass.

Parameters
  • source (str) –

  • kwargs (dict) –

Return type

str

axonius_api_client.tools.parse_value_copy(default, value=None, copy_prefix='Copy of', existing=None)[source]

Pass.

Parameters
Return type

str