ait.core.util module

AIT Utilities

The ait.core.util module provides general utility functions.

exception ait.core.util.YAMLError(arg)

Bases: Exception

__init__(arg)

Initialize self. See help(type(self)) for accurate signature.

exception ait.core.util.YAMLValidationError(arg)

Bases: Exception

__init__(arg)

Initialize self. See help(type(self)) for accurate signature.

class ait.core.util.ObjectCache(filename, loader)

Bases: object

__init__(filename, loader)

Creates a new ObjectCache

Caches the Python object returned by loader(filename), using Python’s pickle object serialization mechanism. An ObjectCache is useful when loader(filename) is slow.

The result of loader(filename) is cached to cachename, the basename of filename with a ‘.pkl’ extension.

Use the load() method to load, either via loader(filename) or the pickled cache file, whichever was modified most recently.

load()

Loads the Python object

Loads the Python object, either via loader (filename) or the pickled cache file, whichever was modified most recently.

cachename

The pickled cache filename

dirty

True if the pickle cache needs to be regenerated, False to use current pickle binary

filename

The filename to cache via loader(filename)

class ait.core.util.TestFile(data, options)

Bases: object

TestFile is a Python Context Manager for quickly creating test data files that delete when a test completes, either successfully or unsuccessfully.

Example:

with TestFile(data) as filename:

# filename (likely something like ‘/var/tmp/tmp.1.uNqbVJ’) now # contains data. assert load(filename)

Whether the above assert passes or throws AssertionError, filename will be deleted.

__init__(data, options)

Creates a new TestFile and writes data to a temporary file.

Parameters:

data: text/binary

the data to be written to the temporary file

options: str

file operations for reading, writing, concatenating the temporary file

ait.core.util.check_yaml_timestamps(yaml_file_name, cache_name)

Checks YAML configuration file timestamp and any ‘included’ YAML configuration file’s timestamp against the pickle cache file timestamp. The term ‘dirty’ means that a yaml config file has a more recent timestamp than the pickle cache file. If a pickle cache file is found to be ‘dirty’ (return true) the pickle cache file is not up-to-date, and a new pickle cache file must be generated. If the cache file in not ‘dirty’ (return false) the existing pickle binary will be loaded.

param: yaml_file_name: str

Name of the yaml configuration file to be tested

param: cache_name: str

Filename with path to the cached pickle file for this config file.

return: boolean

True:

Indicates ‘dirty’ pickle cache: i.e. the file is not current, generate new binary

False

Load current cache file

ait.core.util.crc32File(filename, skip=0)

Computes the CRC-32 of the contents of filename, optionally skipping a certain number of bytes at the beginning of the file.

ait.core.util.endianSwapU16(bytes)

Swaps pairs of bytes (16-bit words) in the given bytearray.

ait.core.util.expandPath(pathname, prefix=None)

Return pathname as an absolute path, either expanded by the users home directory (“~”) or with prefix prepended.

ait.core.util.getDefaultDict(modname, config_key, loader, reload=False, filename=None)

Returns default AIT dictonary for modname

This helper function encapulates the core logic necessary to (re)load, cache (via util.ObjectCache), and return the default dictionary. For example, in ait.core.cmd:

def getDefaultDict(reload=False):

return ait.util.getDefaultDict(__name__, ‘cmddict’, CmdDict, reload)

ait.core.util.getFileSize(filename)

Returns the size of filename in bytes.

ait.core.util.listAllFiles(directory, suffix=None, abspath=False)

Returns the list of all files within the input directory and all subdirectories.

ait.core.util.setDictDefaults(d, defaults)

Sets all defaults for the given dictionary to those contained in a second defaults dictionary. This convenience method calls:

d.setdefault(key, value)

for each key and value in the given defaults dictionary.

ait.core.util.toBCD(n)

Converts the number n into Binary Coded Decimal.

ait.core.util.toFloat(str[, default]) → float | default

Converts the given string to a floating-point value. If the string could not be converted, default (None) is returned.

NOTE: This method is significantly more effecient than toNumber() as it only attempts to parse floating-point numbers, not integers or hexadecimal numbers.

Examples:

>>> f = toFloat("4.2")
>>> assert type(f) is float and f == 4.2

>>> f = toFloat("UNDEFINED", 999.9)
>>> assert type(f) is float and f == 999.9

>>> f = toFloat("Foo")
>>> assert f is None

ait.core.util.toNumber(str[, default]) → integer | float | default

Converts the given string to a numeric value. The string may be a hexadecimal, integer, or floating number. If string could not be converted, default (None) is returned.

Examples:

>>> n = toNumber("0x2A")
>>> assert type(n) is int and n == 42

>>> n = toNumber("42")
>>> assert type(n) is int and n == 42

>>> n = toNumber("42.0")
>>> assert type(n) is float and n == 42.0

>>> n = toNumber("Foo", 42)
>>> assert type(n) is int and n == 42

>>> n = toNumber("Foo")
>>> assert n is None

ait.core.util.toNumberOrStr(str) → integer | float | string

Converts the given string to a numeric value, if possible. Otherwise returns the input string

ait.core.util.toRepr(obj) → string

Converts the Python object to a string representation of the kind often returned by a class __repr__() method.

ait.core.util.toStringDuration(duration)

Returns a description of the given duration in the most appropriate units (e.g. seconds, ms, us, or ns).

ait.core.util.update_cache(yaml_file_name, cache_file_name, object_to_serialize)

Caches the result of loader (yaml_file_name) to pickle binary (cache_file_name), if the yaml config file has been modified since the last pickle cache was created, i.e. (the binary pickle cache is declared to be ‘dirty’ in ‘check_yaml_timestamps()’).

param: yaml_file_name: str

Name of the yaml configuration file to be serialized (‘pickled’)

param: cache_file_name: str

File name with path to the new serialized cached pickle file for this config file.:

param: object_to_serialize: object

Object to serialize (‘pickle’) e.g. instance of ‘ait.core.cmd.CmdDict’