# spinn_utilities package¶

## spinn_utilities.abstract_base module¶

A trimmed down version of standard Python Abstract Base classes.

If using @add_metaclass, this requires:

from six import add_metaclass


Using Python 3 style metaclass=AbstractBase is preferred.

class spinn_utilities.abstract_base.AbstractBase[source]

Bases: type

Metaclass for defining Abstract Base Classes (AbstractBases).

Use this metaclass to create an AbstractBase. An AbstractBase can be subclassed directly, and then acts as a mix-in class.

This is a trimmed down version of ABC. Unlike ABC you can not register unrelated concrete classes.

spinn_utilities.abstract_base.abstractmethod(funcobj)[source]

A decorator indicating abstract methods.

Requires that the metaclass is AbstractBase or derived from it. A class that has a metaclass derived from AbstractBase cannot be instantiated unless all of its abstract methods are overridden. The abstract methods can be called using any of the normal ‘super’ call mechanisms.

Usage:

@add_metaclass(AbstractBase)
class C:
@abstractmethod
def my_abstract_method(self, ...):
...

# Python 3 only syntax
class C3(object, metaclass=AbstractBase):
@abstractmethod
def my_abstract_method(self, ...):
...

class spinn_utilities.abstract_base.abstractproperty[source]

Bases: property

A decorator indicating abstract properties.

Requires that the metaclass is AbstractBase or derived from it. A class that has a metaclass derived from AbstractBase cannot be instantiated unless all of its abstract properties are overridden. The abstract properties can be called using any of the normal ‘super’ call mechanisms.

Usage:

@add_metaclass(AbstractBase)
class C:
@abstractproperty
def my_abstract_property(self):
...

# Python 3 only syntax
class C3(object, metaclass=AbstractBase):
@abstractproperty
def my_abstract_property(self):
...


This defines a read-only property; you can also define a read-write abstract property using the ‘long’ form of property declaration:

@add_metaclass(AbstractBase)
class C:
def getx(self): ...
def setx(self, value): ...
x = abstractproperty(getx, setx)

# Python 3 only syntax
class C3(object, metaclass=AbstractBase):
def getx(self): ...
def setx(self, value): ...
x = abstractproperty(getx, setx)


## spinn_utilities.abstract_context_manager module¶

class spinn_utilities.abstract_context_manager.AbstractContextManager[source]

Bases: object

Closeable class that supports being used as a simple context manager.

close()[source]

How to actually close the underlying resources.

## spinn_utilities.bytestring_utils module¶

spinn_utilities.bytestring_utils.as_hex(bytestring, start=None, end=None)[source]

Returns the bytestring as string showing the hex values

Parameters: bytestring – data as a byteString start – the inclusive start of the slice to return. May be None end – the exclusive end of the slice to return. May be None Comma separated hex values
spinn_utilities.bytestring_utils.as_string(bytestring, start=None, end=None)[source]

Returns the length and the hex values.

The length is always the full length irrespective of the start and end.

Parameters: bytestring – data as a bytestring start – the inclusive start of the slice to return. May be None end – the exclusive end of the slice to return. May be None The length of the bytesting and the hex values, comma separated

## spinn_utilities.classproperty module¶

class spinn_utilities.classproperty.ClassPropertyDescriptor(fget)[source]

Bases: object

A class to handle the management of class properties

spinn_utilities.classproperty.classproperty(func)[source]

Defines a property at the class-level

spinn_utilities.conf_loader.install_cfg_and_IOError(filename, defaults, config_locations)[source]

Installs a local configuration file based on the templates and raises an exception.

This method is called when no user configuration file is found.

It will create a file in the users home directory based on the defaults. Then it prints a helpful message and throws an error with the same message.

Parameters: filename (str) – Name under which to save the new configuration file defaults (list(str)) – List of full paths to the default configuration files. Each of which must have an associated template file with exactly the same path plus .template. config_locations (list(str)) – List of paths where the user configuration files were looked for. Only used for the message spinn_utilities.configs.NoConfigFoundException – Always raised
spinn_utilities.conf_loader.load_config(filename, defaults, config_parsers=None)[source]

Parameters: filename (str) – The base name of the configuration file(s). Should not include any path components. defaults (list(str)) – The list of files to get default configurations from. config_parsers (list(tuple(str, ConfigParser))) – The parsers to parse the sections of the configuration file with, as a list of (section name, parser); a configuration section will only be parsed if the section_name is found in the configuration files already loaded. The standard logging parser is appended to (a copy of) this list. the fully-loaded and checked configuration
spinn_utilities.conf_loader.logging_parser(config)[source]

