scruby 0.24.4__py3-none-any.whl → 0.28.3__py3-none-any.whl

scruby/__init__.py

@@ -1,3 +1,12 @@
+#
+# .dP"Y8  dP""b8 88""Yb 88   88 88""Yb Yb  dP
+# `Ybo." dP   `" 88__dP 88   88 88__dP  YbdP
+# o.`Y8b Yb      88"Yb  Y8   8P 88""Yb   8P
+# 8bodP'  YboodP 88  Yb `YbodP' 88oodP  dP
+#
+# Copyright (c) 2025 Gennady Kostyunin
+# SPDX-License-Identifier: MIT
+#
 """Asynchronous library for building and managing a hybrid database, by scheme of key-value.
 
 The library uses fractal-tree addressing and
@@ -16,14 +25,10 @@ requires a large number of processor threads.
 
 from __future__ import annotations
 
-__all__ = ("Scruby",)
-
-import logging
+__all__ = (
+    "settings",
+    "Scruby",
+)
 
+from scruby import settings
 from scruby.db import Scruby
-
-logging.basicConfig(
-    level=logging.INFO,
-    datefmt="%Y-%m-%d %H:%M:%S",
-    format="[%(asctime)s.%(msecs)03d] %(module)10s:%(lineno)-3d %(levelname)-7s - %(message)s",
-)

scruby/aggregation.py

@@ -1,3 +1,7 @@
+# Scruby - Asynchronous library for building and managing a hybrid database, by scheme of key-value.
+# Copyright (c) 2025 Gennady Kostyunin
+# SPDX-License-Identifier: MIT
+#
 """Aggregation classes."""
 
 from __future__ import annotations

scruby/db.py

@@ -1,3 +1,7 @@
+# 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
@@ -6,18 +10,15 @@ __all__ = ("Scruby",)
 
 import contextlib
 import logging
+import re
 import zlib
 from shutil import rmtree
-from typing import Any, Literal, Never, TypeVar, assert_never
+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__)
-
-T = TypeVar("T")
+from scruby import mixins, settings
 
 
 class _Meta(BaseModel):
@@ -30,7 +31,7 @@ class _Meta(BaseModel):
     counter_documents: int
 
 
-class Scruby[T](
+class Scruby(
     mixins.Keys,
     mixins.Find,
     mixins.CustomTask,
@@ -46,8 +47,9 @@ class Scruby[T](
     ) -> None:
         super().__init__()
         self._meta = _Meta
-        self._db_root = constants.DB_ROOT
-        self._hash_reduce_left = constants.HASH_REDUCE_LEFT
+        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:
@@ -60,29 +62,30 @@ class Scruby[T](
                 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))
+                logging.critical(msg)
+                assert_never(Never(unreachable))  # pyrefly: ignore[not-callable]
 
     @classmethod
-    async def create(cls, class_model: T) -> Any:
+    async def collection(cls, class_model: Any) -> Any:
         """Get an object to access a collection.
 
         Args:
-            class_model: Class of Model (Pydantic).
+            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 :]
+        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 = (
-            constants.DB_ROOT,
+            settings.DB_ROOT,
             class_model.__name__,
             separated_hash,
         )
