spinn_utilities.ranged package¶

Submodules¶

spinn_utilities.ranged.ids_view module¶

spinn_utilities.ranged.single_view module¶

spinn_utilities.ranged.slice_view module¶

Module contents¶

An implementation of a dictionary and a list that support efficiently working with ranges of values, used to implement efficient collections for PyNN population views and assemblies.

class spinn_utilities.ranged.AbstractDict[source]¶

Bases: Generic[T]

Base class for the RangeDictionary and all views. This allows the users to not have to worry if they have a view.

abstractmethod get_default(key: str) → T | None[source]¶

Gets the default value for a single key. Unless changed, the default is the original value.

Note

Does not change any values but only changes what reset_value would do

Parameters:: key (str) – Existing dict key
Returns:: default for this key.

Lists the ranges(s) for all IDs covered by this view. There will be one yield for each range which may cover one or more IDs.

Note

As the data is created in a single call this is not affected by any updates.

Parameters:: key (str or iterable(str) or None) – The key or keys to get the value of. Use None for all
Returns:: List of tuples of (start, stop, value). start is inclusive so is the first ID in the range. stop is exclusive so is the last ID in the range + 1. If key is a str, value is a single object. If key is iterable (list, tuple, set, etc.) of str (or None) value is a dictionary object

Gets a single shared value for all IDs covered by this view.

Parameters:: key (str or iterable(str) or None) – The key or keys to get the value of. Use None for all
Returns:: If key is a str, this returns the single object. If key is iterable (list, tuple, set, etc.) of str (or None), returns a dictionary object
Raises:: MultipleValuesException – If even one of the keys has multiple values set. But not if other keys not asked for have multiple values

has_key(key: str) → bool[source]¶

As the Deprecated dict has_keys function.

Note

Int keys to IDs are not supported.

Parameters:: key (str) – the key
Returns:: If the key is in dict
Return type:: bool

abstractmethod ids() → Sequence[int][source]¶

Returns the IDs in range or view. If the view is setup with IDs out of numerical order the order used to create the view is maintained.

Note

If indexing into a view, you are picking the Nth ID. So if the IDs are [2,3,4,5] the view[2] will be the data for ID 4 and not 2

Returns:: list of IDs
Return type:: list(int)

items() → Sequence[Tuple[str, T]][source]¶

Returns a list of (key, value) tuples. Works only if the whole ranges/view has single values.

If the key is a str, the values are single objects. If the key is iterable (list, tuple, set, etc.) of str (or None), the values are dictionary objects.

Returns:: List of (key, value) tuples
Return type:: list(tuple)
Raises:: MultipleValuesException – If even one of the keys has multiple values set.

Iterates over the value(s) for all IDs covered by this view. There will be one yield for each ID even if values are repeated.

Parameters:

key (str or iterable(str) or None) – The key or keys to get the value of. Use None for all keys
update_safe – If set True the iteration will work even if values are updated during iteration. If left False the iterator may be faster but behaviour is undefined and unchecked if any values are changed during iteration.

Returns:

If key is a str, this yields single objects. If key is iterable (list, tuple, set, etc.) of str (or None), yields dictionary objects

Iterates over the ranges(s) for all IDs covered by this view. There will be one yield for each range which may cover one or more IDs.

Warning

This iterator is not update safe! Behaviour is undefined and unchecked if any values are changed during iteration.

Parameters:: key (str or iterable(str) or None) – The key or keys to get the value of. Use None for all
Returns:: yields tuples of (start, stop, value). start is inclusive so is the first ID in the range. stop is exclusive so is the last ID in the range + 1. If key is a str, value is a single object. If key is iterable (list, tuple, set, etc.) of str (or None), value is a dictionary object

iteritems() → Iterator[Tuple[str, T]][source]¶

Iterates over the (key, value) tuples. Works only if the whole ranges/view has single values.

If the key is a str, the values are single objects. If the key is iterable (list, tuple, set, etc.) of str (or None), the values are dictionary objects

This function is safe for value updates but may miss new keys added during iteration.

