hio.help

hio.help package

Submodules

• hio.help.decking
• hio.help.helping
• hio.help.hicting
• hio.help.ogling
• hio.help.timing

Package Contents

Classes

Deck	Extends deque to support deque access convenience methods .push and .pull
Hict	Hict is a Case Insensitive Keyed Multiple valued dictionary like class that
Mict	Mict is a multiple valued dictionary like class that extends MultiDict.
Timer	Class to manage real elaspsed time using time module.
MonoTimer	Class to manage real elaspsed time using time module but with monotonically

Attributes

ogler

hio.help.ogler

class hio.help.Deck(iterable=None, maxlen=None)

Bases: collections.deque

Extends deque to support deque access convenience methods .push and .pull to remove confusion about which side of the deque to use (left or right).

Extends deque with .push an .pull methods to support a different pattern for access. .push does not allow a value of None to be added to the Deck. This enables retrieval with .pull(emptive=True) which returns None when empty instead of raising IndexError. This allows use of the walrus operator on a pull to both assign and check for empty. For example:

deck.extend([False, “”, []]) # falsy elements but not None stuff = [] while (x := deck.pull(emptive=True)) is not None:

stuff.append(x)

assert stuff == [False, “”, []] assert not deck

Local methods: .push(x) = add x if x is not None to the right side of deque (like append) .pull(x) = remove and return element from left side of deque (like popleft)

Inherited methods from deque: .append(x) = add x to right side of deque .appendleft(x) = add x to left side of deque .clear() = clear all items from deque leaving it a length 0 .count(x) = count the number of deque elements equal to x. .extend(iterable) = append elements of iterable to right side .extendleft(iterable) = append elemets of iterable to left side

(this reverses iterable)

.pop() = remove and return element from right side

if empty then raise IndexError

.popleft() = remove and return element from left side

if empty then raise IndexError

.remove(x) = remove first occurence of x left to right

if not found raise ValueError

.rotate(n) = rotate n steps to right if neg rotate to left

Built in methods supported: len(d) reversed(d) copy.copy(d) copy.deepcopy(d) subscripts d[0] d[-1]

Attributes: .maxlen = maximum size of Deck or None if unbounded

__repr__(self)

Custome repr for Deck

push(self, elem: Any)

If not None, add elem to right side of deque, Otherwise ignore :param elem: element to be appended to deck (deque) :type elem: Any

pull(self, emptive=False)

Remove and return elem from left side of deque, If empty and emptive return None else raise IndexError

Parameters

emptive (bool) – True means return None instead of raise IndexError when attempt to pull False means normal behavior of deque

class hio.help.Hict

Bases: multidict.CIMultiDict

Hict is a Case Insensitive Keyed Multiple valued dictionary like class that extends CIMultiDict and is used for HTTP headers which have case insentive labels. Insertion order of keys preserved. Associated with each key is a valuelist i.e. a list of values for that key.

https://multidict.readthedocs.io/en/stable/ CIMultiDict keys must be subclass of str no ints allowed In CIMultiDict:

.add(key,value) appends value to the valuelist at key

m[“key”] = value replaces the valuelist at key with [value]

m[“key”] returns the first added element of the valuelist at key

MultiDict methods access values in FIFO order Hict adds method to access values in LIFO order

Extended methods in Hict but not in CIMultiDict are:

nabone(key [,default]) get last value at key else default or KeyError nab(key [,default]) get last value at key else default or None naball(key [,default]) get all values inverse order else default or KeyError firsts() get all items where item value is first inserted value at key lasts() get all items where item value is last insterted value at key

__repr__(self)

nabone(self, key, *pa, **kwa)

Usage:

.nabone(key [, default])

returns last value at key if key in dict else default raises KeyError if key not in dict and default not provided.

nab(self, key, *pa, **kwa)

Usage:

.nab(key [, default])

returns last value at key if key in dict else default returns None if key not in dict and default not provided.

naball(self, key, *pa, **kwa)

Usage:

.nabone(key [, default])

returns list of values at key if key in dict else default raises KeyError if key not in dict and default not provided.

firsts(self)

Returns list of (key, value) pair where each value is first value at key but with no duplicate keys. MultiDict .keys() returns a key for each duplicate value

lasts(self)

Returns list of (key, value) pairs where each value is last value at key but with no duplicate keys. MultiDict .keys() returns a key for each duplicate value

class hio.help.Mict

Bases: multidict.MultiDict

