pushable package

Module contents

class pushable.Pushable(source)

Bases: Iterator[T]

Wraps an iterator so that it supports peeking and pushing, much like a LIFO queue (aka stack). Another way of looking at it is a lazy queue that supports pushbacks.

This is focussed on the use-case of providing modest look-ahead capabilities on a stream of tokens.

lenAtLeast(N: int) → bool

Are there at least N items in the queue? Does not change the queue.

multiPeek(skip: int = 0, count: int = 1)

Returns zero, one or more items from the front of the queue, as an iterator, optionally skipping the first N items. There must be at least N+count items or a RuntimeError will be raised. The queue will not be affected, although it may be partly instantiated.

multiPeekOr(default=None, skip: int = 0, count: int = 1) → Iterator[Any]

Returns zero, one or more items from the front of the queue as an iterable, optionally skipping the first N items. If there are insufficient items in the queue, the default value is substituted sufficient to make up the numbers. The queue will not be affected, although it will likely be partly instantiated.

multiPop(skip: int = 0, count: int = 1) → Iterator[Any]

Removes and returns zero, one or more items from the front of the queue as an iterator, optionally skipping the first N items. There must be at least N+count items or a RuntimeError will be raised.

multiPopOr(default=None, skip: int = 0, count: int = 1) → Iterator[Any]

Removes and returns zero, one or more items from the front of the queue, optionally skipping the first skip+count items. If there are insufficient items available then the default value is substututed as many times as needed.

multiPush(*values)

Pushes one or more items onto the queue in reverse order, so that the first item becomes the new head of the queue.

peek() → T

Gets an item from the head of the queue without affecting the queue. There must be at least one item or StopIteration is raised.

peekOr(default=None) → Any

Gets an item from the head of the queue without affecting the queue. If no item is available the default value is returned.

pop() → T

Gets an item from the head of the queue, removing it from the queue. If there are less than 1 item, raise StopIteration. This is a synonym for __next__.

popOr(default=None) → Any

Gets an item from the head of the queue, removing it from the queue. If there is less than 1 item, return the supplied default value instead.

push(value)

Pushes one item onto the queue, so that it is the new head of the queue.

skipPeek(skip: int = 0) → T

Gets an item from the head of the queue without affecting the queue, optionally skipping the first N items. There must be at least N+1 items or StopIteration will be raised, although the queue will be unaffected.

skipPeekOr(default=None, skip: int = 0) → Any

Gets an item from the head of the queue without affecting the queue, optionally skipping the first N items. If there are less than N+1 items, the default is returned.

skipPop(skip: int = 0) → T

Gets an item from the head of the queue, removing it from the queue, optionally removing the preceding N items. If there are less than N+1 items, raise StopIteration.

skipPopOr(default=None, skip: int = 0) → Any

Gets an item from the head of the queue, removing it from the queue, optionally removing the preceding N items. If there are less than N+1 items, return the supplied default value.