aspecd.utils module

General purpose functions and classes used in other modules.

To avoid circular dependencies, this module does not depend on any other modules of the ASpecD package, but it can be imported into every other module.

exception aspecd.utils.Error

Bases: Exception

Base class for exceptions in this module.

exception aspecd.utils.MissingFilenameError(message='')

Bases: aspecd.utils.Error

Exception raised when expecting a filename but none is provided

message

explanation of the error

Type

str

exception aspecd.utils.MissingDictError(message='')

Bases: aspecd.utils.Error

Exception raised when expecting a dict but none is provided

message

explanation of the error

Type

str

aspecd.utils.full_class_name(object_)

Return full class name of an object including packages and modules.

Parameters

object (object) – object the class name should be inferred for

Returns

class_name – string with full class name of object

Return type

str

aspecd.utils.object_from_class_name(full_class_name_string)

Create object from full class name.

To obtain the full class name of an object, you might want to use the function full_class_name()

Parameters

full_class_name_string (str) – string with full class name of an object that shall be instantiated

Returns

object_ – object instantiated from the class given in full_class_name_string

Return type

object

class aspecd.utils.ToDictMixin

Bases: object

Mixin class for returning all public attributes as dict.

__odict__

Dictionary of attributes preserving the order of their definition

Type

collections.OrderedDict

to_dict()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

aspecd.utils.get_aspecd_version()

Get version of ASpecD package.

The function directly reads the contents of the file VERSION in the root directory of the package installation, not relying on introspection.

Returns

version – Version number as string

Return type

str

aspecd.utils.package_version(name='')

Get version of arbitrary package.

The function relies on introspection using pkg_resources.

Parameters

name (str) – Name of package the version should be obtained for

Returns

version – Version number as string

Return type

str

aspecd.utils.package_name(obj=None)

Get name of package an object resides in.

Parameters

obj (object) –

Object the package it resides in should be returned.

If no object is given, the name of the package this function is defined in (“aspecd”) will be returned.

Returns

package_name – Name of the package

Return type

str

aspecd.utils.config_dir()

Get config directory for per-user configurations.

Configuration on a per-user level should be stored within a directory (only) readable by the currently logged-in user.

Returns

config_dir – Path to config directory, usually in the user’s directory

Return type

str

class aspecd.utils.Yaml

Bases: object

Handle reading from and writing to YAML files.

YAML file contents are read into an ordered dict, making use of the oyaml package. This preserves the order of the entries of any dict.

dict

Contents read from/written to a YAML file

Type

collections.OrderedDict

Raises

aspecd.utils.MissingFilenameError – Raised if no filename is given to read from/write to

read_from(filename='')

Read from YAML file.

Parameters

filename (str) – Name of the YAML file to read from.

Raises

aspecd.processing.MissingFilenameError – Raised if no filename is given to read from.

write_to(filename='')

Write to YAML file.

Parameters

filename (str) – Name of the YAML file to write to.

Raises

aspecd.processing.MissingFilenameError – Raised if no filename is given to write to.

aspecd.utils.replace_value_in_dict(replacement=None, target=None)

Replace value for given key in a dictionary, traversing recursively.

The key in replacement needs to correspond to the value in target_dict that should be replaced. Keys inthe dict replacement that have no corresponding value in target_dict are silently ignored.

Parameters
  • replacement (dict) – dict containing key corresponding to the value in target_dict that should be replaced by the associated value

  • target (dict) – dict containing the key whose value should be replaced by the value of the key in replacement named identical to the value

Returns

target – dict containing the key whose value has been replaced by the value of the corresponding key in replacement

Return type

dict

aspecd.utils.copy_values_between_dicts(source=None, target=None)

Copy values between two dicts in case of identical keys.

Each value in source is copied to target in case of matching keys in a recursive manner. Non-matching keys in source are silently ignored.

Parameters
  • source (dict) – Dictionary the values should be copied from in case of matching keys

  • target (dict) – Dictionary the values should be copied to in case of matching keys

Returns

target – Dictionary the values have been copied to in case of matching keys

Return type

dict

aspecd.utils.copy_keys_between_dicts(source=None, target=None)

Copy keys between two dicts.

Each key in source is copied to target in a recursive manner. If the key in source is a dict and exists in target, the two dicts will be joined, not loosing keys in target.

Parameters
  • source (dict) – Dictionary the keys should be copied from

  • target (dict) – Dictionary the keys should be copied to

Returns

target – Dictionary the keys have been copied to

Return type

dict

aspecd.utils.all_equal(list_=None)

Check whether all elements of a list are equal.

Parameters

list (list) – List whose elements should be checked for being equal

Returns

result

Return type

boolean

class aspecd.utils.Properties

Bases: aspecd.utils.ToDictMixin

General properties class allowing to set properties from dict.

Properties classes often need to set their properties from dicts, and additionally, they should be able to convert themselves into dicts for persistence.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters

dict (dict) – Dictionary containing information of a task.

Raises

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns

properties – public properties

Return type

list