scruby 0.9.3__py3-none-any.whl → 0.27.2__py3-none-any.whl

scruby/db.py

@@ -1,301 +1,213 @@
-"""Creation and management of the database."""
-
-from __future__ import annotations
-
-__all__ = ("Scruby",)
-
-import concurrent.futures
-import contextlib
-import logging
-import zlib
-from collections.abc import Callable
-from pathlib import Path as SyncPath
-from shutil import rmtree
-from typing import Any, Never, TypeVar, assert_never
-
-import orjson
-from anyio import Path, to_thread
-
-from scruby import constants
-
-logger = logging.getLogger(__name__)
-
-T = TypeVar("T")
-
-
-class Scruby[T]:
-    """Creation and management of database.
-
-    Args:
-        class_model: Class of Model (Pydantic).
-    """
-
-    def __init__(  # noqa: D107
-        self,
-        class_model: T,
-    ) -> None:
-        self.__class_model = class_model
-        self.__db_root = constants.DB_ROOT
-        self.__length_reduction_hash = constants.LENGTH_REDUCTION_HASH
-        # The maximum number of keys.
-        match self.__length_reduction_hash:
-            case 0:
-                self.__max_num_keys = 4294967296
-            case 2:
-                self.__max_num_keys = 16777216
-            case 4:
-                self.__max_num_keys = 65536
-            case 6:
-                self.__max_num_keys = 256
-            case _ as unreachable:
-                msg: str = f"{unreachable} - Unacceptable value for LENGTH_REDUCTION_HASH."
-                logger.critical(msg)
-                assert_never(Never(unreachable))
-
-    async def get_leaf_path(self, key: str) -> Path:
-        """Asynchronous method for getting path to collection cell by key.
-
-        Args:
-            key: Key name.
-        """
-        if not isinstance(key, str):
-            logger.error("The key is not a type of `str`.")
-            raise KeyError("The key is not a type of `str`.")
-        if len(key) == 0:
-            logger.error("The key should not be empty.")
-            raise KeyError("The key should not be empty.")
-        # Key to crc32 sum.
-        key_as_hash: str = f"{zlib.crc32(key.encode('utf-8')):08x}"[self.__length_reduction_hash :]
-        # Convert crc32 sum in the segment of path.
-        separated_hash: str = "/".join(list(key_as_hash))
-        # The path of the branch to the database.
-        branch_path: Path = Path(
-            *(
-                self.__db_root,
-                self.__class_model.__name__,
-                separated_hash,
-            ),
-        )
-        # If the branch does not exist, need to create it.
-        if not await branch_path.exists():
-            await branch_path.mkdir(parents=True)
-        # The path to the database cell.
-        leaf_path: Path = Path(*(branch_path, "leaf.json"))
-        return leaf_path
-
-    async def set_key(
-        self,
-        key: str,
-        value: T,
-    ) -> None:
-        """Asynchronous method for adding and updating keys to collection.
-
-        Args:
-            key: Key name.
-            value: Value of key.
-        """
-        # The path to the database cell.
-        leaf_path: Path = await self.get_leaf_path(key)
-        value_json: str = value.model_dump_json()
-        # Write key-value to the database.
-        if await leaf_path.exists():
-            # Add new key or update existing.
-            data_json: bytes = await leaf_path.read_bytes()
-            data: dict = orjson.loads(data_json) or {}
-            data[key] = value_json
-            await leaf_path.write_bytes(orjson.dumps(data))
-        else:
-            # Add new key to a blank leaf.
-            await leaf_path.write_bytes(orjson.dumps({key: value_json}))
-
-    async def get_key(self, key: str) -> T:
-        """Asynchronous method for getting value of key from collection.
-
-        Args:
-            key: Key name.
-        """
-        # The path to the database cell.
-        leaf_path: Path = await self.get_leaf_path(key)
-        # Get value of key.
-        if await leaf_path.exists():
-            data_json: bytes = await leaf_path.read_bytes()
-            data: dict = orjson.loads(data_json) or {}
-            obj: T = self.__class_model.model_validate_json(data[key])
-            return obj
-        msg: str = "`get_key` - The unacceptable key value."
-        logger.error(msg)
-        raise KeyError()
-
-    async def has_key(self, key: str) -> bool:
-        """Asynchronous method for checking presence of key in collection.
-
-        Args:
-            key: Key name.
-        """
-        # The path to the database cell.
-        leaf_path: Path = await self.get_leaf_path(key)
-        # Checking whether there is a key.
-        if await leaf_path.exists():
-            data_json: bytes = await leaf_path.read_bytes()
-            data: dict = orjson.loads(data_json) or {}
-            try:
-                data[key]
-                return True
-            except KeyError:
-                return False
-        return False
-
-    async def delete_key(self, key: str) -> None:
-        """Asynchronous method for deleting key from collection.
-
-        Args:
-            key: Key name.
-        """
-        # The path to the database cell.
-        leaf_path: Path = await self.get_leaf_path(key)
-        # Deleting key.
-        if await leaf_path.exists():
-            data_json: bytes = await leaf_path.read_bytes()
-            data: dict = orjson.loads(data_json) or {}
-            del data[key]
-            await leaf_path.write_bytes(orjson.dumps(data))
-            return
-        msg: str = "`delete_key` - The unacceptable key value."
-        logger.error(msg)
-        raise KeyError()
-
-    @staticmethod
-    async def napalm() -> None:
-        """Asynchronous method for full database deletion.
-
-        The main purpose is tests.
-
-        Warning:
-            - `Be careful, this will remove all keys.`
-        """
-        with contextlib.suppress(FileNotFoundError):
-            await to_thread.run_sync(rmtree, constants.DB_ROOT)
-        return
-
-    @staticmethod
-    def search_task(
-        key: int,
-        filter_fn: Callable,
-        length_reduction_hash: str,
-        db_root: str,
-        class_model: T,
-    ) -> dict[str, Any] | None:
-        """Search task."""
-        key_as_hash: str = f"{key:08x}"[length_reduction_hash:]
-        separated_hash: str = "/".join(list(key_as_hash))
-        leaf_path: SyncPath = SyncPath(
-            *(
-                db_root,
-                class_model.__name__,
-                separated_hash,
-                "leaf.json",
-            ),
-        )
-        if leaf_path.exists():
-            data_json: bytes = leaf_path.read_bytes()
-            data: dict[str, str] = orjson.loads(data_json) or {}
-            for _, val in data.items():
-                doc = class_model.model_validate_json(val)
-                if filter_fn(doc):
-                    return doc
-        return None
-
-    def find_one(
-        self,
-        filter_fn: Callable,
-        max_workers: int | None = None,
-        timeout: float | None = None,
-    ) -> T | None:
-        """Find a single document matching the filter.
-
-        The search is based on the effect of a quantum loop.
-        The search effectiveness depends on the number of processor threads.
-        Ideally, hundreds and even thousands of threads are required.
-
-        Args:
-            filter_fn: A function that execute the conditions of filtering.
-            max_workers: The maximum number of processes that can be used to
-                         execute the given calls. If None or not given then as many
-                         worker processes will be created as the machine has processors.
-            timeout: The number of seconds to wait for the result if the future isn't done.
-                     If None, then there is no limit on the wait time.
-        """
-        keys: range = range(1, self.__max_num_keys)
-        search_task_fn: Callable = self.search_task
-        length_reduction_hash: int = self.__length_reduction_hash
-        db_root: str = self.__db_root
-        class_model: T = self.__class_model
-        with concurrent.futures.ThreadPoolExecutor(max_workers) as executor:
-            for key in keys:
-                future = executor.submit(
-                    search_task_fn,
-                    key,
-                    filter_fn,
-                    length_reduction_hash,
-                    db_root,
-                    class_model,
-                )
-                doc = future.result(timeout)
-                if doc is not None:
-                    return doc
-        return None
-
-    def find(
-        self,
-        filter_fn: Callable,
-        db_query_docs_limit: int = 1000,
-        max_workers: int | None = None,
-        timeout: float | None = None,
-    ) -> list[T] | None:
-        """Find one or more documents matching the filter.
-
-        The search is based on the effect of a quantum loop.
-        The search effectiveness depends on the number of processor threads.
-        Ideally, hundreds and even thousands of threads are required.
-
-        Args:
-            filter_fn: A function that execute the conditions of filtering.
-            db_query_docs_limit: Limiting the number of request results. By default = 1000.
-            max_workers: The maximum number of processes that can be used to
-                         execute the given calls. If None or not given then as many
-                         worker processes will be created as the machine has processors.
-            timeout: The number of seconds to wait for the result if the future isn't done.
-                     If None, then there is no limit on the wait time.
-        """
-        keys: range = range(1, self.__max_num_keys)
-        search_task_fn: Callable = self.search_task
-        length_reduction_hash: int = self.__length_reduction_hash
-        db_root: str = self.__db_root
-        class_model: T = self.__class_model
-        counter: int = 0
-        with concurrent.futures.ThreadPoolExecutor(max_workers) as executor:
-            results = []
-            for key in keys:
-                if counter == db_query_docs_limit:
-                    break
-                future = executor.submit(
-                    search_task_fn,
-                    key,
-                    filter_fn,
-                    length_reduction_hash,
-                    db_root,
-                    class_model,
-                )
-                doc = future.result(timeout)
-                if doc is not None:
-                    results.append(doc)
-                    counter += 1
-        return results or None
-
-    def collection_name(self) -> str:
-        """Get collection name."""
-        return self.__class_model.__name__
-
-    def collection_full_name(self) -> str:
-        """Get full name of collection."""
-        return f"{self.__db_root}/{self.__class_model.__name__}"
+# Scruby - Asynchronous library for building and managing a hybrid database, by scheme of key-value.
+# Copyright (c) 2025 Gennady Kostyunin
+# SPDX-License-Identifier: MIT
+#
+"""Creation and management of the database."""
+
+from __future__ import annotations
+
+__all__ = ("Scruby",)
+
+import contextlib
+import logging
+import re
+import zlib
+from shutil import rmtree
+from typing import Any, Literal, Never, assert_never
+
+from anyio import Path
+from pydantic import BaseModel
+
+from scruby import mixins, settings
+
+
+class _Meta(BaseModel):
+    """Metadata of Collection."""
+
+    db_root: str
+    collection_name: str
+    hash_reduce_left: int
+    max_branch_number: int
+    counter_documents: int
+
+
+class Scruby(
+    mixins.Keys,
+    mixins.Find,
+    mixins.CustomTask,
+    mixins.Collection,
+    mixins.Count,
+    mixins.Delete,
+    mixins.Update,
+):
+    """Creation and management of database."""
+
+    def __init__(  # noqa: D107
+        self,
+    ) -> None:
+        super().__init__()
+        self._meta = _Meta
+        self._db_root = settings.DB_ROOT
+        self._hash_reduce_left = settings.HASH_REDUCE_LEFT
+        self._max_workers = settings.MAX_WORKERS
+        # The maximum number of branches.
+        match self._hash_reduce_left:
+            case 0:
+                self._max_branch_number = 4294967296
+            case 2:
+                self._max_branch_number = 16777216
+            case 4:
+                self._max_branch_number = 65536
+            case 6:
+                self._max_branch_number = 256
+            case _ as unreachable:
+                msg: str = f"{unreachable} - Unacceptable value for HASH_REDUCE_LEFT."
+                logging.critical(msg)
+                assert_never(Never(unreachable))  # pyrefly: ignore[not-callable]
+
+    @classmethod
+    async def collection(cls, class_model: Any) -> Any:
+        """Get an object to access a collection.
+
+        Args:
+            class_model: Class of Model (pydantic.BaseModel).
+
+        Returns:
+            Instance of Scruby for access a collection.
+        """
+        assert BaseModel in class_model.__bases__, "`class_model` does not contain the base class `pydantic.BaseModel`!"
+
+        instance = cls()
+        instance.__dict__["_class_model"] = class_model
+        # Caching a pati for metadata.
+        # The zero branch is reserved for metadata.
+        branch_number: int = 0
+        branch_number_as_hash: str = f"{branch_number:08x}"[settings.HASH_REDUCE_LEFT :]
+        separated_hash: str = "/".join(list(branch_number_as_hash))
+        meta_dir_path_tuple = (
+            settings.DB_ROOT,
+            class_model.__name__,
+            separated_hash,
+        )
+        instance.__dict__["_meta_path"] = Path(
+            *meta_dir_path_tuple,
+            "meta.json",
+        )
+        # Create metadata for collection, if missing.
+        branch_path = Path(*meta_dir_path_tuple)
+        if not await branch_path.exists():
+            await branch_path.mkdir(parents=True)
+            meta = _Meta(
+                db_root=settings.DB_ROOT,
+                collection_name=class_model.__name__,
+                hash_reduce_left=settings.HASH_REDUCE_LEFT,
+                max_branch_number=instance.__dict__["_max_branch_number"],
+                counter_documents=0,
+            )
+            meta_json = meta.model_dump_json()
+            meta_path = Path(*(branch_path, "meta.json"))
+            await meta_path.write_text(meta_json, "utf-8")
+        return instance
+
+    async def get_meta(self) -> _Meta:
+        """Asynchronous method for getting metadata of collection.
+
+        This method is for internal use.
+
+        Returns:
+            Metadata object.
+        """
+        meta_json = await self._meta_path.read_text()
+        meta: _Meta = self._meta.model_validate_json(meta_json)
+        return meta
+
+    async def _set_meta(self, meta: _Meta) -> None:
+        """Asynchronous method for updating metadata of collection.
+
+        This method is for internal use.
+
+        Args:
+            meta (_Meta): Metadata of Collection.
+
+        Returns:
+            None.
+        """
+        meta_json = meta.model_dump_json()
+        await self._meta_path.write_text(meta_json, "utf-8")
+
+    async def _counter_documents(self, step: Literal[1, -1]) -> None:
+        """Asynchronous method for management of documents in metadata of collection.
+
+        This method is for internal use.
+
+        Args:
+            step (Literal[1, -1]): Number of documents added or removed.
+
+        Returns:
+            None.
+        """
+        meta_path = self._meta_path
+        meta_json = await meta_path.read_text("utf-8")
+        meta: _Meta = self._meta.model_validate_json(meta_json)
+        meta.counter_documents += step
+        meta_json = meta.model_dump_json()
+        await meta_path.write_text(meta_json, "utf-8")
+
+    async def _get_leaf_path(self, key: str) -> tuple[Path, str]:
+        """Asynchronous method for getting path to collection cell by key.
+
+        This method is for internal use.
+
+        Args:
+            key (str): Key name.
+
+        Returns:
+            Path to cell of collection.
+        """
+        if not isinstance(key, str):
+            msg = "The key is not a string."
+            logging.error(msg)
+            raise KeyError(msg)
+        # Prepare key.
+        # Removes spaces at the beginning and end of a string.
+        # Replaces all whitespace characters with a single space.
+        prepared_key = re.sub(r"\s+", " ", key).strip().lower()
+        # Check the key for an empty string.
+        if len(prepared_key) == 0:
+            msg = "The key should not be empty."
+            logging.error(msg)
+            raise KeyError(msg)
+        # Key to crc32 sum.
+        key_as_hash: str = f"{zlib.crc32(prepared_key.encode('utf-8')):08x}"[self._hash_reduce_left :]
+        # Convert crc32 sum in the segment of path.
+        separated_hash: str = "/".join(list(key_as_hash))
+        # The path of the branch to the database.
+        branch_path: Path = Path(
+            *(
+                self._db_root,
+                self._class_model.__name__,
+                separated_hash,
+            ),
+        )
+        # If the branch does not exist, need to create it.
+        if not await branch_path.exists():
+            await branch_path.mkdir(parents=True)
+        # The path to the database cell.
+        leaf_path: Path = Path(*(branch_path, "leaf.json"))
+        return (leaf_path, prepared_key)
+
+    @staticmethod
+    def napalm() -> None:
+        """Method for full database deletion.
+
+        The main purpose is tests.
+
+        Warning:
+            - `Be careful, this will remove all keys.`
+
+        Returns:
+            None.
+        """
+        with contextlib.suppress(FileNotFoundError):
+            rmtree(settings.DB_ROOT)
+        return