Mict is a multiple valued dictionary like class that extends MultiDict. Insertion order of keys preserved. Associated with each key is a valuelist i.e. a list of values for that key.

https://multidict.readthedocs.io/en/stable/ MultiDict keys must be subclass of str no ints allowed In MultiDict:

.add(key,value) appends value to the valuelist at key

m[“key”] = value replaces the valuelist at key with [value]

m[“key”] returns the first added element of the valuelist at key

MultiDict methods access values in FIFO order Mict adds methods to access values in LIFO order

Extended methods in Mict but not in MultiDict are:

nabone(key [,default]) get last value at key else default or KeyError nab(key [,default]) get last value at key else default or None naball(key [,default]) get all values inverse order else default or KeyError

__repr__(self)

nabone(self, key, *pa, **kwa)

Usage:

.nabone(key [, default])

returns last value at key if key in dict else default raises KeyError if key not in dict and default not provided.

nab(self, key, *pa, **kwa)

Usage:

.nab(key [, default])

returns last value at key if key in dict else default returns None if key not in dict and default not provided.

naball(self, key, *pa, **kwa)

Usage:

.nabone(key [, default])

returns list of values at key if key in dict else default raises KeyError if key not in dict and default not provided.

firsts(self)

Returns list of (key, value) pair where each value is first value at key No duplicate keys

lasts(self)

Returns list of (key, value) pairs where each value is last value at key No duplicate keys

class hio.help.Timer(duration=0.0, start=None, **kwa)

Bases: hio.hioing.Mixin

Class to manage real elaspsed time using time module. .. attribute:: ._start is start tyme in seconds

._stop  is stop tyme in seconds

Properties:

.duration is float time duration in seconds of timer from ._start to ._stop .elaspsed is float time elasped in seconds since ._start .remaining is float time remaining in seconds until ._stop .expired is boolean, True if expired, False otherwise, i.e. time >= ._stop

.start()  start timer at current time

.restart() = restart timer at last ._stop so no time lost

property duration(self)

duration property getter, .duration = ._stop - ._start .duration is float duration tyme

property elapsed(self)

elapsed time property getter, Returns elapsed time in seconds (fractional) since ._start.

property remaining(self)

remaining time property getter, Returns remaining time in seconds (fractional) before ._stop.

property expired(self)

Returns True if timer has expired, False otherwise. time.time() >= ._stop,

start(self, duration=None, start=None)

Starts Timer of duration secs at start time start secs.

If duration not provided then uses current duration If start not provided then starts at current time.time()

restart(self, duration=None)

Lossless restart of Timer at start = ._stop for duration if provided, Otherwise current duration. No time lost. Useful to extend Timer so no time lost

class hio.help.MonoTimer(duration=0.0, start=None, retro=True)

Bases: Timer

Class to manage real elaspsed time using time module but with monotonically increating time guarantee in spite of system time being retrograded.

If the system clock is retrograded (moved back in time) while the timer is running then time.time() could move to before the start time. MonoTimer detects this retrograde and if retro is True then retrogrades the start and stop times back Otherwise it raises a TimerRetroError. MonoTimer is not able to detect a prograded clock (moved forward in time)

._start is start time in seconds

._stop  is stop time in seconds

._last is last measured time in seconds with retrograde handling

.retro is boolean If True retrograde ._start and ._stop when time is retrograded.

Properties:

.duration is float time duration in seconds of timer from ._start to ._stop .elaspsed is float time elasped in seconds since ._start .remaining is float time remaining in seconds until ._stop .expired is boolean True if expired, False otherwise, i.e. time >= ._stop .latest is float latest measured time in seconds with retrograte handling

.start() = start timer at current time returns start time

.restart() = restart timer at last ._stop so no time lost, returns start time

property elapsed(self)

elapsed time property getter, Returns elapsed time in seconds (fractional) since ._start.

property remaining(self)

remaining time property getter, Returns remaining time in seconds (fractional) before ._stop.

property expired(self)

Returns True if timer has expired, False otherwise. .latest >= ._stop,

property latest(self)

latest measured time property getter, Returns latest measured time in seconds adjusted for retrograded system time.

exception hio.help.TimerError

Bases: hio.hioing.HioError

Generic Timer Errors Usage:

raise TimerError(“error message”)

exception hio.help.RetroTimerError

Bases: TimerError

Error due to real time being retrograded before start time of timer Usage:

raise RetroTimerError(“error message”)