@@ -95,9 +98,9 @@ class Scruby[T](
         if not await branch_path.exists():
             await branch_path.mkdir(parents=True)
             meta = _Meta(
-                db_root=constants.DB_ROOT,
+                db_root=settings.DB_ROOT,
                 collection_name=class_model.__name__,
-                hash_reduce_left=constants.HASH_REDUCE_LEFT,
+                hash_reduce_left=settings.HASH_REDUCE_LEFT,
                 max_branch_number=instance.__dict__["_max_branch_number"],
                 counter_documents=0,
             )
@@ -123,6 +126,9 @@ class Scruby[T](
 
         This method is for internal use.
 
+        Args:
+            meta (_Meta): Metadata of Collection.
+
         Returns:
             None.
         """
@@ -134,6 +140,9 @@ class Scruby[T](
 
         This method is for internal use.
 
+        Args:
+            step (Literal[1, -1]): Number of documents added or removed.
+
         Returns:
             None.
         """
@@ -144,22 +153,32 @@ class Scruby[T](
         meta_json = meta.model_dump_json()
         await meta_path.write_text(meta_json, "utf-8")
 
-    async def _get_leaf_path(self, key: str) -> Path:
+    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: Key name.
+            key (str): Key name.
 
         Returns:
             Path to cell of collection.
         """
-        if len(key) == 0:
-            logger.error("The key should not be empty.")
-            raise KeyError("The key should not be empty.")
+        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(key.encode('utf-8')):08x}"[self._hash_reduce_left :]
+        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.
@@ -175,7 +194,7 @@ class Scruby[T](
             await branch_path.mkdir(parents=True)
         # The path to the database cell.
         leaf_path: Path = Path(*(branch_path, "leaf.json"))
-        return leaf_path
+        return (leaf_path, prepared_key)
 
     @staticmethod
     def napalm() -> None:
@@ -190,5 +209,5 @@ class Scruby[T](
             None.
         """
         with contextlib.suppress(FileNotFoundError):
-            rmtree(constants.DB_ROOT)
+            rmtree(settings.DB_ROOT)
         return

scruby/errors.py

@@ -1,3 +1,7 @@
+# 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

scruby/mixins/__init__.py

@@ -1,3 +1,7 @@
+# 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

scruby/mixins/collection.py

@@ -1,3 +1,7 @@
+# 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
@@ -5,16 +9,13 @@ from __future__ import annotations
 __all__ = ("Collection",)
 
 from shutil import rmtree
-from typing import TypeVar
 
 from anyio import Path, to_thread
 
-from scruby import constants
+from scruby import settings
 
-T = TypeVar("T")
 
-
-class Collection[T]:
+class Collection:
     """Methods for working with collections."""
 
     def collection_name(self) -> str:
@@ -28,7 +29,7 @@ class Collection[T]:
     @staticmethod
     async def collection_list() -> list[str]:
         """Get collection list."""
-        target_directory = Path(constants.DB_ROOT)
+        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]
@@ -44,6 +45,6 @@ class Collection[T]:
         Returns:
             None.
         """
-        target_directory = f"{constants.DB_ROOT}/{name}"
-        await to_thread.run_sync(rmtree, target_directory)
+        target_directory = f"{settings.DB_ROOT}/{name}"
+        await to_thread.run_sync(rmtree, target_directory)  # pyrefly: ignore[bad-argument-type]
         return

scruby/mixins/count.py

@@ -1,3 +1,7 @@
+# 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 counting the number of documents."""
 
 from __future__ import annotations
@@ -6,12 +10,10 @@ __all__ = ("Count",)
 
 import concurrent.futures
 from collections.abc import Callable
-from typing import TypeVar
+from typing import Any
 
-T = TypeVar("T")
 
-
-class Count[T]:
+class Count:
     """Methods for counting the number of documents."""
 
     async def estimated_document_count(self) -> int:
@@ -26,30 +28,27 @@ class Count[T]:
     async def count_documents(
         self,
         filter_fn: Callable,
-        max_workers: int | 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.
 
         Returns:
             The number of documents.
         """
-        branch_numbers: range = range(1, self._max_branch_number)
+        # Variable initialization
         search_task_fn: Callable = self._task_find
+        branch_numbers: range = range(1, self._max_branch_number)
         hash_reduce_left: int = self._hash_reduce_left
         db_root: str = self._db_root
-        class_model: T = self._class_model
+        class_model: Any = self._class_model
         counter: int = 0
-        with concurrent.futures.ThreadPoolExecutor(max_workers) as executor:
+        # Run quantum loop
+        with concurrent.futures.ThreadPoolExecutor(self._max_workers) as executor:
             for branch_number in branch_numbers:
                 future = executor.submit(
                     search_task_fn,

scruby/mixins/custom_task.py

@@ -1,22 +1,21 @@
+# Scruby - Asynchronous library for building and managing a hybrid database, by scheme of key-value.
+# Copyright (c) 2025 Gennady Kostyunin
+# SPDX-License-Identifier: MIT
+#
 """Quantum methods for running custom tasks."""
 
 from __future__ import annotations
 
 __all__ = ("CustomTask",)
 
-import logging
 from collections.abc import Callable
-from typing import Any, TypeVar
+from typing import Any
 
 import orjson
 from anyio import Path
 
-logger = logging.getLogger(__name__)
 
-T = TypeVar("T")
-
-
-class CustomTask[T]:
+class CustomTask:
     """Quantum methods for running custom tasks."""
 
     @staticmethod
@@ -24,7 +23,7 @@ class CustomTask[T]:
         branch_number: int,
         hash_reduce_left: int,
         db_root: str,
-        class_model: T,
+        class_model: Any,
     ) -> list[Any]:
         """Get documents for custom task.
 
@@ -43,7 +42,7 @@ class CustomTask[T]:
                 "leaf.json",
             ),
         )
-        docs: list[str, T] = []
+        docs: list[Any] = []
         if await leaf_path.exists():
             data_json: bytes = await leaf_path.read_bytes()
             data: dict[str, str] = orjson.loads(data_json) or {}
@@ -56,7 +55,6 @@ class CustomTask[T]:
 
         This method running a task created on the basis of a quantum loop.
         Effectiveness running task depends on the number of processor threads.
-        Ideally, hundreds and even thousands of threads are required.
 
         Args:
             custom_task_fn: A function that execute the custom task.

scruby/mixins/delete.py

@@ -1,3 +1,7 @@
+# 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 deleting documents."""
 
 from __future__ import annotations
@@ -5,19 +9,14 @@ from __future__ import annotations
 __all__ = ("Delete",)
 
 import concurrent.futures
-import logging
 from collections.abc import Callable
-from typing import TypeVar
+from typing import Any
 
 import orjson
 from anyio import Path
 
-logger = logging.getLogger(__name__)
 
-T = TypeVar("T")
-
-
-class Delete[T]:
+class Delete:
     """Methods for deleting documents."""
 
     @staticmethod
@@ -26,7 +25,7 @@ class Delete[T]:
         filter_fn: Callable,
         hash_reduce_left: int,
         db_root: str,
-        class_model: T,
+        class_model: Any,
     ) -> int:
         """Task for find and delete documents.
 
@@ -62,30 +61,27 @@ class Delete[T]:
     async def delete_many(
         self,
         filter_fn: Callable,
-        max_workers: int | None = None,
     ) -> int:
         """Delete 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.
