Keys

Key

class trueq.Key(**kwargs)

A hashable unordered map, whose primary purpose is to be used as a bookkeeping object that enables fast and convenient subset lookups.

from trueq import Key

k1 = Key(apple=0, banana=1)
k2 = Key(banana=1, apple=0)
print(k1 == k2)  # True

True
Parameters:

**kwargs – key/value pairs to store in the Key.

match(**filter)

Returns True whenever all of the given filter keys exist as names in this Key, and all the given filter values match this Key's corresponding values. A match occurs if the values are equal, or if a value in the filter is set and the Keys value is in the set.

Given a keyword in the filter and an identical keyword in a Key, three types of matching are supported for their values:

  1. Exact value matching, e.g. keyword="hello" matches keyword="hello".

  2. “Any of” value matching with set notation, e.g. keyword={"hello", "hi there"} matches keyword="hello".

  3. “Not any of” value matching with list notation, e.g. keyword=["bye", "ciao"] matches keyword="hello".

from trueq import Key

k = Key(apple=0, banana=1)

print(k.match(cranberry=1))  # False
print(k.match(apple=0))  # True
print(k.match(apple=0, banana=0))  # False
print(k.match(apple=0, banana=1))  # True
print(k.match(apple={0, 1, 2}))  # True
print(k.match(apple=[0, 1, 2]))  # False

False
True
False
True
True
False
Parameters:

**filter – A filter to apply to the Key to match based on key/value pair(s).

Return type:

bool

static compile_filter(filter)

Hashes key-value pairs in the filter and returns an object that allows hash_match() to quickly check if it matches the filter. This will give identical results but better performance than match() when the same filter needs to be applied to many keys.

Given a keyword in the filter and an identical keyword in a Key, three types of matching are supported for their values:

  1. Exact value matching, e.g. keyword="hello" matches keyword="hello".

  2. “Any of” value matching with set notation, e.g. keyword={"hello", "hi there"} matches keyword="hello".

  3. “Not any of” value matching with list notation, e.g. keyword=["bye", "ciao"] matches keyword="hello".

import trueq as tq

k = tq.Key(apples=0, bananas=2, kiwis=3)

# this equality will always be True
k.match(apples=0) == k.hash_match(*tq.Key.compile_filter({"apples": 0}))

True
Parameters:

**filter – Key/value pairs to be used as a filter.

Returns:

A triple as described by hash_match().

Return type:

tuple

hash_match(must_have, any_of, cannot_have)

A lower-level interface to Key.match() where hashes of key-value pairs are passed in, instead of the key-value pairs themselves. See also compile_filter().

Parameters:

  • must_have – An iterable of hashes that this key must contain to return True.

  • any_of – An iterable of iterables. For each inner iterable, at least one of the hashes must match something in this key’s hashset in order for this method to return True.

  • cannot_have – An iterable of hashes, which cannot intersect with the hashset of this key in order for this method to return True.

Return type:

bool

property names

The names of this Key.

Type:

tuple

property values

The values of this Key.

Type:

tuple

property items

Returns a tuple containing (name, value) pairs

Type:

tuple

get(name, *default)

Gets the value corresponding to the given name.

Parameters:

  • name (str) – A name present in this Key.

  • *default – A value to return if the name is not found.

Raises:

  • ValueError – If more than one default value is provided.

  • AttributeError – If the name is not found, and the default is not provided.

to_dict()

Returns a dictionary representation of a py:class:trueq.Key object.

Return type:

dict

static from_dict(dic)

Returns a py:class:trueq.Key constructed from a dictionary representation.

Parameters:

dic (dict) – A dictionary used to construct a new py:class:trueq.Key.

Return type:

trueq.Key

copy(*other, keep=None, remove=None, **kwargs)

Returns a copy of this key with specified modifications. A subset of existing items of this key are first, optionally, kept or removed. Following this, new items are added or updated based on one or more Key-likes or kwargs.

from trueq import Key

# copy with no changes
copy = Key(apple=5, coffee=True).copy()
print(1, copy)

# copy keeping only some names
copy = Key(apple=5, coffee=True).copy(keep="coffee")
print(2, copy)

# copy and remove some names
copy = Key(apple=5, coffee=True, strength=5.2).copy(remove="apple")
print(3, copy)

# copy and update/add values with kwargs
copy = Key(apple=5, coffee=True).copy(banana=2, coffee=False)
print(4, copy)

# copy and update/add values with another Key
copy = Key(apple=5, coffee=True).copy(Key(banana=2), coffee=10)
print(5, copy)

# remove and update/add at the same time
key = Key(apple=5, banana=2, coffee=True)
copy = key.copy(Key(apple=2), remove="coffee", strength=5.2)
print(6, copy)

