aldict 1.0.2__py3-none-any.whl → 1.1.0__py3-none-any.whl

aldict/__init__.py

@@ -1,3 +1,6 @@
 from .alias_dict import AliasDict as AliasDict
 from .exception import AliasError as AliasError
 from .exception import AliasValueError as AliasValueError
+
+__version__ = "1.1.0"
+__all__ = ["AliasDict", "AliasError", "AliasValueError"]

aldict/alias_dict.py

@@ -1,75 +1,118 @@
 from collections import UserDict, defaultdict
+from collections.abc import Mapping
+from itertools import chain
 
 from aldict.exception import AliasError, AliasValueError
 
 
 class AliasDict(UserDict):
-    """Custom Dict class supporting key-aliases pointing to shared values"""
+    """Dict with key-aliases pointing to shared values."""
 
-    def __init__(self, dict_):
+    def __init__(self, dict_=None, /, aliases=None):
         self._alias_dict = {}
-        super().__init__(**dict_)
+        if isinstance(dict_, AliasDict):
+            super().__init__(dict_.data)
+            self._alias_dict = dict(dict_._alias_dict)
+        else:
+            super().__init__(dict_)
+
+        if aliases:
+            for key, alias_list in aliases.items():
+                self.add_alias(key, alias_list)
 
     def add_alias(self, key, *aliases):
-        """Adds one or more aliases to specified key in the dictionary"""
-        if key not in self.data.keys():
+        """Add one or more aliases to a key. Accepts *args or a list/tuple."""
+        if key not in self.data:
             raise KeyError(key)
-        for alias in aliases:
+
+        for alias in self._unpack(aliases):
             if alias == key:
                 raise AliasValueError(f"Key and corresponding alias cannot be equal: '{key}'")
+            if alias in self.data:
+                raise AliasValueError(f"Alias '{alias}' already exists as a key in the dictionary")
             self._alias_dict[alias] = key
 
     def remove_alias(self, *aliases):
-        """Removes one or more aliases"""
-        for alias in aliases:
+        """Remove one or more aliases. Accepts *args or a list/tuple."""
+        for alias in self._unpack(aliases):
             try:
                 self._alias_dict.__delitem__(alias)
             except KeyError as e:
-                raise AliasError(alias) from e
+                raise AliasError(f"Alias '{alias}' not found") from e
+
+    @staticmethod
+    def _unpack(args):
+        return args[0] if len(args) == 1 and isinstance(args[0], (list, tuple)) else args
+
+    @classmethod
+    def fromkeys(cls, iterable, value=None, aliases=None):
+        """Create an AliasDict from an iterable of keys with optional aliases."""
+        return cls(dict.fromkeys(iterable, value), aliases=aliases)
+
+    def clear(self):
+        """Clear all data and aliases."""
+        super().clear()
+        self._alias_dict.clear()
 
     def clear_aliases(self):
-        """Removes all aliases"""
+        """Remove all aliases."""
         self._alias_dict.clear()
 
     def aliases(self):
-        """Returns all aliases present in the dictionary"""
+        """Return all aliases."""
         return self._alias_dict.keys()
 
-    def aliased_keys(self):
-        """Returns a dictview of all keys with their corresponding aliases"""
+    def is_alias(self, key):
+        """Return True if the key is an alias, False otherwise."""
+        return key in self._alias_dict
+
+    def has_aliases(self, key):
+        """Return True if the key has any aliases, False otherwise."""
+        return key in self._alias_dict.values()
+
+    def keys_with_aliases(self):
+        """Return keys with their aliases."""
         result = defaultdict(list)
         for alias, key in self._alias_dict.items():
             result[key].append(alias)
         return result.items()
 
     def origin_keys(self):
-        """Returns all keys"""
+        """Return original keys (without aliases)."""
         return self.data.keys()
 
+    def origin_key(self, alias):
+        """Return the original key for an alias, or None if not an alias."""
+        return self._alias_dict.get(alias)
+
     def keys(self):
-        """Returns all keys and aliases"""
+        """Return all keys and aliases."""
         return dict(**self.data, **self._alias_dict).keys()
+        # NB: could be optimized as 'return iter(self)' but we won't be able to call e.g. len(alias_dict.keys())
 
     def values(self):
-        """Returns all values"""
+        """Return all values."""
         return self.data.values()
 
     def items(self):
-        """Returns a dictview with all items (including alias/value tuples)"""
+        """Return all items (including alias/value pairs)."""
         return dict(**self.data, **{k: self.data[v] for k, v in self._alias_dict.items()}).items()