Create the root logger with the given level.

Create filters based on logging levels

Note

You do not normally need to call this function; it is used automatically to parse Logging configuration sections.

## spinn_utilities.default_ordered_dict module¶

class spinn_utilities.default_ordered_dict.DefaultOrderedDict(default_factory=None, *args, **kwargs)[source]
copy() → a shallow copy of od[source]

## spinn_utilities.exceptions module¶

exception spinn_utilities.exceptions.FailedToFindBinaryException[source]

Raised when the executable finder cant find the binary

exception spinn_utilities.exceptions.SpiNNUtilsException[source]

Bases: Exception

Superclass of all exceptions from the SpiNNUtils module.

## spinn_utilities.executable_finder module¶

class spinn_utilities.executable_finder.ExecutableFinder(binary_search_paths)[source]

Bases: object

Manages a set of folders in which to search for binaries, and allows for binaries to be discovered within this path

Parameters: binary_search_paths (iterable(str)) – The initial set of folders to search for binaries.
add_path(path)[source]

Adds a path to the set of folders to be searched. The path is added to the end of the list, so it is searched after all the paths currently in the list.

Parameters: path (str) – The path to add
binary_paths

The set of folders to search for binaries, as a printable colon-separated string.

Return type: str
check_logs()[source]
clear_logs()[source]
get_executable_path(executable_name)[source]

Finds an executable within the set of folders. The set of folders is searched sequentially and the first match is returned.

Parameters: executable_name (str) – The name of the executable to find The full path of the discovered executable str KeyError – If no executable was found in the set of folders
get_executable_paths(executable_names)[source]

Finds each executables within the set of folders.

The names are assumed to be comma separated The set of folders is searched sequentially and the first match for each name is returned.

Parameters: executable_names (str) – The name of the executable to find. Assumed to be comma separated. The full path of the discovered executable, or None if no executable was found in the set of folders list(str)

## spinn_utilities.find_max_success module¶

spinn_utilities.find_max_success.find_max_success(max_possible, check)[source]

Finds the maximum value that will pass the check

Parameters: max_possible (int) – The maximum value that should be tested. check – A boolean function that given an int value returns true for every value up and including the cutoff and false for every value greater than the cutoff The highest value that returns true for the check but is not more than the max_possible
spinn_utilities.find_max_success.search_for_max_success(best_success, min_fail, check)[source]

Finds the maximun value in the range that pass the check

Parameters: best_success (int) – A minimum value that needs not be tested because it is either known to succeed or is a flag for total failure. Can be negative min_fail (int) – A maximum value that needs not be tested because it is either known to fail or one more than the maximum interesting value but must be greater than best_success but may also be negative check – A boolean function that given an int value returns true for every value up and including the cutoff and false for every value greater than the cutoff The highest value that returns true in the range between best_success and min_fail (both exclusive ends) or best_success if the whole range fails or is empty.

spinn_utilities.helpful_functions.gcd(*numbers)[source]

Greatest common divisor of 1 or more integers.

GIGO: If any of the values are anything except positive int values this function will either produce incorrect results or raise an exception.

Parameters: numbers – The Positive integers to get the GCD for. This can be one or more int values or a singleton which is an iterator (not empty) of ints. the gcd or 1 if numbers is empty or an empty iterator int TypeError – If any value can not be interpreted as an Integer or if no values are provided ZeroDivisionError – May be raised if one of the values is zero
spinn_utilities.helpful_functions.get_valid_components(module, terminator)[source]

Get possible components, stripping the given suffix from their class names.

Parameters: module – The module containing the classes to obtain. terminator (str) – Regular expression string to match the suffix. Anchoring not required. mapping from (shortened) name to class dict(str -> class)
spinn_utilities.helpful_functions.is_singleton(value)[source]

Tests whether the value is a singleton.

Singleton types are strings and any other class that can not be iterated.

Strings are considered singleton as rarely will someone use a String to represent an iterable of characters

spinn_utilities.helpful_functions.lcm(*numbers)[source]

Lowest common multiple of 0, 1 or more integers.

GIGO: If any of the values are anything except positive int values this function will either produce incorrect results or raise an exception.

Parameters: numbers – The Positive integers to get the lcm for. This can be zero, one or more int values or a singleton which is an iterator (possibly empty) of ints. the lcm or 1 if numbers is empty or an empty iterator int TypeError – If any value can not be interpreted as an Integer ZeroDivisionError – May be raised if one of the values is zero

## spinn_utilities.index_is_value module¶

class spinn_utilities.index_is_value.IndexIsValue[source]

