# `taurus.core.util.containers`

This module contains a set of useful containers that are not part of the standard python distribution.

Classes

class ArrayBuffer(buffer, maxSize=0)

  A data buffer which internally uses a preallocated numpy.array. An ArrayBuffer will only present the actual contents, not the full internal buffer, so when appending or extending, it behaves as if dynamic reallocation was taking place.

  The contents of the class:ArrayBuffer can be accessed as if it was a numpy array (i.e slicing notation like b[2:3], b[:,2], b[-1],… are all valid).

  For retrieving the full contents, see `ArrayBuffer.contents()` and `ArrayBuffer.toArray()`

  On creation, a given initial internal buffer and a maximum size are set. If the maximum size is larger than the original internal buffer, this will be automatically grown in geometrical steps if needed to accommodate the contents, up to the maximum size. Once the contents fill the maximum size, appending or extending the contents will result in older contents being discarded (in a FIFO way)

  The `append()` and meth:extend methods are designed to be cheap (especially if the internal buffer size is already at the maximum size), at the expense of memory usage

  (more info)

class CaselessDefaultDict

  a join venture between caseless and default dict This class merges the two previous ones. This declaration equals to:

      CaselessDefaultDict = type(
          'CaselessDefaultType',
          (CaselessDict,defaultdict_fromkey),
          {}
      )

  (more info)

class CaselessDict(other=None)

  A case insensitive dictionary. Use this class as a normal dictionary. The keys must be strings

  (more info)

class CaselessList(inlist=[])

  A case insensitive lists that has some caseless methods. Only allows strings as list members. Most methods that would normally return a list, return a CaselessList. (Except list() and lowercopy()) Sequence Methods implemented are : __contains__, remove, count, index, append, extend, insert, __getitem__, __setitem__, __getslice__, __setslice__ __add__, __radd__, __iadd__, __mul__, __rmul__ Plus Extra methods: findentry, copy , lowercopy, list Inherited methods : __imul__, __len__, __iter__, pop, reverse, sort

  (more info)

class CaselessWeakValueDict(other=None)

  (more info)

class CircBuf(leng)

  A circular buffer of Python values.

  Examples:

      >>> cb = CircBuf(3)
      >>> cb.is_empty()
      1
      >>> cb.put('first')
      >>> cb.is_empty()
      0
      >>> cb.put('second')
      >>> cb.put('third')
      >>> cb.is_full()
      1
      >>> cb.put('fourth')
      >>> cb.get()
      'second'
      >>> cb.get()
      'third'
      >>> cb.get()
      'fourth'
      >>> cb.is_empty()
      1

  (more info)

class defaultdict

  defaultdict(default_factory=None, /, […]) –> dict with default factory

  The default factory is called without arguments to produce a new value when a key is not present, in __getitem__ only. A defaultdict compares equal to a dict with the same items. All remaining arguments are treated the same as if they were passed to the dict constructor, including keyword arguments.

  (more info)

class defaultdict_fromkey

  Creates a dictionary with a default_factory function that creates new elements using key as argument.

  Usagenew_dict = defaultdict_fromkey(method)

    where method like (lambda key: return new_obj(key))

  Each time that new_dict[key] is called with a key that doesn’t exist, method(key) is used to create the value Copied from PyAlarm device server

  (more info)

class DefaultThreadDict(other=None, default_factory=None, read_method=None, write_method=None, timewait=0.1, threaded=True)

  a join venture between thread and default dict This class merges the two previous ones.

  (more info)

class LIFO(max=10)

  (more info)

class LoopList(itemlist=[])

  this class provides an effectively cyclic list. It can be used, e.g., for storing colors or pen properties to be changed automatically in a plot

  A LoopList stores an internal index to remember the last accessed item in the list. It provides previous(), current() and next() methods that return the previous, current and next items in the list.

  The method allItems() returns a copy of all items contained in the list.

  The index can be accessed by setCurrentIndex() and getCurrentIndex() (setCurrentIndex(i) additionally returns new current item).

  Items can be accessed *without modifying the current index* by using llist[i] and llist[i]=x syntax len(llist) returns the period of the list.

  Note

  only basic methods of lists are implemented for llists. In particular, the following are not implemented:

  > - slicing

  > - resizing (append, insert, del,…)

  > - binary operators (+,*,…)

  ..note:

      it can be used for loops, but the loop will be infinite unless other
      condition is used for exiting it:

          - for item in llist: print(item)  # This is a infinite loop!!
          - for i in range(len(llist)):print(llist[i])  # not infinite
            since len(llist) returns the period of the list

  (more info)

class ThreadDict(other=None, read_method=None, write_method=None, timewait=0.1, threaded=True)

  Thread safe dictionary with redefinable read/write methods and a background thread for hardware update. All methods are thread-safe using @self_lock decorator.

  Note

  any method decorated in this way CANNOT call other decorated methods! All values of the dictionary will be automatically updated in a separate Thread using read_method provided. Any value overwritten in the dict should launch the write_method.

  Briefing:

      a[2] equals to a[2]=read_method(2)
      a[2]=1 equals to a[2]=write_method(2,1)

  (more info)

class TimedQueue(arg=None)

  A FIFO that keeps all the values introduced at least for a given time. Applied to some device servers, to force States to be kept at least a minimum time. Previously named as PyTango_utils.device.StateQueue pop(): The value is removed only if delete_time has been reached. at least 1 value is always kept in the list

  (more info)

Functions

dictFromSequence(seq)

  Translates a sequence into a dictionary by converting each to elements of the sequence (k,v) into a k:v pair in the dictionary

  Parameters:

    seq (sequence) – any sequence object

  Returns:

    dictionary built from the given sequence

  Return type:

    dict

getDictAsTree(dct)

  This method will print a recursive dict in a tree-like shape:

      >>> print(getDictAsTree({'A':{'B':[1,2],'C':[3]}}))

self_locked(func, reentrant=True)

  Decorator to make thread-safe class members Decorator to create thread-safe objects.

  Warning

  - With Lock() this decorator should not be used to decorate nested functions; it will cause Deadlock!

  - With RLock this problem is avoided … but you should rely more on python threading