43. track — Add tracking facilities to any class.

This module provides some functions to help in creating classes with tracking facilities. This can e.g. be use to detect if the contents of a list or dict has been changed.

The tracking facility consists in marking some of the class’ methods and count how many times any of these methods is used.

Examples

>>> TrackedDict = track_class_factory(dict)
>>> D = TrackedDict({'a':1,'b':2})
>>> print(D.hits)
0
>>> D['c'] = 3
>>> print(D.hits)
1
>>> D.hits = 0
>>> print(D.hits)
0
>>> D.update({'d':1,'b':3})
>>> del D['a']
>>> print(D.hits)
2

43.1. Variables defined in module track

track.track_methods = ['__delitem__', '__iadd__', '__imul__', '__ior__', '__setitem__', 'append', 'clear', 'extend', 'insert', 'pop', 'popitem', 'remove', 'setdefault', 'update']

This list of methods that can possibly change an object of type dict or list is the default list of tracked methods.

43.2. Classes defined in module track

class track.TrackedDict

Tracked dict class

This dict class tracks the usage of the following methods: [‘__delitem__’, ‘__iadd__’, ‘__imul__’, ‘__ior__’, ‘__setitem__’, ‘append’, ‘clear’, ‘extend’, ‘insert’, ‘pop’, ‘popitem’, ‘remove’, ‘setdefault’, ‘update’] Usage of any of these methods increments the class’ hits attribute.

clear(**kw)

Wrapper function for a class method.

copy() → a shallow copy of D

fromkeys(value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

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

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

keys() → a set-like object providing a view on D's keys

pop(**kw)

Wrapper function for a class method.

popitem(**kw)

Wrapper function for a class method.

setdefault(**kw)

Wrapper function for a class method.

update(**kw)

Wrapper function for a class method.

values() → an object providing a view on D's values

class track.TrackedList(iterable=(), /)

Tracked list class

This list class tracks the usage of the following methods: [‘__delitem__’, ‘__iadd__’, ‘__imul__’, ‘__ior__’, ‘__setitem__’, ‘append’, ‘clear’, ‘extend’, ‘insert’, ‘pop’, ‘popitem’, ‘remove’, ‘setdefault’, ‘update’] Usage of any of these methods increments the class’ hits attribute.

append(**kw)

Wrapper function for a class method.

clear(**kw)

Wrapper function for a class method.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

extend(**kw)

Wrapper function for a class method.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

insert(**kw)

Wrapper function for a class method.

pop(**kw)

Wrapper function for a class method.

remove(**kw)

Wrapper function for a class method.

reverse()

Reverse IN PLACE.

sort(*, key=None, reverse=False)

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

43.3. Functions defined in module track

track.track_decorator(func)

Create a wrapper function for tracked class methods.

The wrapper function increases the ‘hits’ attribute of the class and then executes the wrapped method. The class is passed as the first argument.

track.track_class_factory(clas, name='', methods=['__delitem__', '__iadd__', '__imul__', '__ior__', '__setitem__', 'append', 'clear', 'extend', 'insert', 'pop', 'popitem', 'remove', 'setdefault', 'update'])

Create a wrapper class with method tracking facilities.

Parameters:

• clas (class) – The class to be tracked.

• name (str, optional) – The name of the class wrapper. If not provided, the name will be ‘Tracked’ followed by the capitalized class name.

• methods (list of str) – List of class method names that should be taken into account in the tracking. Calls to any of these methods will increment the number of hits. The methods should be owned by the class itself, not by a parent class. The default list will track all methods which could possibly change a ‘list’ or a ‘dict’.

Returns:

class – A class wrapping the input class and tracking access to any of the specified methods. The class has an extra attribute ‘hits’ counting the number accesses to one of these methods. The hits attribute can be reset to zero to track changes after some breakpoint.