+        # NB: could be optimized as
+        #   'return chain(self.data.items(), ((k, self.data[v]) for k, v in self._alias_dict.items()))'
+        # (same as .keys() above)
 
     def origin_len(self):
-        """Returns the length of the original dictionary (without aliases)"""
+        """Return count of original keys (without aliases)."""
         return len(self.data)
 
     def __len__(self):
-        return len(self.keys())
+        return len(self.data) + len(self._alias_dict)
 
     def __missing__(self, key):
         try:
             return super().__getitem__(self._alias_dict[key])
-        except AttributeError as e:
-            raise KeyError(key) from e
+        except KeyError:
+            raise KeyError(key) from None
 
     def __setitem__(self, key, value):
         try:
@@ -81,25 +124,57 @@ class AliasDict(UserDict):
     def __delitem__(self, key):
         try:
             self.data.__delitem__(key)
-            self._alias_dict = {k: v for k, v in self._alias_dict.items() if v != key}
+            for alias in [k for k, v in self._alias_dict.items() if v == key]:
+                del self._alias_dict[alias]
         except KeyError:
-            # in case we try to delete alias via pop() or del
             return self.remove_alias(key)
 
     def __contains__(self, item):
-        return item in set(self.keys())
+        return item in self.data or item in self._alias_dict
 
     def __iter__(self):
-        for item in self.keys():
-            yield item
+        return chain(self.data, self._alias_dict)
+
+    def __reversed__(self):
+        return chain(reversed(self._alias_dict), reversed(self.data))
+
+    def copy(self):
+        """Return a shallow copy of the AliasDict."""
+        return type(self)(self)
 
     def __repr__(self):
-        return f"AliasDict({self.items()})"
+        return f"AliasDict({dict(self.items())})"
 
     def __eq__(self, other):
         if not isinstance(other, AliasDict):
-            raise TypeError(f"{other} is not an AliasDict")
+            return NotImplemented
         return self.data == other.data and self._alias_dict == other._alias_dict
 
-    def __hash__(self):
-        return hash((self.data, self._alias_dict))
+    def __or__(self, other):
+        if not isinstance(other, Mapping):
+            return NotImplemented
+        new = self.copy()
+        if isinstance(other, AliasDict):
+            new.update(other.data)
+            new._alias_dict.update(other._alias_dict)
+        else:
+            new.update(other)
+        return new
+
+    def __ror__(self, other):
+        if not isinstance(other, Mapping):
+            return NotImplemented
+        new = AliasDict(other)
+        new.update(self.data)
+        new._alias_dict.update(self._alias_dict)
+        return new
+
+    def __ior__(self, other):
+        if isinstance(other, AliasDict):
+            self.update(other.data)
+            self._alias_dict.update(other._alias_dict)
+        else:
+            self.update(other)
+        return self
+
+    __hash__ = None

{aldict-1.0.2.dist-info → aldict-1.1.0.dist-info}/METADATA

@@ -1,18 +1,13 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: aldict
-Version: 1.0.2
+Version: 1.1.0
 Summary: Multi-key dictionary, supports adding and manipulating key-aliases pointing to shared values
-Author-email: Kaloyan Ivanov <kaloyan.ivanov88@gmail.com>
-Project-URL: repository, https://github.com/kaliv0/aldict
 Keywords: multi-key dictionary,multidict,alias-dict
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
+Author-Email: kaliv0 <kaloyan.ivanov88@gmail.com>
 License-File: LICENSE
-Provides-Extra: dev
-Requires-Dist: pytest>=8.3.4; extra == "dev"
-Requires-Dist: ruff>=0.8.3; extra == "dev"
-Requires-Dist: build>=1.2.2; extra == "dev"
-Requires-Dist: twine>=6.0.1; extra == "dev"
+Project-URL: repository, https://github.com/kaliv0/aldict
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
 
 <p align="center">
   <img src="https://github.com/kaliv0/aldict/blob/main/assets/alter-ego.jpg?raw=true" width="250" alt="Alter Ego">
@@ -22,7 +17,7 @@ Requires-Dist: twine>=6.0.1; extra == "dev"
 # 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)
