ducks.mutable package


ducks.mutable.main module

class ducks.mutable.main.Dex(objs: Iterable[Any] | None = None, on: Iterable[str | Callable] | None = None)

Bases: object

__getitem__(query: Dict) List[Any]

Find objects in the Dex that satisfy the constraints.



Dict of {attribute: expression} defining the subset of objects that match. If {}, all objects will match.

Each attribute is a string or Callable. Must be one of the attributes specified in the constructor.

The expression can be any of the following:
  • A dict of {operator: value}, such as {'==': 1} {'>': 5}, or {'in': [1, 2, 3]}.

  • A single value, which is a shorthand for {‘==’: value}.

  • A list of values, which is a shorthand for {'in': [list_of_values]}.

The expression {'==': ducks.ANY} will match all objects having the attribute. The expression {'!=': ducks.ANY} will match all objects without the attribute.

Valid operators are ‘==’, ‘!=’, ‘in’, ‘not in’, ‘<’, ‘<=’, ‘>’, ‘>=’. The aliases ‘eq’, ‘ne’, ‘lt’, ‘le’, ‘lte’, ‘gt’, ‘ge’, and ‘gte’ work too. To match a None value, use {'==': None}. There is no separate operator for None values.


List of objects matching the constraints. List will be unordered.

__init__(objs: Iterable[Any] | None = None, on: Iterable[str | Callable] | None = None)

Create a Dex containing the objs, queryable by the on attributes.

  • objs – The objects that Dex will contain initially. Optional.

  • on – The attributes that will be used for finding objects. Must contain at least one.

It’s OK if the objects in objs are missing some or all of the attributes in on.

For the objects that do contain the attributes in on, those attribute values must be hashable and sortable. Most Python objects are hashable. Implement the function __lt__(self, other) to make a class sortable. An attribute value of None is acceptable as well, even though None is not sortable.

add(obj: Any)

Add the object, evaluating any attributes and storing the results. If the object is already present, it will not be updated.

get_values(attr: str | Callable) Set

Get the unique values we have for the given attribute.


attr – The attribute to get values for.


Set of all unique values for this attribute.

remove(obj: Any)

Remove the object. Raises KeyError if not present.

update(obj: Any)

Remove and re-add the object, updating all stored attributes. Raises KeyError if object not present.

ducks.mutable.main.load(saved: Dict) Dex

Creates a Dex from the pickle file. Dex, filepath: str)

Saves this object to a pickle file.

ducks.mutable.mutable_attr module

class ducks.mutable.mutable_attr.MutableAttrIndex(attr: Callable | str, objs: Iterable[Any] | None = None)

Bases: object

Stores data and handles requests that are relevant to a single attribute of a Dex.

__init__(attr: Callable | str, objs: Iterable[Any] | None = None)
add(ptr: int, obj: Any)

Add an object if it has this attribute.

get_all_ids() Int64Set

Get the ID of every object that has this attribute. Called when matching or excluding {attr: hashindex.ANY}.

get_ids_by_range(expr: Dict[str, Any])

Get object IDs based on less than / greater than some value

get_obj_ids(val: Any) Int64Set

Get the object IDs associated with this value as an Int64Set.

get_values() Set

Get unique values we have objects for.

remove(ptr: int, obj: Any)

Remove a single object from the index. ptr is already known to be in the Dex. Runs in O(1) if obj has this attr and the value of the attr hasn’t changed. O(n_keys) otherwise.

Module contents