scruby/errors.py

@@ -0,0 +1,45 @@
+# Scruby - Asynchronous library for building and managing a hybrid database, by scheme of key-value.
+# Copyright (c) 2025 Gennady Kostyunin
+# SPDX-License-Identifier: MIT
+#
+"""Scruby Exceptions."""
+
+from __future__ import annotations
+
+__all__ = (
+    "ScrubyException",
+    "MetadataValueError",
+    "KeyAlreadyExistsError",
+    "KeyNotExistsError",
+)
+
+
+class ScrubyException(Exception):
+    """Root Custom Exception."""
+
+    def __init__(self, *args, **kwargs) -> None:  # type: ignore[no-untyped-def]  # noqa: D107
+        super().__init__(*args, **kwargs)
+
+
+class MetadataValueError(ScrubyException):
+    """Exception is raised if value of variable in metadata does not matching expected."""
+
+    def __init__(self, message: str) -> None:  # noqa: D107
+        self.message = message
+        super().__init__(self.message)
+
+
+class KeyAlreadyExistsError(ScrubyException):
+    """Exception is raised if the key already exists."""
+
+    def __init__(self) -> None:  # noqa: D107
+        self.message = "The key already exists."
+        super().__init__(self.message)
+
+
+class KeyNotExistsError(ScrubyException):
+    """Exception is raised If the key is not exists."""
+
+    def __init__(self) -> None:  # noqa: D107
+        self.message = "The key not exists."
+        super().__init__(self.message)

