xloft 0.1.19__py3-none-any.whl → 0.10.10__py3-none-any.whl

xloft/{namedtuple.py → types/named_tuple.py}

@@ -1,255 +1,240 @@
-"""This module contains the implementation of the `NamedTuple` class.
-
-`NamedTuple` class imitates the behavior of the _named tuple_.
-
-Examples:
-    >>> from xloft import NamedTuple
-    >>> nt = NamedTuple(x=10, y="Hello", _id="507c7f79bcf86cd7994f6c0e")
-    >>> nt.x
-    10
-    >>> nt.y
-    Hello
-    >>> nt._id
-    507c7f79bcf86cd7994f6c0e
-    >>> nt.z
-    KeyError
-    >>> len(nt)
-    3
-    >>> nt.keys()
-    ["x", "y", "_id"]
-    >>> nt.values()
-    [10, "Hello", "507c7f79bcf86cd7994f6c0e"]
-    >>> nt.has_key("x")
-    True
-    >>> nt.has_key("z")
-    False
-    >>> nt.has_value(10)
-    True
-    >>> nt.has_value([1, 2, 3])
-    False
-    >>> nt.get("x")
-    10
-    >>> nt.get("z")
-    None
-    >>> d = nt.to_dict()
-    >>> d["x"]
-    10
-    >>> for key, val in nt.items():
-    ...     print(f"Key: {key}, Value: {val}")
-    "Key: x, Value: 10"
-    "Key: y, Value: Hello"
-    "Key: _id, value: 507c7f79bcf86cd7994f6c0e"
-    >>> nt.update("x", 20)
-    >>> nt.x
-    20
-    >>> nt.update("z", [1, 2, 3])
-    KeyError
-    >>> nt["z"] = [1, 2, 3]
-    TypeError
-    >>> nt.x = 20
-    Error: AttributeDoesNotSetValue
-    >>> del nt.x
-    Error: AttributeCannotBeDelete
-"""
-
-from typing import Any
-
-from xloft.errors import (
-    AttributeCannotBeDelete,
-    AttributeDoesNotSetValue,
-)
-
-
-class NamedTuple:
-    """This class imitates the behavior of the _named tuple_."""
-
-    def __init__(self, **kwargs: dict[str, Any]) -> None:  # noqa: D107
-        self.__dict__["_jWjSaNy1RbtQinsN_keys"] = []
-        for name, value in kwargs.items():
-            self.__dict__[name] = value
-            self._jWjSaNy1RbtQinsN_keys.append(name)
-
-    def __len__(self) -> int:
-        """Get the number of elements.
-
-        Examples:
-            >>> from xloft import NamedTuple
-            >>> nt = NamedTuple(x=10, y="Hello")
-            >>> len(nt)
-            2
-
-        Returns:
-            The number of elements in the tuple.
-        """
-        return len(self._jWjSaNy1RbtQinsN_keys)
-
-    def __getattr__(self, name: str) -> Any:
-        """Getter.
-
-        Examples:
-            >>> from xloft import NamedTuple
-            >>> nt = NamedTuple(x=10, y="Hello")
-            >>> nt.x
-            10
-
-        Args:
-            name: Key name.
-
-        Returns:
-            Value of key.
-        """
-        return self.__dict__[name]
-
-    def __setattr__(self, name: str, value: Any) -> None:
-        """Blocked Setter."""
-        raise AttributeDoesNotSetValue(name)
-
-    def __delattr__(self, name: str) -> None:
-        """Blocked Deleter."""
-        raise AttributeCannotBeDelete(name)
-
-    def get(self, key: str) -> Any:
-        """Return the value for key if key is in the dictionary, else `None`.
-
-        Args:
-            key: Key name.
-
-        Examples:
-            >>> from xloft import NamedTuple
-            >>> nt = NamedTuple(x=10, y="Hello")
-            >>> nt.get("x")
-            10
-
-        Returns:
-            Value of key.
-        """
-        value = self.__dict__.get(key)
-        if value is not None:
-            return value
-        return None
-
-    def update(self, key: str, value: Any) -> None:
-        """Update a value of key.
-
-        Attention: This is an uncharacteristic action for the type `tuple`.
-
-        Args:
-            key: Key name.
-            value: Value of key.
-
-        Examples:
-            >>> from xloft import NamedTuple
-            >>> nt = NamedTuple(x=10, y="Hello")
-            >>> nt.update("x", 20)
-            >>> nt.x
-            20
-
-        Returns:
-            None
-        """
-        keys: list[str] = self._jWjSaNy1RbtQinsN_keys
-        if key not in keys:
-            err_msg = f"The key `{key}` is missing!"
-            raise KeyError(err_msg)
-        self.__dict__[key] = value
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to the dictionary.
-
-        Examples:
-            >>> from xloft import NamedTuple
-            >>> nt = NamedTuple(x=10, y="Hello")
-            >>> d = nt.to_dict()
-            >>> d["x"]
-            10
-
-        Returns:
-            Dictionary with keys and values of the tuple.
-        """
-        attrs: dict[str, Any] = self.__dict__
-        keys: list[str] = self._jWjSaNy1RbtQinsN_keys
-        return {key: attrs[key] for key in keys}
-
-    def items(self) -> list[tuple[str, Any]]:
-        """Return a set-like object providing a view on the NamedTuple's items.
-
-        Examples:
-            >>> from xloft import NamedTuple
-            >>> nt = NamedTuple(x=10, y="Hello")
-            >>> for key, val in nt.items():
-            ...     print(f"Key: {key}, Value: {val}")
-            "Key: x, Value: 10"
-            "Key: y, Value: Hello"
-
-        Returns:
-            list[tuple[str, Any]]
-        """
-        attrs: dict[str, Any] = self.__dict__
-        keys: list[str] = self._jWjSaNy1RbtQinsN_keys
-        return [(key, attrs[key]) for key in keys]
-
-    def keys(self) -> list[str]:
-        """Get a list of keys.
-
-        Examples:
-            >>> from xloft import NamedTuple
-            >>> nt = NamedTuple(x=10, y="Hello")
-            >>> nt.keys()
-            ["x", "y"]
-
-        Returns:
-            List of keys.
-        """
-        return self._jWjSaNy1RbtQinsN_keys
-
-    def values(self) -> list[Any]:
-        """Get a list of values.
-
-        Examples:
-            >>> from xloft import NamedTuple
-            >>> nt = NamedTuple(x=10, y="Hello")
-            >>> nt.values()
-            [10, "Hello"]
-
-        Returns:
-            List of values.
-        """
-        attrs: dict[str, Any] = self.__dict__
-        keys: list[str] = self._jWjSaNy1RbtQinsN_keys
-        return [attrs[key] for key in keys]
-
-    def has_key(self, key: str) -> bool:
-        """Returns True if the key exists, otherwise False.
-
-        Args:
-            key: Key name.
-
-        Examples:
-            >>> from xloft import NamedTuple
-            >>> nt = NamedTuple(x=10, y="Hello")
-            >>> nt.has_key("x")
-            True
-
-        Returns:
-            True if the key exists, otherwise False.
-        """
-        keys: list[str] = self._jWjSaNy1RbtQinsN_keys
-        return key in keys
-
-    def has_value(self, value: Any) -> bool:
-        """Returns True if the value exists, otherwise False.
-
-        Args:
-            value: Value of key.
-
-        Examples:
-            >>> from xloft import NamedTuple
-            >>> nt = NamedTuple(x=10, y="Hello")
-            >>> nt.has_value(10)
-            True
-
-        Returns:
-            True if the value exists, otherwise False.
-        """
-        values = self.values()
-        return value in values
+# XLOFT - X-Library of tools.
+# Copyright (c) 2025 Gennady Kostyunin
+# SPDX-License-Identifier: MIT
+"""`NamedTuple` - Imitates the behavior of the *named tuple*.
+
+Class `NamedTuple` contains the following methods:
+
+- `get` - Return the value for key if key is in the dictionary, else `None`.
+- `update` - Update a value of key.
+- `to_dict` - Convert to the dictionary.
+- `items` - Returns a generator of list of `NamedTuple` elements grouped into tuples.
+- `keys` - Get a generator of list of keys.
+- `values` - Get a generator of list of values.
+- `has_key` - Returns True if the key exists, otherwise False.
+- `has_value` - Returns True if the value exists, otherwise False.
+"""
+
+from __future__ import annotations
+
+__all__ = ("NamedTuple",)
+
+import copy
+from typing import Any
+
+from xloft.errors import (
+    AttributeCannotBeDeleteError,
+    AttributeDoesNotSetValueError,
+)
+
+
+class NamedTuple:
+    """This class imitates the behavior of the `named tuple`."""
+
+    def __init__(self, **kwargs: dict[str, Any]) -> None:  # noqa: D107
+        self.__dict__["_store"] = kwargs
+
+    def __len__(self) -> int:
+        """Get the number of elements in the tuple.
+
+        Examples:
+            >>> from xloft import NamedTuple
+            >>> nt = NamedTuple(x=10, y="Hello")
+            >>> len(nt)
+            2
+
+        Returns:
+            The number of elements in the tuple.
+        """
+        return len(self._store)
+
+    def __getattr__(self, name: str) -> Any:
+        """Getter.
+
+        Examples:
+            >>> from xloft import NamedTuple
+            >>> nt = NamedTuple(x=10, y="Hello")
+            >>> nt.x
+            10
+
+        Args:
+            name: Key name.
+
+        Returns:
+            Value of key.
+        """
+        return self._store[name]
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Blocked Setter."""
+        raise AttributeDoesNotSetValueError(name)
+
+    def __delattr__(self, name: str) -> None:
+        """Blocked Deleter."""
+        raise AttributeCannotBeDeleteError(name)
+
+    def __getitem__(self, key: str) -> Any:
+        """Get value by [key_name].
+
+        Args:
+            key: Key name.
+
+        Examples:
+            >>> from xloft import NamedTuple
+            >>> nt = NamedTuple(x=10, y="Hello")
+            >>> nt["x"]
+            10
+
+        Returns:
+            Deep copy of the value associated with the key.
+        """
+        value = self._store[key]
+        return copy.deepcopy(value)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Return the value for key if key is in the dictionary, else `None`.
+
+        Args:
+            key: Key name.
+
+        Examples:
+            >>> from xloft import NamedTuple
+            >>> nt = NamedTuple(x=10, y="Hello")
+            >>> nt.get("x")
+            10
+
+        Returns:
+            Deep copy of the value associated with the alias or value by default.
+        """
+        value = self._store.get(key)
+        if value is not None:
+            return copy.deepcopy(value)
+        return default
+
+    def update(self, key: str, value: Any) -> None:
+        """Update a value of key.
+
+        Attention: This is an uncharacteristic action for the type `tuple`.
+
+        Args:
+            key: Key name.
+            value: Value of key.
+
+        Examples:
+            >>> from xloft import NamedTuple
+            >>> nt = NamedTuple(x=10, y="Hello")
+            >>> nt.update("x", 20)
+            >>> nt.x
+            20
+
+        Returns:
+            None
+        """
+        keys: list[str] = self._store.keys()
+        if key not in keys:
+            err_msg = f"The key `{key}` is missing!"
+            raise KeyError(err_msg)
+        self._store[key] = value
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to the dictionary.
+
+        Examples:
+            >>> from xloft import NamedTuple
+            >>> nt = NamedTuple(x=10, y="Hello")
+            >>> d = nt.to_dict()
+            >>> d["x"]
+            10
+
+        Returns:
+            Dictionary with keys and values of the tuple.
+        """
+        return dict(self._store)
+
+    def items(self) -> Any:
+        """Returns a generator of list containing a tuple for each key-value pair.
+
+        This is convenient for use in a `for` loop.
+        If you need to get a list, do it list(instance.items()).
+
+        Examples:
+            >>> from xloft import NamedTuple
+            >>> nt = NamedTuple(x=10, y="Hello")
+            >>> for key, val in nt.items():
+            ...     print(f"Key: {key}, Value: {val}")
+            "Key: x, Value: 10"
+            "Key: y, Value: Hello"
+
+        Returns:
+            Returns a list containing a tuple for each key-value pair.
+            Type: `list[tuple[str, Any]]`.
+        """
+        return self._store.items()
+
+    def keys(self) -> Any:
+        """Get a generator of list of keys.
+
+        If you need to get a list, do it list(instance.items()).
+
+        Examples:
+            >>> from xloft import NamedTuple
+            >>> nt = NamedTuple(x=10, y="Hello")
+            >>> list(nt.keys())
+            ["x", "y"]
+
+        Returns:
+            List of keys.
+        """
+        return self._store.keys()
+
+    def values(self) -> Any:
+        """Get a generator of list of values.
+
+        If you need to get a list, do it list(instance.items()).
+
+        Examples:
+            >>> from xloft import NamedTuple
+            >>> nt = NamedTuple(x=10, y="Hello")
+            >>> list(nt.values())
+            [10, "Hello"]
+
+        Returns:
+            List of values.
+        """
+        return self._store.values()
+
+    def has_key(self, key: str) -> bool:
+        """Check if the key exists.
+
+        Args:
+            key: Key name.
+
+        Examples:
+            >>> from xloft import NamedTuple
+            >>> nt = NamedTuple(x=10, y="Hello")
+            >>> nt.has_key("x")
+            True
+
+        Returns:
+            True if the key exists, otherwise False.
+        """
+        keys = self._store.keys()
+        return key in keys
+
+    def has_value(self, value: Any) -> bool:
+        """Check if the value exists.
+
+        Args:
+            value: Value of key.
+
+        Examples:
+            >>> from xloft import NamedTuple
+            >>> nt = NamedTuple(x=10, y="Hello")
+            >>> nt.has_value(10)
+            True
+
+        Returns:
+            True if the value exists, otherwise False.
+        """
+        values = self._store.values()
+        return value in values