1 Key(apple=5, coffee=True)
2 Key(coffee=True)
3 Key(coffee=True, strength=5.2)
4 Key(apple=5, coffee=False, banana=2)
5 Key(apple=5, coffee=10, banana=2)
6 Key(apple=2, banana=2, strength=5.2)
Parameters:

  • other (Key | dict) – One or more dict-like objects to update the copy with. Updating is applied in the given order. If a name specified in any of these objects already exists after the keep or remove process has taken place, it is updated.

  • keep (str | list) – A string or list of strings specifying the only names to keep during the copy. By default, all names are kept. Only one of the options keep or remove may be used.

  • remove (str | list) – A string or list of strings specifying names to remove during the copy. By default, no names are removed. Only one of the options keep or remove may be used.

  • **kwargs – Name-value items to update the copy with. If a name specified here already exists after the keep or remove process has taken place, it is updated.

Return type:

Key

Raises:

ValueError – If the mutally exclusive keep and remove are both set to True.

KeySet

class trueq.KeySet(*keysets)

An immutable set of Keys, with the feature of fancy attribute fetching; when asked for an attribute whose name is present in at least one of the keys, a set is returned containing all values of keys corresponding to that name.

from trueq import KeySet, Key

KeySet(Key(fruit="apple", n=1), [Key(fruit="banana"), Key(fruit="kiwi", n=3)])
True-Q formatting will not be loaded without trusting this notebook or rerunning the affected cells. Notebooks can be marked as trusted by clicking "File -> Trust Notebook".
KeySet
List of all the keys in the KeySet
 fruit n
Key
Key:
  • fruit: apple
  • n: 1
 apple 1
Key
Key:
  • fruit: banana
 banana
Key
Key:
  • fruit: kiwi
  • n: 3
 kiwi 3
Parameters:

*keysets – Any mixture of Keys and iterables of Keys. Note that for efficiency, no type checking is done on the input.

property names

A set of the names present in all Key objects in the KeySet.

Type:

set

one_or_none(name)

If the given name exists in this KeySet and contains exactly one value, returns that value. Otherwise, None is returned.

Parameters:

name (str) – The name to look for.

Return type:

NoneType | object

subset(**filter)

Returns all Key objects in the KeySet which match the keyword arguments provided. See Key.match() for details on how matches work.

Parameters:

**filter – A filter applied to the KeySet, which matches Keys based on the filter’s key/value pair.

Return type:

KeySet

similar_keys(*names, invert=False, **filter)

Returns a generator over disjoint KeySets, where all of the keys in each set have equal values for all names appearing in the given names, and have any specific values specified in filter.

from trueq import KeySet, Key

all_keys = KeySet(Key(a=4, b="x"), Key(a=10, b="y"), Key(a=10, b="x"))
for keys in all_keys.similar_keys("a"):
    print(keys)

KeySet(
	Key(a=10, b='y'),
	Key(a=10, b='x'))
KeySet(
	Key(a=4, b='x'))
Parameters:

  • names – An iterable of names.

  • invert (bool) – Whether the list of names to use should be those presented, or all names except those presented. It does not apply to the filter.

  • **filter – A filter to apply to the KeySet before the process of finding disjoint subsets begins.

Return type:

generator

copy(*other, keep=None, remove=None, **kwargs)

Returns a copy of this keyset by calling Key.copy() on every key.

Parameters:

  • other (Key | dict) – One or more dict-like objects to update the copies with. Updating is applied in the given order. If a name specified in any of these objects already exists after the keep or remove process has taken place, it is updated.

  • keep (str | list) – A string or list of strings specifying the only names to keep during the copying. By default, all names are kept. Only one of the options keep or remove may be used.

  • remove (str | list) – A string or list of strings specifying names to remove during copying. By default, no names are removed. Only one of the options keep or remove may be used.

  • **kwargs – Name-value items to update the copies with. If a name specified here already exists after the keep or remove process has taken place, it is updated.

Return type:

KeySet

Raises:

ValueError – If the mutally exclusive keep and remove are both set to True.

sorted(*names)

Sorts this set lexicographically by value, using this set’s sorted names as the order to place values in. This order of names can be overridden by providing one or more names that you would like to appear first.

Parameters:

*names – One or more name strings that should take priority in sorting.

Returns:

A list of sorted Keys.

Return type:

list

table(row_name, col_name)

Sorts this KeySet into a table where all of the rows share the same value of row_name, and all of the columns share the same value of col_name. Keys that do not contain both of these attributes are omitted from the returned table. Every element of the table is a new KeySet that share the corresponding row and column value; these sets can contain zero or many elements. Rows and columns are sorted by their value, if possible.

Parameters:

  • row_name (str) – A name present in this key set for indexing the rows of the resultant table.

  • col_name (str) – A name present in this key set for indexing the columns of the resultant table.

Returns:

A triple rows, columns, table where table is a list of lists of key sets as described above, rows is a list of the values of row_name for each row, and columns is a list of the values of col_name for each column.

Return type:

tuple