Bases: object

Tiny support class that implements object[x] by just returning x itself.

Used for where you want a range from 1 to N but you don’t know N.

Clearly, operations that assume a finite list are not supported.

## spinn_utilities.log module¶

class spinn_utilities.log.ConfiguredFilter(conf)[source]

Bases: object

Allow a parent logger to filter a child logger.

filter(record)[source]

Get the level for the deepest parent, and filter appropriately.

class spinn_utilities.log.ConfiguredFormatter(conf)[source]

Defines the logging format for the SpiNNaker host software.

static construct_logging_parents(conf)[source]

Create a dictionary of module names and logging levels.

static deepest_parent(parents, child)[source]

Greediest match between child and parent.

static level_of_deepest_parent(parents, child)[source]

The logging level of the greediest match between child and parent.

class spinn_utilities.log.FormatAdapter(logger, extra=None)[source]

An adaptor for logging with messages that uses Python format strings.

Example:

log = FormatAdapter(logging.getLogger(__name__))
log.info("this message has {} inside {}", 123, 'itself')
# --> INFO: this message has 123 inside itself

log(level, msg, *args, **kwargs)[source]

Delegate a log call to the underlying logger, applying appropriate transformations to allow the log message to be written using Python format string, rather than via %-substitutions.

process(msg, kwargs)[source]

Process the logging message and keyword arguments passed in to a logging call to insert contextual information. You can either manipulate the message itself, the keyword arguments or both. Return the message and kwargs modified (or not) to suit your needs.

classmethod set_kill_level(level=None)[source]

Allow system to change the level at which a log is changed to an Exception

Static so effects all log messages

Parameters: level (int) – The level to set. The values in logging are recommended.
classmethod set_report_File(report_file)[source]
Parameters: report_file – write_normal –
exception spinn_utilities.log.LogLevelTooHighException[source]

Bases: Exception

An Exception throw when the System tries to log at a level where an Exception is a better option.

## spinn_utilities.logger_utils module¶

spinn_utilities.logger_utils.error_once(logger, msg)[source]
spinn_utilities.logger_utils.reset()[source]
spinn_utilities.logger_utils.warn_once(logger, msg)[source]

## spinn_utilities.ordered_set module¶

class spinn_utilities.ordered_set.OrderedSet(iterable=None)[source]
add(value)[source]

discard(value)[source]

Remove an element. Do not raise an exception if absent.

peek(last=True)[source]
pop(last=True)[source]

Return the popped value. Raise KeyError if empty.

update(iterable)[source]

## spinn_utilities.overrides module¶

class spinn_utilities.overrides.overrides(super_class_method, extend_doc=True, additional_arguments=None, extend_defaults=False)[source]

Bases: object

A decorator for indicating that a method overrides another method in a superclass. This checks that the method does actually exist, copies the doc-string for the method, and enforces that the method overridden is specified, making maintenance easier.

Parameters: super_class_method – The method to override in the superclass extend_doc (bool) – True the method doc string should be appended to the super-method doc string, False if the documentation should be set to the super-method doc string only if there isn’t a doc string already additional_arguments (iterable(str)) – Additional arguments taken by the subclass method over the superclass method, e.g., that are to be injected extend_defaults (bool) – Whether the subclass may specify extra defaults for the parameters
__call__(method)[source]

Apply the decorator to the given method.

spinn_utilities.package_loader.all_modules(directory, prefix, remove_pyc_files=False)[source]

List all the python files found in this directory giving then the prefix.

Any file that ends in either .py or .pyc is assume a python module and added to the result set.

Parameters: directory (str) – path to check for python files prefix (str) – package prefix top add to the file name set of python package names set(str)
spinn_utilities.package_loader.load_module(name, remove_pyc_files=False, exclusions=None, gather_errors=True)[source]

Loads this modules and all its children.

Parameters: name (str) – name of the modules remove_pyc_files (bool) – True if .pyc files should be deleted exclusions (list(str)) – a list of modules to exclude gather_errors (bool) – True if errors should be gathered, False to report on first error None
spinn_utilities.package_loader.load_modules(directory, prefix, remove_pyc_files=False, exclusions=None, gather_errors=True)[source]

Loads all the python files found in this directory, giving them the specified prefix

Any file that ends in either .py or .pyc is assume a python module and added to the result set.

Parameters: directory (str) – path to check for python files prefix (str) – package prefix top add to the file name remove_pyc_files (bool) – True if .pyc files should be deleted exclusions (list(str)) – a list of modules to exclude gather_errors (bool) – True if errors should be gathered, False to report on first error None