Returns:: yield (key, value) tuples
Return type:: iterable(tuple)
Raises:: MultipleValuesException – If even one of the keys has multiple values set.

itervalues() → Iterator[T][source]¶

Iterates over the values. Works only if the whole ranges/view has single values.

If a key is a str, its value is a single object. If a key is an iterable (list, tuple, set, etc.) of str (or None), its value is a dictionary object.

This function is safe for value updates but may miss new keys added during iteration.

Returns:: yield values
Raises:: MultipleValuesException – If even one of the keys has multiple values set.

abstractmethod keys() → Iterable[str][source]¶

Returns the keys in the dictionary

Returns:: keys in the dict

reset(key: str) → None[source]¶

Sets the value(s) for a single key back to the default value.

Parameters:

key (str) – Existing dict key
default – Value to be used by reset

abstractmethod set_value(key: str, value: T, use_list_as_value: bool = False) → None[source]¶

Sets a already existing key to the new value. All IDs in the whole range or view will have this key set.

Warning

This method does not allow adding keys. Using dict[str] = will add a new key, but it is not supported for views.

Warning

If a View is created over multiple ranges this method would raise a KeyError if any the ranges does not have the key. (Currently multiple ranges not yet supported.)

Parameters:

key (str) – key to value being set
value – any object
use_list_as_value – True if the value is a list

Raises:

KeyError – If a new key is being used.

values() → Sequence[T][source]¶

Returns a list of values. Works only if the whole ranges/view has single values.

If a key is a str, its value is a single object. If a key is an iterable (list, tuple, set, etc.) of str (or None), its value is a dictionary object.

Returns:: List of values
Raises:: MultipleValuesException – If even one of the keys has multiple values set.

class spinn_utilities.ranged.AbstractList(size: int, key: str | None = None)[source]¶

Bases: AbstractSized, Generic[T]

A ranged implementation of list.

Functions that change the size of the list are not supported. These include:

`__setitem__` where `key` >= `len`
`__delitem__`
`append`
`extend`
`insert`
`pop`
`remove`

Function that manipulate the list based on values are not supported. These include:

`reverse`, `__reversed__`
`sort`

In the current version the IDs are zero-based consecutive numbers so there is no difference between value-based IDs and index-based IDs, but this could change in the future.

Supports the following arithmetic operations over the list:

+: element-wise addition or addition of a single scalar
-: element-wise subtraction or subtraction of a single scalar
*: element-wise multiplication or multiplication by a single scalar
/: element-wise true division or true division by a single scalar
//: element-wise floor division or floor division by a single scalar

Parameters:

size (int) – Fixed length of the list
key – The dict key this list covers. This is used only for better Exception messages

apply_operation(operation: Callable[[T], U]) → AbstractList[U][source]¶

Applies a function on the list to create a new one. The values of the new list are created on the fly so any changes to the original lists are reflected.

Parameters:: operation – A function that can be applied over the individual values to create new ones.
Returns:: new list
Return type:: AbstractList

count(x: T) → int[source]¶

Counts the number of elements in the list with value x.

Parameters:: x
Returns:: count of matching elements
Return type:: int

abstractmethod get_default() → T | None[source]¶

Gets the default value of the list. Just in case we later allow to increase the number of elements.

Returns:: Default value

get_single_value_all() → T[source]¶

If possible, returns a single value shared by the whole list.

For multiple values use for x in list, iter(list) or list.iter, or one of the iter_ranges methods

Returns:: Value shared by all elements in the list
Raises:: MultipleValuesException – If even one elements has a different value

abstractmethod get_single_value_by_ids(ids: Sequence[int] | ndarray[tuple[int, ...], dtype[integer]]) → T[source]¶

If possible, returns a single value shared by all the IDs.

For multiple values, use for x in list, iter(list), list.iter, or one of the iter_ranges methods.

Returns:: Value shared by all elements with these IDs
Raises:: MultipleValuesException – If even one elements has a different value. Not thrown if elements outside of the IDs have a different value, even if these elements are between the ones pointed to by IDs