-            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.
 
         Returns:
             The number of deleted documents.
         """
-        branch_numbers: range = range(1, self._max_branch_number)
+        # Variable initialization
         search_task_fn: Callable = self._task_delete
+        branch_numbers: range = range(1, self._max_branch_number)
         hash_reduce_left: int = self._hash_reduce_left
         db_root: str = self._db_root
-        class_model: T = self._class_model
+        class_model: Any = self._class_model
         counter: int = 0
-        with concurrent.futures.ThreadPoolExecutor(max_workers) as executor:
+        # Run quantum loop
+        with concurrent.futures.ThreadPoolExecutor(self._max_workers) as executor:
             for branch_number in branch_numbers:
                 future = executor.submit(
                     search_task_fn,

scruby/mixins/find.py

@@ -1,3 +1,7 @@
+# Scruby - Asynchronous library for building and managing a hybrid database, by scheme of key-value.
+# Copyright (c) 2025 Gennady Kostyunin
+# SPDX-License-Identifier: MIT
+#
 """Quantum methods for searching documents."""
 
 from __future__ import annotations
@@ -5,19 +9,14 @@ from __future__ import annotations
 __all__ = ("Find",)
 
 import concurrent.futures
-import logging
 from collections.abc import Callable
-from typing import TypeVar
+from typing import Any
 
 import orjson
 from anyio import Path
 
-logger = logging.getLogger(__name__)
 
-T = TypeVar("T")
-
-
-class Find[T]:
+class Find:
     """Quantum methods for searching documents."""
 
     @staticmethod
@@ -26,8 +25,8 @@ class Find[T]:
         filter_fn: Callable,
         hash_reduce_left: str,
         db_root: str,
-        class_model: T,
-    ) -> list[T] | None:
+        class_model: Any,
+    ) -> list[Any] | None:
         """Task for find documents.
 
         This method is for internal use.
@@ -35,6 +34,7 @@ class Find[T]:
         Returns:
             List of documents or None.
         """
+        # Variable initialization
         branch_number_as_hash: str = f"{branch_number:08x}"[hash_reduce_left:]
         separated_hash: str = "/".join(list(branch_number_as_hash))
         leaf_path: Path = Path(
@@ -45,7 +45,7 @@ class Find[T]:
                 "leaf.json",
             ),
         )
-        docs: list[T] = []
+        docs: list[Any] = []
         if await leaf_path.exists():
             data_json: bytes = await leaf_path.read_bytes()
             data: dict[str, str] = orjson.loads(data_json) or {}
@@ -58,29 +58,26 @@ class Find[T]:
     async def find_one(
         self,
         filter_fn: Callable,
-        max_workers: int | None = None,
-    ) -> T | None:
-        """Finds a single document matching the filter.
+    ) -> Any | None:
+        """Find one 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.
+            filter_fn (Callable): A function that execute the conditions of filtering.
 
         Returns:
             Document or None.
         """
-        branch_numbers: range = range(1, self._max_branch_number)
+        # Variable initialization
         search_task_fn: Callable = self._task_find
+        branch_numbers: range = range(1, self._max_branch_number)
         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:
+        class_model: Any = self._class_model
+        # Run quantum loop
+        with concurrent.futures.ThreadPoolExecutor(self._max_workers) as executor:
             for branch_number in branch_numbers:
                 future = executor.submit(
                     search_task_fn,
@@ -97,36 +94,40 @@ class Find[T]:
 
     async def find_many(
         self,
-        filter_fn: Callable,
+        filter_fn: Callable = lambda _: True,
         limit_docs: int = 1000,
-        max_workers: int | None = None,
-    ) -> list[T] | None:
-        """Finds one or more documents matching the filter.
+        page_number: int = 1,
+    ) -> list[Any] | None:
+        """Find many 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.
-            limit_docs: Limiting the number of documents. 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.
+            filter_fn (Callable): A function that execute the conditions of filtering.
+                                  By default it searches for all documents.
+            limit_docs (int): Limiting the number of documents. By default = 1000.
+            page_number (int): For pagination output. By default = 1.
+                               Number of documents per page = limit_docs.
 
         Returns:
             List of documents or None.
         """
-        branch_numbers: range = range(1, self._max_branch_number)
+        # The `page_number` parameter must not be less than one
+        assert page_number > 0, "`find_many` => The `page_number` parameter must not be less than one."
+        # Variable initialization
         search_task_fn: Callable = self._task_find
+        branch_numbers: range = range(1, self._max_branch_number)
         hash_reduce_left: int = self._hash_reduce_left
         db_root: str = self._db_root
-        class_model: T = self._class_model
+        class_model: Any = self._class_model
         counter: int = 0
-        result: list[T] = []
-        with concurrent.futures.ThreadPoolExecutor(max_workers) as executor:
+        number_docs_skippe: int = limit_docs * (page_number - 1) if page_number > 1 else 0
+        result: list[Any] = []
+        # Run quantum loop
+        with concurrent.futures.ThreadPoolExecutor(self._max_workers) as executor:
             for branch_number in branch_numbers:
-                if counter >= limit_docs:
+                if number_docs_skippe == 0 and counter >= limit_docs:
                     return result[:limit_docs]
                 future = executor.submit(
                     search_task_fn,
@@ -139,8 +140,11 @@ class Find[T]:
                 docs = await future.result()
                 if docs is not None:
                     for doc in docs:
-                        if counter >= limit_docs:
-                            return result[:limit_docs]
-                        result.append(doc)
-                        counter += 1
+                        if number_docs_skippe == 0:
+                            if counter >= limit_docs:
+                                return result[:limit_docs]
+                            result.append(doc)
+                            counter += 1
+                        else:
+                            number_docs_skippe -= 1
         return result or None

scruby/mixins/keys.py

@@ -1,3 +1,7 @@
+# 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 keys."""
 
 from __future__ import annotations
@@ -5,98 +9,99 @@ from __future__ import annotations
 __all__ = ("Keys",)
 
 import logging
-import re
-from typing import TypeVar
+from typing import Any
 
 import orjson
-from anyio import Path
 
 from scruby.errors import (
     KeyAlreadyExistsError,
     KeyNotExistsError,
 )
 
-logger = logging.getLogger(__name__)
 
-T = TypeVar("T")
-
-
-class Keys[T]:
+class Keys:
     """Methods for working with keys."""
 
-    async def add_key(
-        self,
-        key: str,
-        value: T,
-    ) -> None:
-        """Asynchronous method for adding key to collection.
+    async def add_doc(self, doc: Any) -> None:
+        """Asynchronous method for adding document to collection.
 
         Args:
-            key: Key name. Type `str`.
-            value: Value of key. Type `BaseModel`.
+            doc: Value of key. Type, derived from `BaseModel`.
 
         Returns:
             None.
         """
-        key = re.sub(r"\s+", " ", key.strip())
+        # Check if the Model matches the collection
+        if not isinstance(doc, self._class_model):
+            doc_class_name = doc.__class__.__name__
+            collection_name = self._class_model.__name__
+            msg = (
+                f"(add_doc) Parameter `doc` => Model `{doc_class_name}` does not match collection `{collection_name}`!"
+            )
+            logging.error(msg)
+            raise TypeError(msg)
         # The path to cell of collection.
-        leaf_path: Path = await self._get_leaf_path(key)
-        value_json: str = value.model_dump_json()
+        leaf_path, prepared_key = await self._get_leaf_path(doc.key)
+        doc_json: str = doc.model_dump_json()
         # Write key-value to collection.
         if await leaf_path.exists():
             # Add new key.
             data_json: bytes = await leaf_path.read_bytes()
             data: dict = orjson.loads(data_json) or {}
             try:
-                data[key]
+                data[prepared_key]
             except KeyError:
-                data[key] = value_json
+                data[prepared_key] = doc_json
                 await leaf_path.write_bytes(orjson.dumps(data))
             else:
                 err = KeyAlreadyExistsError()
-                logger.error(err.message)
+                logging.error(err.message)
                 raise err
         else:
-            # Add new key to a blank leaf.
-            await leaf_path.write_bytes(orjson.dumps({key: value_json}))
+            # Add new document to a blank leaf.
+            await leaf_path.write_bytes(orjson.dumps({prepared_key: doc_json}))
         await self._counter_documents(1)
 
-    async def update_key(
-        self,
-        key: str,
-        value: T,
-    ) -> None:
+    async def update_doc(self, doc: Any) -> None:
         """Asynchronous method for updating key to collection.
 
         Args:
-            key: Key name. Type `str`.
-            value: Value of key. Type `BaseModel`.
+            doc: Value of key. Type `BaseModel`.
 
         Returns:
             None.
         """
-        key = re.sub(r"\s+", " ", key.strip())
+        # Check if the Model matches the collection
+        if not isinstance(doc, self._class_model):
+            doc_class_name = doc.__class__.__name__
+            collection_name = self._class_model.__name__
+            msg = (
+                f"(update_doc) Parameter `doc` => Model `{doc_class_name}` "
+                f"does not match collection `{collection_name}`!"
+            )
+            logging.error(msg)
+            raise TypeError(msg)
         # The path to cell of collection.
-        leaf_path: Path = await self._get_leaf_path(key)
-        value_json: str = value.model_dump_json()
+        leaf_path, prepared_key = await self._get_leaf_path(doc.key)
+        doc_json: str = doc.model_dump_json()
         # Update the existing key.
         if await leaf_path.exists():
             # Update the existing key.
             data_json: bytes = await leaf_path.read_bytes()
             data: dict = orjson.loads(data_json) or {}
             try:
-                data[key]
-                data[key] = value_json
+                data[prepared_key]
+                data[prepared_key] = doc_json
                 await leaf_path.write_bytes(orjson.dumps(data))
             except KeyError:
                 err = KeyNotExistsError()
-                logger.error(err.message)
+                logging.error(err.message)
                 raise err from None
         else:
-            logger.error("The key not exists.")
+            logging.error("The key not exists.")
             raise KeyError()
 
-    async def get_key(self, key: str) -> T:
+    async def get_key(self, key: str) -> Any:
         """Asynchronous method for getting value of key from collection.
 
         Args:
@@ -105,17 +110,16 @@ class Keys[T]:
         Returns:
             Value of key or KeyError.
         """
-        key = re.sub(r"\s+", " ", key.strip())
         # The path to the database cell.
-        leaf_path: Path = await self._get_leaf_path(key)
+        leaf_path, prepared_key = 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])
+            obj: Any = self._class_model.model_validate_json(data[prepared_key])
             return obj
         msg: str = "`get_key` - The unacceptable key value."
-        logger.error(msg)
+        logging.error(msg)
         raise KeyError()
 
     async def has_key(self, key: str) -> bool:
@@ -127,15 +131,14 @@ class Keys[T]:
         Returns:
             True, if the key is present.
         """
-        key = re.sub(r"\s+", " ", key.strip())
         # Get path to cell of collection.
-        leaf_path: Path = await self._get_leaf_path(key)
+        leaf_path, prepared_key = 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]
+                data[prepared_key]
                 return True
             except KeyError:
                 return False