## spinn_utilities.ping module¶

class spinn_utilities.ping.Ping[source]

Bases: object

static host_is_reachable(ipaddr)[source]
static ping(ipaddr)[source]
unreachable = {}

## spinn_utilities.progress_bar module¶

class spinn_utilities.progress_bar.DummyProgressBar(total_number_of_things_to_do, string_describing_what_being_progressed, step_character='=', end_character='|')[source]

This is a dummy version of the progress bar that just stubs out the internal printing operations with code that does nothing. It otherwise fails in exactly the same way.

class spinn_utilities.progress_bar.ProgressBar(total_number_of_things_to_do, string_describing_what_being_progressed, step_character='=', end_character='|')[source]

Bases: object

Progress bar for telling the user where a task is up to

MAX_LENGTH_IN_CHARS = 60
TOO_MANY_ERROR = 'Too many update steps in progress bar! This may be a sign that something else has gone wrong!'
end()[source]

Close the progress bar, updating whatever is left if needed

Return type: None
over(collection, finish_at_end=True)[source]

Simple wrapper for the cases where the progress bar is being used to show progress through the iteration over a single collection. The progress bar should have been initialised to the size of the collection being iterated over.

Parameters: collection – The base collection (any iterable) being iterated over finish_at_end (bool) – Flag to say if the bar should finish at the end of the collection An iterable. Expected to be directly used in a for.
update(amount_to_add=1)[source]

Update the progress bar by a given amount

## spinn_utilities.require_subclass module¶

spinn_utilities.require_subclass.require_subclass(required_class)[source]

Decorator that arranges for subclasses of the decorated class to require that they are also subclasses of the given class.

Parameters: required_class (type) – The class that the subclass of the decorated class must be an instance of (if that subclass is concrete).

## spinn_utilities.safe_eval module¶

class spinn_utilities.safe_eval.SafeEval(*args, **kwargs)[source]

Bases: object

This provides expression evaluation capabilities while allowing the set of symbols exposed to the expression to be strictly controlled.

Sample of use:

>>> import math
>>> def evil_func(x):
...    print("HAHA!")
...    return x/0.0
...
>>> eval_safely = SafeEval(math)
>>> eval_safely.eval("math.sqrt(x)", x=1.23)
1.1090536506409416
>>> eval_safely.eval("evil_func(1.23)")
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File ".../safe_eval.py", line 62, in eval
return eval(expression, self._environment, kwargs)
File "<string>", line 1, in <module>
NameError: name 'evil_func' is not defined


Warning

This is not guaranteed to be safe under all circumstances. It is not designed to be a fully secured interface; it just discourages abuse.

Parameters: args – The symbols to use to populate the global reference table. Note that all of these symbols must support the __name__ property, but that includes any function, method of an object, or module. If you want to make an object available by anything other than its inherent name, define it in the eval() call. kwargs – Define the symbols with explicit names. Needed because some symbols (e.g., constants in numpy) do not have names that we can otherwise look up easily.
eval(expression, **kwargs)[source]

Evaluate an expression and return the result.

Parameters: expression (str) – The expression to evaluate kwargs – The extra symbol bindings to use for this evaluation. This is useful for passing in particular parameters to an individual evaluation run. The expression result, the type of which will depend on the expression itself and the operations exposed to it.

## spinn_utilities.see module¶

class spinn_utilities.see.see(documentation_method, extend_doc=True, additional_arguments=None, extend_defaults=False)[source]

A decorator for indicating that the documentation of the method is provided by another method with exactly the same arguments.

Note

This has the same effect as overrides in reality, but is provided to show that the method doesn’t actually override

class spinn_utilities.socket_address.SocketAddress(notify_host_name, notify_port_no, listen_port)[source]

Bases: object

Data holder for a socket interface for notification protocol.

listen_port

The port to listen to for responses

notify_host_name

The notify host name

notify_port_no

The notify port no

## spinn_utilities.timer module¶

class spinn_utilities.timer.Timer[source]

Bases: object

A timer used for performance measurements.

Recommended usage:

with Timer() as timer:
... do stuff that takes time ...

elapsed_time = timer.measured_interval


or alternatively:

timer = Timer()
timer.start_timing()
... do stuff that takes time ...
elapsed_time = timer.take_sample()


Mixing these two styles is not recommended.

measured_interval

Get how long elapsed during the measured section.

Return type: datetime.timedelta
start_timing()[source]

Start the timing. Use take_sample() to get the end.

take_sample()[source]

Describes how long has elapsed since the instance that the start_timing() method was last called.

Return type: datetime.timedelta