abstractmethod get_single_value_by_slice(slice_start: int, slice_stop: int) → T[source]¶

If possible, returns a single value shared by the whole slice list.

For multiple values, use for x in list, iter(list), list.iter, or one of the iter_ranges methods

Returns:: Value shared by all elements in the slice
Raises:: MultipleValuesException – If even one elements has a different value. Not thrown if elements outside of the slice have a different value

abstractmethod get_value_by_id(the_id: int) → T[source]¶

Returns the value for one item in the list.

Parameters:: the_id (int) – One of the IDs of an element in the list
Returns:: The value of that element

Get the value all elements pointed to the selector.

Note

Unlike __get_item__ this method always returns a list even if the selector is a single int.

Parameters:: selector – See AbstractSized.selector_to_ids()
Returns:: returns a list if the item which may be empty or have only single value
Return type:: list

index(x: T) → int[source]¶

Finds the first ID of the first element in the list with the given value.

Parameters:: x – The value to find.
Returns:: The ID/index
Raises:: ValueError – If the value is not found

iter() → Iterator[T][source]¶

Update-safe iterator of all elements.

Note

Duplicate/Repeated elements are yielded for each ID

Returns:: yields each element one by one

iter_by_id(the_id: int) → Iterator[T][source]¶

Fast but not update-safe iterator by one ID.

While next can only be called once, this is an iterator so it can be mixed in with other iterators.

Parameters:: the_id – ID
Returns:: yields the elements

iter_by_ids(ids: Sequence[int] | ndarray[tuple[int, ...], dtype[integer]]) → Iterator[T][source]¶

Fast but not update-safe iterator by collection of IDs.

Note

Duplicate/Repeated elements are yielded for each ID.

Parameters:: ids – IDs
Returns:: yields the elements pointed to by IDs

Fast but not update-safe iterator of all elements in the slice.

Parameters:: selector – See AbstractSized.selector_to_ids()
Returns:: yields the selected elements one by one

iter_by_slice(slice_start: int, slice_stop: int) → Iterator[T][source]¶

Fast but not update-safe iterator of all elements in the slice.

Note

Duplicate/Repeated elements are yielded for each ID

Returns:: yields each element one by one

abstractmethod iter_ranges() → Iterator[Tuple[int, int, T]][source]¶

Fast but not update-safe iterator of the ranges.

Returns:: yields each range one by one

iter_ranges_by_id(the_id: int) → Iterator[Tuple[int, int, T]][source]¶

Iterator of the range for this ID.

Note

The start and stop of the range will be reduced to just the ID

This method purpose is so one a control method can select which iterator to use.

Returns:: yields the one range

iter_ranges_by_ids(ids: Sequence[int] | ndarray[tuple[int, ...], dtype[integer]]) → Iterator[Tuple[int, int, T]][source]¶

Fast but not update-safe iterator of the ranges covered by these IDs.

For consecutive IDs where the elements have the same value a single range may be yielded.

Note

The start and stop of the range will be reduced to just the IDs

Returns:: yields each range one by one
Return type:: iterable

abstractmethod iter_ranges_by_slice(slice_start: int, slice_stop: int) → Iterator[Tuple[int, int, T]][source]¶

Fast but not update-safe iterator of the ranges covered by this slice.

Note

The start and stop of the range will be reduced to just the IDs inside the slice.

Returns:: yields each range one by one

abstractmethod range_based() → bool[source]¶

Shows if the list is suited to deal with ranges or not.

All list must implement all the range functions, but there are times when using ranges will probably be slower than using individual values. For example the individual values may be stored in a list in which case the ranges are created on demand.

Returns:: True if and only if Ranged based calls are recommended.
Return type:: bool

class spinn_utilities.ranged.AbstractSized(size: int | float)[source]¶

Bases: object

Base class for slice and ID checking against size. Subclasses of this support the len() built-in.

Parameters:: size (int) – Fixed length of the list.

Gets the list of IDs covered by this selector. The types of selector currently supported are:

None:: Returns all IDs.
slice: Standard python slice.: Negative values and values larger than size are handled using slice’s indices method. This could result in am empty list.
int: Handles negative values as normal.: Checks if ID is within expected range.
iterator(bool): Used as a mask.: If the length of the mask is longer or shorted than number of IDs the result is the shorter of the two, with the remainder of the longer ignored.
iterator(int) but not bool:: Every value checked that it is with the range 0 to size. Negative values are not allowed. Original order and duplication is respected so result may be unordered and contain duplicates.

Parameters:

selector – Some object that identifies a range of IDs.
warn (bool) – If True, this method will warn about problems with the selector.

Returns:

a (possibly sorted) list of IDs

class spinn_utilities.ranged.AbstractView(range_dict: RangeDictionary[T])[source]¶

Bases: AbstractDict[T], Generic[T]

A view over a ranged dictionary.

Note

The view may currently be read from only with int and int-collection indices, and only be written to with str indices. This may change to become more permissive in future versions.

Use RangeDictionary.view_factory() to create views

get_default(key: str) → T | None[source]¶

Gets the default value for a single key. Unless changed, the default is the original value.

Note

Does not change any values but only changes what reset_value would do

Parameters:: key (str) – Existing dict key
Returns:: default for this key.

keys() → Iterable[str][source]¶

Returns the keys in the dictionary

Returns:: keys in the dict

class spinn_utilities.ranged.DualList(left: AbstractList[T], right: AbstractList[U], operation: Callable[[T, U], R], key: str | None = None)[source]¶

Bases: AbstractList[R], Generic[T, U, R]

A list which combines two other lists with an operation.

Parameters:

left (AbstractList) – The first list to combine
right (AbstractList) – The second list to combine
operation (callable) – The operation to perform as a function that takes two values and returns the result of the operation
key – The dict key this list covers. This is used only for better Exception messages

Raises:

ValueError – If list are not the same size

get_default() → R | None[source]¶

Gets the default value of the list. Just in case we later allow to increase the number of elements.

Returns:: Default value

get_single_value_by_ids(ids: Sequence[int] | ndarray[tuple[int, ...], dtype[integer]]) → R[source]¶

If possible, returns a single value shared by all the IDs.

For multiple values, use for x in list, iter(list), list.iter, or one of the iter_ranges methods.

Returns:: Value shared by all elements with these IDs
Raises:: MultipleValuesException – If even one elements has a different value. Not thrown if elements outside of the IDs have a different value, even if these elements are between the ones pointed to by IDs

get_single_value_by_slice(slice_start: int, slice_stop: int) → R[source]¶

If possible, returns a single value shared by the whole slice list.

For multiple values, use for x in list, iter(list), list.iter, or one of the iter_ranges methods

Returns:: Value shared by all elements in the slice
Raises:: MultipleValuesException – If even one elements has a different value. Not thrown if elements outside of the slice have a different value

get_value_by_id(the_id: int) → R[source]¶

Returns the value for one item in the list.

Parameters:: the_id (int) – One of the IDs of an element in the list
Returns:: The value of that element

iter_by_slice(slice_start: int, slice_stop: int) → Iterator[R][source]¶

Fast but not update-safe iterator of all elements in the slice.

Note

Duplicate/Repeated elements are yielded for each ID

Returns:: yields each element one by one

iter_ranges() → Iterator[Tuple[int, int, R]][source]¶

Fast but not update-safe iterator of the ranges.

Returns:: yields each range one by one

iter_ranges_by_slice(slice_start: int, slice_stop: int) → Iterator[Tuple[int, int, R]][source]¶

Fast but not update-safe iterator of the ranges covered by this slice.

Note

The start and stop of the range will be reduced to just the IDs inside the slice.

Returns:: yields each range one by one

range_based() → bool[source]¶

Shows if the list is suited to deal with ranges or not.

All list must implement all the range functions, but there are times when using ranges will probably be slower than using individual values. For example the individual values may be stored in a list in which case the ranges are created on demand.

Returns:: True if and only if Ranged based calls are recommended.
Return type:: bool

exception spinn_utilities.ranged.MultipleValuesException(key: str | None, value1: Any, value2: Any)[source]¶