scruby/mixins/__init__.py

@@ -0,0 +1,25 @@
+# Scruby - Asynchronous library for building and managing a hybrid database, by scheme of key-value.
+# Copyright (c) 2025 Gennady Kostyunin
+# SPDX-License-Identifier: MIT
+#
+"""Mixins."""
+
+from __future__ import annotations
+
+__all__ = (
+    "Collection",
+    "Count",
+    "CustomTask",
+    "Delete",
+    "Find",
+    "Keys",
+    "Update",
+)
+
+from scruby.mixins.collection import Collection
+from scruby.mixins.count import Count
+from scruby.mixins.custom_task import CustomTask
+from scruby.mixins.delete import Delete
+from scruby.mixins.docs import Keys
+from scruby.mixins.find import Find
+from scruby.mixins.update import Update

scruby/mixins/collection.py

@@ -0,0 +1,50 @@
+# Scruby - Asynchronous library for building and managing a hybrid database, by scheme of key-value.
+# Copyright (c) 2025 Gennady Kostyunin
+# SPDX-License-Identifier: MIT
+#
+"""Methods for working with collections."""
+
+from __future__ import annotations
+
+__all__ = ("Collection",)
+
+from shutil import rmtree
+
+from anyio import Path, to_thread
+
+from scruby import settings
+
+
+class Collection:
+    """Methods for working with collections."""
+
+    def collection_name(self) -> str:
+        """Get collection name.
+
+        Returns:
+            Collection name.
+        """
+        return self._class_model.__name__
+
+    @staticmethod
+    async def collection_list() -> list[str]:
+        """Get collection list."""
+        target_directory = Path(settings.DB_ROOT)
+        # Get all entries in the directory
+        all_entries = Path.iterdir(target_directory)
+        directory_names: list[str] = [entry.name async for entry in all_entries]
+        return directory_names
+
+    @staticmethod
+    async def delete_collection(name: str) -> None:
+        """Asynchronous method for deleting a collection by its name.
+
+        Args:
+            name (str): Collection name.
+
+        Returns:
+            None.
+        """
+        target_directory = f"{settings.DB_ROOT}/{name}"
+        await to_thread.run_sync(rmtree, target_directory)  # pyrefly: ignore[bad-argument-type]
+        return