expanded readme

Author: kaliv0

README.md

@@ -3,12 +3,86 @@
 </p>
 
 ---
-
 # Aldict
 
 [![tests](https://img.shields.io/github/actions/workflow/status/kaliv0/aldict/ci.yml)](https://github.com/kaliv0/aldict/actions/workflows/ci.yml)
 ![Python 3.x](https://img.shields.io/badge/python-^3.11-blue?style=flat-square&logo=Python&logoColor=white)
 [![PyPI](https://img.shields.io/pypi/v/aldict.svg)](https://pypi.org/project/aldict/)
 [![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](https://github.com/kaliv0/aldict/blob/main/LICENSE)
 
-Multi-key dictionary, supports adding and manipulating key-aliases pointing to shared values
+Multi-key dictionary, supports adding and manipulating key-aliases pointing to shared values
+
+---
+## How to use
+
+- add_alias
+<br>(pass <i>key</i> as first parameter and <i>alias(es)</i> as variadic params)
+```python
+ad = AliasDict({"a": 1, "b": 2})
+ad.add_alias("a", "aa")
+ad.add_alias("b", "bb", "Bbb")
+assert ad["a"] == ad["aa"] == 1
+assert ad["b"] == ad["bb"] == ad["Bbb"] == 2
+```
+- remove_alias
+<br>(pass <i>alias(es)</i> to be removed as variadic parameters)
+```python
+ad.remove_alias("aa")
+ad.remove_alias("bb", "Bbb")
+assert len(ad.aliases()) == 0
+```
+- clear_aliases
+<br>(remove all <i>aliases</i> at once)
+```python
+ad.clear_aliases()
+assert len(ad.aliases()) == 0
+```
+- update alias
+<br>(point <i>alias</i> to different <i>key</i>)
+```python
+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
+```python
+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']
+```
+- aliased_keys
+<br>(read <i>keys</i> with corresponding <i>alias(es)</i>)
+```python
+assert dict(ad.aliased_keys()) == {'a': ['aa', 'ab', 'A'], 'b': ['bb', 'B']}
+```
+- read dictviews
+<br>(<i>dict.keys()</i> and <i>dict.items()</i> include <i>aliased</i> versions)
+```python
+ad = AliasDict({"x": 10, "y": 20})
+ad.add_alias("x", "Xx")
+ad.add_alias("y", "Yy", "xyz")
+
+ad.keys()
+ad.values()
+ad.items()
+```
+```shell
+dict_keys(['x', 'y', 'Xx', 'Yy', 'xyz'])
+dict_values([10, 20])
+dict_items([('x', 10), ('y', 20), ('Xx', 10), ('Yy', 20), ('xyz', 20)])
+```
+- remove key and aliases
+```python
+ad.pop("y")
+assert list(ad.items()) == [('x', 10), ('Xx', 10)]
+```
+- origin_keys
+<br>(get original <i>keys</i> only)
+```python
+assert list(ad.origin_keys()) == ['x', 'y']
+```

aldict/alias_dict.py

@@ -22,8 +22,8 @@ def remove_alias(self, *aliases):
         for alias in aliases:
             try:
                 self._alias_dict.__delitem__(alias)
-            except KeyError:
-                raise AliasError(alias)
+            except KeyError as e:
+                raise AliasError(alias) from e
 
     def clear_aliases(self):
         self._alias_dict.clear()
@@ -52,8 +52,8 @@ def items(self):
     def __missing__(self, key):
         try:
             return super().__getitem__(self._alias_dict[key])
-        except AttributeError:
-            raise KeyError(key)
+        except AttributeError as e:
+            raise KeyError(key) from e
 
     def __setitem__(self, key, value):
         try:
@@ -77,6 +77,9 @@ def __iter__(self):
         for item in self.keys():
             yield item
 
+    def __len__(self):
+        return len(self.keys())
+
     def __repr__(self):
         return f"AliasDict({self.items()})"
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aldict"
-version = "0.1.0"
+version = "1.0.0"
 readme = "README.md"
 authors = [{ name = "Kaloyan Ivanov", email = "kaloyan.ivanov88@gmail.com" }]
 description = "Multi-key dictionary, supports adding and manipulating key-aliases pointing to shared values"

tests/test_alias_dict.py

@@ -189,9 +189,9 @@ def test_eq():
     assert ad_2 != ad_3
 
 
-def test_dict_len_doesnt_include_aliases(alias_dict):
+def test_dict_len_includes_aliases(alias_dict):
     assert list(alias_dict.keys()) == [".json", ".yaml", ".toml", ".yml"]
-    assert len(alias_dict) == 3
+    assert len(alias_dict) == 4
 
 
 def test_popitem(alias_dict):