Bases: Exception

Raised when there more than one value found unexpectedly.

class spinn_utilities.ranged.RangeDictionary(size: int, defaults: Dict[str, T] | None = None)[source]¶

Bases: AbstractSized, AbstractDict[T], Generic[T]

Main holding class for a range of similar Dictionary object. Keys in the dictionary must be str object and can not be removed. New keys can be added using the dict[str] = value format. The size (length of the list) is fixed and set at initialisation time.

The Object is set up initially where every ID in the range will share the same value for each key. All keys must be of type str. The default values can be anything, including None.

Warning

Using mutable default values can result in weird problems.

Parameters:

size (int) – Fixed number of IDs / Length of lists
defaults (dict(str,object)) – Default dictionary where all keys must be str

copy() → RangeDictionary[T][source]¶

Make a copy of this dictionary. Inner ranged entities are deep copied, inner leaf values are shallow copied.

Returns:: The copy.
Return type:: RangeDictionary

copy_into(other: RangeDictionary[T]) → None[source]¶

Turns this dict into a copy of the other dict but keep its id.

Parameters:: other (RangeDictionary) – Another ranged dictionary assumed created by cloning this one

get_default(key: str) → T | None[source]¶

Gets the default value for a single key. Unless changed, the default is the original value.

Note

Does not change any values but only changes what reset_value would do

Parameters:: key (str) – Existing dict key
Returns:: default for this key.

get_list(key: str) → RangedList[T][source]¶

Gets the storage unit for a single key.

Note

Mainly intended by Views to access the data for one key directly.

Parameters:: key (str) – a key which must be present in the dict
Return type:: ranged_list.RangedList

Gets a single shared value for all IDs covered by this view.

Parameters:: key (str or iterable(str) or None) – The key or keys to get the value of. Use None for all
Returns:: If key is a str, this returns the single object. If key is iterable (list, tuple, set, etc.) of str (or None), returns a dictionary object
Raises:: MultipleValuesException – If even one of the keys has multiple values set. But not if other keys not asked for have multiple values

Same as get_value() but limited to a single ID.

Parameters:

key – as get_value()
the_id – single int ID

Returns:

See get_value()

has_key(key: str) → bool[source]¶

As the Deprecated dict has_keys function.

Note

Int keys to IDs are not supported.

Parameters:: key (str) – the key
Returns:: If the key is in dict
Return type:: bool

ids() → Sequence[int][source]¶

Returns the IDs in range or view. If the view is setup with IDs out of numerical order the order used to create the view is maintained.

Note

If indexing into a view, you are picking the Nth ID. So if the IDs are [2,3,4,5] the view[2] will be the data for ID 4 and not 2

Returns:: list of IDs
Return type:: list(int)

Returns a list of the IDs in this Range

Returns:: a list of the IDs in this Range
Return type:: list(int)

Iterates over the value(s) for all IDs covered by this view. There will be one yield for each ID even if values are repeated.

Parameters:

key (str or iterable(str) or None) – The key or keys to get the value of. Use None for all keys
update_safe – If set True the iteration will work even if values are updated during iteration. If left False the iterator may be faster but behaviour is undefined and unchecked if any values are changed during iteration.

Returns:

If key is a str, this yields single objects. If key is iterable (list, tuple, set, etc.) of str (or None), yields dictionary objects

Iterates over the ranges(s) for all IDs covered by this view. There will be one yield for each range which may cover one or more IDs.

Warning

This iterator is not update safe! Behaviour is undefined and unchecked if any values are changed during iteration.

Parameters:: key (str or iterable(str) or None) – The key or keys to get the value of. Use None for all
Returns:: yields tuples of (start, stop, value). start is inclusive so is the first ID in the range. stop is exclusive so is the last ID in the range + 1. If key is a str, value is a single object. If key is iterable (list, tuple, set, etc.) of str (or None), value is a dictionary object

Same as iter_ranges() but limited to one ID.

Parameters:

key – see iter_ranges() parameter key
the_id – single ID which is the actual ID and not an index into IDs