@@ -150,17 +153,16 @@ class Keys[T]:
         Returns:
             None.
         """
-        key = re.sub(r"\s+", " ", key.strip())
         # The path to the database cell.
-        leaf_path: Path = await self._get_leaf_path(key)
+        leaf_path, prepared_key = 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]
+            del data[prepared_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)
+        logging.error(msg)
         raise KeyError()

scruby/mixins/update.py

@@ -1,3 +1,7 @@
+# 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 updating documents."""
 
 from __future__ import annotations
@@ -5,19 +9,14 @@ from __future__ import annotations
 __all__ = ("Update",)
 
 import concurrent.futures
-import logging
 from collections.abc import Callable
-from typing import Any, TypeVar
+from typing import Any
 
 import orjson
 from anyio import Path
 
-logger = logging.getLogger(__name__)
 
-T = TypeVar("T")
-
-
-class Update[T]:
+class Update:
     """Methods for updating documents."""
 
     @staticmethod
@@ -26,7 +25,7 @@ class Update[T]:
         filter_fn: Callable,
         hash_reduce_left: str,
         db_root: str,
-        class_model: T,
+        class_model: Any,
         new_data: dict[str, Any],
     ) -> int:
         """Task for find documents.
@@ -65,31 +64,28 @@ class Update[T]:
         self,
         filter_fn: Callable,
         new_data: dict[str, Any],
-        max_workers: int | None = None,
     ) -> int:
         """Updates 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.
             new_data: New data for the fields that need to be updated.
-            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.
 
         Returns:
             The number of updated documents.
         """
-        branch_numbers: range = range(1, self._max_branch_number)
+        # Variable initialization
         update_task_fn: Callable = self._task_update
+        branch_numbers: range = range(1, self._max_branch_number)
         hash_reduce_left: int = self._hash_reduce_left
         db_root: str = self._db_root
-        class_model: T = self._class_model
+        class_model: Any = self._class_model
         counter: int = 0
-        with concurrent.futures.ThreadPoolExecutor(max_workers) as executor:
+        # Run quantum loop
+        with concurrent.futures.ThreadPoolExecutor(self._max_workers) as executor:
             for branch_number in branch_numbers:
                 future = executor.submit(
                     update_task_fn,

scruby/{constants.py → settings.py}

@@ -1,6 +1,10 @@
-"""Constant variables.
+# Scruby - Asynchronous library for building and managing a hybrid database, by scheme of key-value.
+# Copyright (c) 2025 Gennady Kostyunin
+# SPDX-License-Identifier: MIT
+#
+"""Database settings.
 
-The module contains the following variables:
+The module contains the following parameters:
 
 - `DB_ROOT` - Path to root directory of database. `By default = "ScrubyDB" (in root of project)`.
 - `HASH_REDUCE_LEFT` - The length of the hash reduction on the left side.
@@ -8,6 +12,7 @@ The module contains the following variables:
     - `2` - 16777216 branches in collection.
     - `4` - 65536 branches in collection.
     - `6` - 256 branches in collection (by default).
+- `MAX_WORKERS` - The maximum number of processes that can be used `By default = None`.
 """
 
 from __future__ import annotations
@@ -15,6 +20,7 @@ from __future__ import annotations
 __all__ = (
     "DB_ROOT",
     "HASH_REDUCE_LEFT",
+    "MAX_WORKERS",
 )
 
 from typing import Literal
@@ -31,3 +37,8 @@ DB_ROOT: str = "ScrubyDB"
 # Number of branches is number of requests to the hard disk during quantum operations.
 # Quantum operations: find_one, find_many, count_documents, delete_many, run_custom_task.
 HASH_REDUCE_LEFT: Literal[0, 2, 4, 6] = 6
