Aldict

Multi-key dictionary, supports adding and manipulating key-aliases pointing to shared values

How to use

• initialize with aliases
  (one-liner with aliases dict mapping original key to alias keys)

ad = AliasDict({"a": 1, "b": 2}, aliases={"a": ["aa", "aaa"], "b": "bb"})
assert ad["a"] == ad["aa"] == ad["aaa"] == 1
assert ad["b"] == ad["bb"] == 2

• add_alias
  (pass key as first parameter and alias(es) as variadic params, list or tuple)

ad = AliasDict({"a": 1, "b": 2})
ad.add_alias("a", "aa")
ad.add_alias("b", "bb", "Bbb")
ad.add_alias("a", ["aaa", "aaaa"])
ad.add_alias("b", ("bbb",))

assert ad["a"] == ad["aa"] == ad["aaa"] == ad["aaaa"] == 1
assert ad["b"] == ad["bb"] == ad["Bbb"] == ad["bbb"] == 2

• remove_alias
  (pass alias(es) to be removed as variadic params, list or tuple)

ad.remove_alias("aa")
ad.remove_alias("bb", "Bbb")
ad.remove_alias(["aaa", "aaaa"])
ad.remove_alias(("bbb",))
assert len(ad.aliases()) == 0

• clear_aliases
  (remove all aliases at once)

ad.clear_aliases()
assert len(ad.aliases()) == 0

• update alias
  (point alias to different key)

ad = AliasDict({"a": 1, "b": 2})
ad.add_alias("a", "ab")
assert list(ad.items()) == [('a', 1), ('b', 2), ('ab', 1)]

ad.add_alias("b", "ab")
assert list(ad.items()) == [('a', 1), ('b', 2), ('ab', 2)]

• read all aliases

ad = AliasDict({"a": 1, "b": 2})
ad.add_alias("a", "aa")
ad.add_alias("b", "bb", "B")
ad.add_alias("a", "ab", "A")
assert list(ad.aliases()) == ['aa', 'bb', 'B', 'ab', 'A']

• keys_with_aliases
  (read keys with corresponding alias(es))

assert dict(ad.keys_with_aliases()) == {'a': ['aa', 'ab', 'A'], 'b': ['bb', 'B']}

• read dictviews
  (dict.keys() and dict.items() include aliased versions)

ad = AliasDict({"x": 10, "y": 20})
ad.add_alias("x", "Xx")
ad.add_alias("y", "Yy", "xyz")

ad.keys()
ad.values()
ad.items()

# dict_keys(['x', 'y', 'Xx', 'Yy', 'xyz'])
# dict_values([10, 20])
# dict_items([('x', 10), ('y', 20), ('Xx', 10), ('Yy', 20), ('xyz', 20)])

• iterkeys
  (lazy iterator over all keys and aliases)

ad = AliasDict({"x": 10, "y": 20})
ad.add_alias("x", "Xx")

assert list(ad.iterkeys()) == ['x', 'y', 'Xx']

• iteritems
  (lazy iterator over all items including alias/value pairs)

assert list(ad.iteritems()) == [('x', 10), ('y', 20), ('Xx', 10)]

• remove key and aliases

ad.pop("y")
assert list(ad.items()) == [('x', 10), ('Xx', 10)]

• origin_len
  (get original dict length without aliases)

ad = AliasDict({"a": 1, "b": 2})
ad.add_alias("a", "aa")
assert list(ad.keys()) == ["a", "b", "aa"]
assert len(ad) == 3
assert ad.origin_len() == 2

• origin_keys
  (get original keys only)

assert list(ad.origin_keys()) == ['a', 'b']

• origin_key
  (get original key for an alias)

ad = AliasDict({"a": 1, "b": 2})
ad.add_alias("a", "aa")
assert ad.origin_key("aa") == "a"
assert ad.origin_key("a") is None  # not an alias

• is_alias
  (check if key is an alias)

ad = AliasDict({"a": 1, "b": 2})
ad.add_alias("a", "aa")
assert ad.is_alias("aa") is True
assert ad.is_alias("a") is False

• has_aliases
  (check if key has any aliases)

ad = AliasDict({"a": 1, "b": 2})
ad.add_alias("a", "aa")
assert ad.has_aliases("a") is True
assert ad.has_aliases("b") is False

• copy

ad = AliasDict({"a": 1, "b": 2})
ad.add_alias("a", "aa")
ad_copy = ad.copy()
assert ad_copy == ad
assert ad_copy is not ad

• merge with | and |= operators

ad1 = AliasDict({"a": 1}, aliases={"a": "aa"})
ad2 = AliasDict({"b": 2}, aliases={"b": "bb"})

merged = ad1 | ad2
assert merged["aa"] == 1
assert merged["bb"] == 2

ad1 |= {"c": 3}
assert ad1["c"] == 3

• fromkeys

ad = AliasDict.fromkeys(["a", "b", "c"], 0, aliases={"a": "aa"})
assert ad["a"] == ad["aa"] == 0