scruby 0.10.4__py3-none-any.whl → 0.26.0__py3-none-any.whl

scruby/db.py

@@ -1,437 +1,204 @@
-"""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, Literal, Never, TypeVar, assert_never
-
-import orjson
-from anyio import Path, to_thread
-from pydantic import BaseModel
-
-from scruby import constants
-
-logger = logging.getLogger(__name__)
-
-T = TypeVar("T")
-
-
-class _Meta(BaseModel):
-    """Metadata of Collection."""
-
-    counter_documents: int
-
-
-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.__meta = _Meta
-        self.__class_model = class_model
-        self.__db_root = constants.DB_ROOT
-        self.__hash_reduce_left = constants.HASH_REDUCE_LEFT
-        # The maximum number of keys.
-        match self.__hash_reduce_left:
-            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 HASH_REDUCE_LEFT."
-                logger.critical(msg)
-                assert_never(Never(unreachable))
-        # 1.Create metadata if absent.
-        # 2.Check metadata.
-        self._create_metadata()
-
-    def _create_metadata(self) -> None:
-        """Create metadata for collection if absent.
-
-        This method is for internal use.
-        """
-        key: int = 0
-        key_as_hash: str = f"{key:08x}"[self.__hash_reduce_left :]
-        separated_hash: str = "/".join(list(key_as_hash))
-        branch_path = SyncPath(
-            *(
-                self.__db_root,
-                self.__class_model.__name__,
-                separated_hash,
-            ),
-        )
-        if not branch_path.exists():
-            branch_path.mkdir(parents=True)
-            meta = _Meta(
-                counter_documents=0,
-            )
-            meta_json = meta.model_dump_json()
-            meta_path = SyncPath(*(branch_path, "meta.json"))
-            meta_path.write_text(meta_json, "utf-8")
-
-    async def _get_meta_path(self) -> Path:
-        """Asynchronous method for getting path to metadata of collection.
-
-        This method is for internal use.
-        """
-        key: int = 0
-        key_as_hash: str = f"{key:08x}"[self.__hash_reduce_left :]
-        separated_hash: str = "/".join(list(key_as_hash))
-        return Path(
-            *(
-                self.__db_root,
-                self.__class_model.__name__,
-                separated_hash,
-                "meta.json",
-            ),
-        )
-
-    async def _get_meta(self) -> _Meta:
-        """Asynchronous method for getting metadata of collection.
-
-        This method is for internal use.
-        """
-        meta_path = await self._get_meta_path()
-        meta_json = await 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.
-        """
-        meta_path = await self._get_meta_path()
-        meta_json = meta.model_dump_json()
-        await meta_path.write_text(meta_json, "utf-8")
-
-    async def _counter_documents(self, step: Literal[1, -1]) -> None:
-        """Management of documents in metadata of collection.
-
-        This method is for internal use.
-        """
-        meta = await self._get_meta()
-        meta.counter_documents += step
-        if meta.counter_documents < 0:
-            meta.counter_documents = 0
-        await self._set_meta(meta)
-
-    async def _get_leaf_path(self, key: str) -> Path:
-        """Asynchronous method for getting path to collection cell by key.
-
-        This method is for internal use.
-
-        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.__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
-
-    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 {}
-            if data.get(key) is None:
-                await self._counter_documents(1)
-            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}))
-            await self._counter_documents(1)
-
-    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))
-            await self._counter_documents(-1)
-            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 _task_find(
-        key: int,
-        filter_fn: Callable,
-        HASH_REDUCE_LEFT: str,
-        db_root: str,
-        class_model: T,
-    ) -> dict[str, Any] | None:
-        """Task for searching for documents.
-
-        This method is for internal use.
-        """
-        key_as_hash: str = f"{key:08x}"[HASH_REDUCE_LEFT:]
-        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._task_find
-        HASH_REDUCE_LEFT: int = self.__hash_reduce_left
-        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,
-                    HASH_REDUCE_LEFT,
-                    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._task_find
-        HASH_REDUCE_LEFT: int = self.__hash_reduce_left
-        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,
-                    HASH_REDUCE_LEFT,
-                    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__}"
-
-    async def estimated_document_count(self) -> int:
-        """Get an estimate of the number of documents in this collection using collection metadata."""
-        meta = await self._get_meta()
-        return meta.counter_documents
-
-    def count_documents(
-        self,
-        filter_fn: Callable,
-        max_workers: int | None = None,
-        timeout: float | None = None,
-    ) -> int:
-        """Count the number of documents a matching the filter in this collection.
-
-        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._task_find
-        HASH_REDUCE_LEFT: int = self.__hash_reduce_left
-        db_root: str = self.__db_root
-        class_model: T = self.__class_model
-        counter: int = 0
-        with concurrent.futures.ThreadPoolExecutor(max_workers) as executor:
-            for key in keys:
-                future = executor.submit(
-                    search_task_fn,
-                    key,
-                    filter_fn,
-                    HASH_REDUCE_LEFT,
-                    db_root,
-                    class_model,
-                )
-                if future.result(timeout) is not None:
-                    counter += 1
-        return counter
+"""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 constants, mixins
+
+logger = logging.getLogger(__name__)
+
+
+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.Docs,
+    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 = constants.DB_ROOT
+        self._hash_reduce_left = constants.HASH_REDUCE_LEFT
+        # 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."
+                logger.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}"[constants.HASH_REDUCE_LEFT :]
+        separated_hash: str = "/".join(list(branch_number_as_hash))
+        meta_dir_path_tuple = (
+            constants.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=constants.DB_ROOT,
+                collection_name=class_model.__name__,
+                hash_reduce_left=constants.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.
+
+        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.
+
+        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."
+            logger.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."
+            logger.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(constants.DB_ROOT)
+        return