hansken.util — Utilities for internal and external use

hansken.util contains a number of utility methods and classes that hansken.py uses internally for various reasons. hansken.py’s internals are no secret, however, so feel free to use these wherever they fit.

class GeographicLocation(latitude, longitude)

Bases: GeographicLocation

Describes a 2-tuple (latitude, longitude) to translate location data to and from Hansken’s wire format.

classmethod from_string(value)

Parses a string value into a GeographicLocation.

Parameters:

value – a string-representation to be parsed

Returns:

a value of type cls, parsed from value

class Vector(data)

Bases: Sequence

Describes a sequence of floating point numbers to translate vector data to and from Hansken’s wire format.

classmethod from_base64(value)

Creates a Vector from value, assuming it will be base64-encoded sequence of big-endian 4-byte IEEE-754 floating points.

Parameters:

value – a base64-representation to be parsed

Returns:

a new Vector

classmethod from_sequence(seq)

Creates a Vector from seq, assuming it will be a sequence of elements compatible with the f struct format character.

Parameters:

seq – a sequence of float

Returns:

a new Vector

The Vector class primarily deals with serialization from and to Hansken’s wire format for a vector of floating points. A Vector will act as if it’s a sequence of float objects. Should a user algorithm dealing with vector data require something like a numpy array, a Vector object can be turned into a numpy array as such:

# vector obtained from trace metadata
vector = ...
# either directly coerce it
# note that this converts all elements into python float objects first
np_vector = np.array(vector)
# or create the numpy array by wrapping the underlying data
# note that the endianness and data size is critical here (> for big-endian, f4 for float32)
np_vector = np.frombuffer(bytes(vector), dtype=np.dtype('>f4'))

flatten_mapping(mapping, separator='.', prefix=None)

Flattens mapping into a single level dict by concatenating nested keys.

Parameters:

• mapping – the mapping to be flattened

• separator – separator to be used to concatenate nested keys

• prefix – prefix for all keys in the nested result (typically only useful for recursive calls)

Returns:

mapping, flattened into a single level dict

format_byte_size(size, template='{value:.4g} {unit}')

Converts a byte size into a human-readable format using binary suffixes.

Parameters:

• size – the value to be formatted

• template – a format string with two named parameters: value and unit

Returns:

a human-readable file size

Dealing with Base64

Python’s standard library is capable of encoding or decoding Base64, but the b64encode and b64decode functions don’t always play nice with differences between str and bytes. hansken.util’s versions make sure a Base64 string is a str at runtime and the decoded variant is a bytes.

b64encode(s)

Encodes bytes to a str using default Base64 encoding.

Parameters:

s – bytes

Returns:

s, Base64-encoded

Return type:

str

b64decode(s, validate=False)

Decode a Base64-encoded string.

Parameters:

• s – the string to decode

• validate – validate the input against the Base64 alphabet

Returns:

decoded byte string

Return type:

bytes

Raises:

TypeError – when an invalid character is found

Naming converters

As hansken.py reads from services that communicate in ways common to environments that are not Python, hansken.py applies naming conversions in some places to present an API that looks and feels like Python. To accomplish this, a set of name converters is available going back and forth between different naming conventions.

to_property_name(name)

Converts a name to a property name by convention (camelCase) by converting snake_case to snakeCase.

Parameters:

name – name to convert

Returns:

name converted to a property name

to_attr_name(name)

Converts a name to an attribute name by convention (snake_case) by converting camelCase to camel_case.

Parameters:

name – name to convert

Returns:

name converted to a attribute name

to_class_name(name)

Converts a name to a class name by convention (PascalCase) by converting snake_case to SnakeCase.

Parameters:

name – name to convert

Returns:

name converted to a class name