Top

grizzled.collections module

grizzled.collections provides some useful Python collection classes.

Classes

class LRUDict

LRUDict is a dictionary of a fixed maximum size that enforces a least recently used discard policy. When the dictionary is full (i.e., contains the maximum number of entries), any attempt to insert a new entry causes one of the least recently used entries to be discarded.

Note:

  • Setting or updating a key in the dictionary refreshes the corresponding value, making it "new" again, even if it replaces the existing value with itself.
  • Retrieving a value from the dictionary also refreshes the entry.
  • Iterating over the contents of the dictionary (via in or items() or any other similar method) does not affect the recency of the dictionary's contents.
  • This implementation is not thread-safe.

An LRUDict also supports the concept of removal listeners. Removal listeners are functions that are notified when objects are removed from the dictionary. Removal listeners can be:

  • eject only listeners, meaning they're only notified when objects are ejected from the cache to make room for new objects, or
  • removal listeners, meaning they're notified whenever an object is removed for any reason, including via del.

Ancestors (in MRO)

  • LRUDict
  • builtins.dict
  • builtins.object

Class variables

var max_capacity

Static methods

def __init__(

self, *args, **kw)

Initialize an LRUDict that will hold, at most, max_capacity items. Attempts to insert more than max_capacity items in the dictionary will cause the least-recently used entries to drop out of the dictionary.

Keywords

  • max_capacity (int): The maximum size of the dictionary

def add_ejection_listener(

self, listener, *args)

Add an ejection listener to the dictionary. The listener function should take at least two parameters: the key and value being removed. It can also take additional parameters, which are passed through unmodified.

An ejection listener is only notified when objects are ejected from the cache to make room for new objects; more to the point, an ejection listener is never notified when an object is removed from the cache manually, via use of the del operator.

Parameters

  • listener (function): function to invoke
  • args (iterable): Any additional parameters to pass to the function

def add_removal_listener(

self, listener, *args)

Add a removal listener to the dictionary. The listener function should take at least two parameters: the key and value being removed. It can also take additional parameters, which are passed through unmodified.

A removal listener is notified when objects are ejected from the cache to make room for new objects and when objects are manually deleted from the cache.

Parameters

  • listener (function): function to invoke
  • args (iterable): Any additional parameters to pass to the function

def clear(

self)

D.clear() -> None. Remove all items from D.

def clear_listeners(

self)

Clear all removal and ejection listeners from the list of listeners.

def get(

self, key, default=None)

Return the value for key if key is in the dictionary, else default.

def get_max_capacity(

self)

Get the maximum capacity of the dictionary.

Returns

The maximum capacity (an int)

def items(

self)

D.items() -> a set-like object providing a view on D's items

def iteritems(

self)

def iterkeys(

self)

def itervalues(

self)

def keys(

self)

Get the list of keys in the dictionary.

def pop(

self, key, default=None)

"Pop" (i.e., retrieve and remove) the specified key from the dictionary.

Parameters

  • key: The key to remove
  • default: The default to apply if the key is not there. If None, then a KeyError is raised if the key isn't present.

Returns

The value associated with key. If there is no value associated with the key, default. If default is None, raises a KeyError.

def popitem(

self)

Pops the least recently used recent key/value pair from the dictionary.

Returns

The least recently used (key, value) pair, as a tuple.

Raises

KeyError on empty dictionary

def remove_listener(

self, listener)

Remove the specified removal or ejection listener from the list of listeners.

Parameters

  • listener (function): Function object to remove

Returns

True if the function was found and removed, False otherwise

def set_max_capacity(

self, new_capacity)

Set or change the maximum capacity of the dictionary. Reducing the size of a dictionary with items already in it might result in items being evicted.

Parameters

  • new_capacity (int): the new maximum capacity

def update(

self, d, **kw)

Update the dictionary with the key/value pairs from d, overwriting existing keys. Returns nothing.

update() accepts either another dictionary object or an iterable of key/value pairs (as tuples or other iterables of length two). If keyword arguments are specified, the dictionary is then updated with those key/value pairs, e.g., d.update(red=1, blue=2).

Keywords arguments take precedence. Thus, in:

d.update({'red': 1}, red=2)

the value 2 will be associated with key red.

def values(

self)

D.values() -> an object providing a view on D's values

Instance variables

var max_capacity

The maximum capacity. Can be reset at will.