+![Python 3.x](https://img.shields.io/badge/python-^3.10-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)
 [![Downloads](https://static.pepy.tech/badge/aldict)](https://pepy.tech/projects/aldict)
@@ -32,20 +27,32 @@ Multi-key dictionary, supports adding and manipulating key-aliases pointing to s
 ---
 ## How to use
 
+- initialize with aliases
+<br>(one-liner with <i>aliases</i> dict mapping <i>key</i> to list of <i>aliases</i>)
+```python
+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
-<br>(pass <i>key</i> as first parameter and <i>alias(es)</i> as variadic params)
+<br>(pass <i>key</i> as first parameter and <i>alias(es)</i> as variadic params, list or tuple)
 ```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
+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
-<br>(pass <i>alias(es)</i> to be removed as variadic parameters)
+<br>(pass <i>alias(es)</i> to be removed as variadic params, list or tuple)
 ```python
 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
@@ -72,10 +79,10 @@ ad.add_alias("b", "bb", "B")
 ad.add_alias("a", "ab", "A")
 assert list(ad.aliases()) == ['aa', 'bb', 'B', 'ab', 'A']
 ```
-- aliased_keys
+- keys_with_aliases
 <br>(read <i>keys</i> with corresponding <i>alias(es)</i>)
 ```python
-assert dict(ad.aliased_keys()) == {'a': ['aa', 'ab', 'A'], 'b': ['bb', 'B']}
+assert dict(ad.keys_with_aliases()) == {'a': ['aa', 'ab', 'A'], 'b': ['bb', 'B']}
 ```
 - read dictviews
 <br>(<i>dict.keys()</i> and <i>dict.items()</i> include <i>aliased</i> versions)
@@ -87,11 +94,10 @@ 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)])
+
+# 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
@@ -112,3 +118,52 @@ assert list(ad.keys()) == ["a", "b", "aa"]
 assert len(ad) == 3
 assert ad.origin_len() == 2
 ```
+- copy
+```python
+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
+```python
+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
+```python
+ad = AliasDict.fromkeys(["a", "b", "c"], 0, aliases={"a": ["aa"]})
+assert ad["a"] == ad["aa"] == 0
+```
+- origin_key
+<br>(get original <i>key</i> for an <i>alias</i>)
+```python
+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
+<br>(check if <i>key</i> is an <i>alias</i>)
+```python
+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
+<br>(check if <i>key</i> has any <i>aliases</i>)
+```python
+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
+```

aldict-1.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+aldict-1.1.0.dist-info/METADATA,sha256=AzRxupLUAta9ULmLVV1adUjoMswf7f7obMq7m_IRZlI,4882
+aldict-1.1.0.dist-info/WHEEL,sha256=tsUv_t7BDeJeRHaSrczbGeuK-TtDpGsWi_JfpzD255I,90
+aldict-1.1.0.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+aldict-1.1.0.dist-info/licenses/LICENSE,sha256=frOVyHZrx5o-fh5xC-kggT3MaLdp6yxV_YGpVXFHFSQ,1071
+aldict/__init__.py,sha256=16jYDIi10e4UnbxjdFsssrt4dgUpsgb3h8cDD7U4EzQ,233
+aldict/alias_dict.py,sha256=O4EGRp-VtW1Mb-Fr1-_VDkPof6G9UBYYhx5l2I8FKck,5934
+aldict/exception.py,sha256=rFNmv9HuUOn2toPVYpVPQq6SOsl8nvwtJpGhPkK1puQ,83
+aldict-1.1.0.dist-info/RECORD,,

{aldict-1.0.2.dist-info → aldict-1.1.0.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.6.0)
+Generator: pdm-backend (2.4.6)
 Root-Is-Purelib: true
 Tag: py3-none-any
-

aldict-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+
+[gui_scripts]
+

aldict-1.0.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-aldict/__init__.py,sha256=0l5cJ5LuzCZhZfx-IOk2dEsq6nJQTShr6oGmufIa9i4,153
-aldict/alias_dict.py,sha256=j92SVd2RN1pzrClYhxhtdRIWAZ2_eVml3P4jcK4R890,3304
-aldict/exception.py,sha256=rFNmv9HuUOn2toPVYpVPQq6SOsl8nvwtJpGhPkK1puQ,83
-aldict-1.0.2.dist-info/LICENSE,sha256=frOVyHZrx5o-fh5xC-kggT3MaLdp6yxV_YGpVXFHFSQ,1071
-aldict-1.0.2.dist-info/METADATA,sha256=s-n_Y9mIdqTsWZvdlxkE0qH6YSbnN9DwCtw1TjmuM-g,3470
-aldict-1.0.2.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-aldict-1.0.2.dist-info/top_level.txt,sha256=pXwIKxRsbW2_Lh1HM-4cG2xE44RBzMz07GaY2EONV5M,7
-aldict-1.0.2.dist-info/RECORD,,

aldict-1.0.2.dist-info/top_level.txt

@@ -1 +0,0 @@
-aldict