Same as iter_ranges() but limited to a collection of IDs.

The IDs are actual ID values and not indexes into the IDs

Parameters:

key – see iter_ranges() parameter key
ids – Collection of IDs in the range

Returns:

see iter_ranges()

Same as iter_ranges() but limited to a simple slice.

slice_start and slice_stop are actual ID values and not indexes into the IDs. They must also be actual values, so None, max_int, and negative numbers are not supported.

Parameters:

key – see iter_ranges() parameter key
slice_start – Inclusive i.e. first ID
slice_stop – Exclusive to last ID + 1

Returns:

see iter_ranges()

iter_values_by_ids(ids: Sequence[int] | ndarray[tuple[int, ...], dtype[integer]], key: str | MutableSequence[str] | Tuple[str, ...] | FrozenSet[str] | Set[str] | None = None, update_safe: bool = False) → Generator[T, None, None] | Generator[Dict[str, T], None, None][source]¶: Same as iter_all_values() but limited to a simple slice.

iter_values_by_slice(slice_start: int, slice_stop: int, key: str | MutableSequence[str] | Tuple[str, ...] | FrozenSet[str] | Set[str] | None = None, update_safe: bool = False) → Iterator[T] | Iterator[Dict[str, T]][source]¶: Same as iter_all_values() but limited to a simple slice.

keys() → Iterable[str][source]¶

Returns the keys in the dictionary

Returns:: keys in the dict

list_factory(size: int, value: T, key: str) → RangedList[T][source]¶

Defines which class or subclass of RangedList to use.

Main purpose is for subclasses to use a subclass or RangedList. All parameters are pass through ones to the List constructor

Parameters:

size – Fixed length of the list
value – value to given to all elements in the list
key – The dict key this list covers.

Returns:

AbstractList in this case a RangedList

set_default(key: str, default: T) → None[source]¶

Sets the default value for a single key.

Note

Does not change any values but only changes what reset_value would do

Warning

If called on a view, it sets the default for the whole range and not just the view.

Parameters:

key (str) – Existing dict key
default – Value to be used by reset; should not be mutable!

set_value(key: str, value: T, use_list_as_value: bool = False) → None[source]¶

Sets a already existing key to the new value. All IDs in the whole range or view will have this key set.

Warning

This method does not allow adding keys. Using dict[str] = will add a new key, but it is not supported for views.

Warning

If a View is created over multiple ranges this method would raise a KeyError if any the ranges does not have the key. (Currently multiple ranges not yet supported.)

Parameters:

key (str) – key to value being set
value – any object
use_list_as_value – True if the value is a list

Raises:

KeyError – If a new key is being used.

update_safe_iter_all_values(key: str | MutableSequence[str] | Tuple[str, ...] | FrozenSet[str] | Set[str] | None, ids: Sequence[int] | ndarray[tuple[int, ...], dtype[integer]]) → Generator[T | Dict[str, T], None, None][source]¶: Same as iter_all_values() but limited to a collection of IDs and update-safe.

view_factory(key: _KeyType) → AbstractView[source]¶

Main function for creating views. This is the preferred way of creating new views as it checks parameters and returns the most efficient view.

Note

The __getitem__ methods called by Object[id] and similar defer to this method so are fine to use.

The ID(s) used are the actual IDs in the range and not indexes on the list of IDs

Parameters:: key – A single int ID, a Slice object, or an iterable of int IDs
Returns:: A view over the range

Bases: AbstractList[T], Generic[T]

A list that is able to efficiently hold large numbers of elements that all have the same value.

Parameters:

size (int or None) – Fixed length of the list; if None, the value must be a sized object.
value (object or Sized) – value to given to all elements in the list
key – The dict key this list covers. This is used only for better Exception messages
use_list_as_value (bool) – True if the value is a list

as_list(value: Callable[[int], T] | Sequence[T], size: int, ids: Sequence[int] | ndarray[tuple[int, ...], dtype[integer]] | None = None) → List[T][source]¶

Converts (if required) the value into a list of a given size. An exception is raised if value cannot be given size elements.