+
+# The maximum number of processes that can be used to execute the given calls.
+# If None, then as many worker processes will be
+# created as the machine has processors.
+MAX_WORKERS: int | None = None

{scruby-0.24.4.dist-info → scruby-0.28.3.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: scruby
-Version: 0.24.4
-Summary: A fast key-value storage library.
-Project-URL: Homepage, https://github.com/kebasyaty/scruby
+Version: 0.28.3
+Summary: Asynchronous library for building and managing a hybrid database, by scheme of key-value.
+Project-URL: Homepage, https://kebasyaty.github.io/scruby/
 Project-URL: Repository, https://github.com/kebasyaty/scruby
 Project-URL: Source, https://github.com/kebasyaty/scruby
 Project-URL: Bug Tracker, https://github.com/kebasyaty/scruby/issues
@@ -17,6 +17,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.12
@@ -30,7 +31,7 @@ Requires-Dist: anyio>=4.10.0
 Requires-Dist: orjson>=3.11.3
 Requires-Dist: phonenumbers>=9.0.13
 Requires-Dist: pydantic-extra-types>=2.10.5
-Requires-Dist: pydantic[email]>=2.11.7
+Requires-Dist: pydantic[email,timezone]>=2.11.7
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -52,7 +53,7 @@ Description-Content-Type: text/markdown
       <a href="https://pypi.python.org/pypi/scruby/" alt="PyPI status"><img src="https://img.shields.io/pypi/status/scruby.svg" alt="PyPI status"></a>
       <a href="https://pypi.python.org/pypi/scruby/" alt="PyPI version fury.io"><img src="https://badge.fury.io/py/scruby.svg" alt="PyPI version fury.io"></a>
       <br>
-      <a href="https://mypy-lang.org/" alt="Types: Mypy"><img src="https://img.shields.io/badge/types-Mypy-202235.svg?color=0c7ebf" alt="Types: Mypy"></a>
+      <a href="https://pyrefly.org/" alt="Types: Pyrefly"><img src="https://img.shields.io/badge/types-Pyrefly-FFB74D.svg" alt="Types: Pyrefly"></a>
       <a href="https://docs.astral.sh/ruff/" alt="Code style: Ruff"><img src="https://img.shields.io/badge/code%20style-Ruff-FDD835.svg" alt="Code style: Ruff"></a>
       <a href="https://pypi.org/project/scruby"><img src="https://img.shields.io/pypi/format/scruby" alt="Format"></a>
       <a href="https://pepy.tech/projects/scruby"><img src="https://static.pepy.tech/badge/scruby" alt="PyPI Downloads"></a>
@@ -65,11 +66,11 @@ Description-Content-Type: text/markdown
         <br>
         The database consists of collections.
         <br>
-        The maximum size of the one collection is 16\*\*8=4294967296 branches,
+        The maximum size of the one collection is <b>16**8=4294967296</b> branches,
         <br>
         each branch can store one or more keys.
         <br>
-        The value of any key in collection can be obtained in 8 steps,
+        The value of any key in collection can be obtained maximum in <b>8</b> steps,
         <br>
         thereby achieving high performance.
         <br>
@@ -108,26 +109,33 @@ See more examples here [https://kebasyaty.github.io/scruby/latest/pages/usage/](
 import anyio
 import datetime
 from typing import Annotated
-from pydantic import BaseModel, EmailStr
+from pydantic import BaseModel, EmailStr, Field
 from pydantic_extra_types.phone_numbers import PhoneNumber, PhoneNumberValidator
-from scruby import Scruby, constants
+from scruby import Scruby, settings
 
-constants.DB_ROOT = "ScrubyDB"  # By default = "ScrubyDB"
-constants.HASH_REDUCE_LEFT = 6  # By default = 6
+settings.DB_ROOT = "ScrubyDB"  # By default = "ScrubyDB"
+settings.HASH_REDUCE_LEFT = 6  # By default = 6
+settings.MAX_WORKERS = None  # By default = None
 
 class User(BaseModel):
-    """Model of User."""
-    first_name: str
-    last_name: str
-    birthday: datetime.datetime
-    email: EmailStr
-    phone: Annotated[PhoneNumber, PhoneNumberValidator(number_format="E164")]
+    """User model."""
+    first_name: str = Field(strict=True)
+    last_name: str = Field(strict=True)
+    birthday: datetime.datetime = Field(strict=True)
+    email: EmailStr = Field(strict=True)
+    phone: Annotated[PhoneNumber, PhoneNumberValidator(number_format="E164")] = Field(frozen=True)
+    # The key is always at the bottom
+    key: str = Field(
+        strict=True,
+        frozen=True,
+        default_factory=lambda data: data["phone"],
+    )
 
 
 async def main() -> None:
     """Example."""
-    # Get collection of `User`.
-    user_coll = await Scruby.create(User)
+    # Get collection `User`.
+    user_coll = await Scruby.collection(User)
 
     user = User(
         first_name="John",
@@ -137,9 +145,9 @@ async def main() -> None:
         phone="+447986123456",
     )
 
-    await user_coll.add_key(user.phone, user)
+    await user_coll.add_doc(user)
 
-    await user_coll.update_key(user.phone, user)
+    await user_coll.update_doc(user)
 
     await user_coll.get_key("+447986123456")  # => user
     await user_coll.get_key("key missing")  # => KeyError
@@ -161,36 +169,42 @@ if __name__ == "__main__":
 ```
 
 ```python
-"""Find a single document matching the filter.
+"""Find one 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.
 """
 
 import anyio
 import datetime
 from typing import Annotated
-from pydantic import BaseModel
-from scruby import Scruby, constants
+from pydantic import BaseModel, Field
+from scruby import Scruby, settings
 from pprint import pprint as pp
 
-constants.DB_ROOT = "ScrubyDB"  # By default = "ScrubyDB"
-constants.HASH_REDUCE_LEFT = 6  # By default = 6
+settings.DB_ROOT = "ScrubyDB"  # By default = "ScrubyDB"
+settings.HASH_REDUCE_LEFT = 6  # By default = 6
+settings.MAX_WORKERS = None  # By default = None
 
 
 class Phone(BaseModel):
     """Phone model."""
-    brand: str
-    model: str
-    screen_diagonal: float
-    matrix_type: str
+    brand: str = Field(strict=True, frozen=True)
+    model: str = Field(strict=True, frozen=True)
+    screen_diagonal: float = Field(strict=True)
+    matrix_type: str = Field(strict=True)
+    # The key is always at the bottom
+    key: str = Field(
+        strict=True,
+        frozen=True,
+        default_factory=lambda data: f"{data['brand']}:{data['model']}",
+    )
 
 
 async def main() -> None:
     """Example."""
-    # Get collection of `Phone`.
-    phone_coll = await Scruby.create(Phone)
+    # Get collection `Phone`.
+    phone_coll = await Scruby.collection(Phone)
 
     # Create phone.
     phone = Phone(
@@ -201,8 +215,7 @@ async def main() -> None:
     )
 
     # Add phone to collection.
-    key = f"{phone.brand} {phone.model}"
-    await phone_coll.add_key(key, phone)
+    await phone_coll.add_doc(phone)
 
     # Find phone by brand.
     phone_details: Phone | None = await phone_coll.find_one(
@@ -232,60 +245,79 @@ if __name__ == "__main__":
 ```
 
 ```python
-"""Find one or more documents matching the filter.
+"""Find many 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.
 """
 
 import anyio
 import datetime
 from typing import Annotated
-from pydantic import BaseModel
-from scruby import Scruby, constants
+from pydantic import BaseModel, Field
+from scruby import Scruby, settings
 from pprint import pprint as pp
 
-constants.DB_ROOT = "ScrubyDB"  # By default = "ScrubyDB"
-constants.HASH_REDUCE_LEFT = 6  # By default = 6
+settings.DB_ROOT = "ScrubyDB"  # By default = "ScrubyDB"
+settings.HASH_REDUCE_LEFT = 6  # By default = 6
+settings.MAX_WORKERS = None  # By default = None
 
 
 class Car(BaseModel):
     """Car model."""
-    brand: str
-    model: str
-    year: int
-    power_reserve: int
+    brand: str = Field(strict=True, frozen=True)
+    model: str = Field(strict=True, frozen=True)
+    year: int = Field(strict=True)
+    power_reserve: int = Field(strict=True)
+    # The key is always at the bottom
+    key: str = Field(
+        strict=True,
+        frozen=True,
+        default_factory=lambda data: f"{data['brand']}:{data['model']}",
+    )
 
 
 async def main() -> None:
     """Example."""
-    # Get collection of `Car`.
-    car_coll = await Scruby.create(Car)
+    # Get collection `Car`.
+    car_coll = await Scruby.collection(Car)
 
     # Create cars.
-    for name in range(1, 10):
+    for num in range(1, 10):
         car = Car(
             brand="Mazda",
             model=f"EZ-6 {num}",
             year=2025,
             power_reserve=600,
         )
-        key = f"{car.brand} {car.model}"
-        await car_coll.add_key(key, car)
+        await car_coll.add_doc(car)
 
     # Find cars by brand and year.
     car_list: list[Car] | None = await car_coll.find_many(
-        filter_fn=lambda doc: doc.brand == "Mazda" or doc.year == 2025,
+        filter_fn=lambda doc: doc.brand == "Mazda" and doc.year == 2025,
     )
     if car_list is not None:
         pp(car_list)
     else:
         print("No cars!")
 
-    # Get collection list.
-    collection_list = await Scruby.collection_list()
-    print(ucollection_list)  # ["Car"]
+    # Find all cars.
+    car_list: list[Car] | None = await car_coll.find_many()
+    if car_list is not None:
+        pp(car_list)
+    else:
+        print("No cars!")
+
+    # For pagination output.
+    car_list: list[Car] | None = await car_coll.find_many(
+        filter_fn=lambda doc: doc.brand == "Mazda",
+        limit_docs=5,
+        page_number=2,
+    )
+    if car_list is not None:
+        pp(car_list)
+    else:
+        print("No cars!")
 
     # Full database deletion.
     # Hint: The main purpose is tests.

scruby-0.28.3.dist-info/RECORD

@@ -0,0 +1,18 @@
+scruby/__init__.py,sha256=bw2Le5ULYlf2nFQT_617rmEumu66Ll-QCLCxqDFERWw,1014
+scruby/aggregation.py,sha256=bd70J1Xye6faNHD8LS3lVQoHWKtPdPV_cqT_i7oui38,3491
+scruby/db.py,sha256=djo4JkfuKCcV3jRbd2L3mIwENS3ptqJBt7SlAuiRhGY,6794
+scruby/errors.py,sha256=D0jisudUsZk9iXp4nRSymaSMwyqHPVshsSlxx4HDVVk,1297
+scruby/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scruby/settings.py,sha256=_uVdZIGWoi6q9zcu0c2PS51OBEBNASRRrxfzaF7Nwy0,1580
+scruby/mixins/__init__.py,sha256=XPMjJvOZN7dLpTE1FfGMBGQ_0421HXug-0rWKMU5fRQ,627
+scruby/mixins/collection.py,sha256=coF-IOhicV_EihDwnYf6SW5Mfi3nOFR0gAhCc619NmI,1382
+scruby/mixins/count.py,sha256=PGzRtgLvseQnHg6wt-A81s30pnsdY1d8cr-EQRnbfyU,2050
+scruby/mixins/custom_task.py,sha256=ZhvCDiYnJ8BTIWlnRu6cTH-9G9o7dHSixjMIsxAtDpw,2316
+scruby/mixins/delete.py,sha256=B2loiowj8ToO0euumDRxpHUVrLQx0iTcRys0jszn-rA,3046
+scruby/mixins/find.py,sha256=gnHjnm0MZbzMHmWOBUJbMm8LZFBqdJ6yWA6Pxfap51Q,5340
+scruby/mixins/keys.py,sha256=OUByWbHfNVWJVkUrhCsJZdVqf0zez_an6Gti2n5iKnM,5671
+scruby/mixins/update.py,sha256=YkUiz1gcVtNXdgf7Mmda-0g3vJm3jL09v-msGy2tAWg,3229
+scruby-0.28.3.dist-info/METADATA,sha256=DoDzTEj_wrZu3EfAhBcKBtCfbr9pb74FS3spyDpFfzY,10849
+scruby-0.28.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+scruby-0.28.3.dist-info/licenses/LICENSE,sha256=mS0Wz0yGNB63gEcWEnuIb_lldDYV0sjRaO-o_GL6CWE,1074
+scruby-0.28.3.dist-info/RECORD,,

scruby-0.24.4.dist-info/RECORD

@@ -1,18 +0,0 @@
-scruby/__init__.py,sha256=elrW_AWMyl3kuTpEqGPaYFSpF8iVzjpivF6MxVNlqoQ,855
-scruby/aggregation.py,sha256=SYGcnMy2eq9vJb-pW3xR9LLAQIQ55TK-LGW_yKQ-7sU,3318
-scruby/constants.py,sha256=KInSZ_4dsQNXilrs7DvtQXevKEYibnNzl69a7XiWG4k,1099
-scruby/db.py,sha256=ggYW4dQPtr7m9-GM4QeYMMDZm5eUYN5bTAdz2Tj0hlw,5980
-scruby/errors.py,sha256=aj1zQlfxGwZC-bZZ07DRX2vHx31SpyWPqXHMpQ9kRVY,1124
-scruby/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-scruby/mixins/__init__.py,sha256=-rRZE-JZwGmEkC0wS_X0hs8OXsEYyvgSNIfil8wmjFA,454
-scruby/mixins/collection.py,sha256=eMnfHFdzk7LWILMmDbzugcOYSeIKp0DlEEqCmmGQRwA,1222
-scruby/mixins/count.py,sha256=Wcn6CeWrYSgsTTmYQ4J-CEiM4630rUSwRP9iKwbCl6c,2193
-scruby/mixins/custom_task.py,sha256=Ib1G1I7NyDGbow4SeafkYd9C0r6u6EDgUK0NxjhsEa0,2297
-scruby/mixins/delete.py,sha256=BmfQH68iX7kzC20w16xzFcLO3uLxYKdNyqZqIbXb1M0,3240
-scruby/mixins/find.py,sha256=va1hTm6Poua7_TMcZW2iqI-xmL1HcCUOx8pkKvTvu6U,5063
-scruby/mixins/keys.py,sha256=Hbb0AX68ph--fA43AXDWoM72PzSmS48h3iVwlQwQH0c,4971
-scruby/mixins/update.py,sha256=A9V4PjA3INnqLTGoBxIvC8y8Wo-nLxlFejkPUhsebzQ,3428
-scruby-0.24.4.dist-info/METADATA,sha256=RDE0Fa_IXd2hx2MDjdsI-5iwGhZOCZ9zOqqQuOe8k5g,9643
-scruby-0.24.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-scruby-0.24.4.dist-info/licenses/LICENSE,sha256=mS0Wz0yGNB63gEcWEnuIb_lldDYV0sjRaO-o_GL6CWE,1074
-scruby-0.24.4.dist-info/RECORD,,