Keys

Key

class trueq.Key(**kwargs)

A hashable unordered map, whose primary purpose is to be used as a bookkeeping object that enable 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

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=4, b='x'))
KeySet(
	Key(a=10, b='y'),
	Key(a=10, 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 (str) – One or more names that should take priority in sorting.

Returns

A list of sorted Keys.

Return type

list