Note

This method can be extended to add other conversions to list in which case listness_check() must also be extended.

Parameters:: value
Returns:: value as a list
Raises:: Exception – if the number of values and the size do not match

copy() → RangedList[T][source]¶

Creates a copy of this list.

Depth is just enough so that any changes done through the RangedList API on other will not change self

Returns:: The copy
Return type:: RangedList

copy_into(other: RangedList[T]) → None[source]¶

Turns this List into a of the other list but keep its ID.

Depth is just enough so that any changes done through the RangedList API on other will not change self

Parameters:: other (RangedList) – Another Ranged List to copy the values from

get_default() → T | None[source]¶

Returns the default value for this list.

Returns:: Default Value
Return type:: object

get_ranges() → List[Tuple[int, int, T]][source]¶

Returns a copy of the list of ranges.

Note

As this is a copy it will not reflect any updates.

Return type:: list(tuple(int,int,object))

get_single_value_by_ids(ids: Sequence[int] | ndarray[tuple[int, ...], dtype[integer]]) → T[source]¶

If possible, returns a single value shared by all the IDs.

For multiple values, use for x in list, iter(list), list.iter, or one of the iter_ranges methods.

Returns:: Value shared by all elements with these IDs
Raises:: MultipleValuesException – If even one elements has a different value. Not thrown if elements outside of the IDs have a different value, even if these elements are between the ones pointed to by IDs

get_single_value_by_slice(slice_start: int, slice_stop: int) → T[source]¶

If possible, returns a single value shared by the whole slice list.

For multiple values, use for x in list, iter(list), list.iter, or one of the iter_ranges methods

Returns:: Value shared by all elements in the slice
Raises:: MultipleValuesException – If even one elements has a different value. Not thrown if elements outside of the slice have a different value

get_value_by_id(the_id: int) → T[source]¶

Returns the value for one item in the list.

Parameters:: the_id (int) – One of the IDs of an element in the list
Returns:: The value of that element

Determines if the value should be treated as a list.

Parameters:: value – The value to examine.

iter_by_slice(slice_start: int, slice_stop: int) → Iterator[T][source]¶

Fast but not update-safe iterator of all elements in the slice.

Note

Duplicate/Repeated elements are yielded for each ID

Returns:: yields each element one by one

iter_ranges() → Iterator[Tuple[int, int, T]][source]¶

Fast but not update-safe iterator of the ranges.

Returns:: yields each range one by one

iter_ranges_by_slice(slice_start: int, slice_stop: int) → Iterator[Tuple[int, int, T]][source]¶

Fast but not update-safe iterator of the ranges covered by this slice.

Note

The start and stop of the range will be reduced to just the IDs inside the slice.

Returns:: yields each range one by one

listness_check(value: T | Callable[[int], T] | Sequence[T] | None) → bool[source]¶

Easier to override in subclasses as not type guard.

Note

This method can be extended to add other checks for list in which case as_list() must also be extended.

Parameters:: value – The value to examine.

range_based() → bool[source]¶

Shows if the list is suited to deal with ranges or not.

All list must implement all the range functions, but there are times when using ranges will probably be slower than using individual values. For example the individual values may be stored in a list in which case the ranges are created on demand.

Returns:: True if and only if Ranged based calls are recommended.
Return type:: bool

set_default(default: T | None) → None[source]¶

Sets the default value.

Note

Does not change the value of any element in the list.

Parameters:: default (object) – new default value

set_value(value: T | Callable[[int], T] | Sequence[T] | None, use_list_as_value: bool = False) → None[source]¶

Sets all elements in the list to this value.

Note

Does not change the default.

Parameters:

value – new value
use_list_as_value – True if the value to be set is a list

set_value_by_id(the_id: int, value: T) → None[source]¶

Sets the value for a single ID to the new value.

Note

This method only works for a single positive int ID. Use set or __set__ for slices, tuples, lists and negative indexes.

Parameters:

the_id (int) – Single ID
value (object) – The value to save

