spinn_utilities package¶
Subpackages¶
- spinn_utilities.citation package
- spinn_utilities.configs package
- spinn_utilities.make_tools package
- spinn_utilities.matrix package
- spinn_utilities.ranged package
- Submodules
- spinn_utilities.ranged.abstract_dict module
- spinn_utilities.ranged.abstract_list module
- spinn_utilities.ranged.abstract_sized module
- spinn_utilities.ranged.abstract_view module
- spinn_utilities.ranged.ids_view module
- spinn_utilities.ranged.multiple_values_exception module
- spinn_utilities.ranged.range_dictionary module
- spinn_utilities.ranged.ranged_list module
- spinn_utilities.ranged.single_view module
- spinn_utilities.ranged.slice_view module
- Module contents
- spinn_utilities.testing package
Submodules¶
spinn_utilities.abstract_base module¶
-
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 fromAbstractBase
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, ...): ...
-
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 fromAbstractBase
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): ...
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)
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
Returns: 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
Returns: The length of the bytesting and the hex values, comma separated
spinn_utilities.classproperty module¶
spinn_utilities.conf_loader module¶
-
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
Raises: spinn_utilities.configs.NoConfigFoundException – Always raised
-
spinn_utilities.conf_loader.
load_config
(filename, defaults, config_parsers=None, validation_cfg=None)[source]¶ Load the configuration.
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.
- validation_cfg (list(str)) – The list of files to read a validation configuration from. If omitted, no such validation is performed.
Returns: the fully-loaded and checked configuration
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 of 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 Returns: Nothing is returned Return type: None
-
binary_paths
¶
-
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 Returns: The full path of the discovered executable, or None
if no executable was found in the set of foldersReturn type: str
-
get_executable_paths
(executable_names)[source]¶ - Finds each executables within the set of folders.
The names are assumed to be comma seperated The set of folders is searched sequentially and the first match for each name is returned.
Names not found are ignored and not added to the list.
Parameters: executable_name (str) – The name of the executable to find. Assumed to be comma seperated. Returns: The full path of the discovered executable, or None
if no executable was found in the set of foldersReturn type: 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
Returns: 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
Returns: 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 module¶
-
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 – Regular expression string to match the suffix. Anchoring not required.
Returns: mapping from (shortened) name to class
Return type: dict(str -> class)
spinn_utilities.index_is_value module¶
spinn_utilities.log module¶
-
class
spinn_utilities.log.
ConfiguredFilter
(conf)[source]¶ Bases:
object
Allow a parent logger to filter a child logger.
-
class
spinn_utilities.log.
ConfiguredFormatter
(conf)[source]¶ Bases:
logging.Formatter
Defines the logging format for the SpiNNaker host software.
-
class
spinn_utilities.log.
FormatAdapter
(logger, extra=None)[source]¶ Bases:
logging.LoggerAdapter
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
-
critical
(msg, *args, **kwargs)[source]¶ Delegate a critical call to the underlying logger, after adding contextual information from this adapter instance.
-
debug
(msg, *args, **kwargs)[source]¶ Delegate a debug call to the underlying logger, after adding contextual information from this adapter instance.
-
error
(msg, *args, **kwargs)[source]¶ Delegate an error call to the underlying logger, after adding contextual information from this adapter instance.
-
exception
(msg, *args, **kwargs)[source]¶ Delegate an exception call to the underlying logger, after adding contextual information from this adapter instance.
-
info
(msg, *args, **kwargs)[source]¶ Delegate an info call to the underlying logger, after adding contextual information from this adapter instance.
-
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.
-
spinn_utilities.logger_utils module¶
spinn_utilities.ordered_default_dict module¶
spinn_utilities.ordered_set module¶
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 – 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 – Additional arguments taken by the subclass method over the superclass method, e.g., that are to be injected
- extend_defaults – Whether the subclass may specify extra defaults for the parameters
spinn_utilities.package_loader module¶
-
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 – path to check for python files
- prefix – package prefix top add to the file name
Returns: set of python package names
-
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 – name of the modules
- remove_pyc_files – True if
.pyc
files should be deleted - exclusions – a list of modules to exclude
- gather_errors – True if errors should be gathered, False to report on first error
Returns: 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 – path to check for python files
- prefix – package prefix top add to the file name
- remove_pyc_files – True if
.pyc
files should be deleted - exclusions – a list of modules to exclude
- gather_errors – True if errors should be gathered, False to report on first error
Returns: None
spinn_utilities.ping module¶
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]¶ Bases:
spinn_utilities.progress_bar.ProgressBar
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!'¶
-
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 – Flag to say if the bar should finish at the end of the collection
Returns: An iterable. Expected to be directly used in a for.
-
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.
Returns: The expression result, the type of which will depend on the expression itself and the operations exposed to it.
- 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
spinn_utilities.see module¶
-
class
spinn_utilities.see.
see
(documentation_method, extend_doc=True, additional_arguments=None, extend_defaults=False)[source]¶ Bases:
spinn_utilities.overrides.overrides
A decorator for indicating that the documentation of the method is provided by another method with exactly the same arguments. Note that this has the same effect as overrides in reality, but is provided to show that the method doesn’t actually override
spinn_utilities.socket_address module¶
-
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
-