set_value_by_ids(ids: Sequence[int] | ndarray[tuple[int, ...], dtype[integer]], value: T | Callable[[int], T] | Sequence[T] | None, use_list_as_value: bool = False) → None[source]¶

Sets a already existing key to the new value. For the ids specified.

Parameters:

key (str)
value

Support for the list[x] = format.

Parameters:

selector (int or slice or list(int)) – A single ID, a slice of IDs or a list of IDs
value (object)

set_value_by_slice(slice_start: int, slice_stop: int, value: T | Callable[[int], T] | Sequence[T] | None, use_list_as_value: bool = False) → None[source]¶

Sets the value for a single range to the new value.

Note

This method only works for a single positive range. Use set or __set__ for slices, tuples, lists and negative indexes.

Parameters:

slice_start (int) – Start of the range
slice_stop (int) – Exclusive end of the range
value (object) – The value to save

Bases: RangedList[List[T]], Generic[T]

A Ranged object for lists of list.

Parameters:

size (int or None) – Fixed length of the list; if None, the value must be a sized object.
value (object or Sized) – value to given to all elements in the list
key – The dict key this list covers. This is used only for better Exception messages
use_list_as_value (bool) – True if the value is a list

listness_check(value: List[T] | Callable[[int], List[T]] | Sequence[List[T]] | None) → bool[source]¶

Easier to override in subclasses as not type guard.

Note

This method can be extended to add other checks for list in which case as_list() must also be extended.

Parameters:: value – The value to examine.

class spinn_utilities.ranged.SingleList(a_list: AbstractList[T], operation: Callable[[T], R], key: str | None = None)[source]¶

Bases: AbstractList[R], Generic[T, R]

A List that performs an operation on the elements of another list.

Parameters:

a_list (AbstractList) – The list to perform the operation on
operation (callable) – A function which takes a single value and returns the result of the operation on that value
key – The dict key this list covers. This is used only for better Exception messages

get_default() → R | None[source]¶

Gets the default value of the list. Just in case we later allow to increase the number of elements.

Returns:: Default value

get_single_value_by_ids(ids: Sequence[int] | ndarray[tuple[int, ...], dtype[integer]]) → R[source]¶

If possible, returns a single value shared by all the IDs.

For multiple values, use for x in list, iter(list), list.iter, or one of the iter_ranges methods.

Returns:: Value shared by all elements with these IDs
Raises:: MultipleValuesException – If even one elements has a different value. Not thrown if elements outside of the IDs have a different value, even if these elements are between the ones pointed to by IDs

get_single_value_by_slice(slice_start: int, slice_stop: int) → R[source]¶

If possible, returns a single value shared by the whole slice list.

For multiple values, use for x in list, iter(list), list.iter, or one of the iter_ranges methods

Returns:: Value shared by all elements in the slice
Raises:: MultipleValuesException – If even one elements has a different value. Not thrown if elements outside of the slice have a different value

get_value_by_id(the_id: int) → R[source]¶

Returns the value for one item in the list.

Parameters:: the_id (int) – One of the IDs of an element in the list
Returns:: The value of that element

iter_ranges() → Iterator[Tuple[int, int, R]][source]¶

Fast but not update-safe iterator of the ranges.

Returns:: yields each range one by one

iter_ranges_by_slice(slice_start: int, slice_stop: int) → Iterator[Tuple[int, int, R]][source]¶

Fast but not update-safe iterator of the ranges covered by this slice.

Note

The start and stop of the range will be reduced to just the IDs inside the slice.

Returns:: yields each range one by one

range_based() → bool[source]¶

Shows if the list is suited to deal with ranges or not.

All list must implement all the range functions, but there are times when using ranges will probably be slower than using individual values. For example the individual values may be stored in a list in which case the ranges are created on demand.

Returns:: True if and only if Ranged based calls are recommended.
Return type:: bool

spinn_utilities.ranged package¶

Submodules¶

spinn_utilities.ranged.ids_view module¶

spinn_utilities.ranged.single_view module¶

spinn_utilities.ranged.slice_view module¶

Module contents¶

Table of Contents

Previous topic

Next topic

This Page