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

scruby/__init__.py

@@ -1,16 +1,11 @@
 #
-# .|'''|                        '||
-# ||                             ||
-# `|'''|, .|'', '||''| '||  ||`  ||''|, '||  ||`
-#  .   || ||     ||     ||  ||   ||  ||  `|..||
-#  |...|' `|..' .||.    `|..'|. .||..|'      ||
-#                                         ,  |'
-#                                          ''
-#
+# .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
-# Scruby is free software under terms of the MIT License.
-# Repository https://github.com/kebasyaty/scruby
+# SPDX-License-Identifier: MIT
 #
 """Asynchronous library for building and managing a hybrid database, by scheme of key-value.
 
@@ -30,14 +25,11 @@ requires a large number of processor threads.
 
 from __future__ import annotations
 
-__all__ = ("Scruby",)
-
-import logging
-
-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",
+__all__ = (
+    "settings",
+    "Scruby",
+    "ScrubyModel",
 )
+
+from scruby import settings
+from scruby.db import Scruby, ScrubyModel

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,22 +1,28 @@
+# 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",)
+__all__ = (
+    "Scruby",
+    "ScrubyModel",
+)
 
 import contextlib
 import logging
 import re
 import zlib
+from datetime import datetime
 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__)
+from scruby import mixins, settings
 
 
 class _Meta(BaseModel):
@@ -29,8 +35,15 @@ class _Meta(BaseModel):
     counter_documents: int
 
 
+class ScrubyModel(BaseModel):
+    """Additional fields for models."""
+
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
 class Scruby(
-    mixins.Docs,
+    mixins.Keys,
     mixins.Find,
     mixins.CustomTask,
     mixins.Collection,
@@ -45,21 +58,22 @@ class Scruby(
     ) -> 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:
-                self._max_branch_number = 4294967296
+                self._max_number_branch = 4294967296
             case 2:
-                self._max_branch_number = 16777216
+                self._max_number_branch = 16777216
             case 4:
-                self._max_branch_number = 65536
+                self._max_number_branch = 65536
             case 6:
-                self._max_branch_number = 256
+                self._max_number_branch = 256
             case _ as unreachable:
                 msg: str = f"{unreachable} - Unacceptable value for HASH_REDUCE_LEFT."
-                logger.critical(msg)
+                logging.critical(msg)
                 assert_never(Never(unreachable))  # pyrefly: ignore[not-callable]
 
     @classmethod
@@ -67,42 +81,67 @@ class Scruby(
         """Get an object to access a collection.
 
         Args:
-            class_model: Class of Model (pydantic.BaseModel).
+            class_model (Any): Class of Model (ScrubyModel).
 
         Returns:
             Instance of Scruby for access a collection.
         """
-        assert BaseModel in class_model.__bases__, "`class_model` does not contain the base class `pydantic.BaseModel`!"
-
+        if __debug__:
+            # Check if the object belongs to the class `ScrubyModel`
+            if ScrubyModel not in class_model.__bases__:
+                msg = (
+                    "Method: `collection` => argument `class_model` " + "does not contain the base class `ScrubyModel`!"
+                )
+                raise AssertionError(msg)
+            # Checking the model for the presence of a key.
+            model_fields = list(class_model.model_fields.keys())
+            if "key" not in model_fields:
+                msg = f"Model: {class_model.__name__} => The `key` field is missing!"
+                raise AssertionError(msg)
+            if "created_at" not in model_fields:
+                msg = f"Model: {class_model.__name__} => The `created_at` field is missing!"
+                raise AssertionError(msg)
+            if "updated_at" not in model_fields:
+                msg = f"Model: {class_model.__name__} => The `updated_at` field is missing!"
+                raise AssertionError(msg)
+            # Check the length of the collection name for an acceptable size.
+            len_db_root_absolut_path = len(str(await Path(settings.DB_ROOT).resolve()).encode("utf-8"))
+            len_model_name = len(class_model.__name__)
+            len_full_path_leaf = len_db_root_absolut_path + len_model_name + 26
+            if len_full_path_leaf > 255:
+                excess = len_full_path_leaf - 255
+                msg = (
+                    f"Model: {class_model.__name__} => The collection name is too long, "
+                    + f"it exceeds the limit of {excess} characters!"
+                )
+                raise AssertionError(msg)
+        # Create instance of Scruby
         instance = cls()
+        # Add model class to Scruby
         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))
+        # Create a path for metadata.
         meta_dir_path_tuple = (
-            constants.DB_ROOT,
+            settings.DB_ROOT,
             class_model.__name__,
-            separated_hash,
+            "meta",
         )
         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_dir_path = Path(*meta_dir_path_tuple)
+        if not await meta_dir_path.exists():
+            await meta_dir_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,
-                max_branch_number=instance.__dict__["_max_branch_number"],
+                hash_reduce_left=settings.HASH_REDUCE_LEFT,
+                max_branch_number=instance.__dict__["_max_number_branch"],
                 counter_documents=0,
             )
             meta_json = meta.model_dump_json()
-            meta_path = Path(*(branch_path, "meta.json"))
+            meta_path = Path(*(meta_dir_path, "meta.json"))
             await meta_path.write_text(meta_json, "utf-8")
         return instance
 
@@ -123,6 +162,9 @@ class Scruby(
 
         This method is for internal use.
 
+        Args:
+            meta (_Meta): Metadata of Collection.
+
         Returns:
             None.
         """
@@ -134,6 +176,9 @@ class Scruby(
 
         This method is for internal use.
 
+        Args:
+            step (Literal[1, -1]): Number of documents added or removed.
+
         Returns:
             None.
         """
@@ -157,7 +202,7 @@ class Scruby(
         """
         if not isinstance(key, str):
             msg = "The key is not a string."
-            logger.error(msg)
+            logging.error(msg)
             raise KeyError(msg)
         # Prepare key.
         # Removes spaces at the beginning and end of a string.
@@ -166,7 +211,7 @@ class Scruby(
         # Check the key for an empty string.
         if len(prepared_key) == 0:
             msg = "The key should not be empty."
-            logger.error(msg)
+            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 :]
@@ -200,5 +245,5 @@ class Scruby(
             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
@@ -8,7 +12,7 @@ __all__ = (
     "CustomTask",
     "Delete",
     "Find",
-    "Docs",
+    "Keys",
     "Update",
 )
 
@@ -16,6 +20,6 @@ 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 Docs
 from scruby.mixins.find import Find
+from scruby.mixins.keys import Keys
 from scruby.mixins.update import Update

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}"
+        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,28 @@ 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.
+        Attention:
+            - The search is based on the effect of a quantum loop.
+            - The search effectiveness depends on the number of processor threads.
 
         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:
             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(self._max_number_branch)
         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.
 
@@ -51,26 +50,25 @@ class CustomTask[T]:
                 docs.append(class_model.model_validate_json(val))
         return docs
 
-    async def run_custom_task(self, custom_task_fn: Callable, limit_docs: int = 1000) -> Any:
+    async def run_custom_task(self, custom_task_fn: Callable) -> Any:
         """Running custom task.
 
-        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.
+        Attention:
+            - The search is based on the effect of a quantum loop.
+            - The search effectiveness depends on the number of processor threads.
 
         Args:
-            custom_task_fn: A function that execute the custom task.
-            limit_docs: Limiting the number of documents. By default = 1000.
+            custom_task_fn (Callable): A function that execute the custom task.
 
         Returns:
             The result of a custom task.
         """
         kwargs = {
             "get_docs_fn": self._task_get_docs,
-            "branch_numbers": range(1, self._max_branch_number),
+            "branch_numbers": range(self._max_number_branch),
             "hash_reduce_left": self._hash_reduce_left,
             "db_root": self._db_root,
             "class_model": self._class_model,
-            "limit_docs": limit_docs,
+            "max_workers": self._max_workers,
         }
         return await custom_task_fn(**kwargs)

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,28 @@ 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.
+        Attention:
+            - The search is based on the effect of a quantum loop.
+            - The search effectiveness depends on the number of processor threads.
 
         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:
             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(self._max_number_branch)
         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,27 @@ 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.
+        Attention:
+            - The search is based on the effect of a quantum loop.
+            - The search effectiveness depends on the number of processor threads.
 
         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(self._max_number_branch)
         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 +95,41 @@ 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.
+        Attention:
+            - The search is based on the effect of a quantum loop.
+            - The search effectiveness depends on the number of processor threads.
 
         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(self._max_number_branch)
         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 +142,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/{docs.py → keys.py}

@@ -1,11 +1,17 @@
+# 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
 
-__all__ = ("Docs",)
+__all__ = ("Keys",)
 
 import logging
+from datetime import datetime
 from typing import Any
+from zoneinfo import ZoneInfo
 
 import orjson
 
@@ -14,17 +20,15 @@ from scruby.errors import (
     KeyNotExistsError,
 )
 
-logger = logging.getLogger(__name__)
 
-
-class Docs:
-    """Methods for working with document."""
+class Keys:
+    """Methods for working with keys."""
 
     async def add_doc(self, doc: Any) -> None:
         """Asynchronous method for adding document to collection.
 
         Args:
-            doc: Value of key. Type, derived from `BaseModel`.
+            doc (Any): Value of key. Type, derived from `ScrubyModel`.
 
         Returns:
             None.
@@ -36,10 +40,15 @@ class Docs:
             msg = (
                 f"(add_doc) Parameter `doc` => Model `{doc_class_name}` does not match collection `{collection_name}`!"
             )
-            logger.error(msg)
+            logging.error(msg)
             raise TypeError(msg)
         # The path to cell of collection.
         leaf_path, prepared_key = await self._get_leaf_path(doc.key)
+        # Init a `created_at` and `updated_at` fields
+        tz = ZoneInfo("UTC")
+        doc.created_at = datetime.now(tz)
+        doc.updated_at = datetime.now(tz)
+        # Convert doc to json
         doc_json: str = doc.model_dump_json()
         # Write key-value to collection.
         if await leaf_path.exists():
@@ -53,7 +62,7 @@ class Docs:
                 await leaf_path.write_bytes(orjson.dumps(data))
             else:
                 err = KeyAlreadyExistsError()
-                logger.error(err.message)
+                logging.error(err.message)
                 raise err
         else:
             # Add new document to a blank leaf.
@@ -61,10 +70,10 @@ class Docs:
         await self._counter_documents(1)
 
     async def update_doc(self, doc: Any) -> None:
-        """Asynchronous method for updating key to collection.
+        """Asynchronous method for updating document to collection.
 
         Args:
-            doc: Value of key. Type `BaseModel`.
+            doc (Any): Value of key. Type `ScrubyModel`.
 
         Returns:
             None.
@@ -77,10 +86,13 @@ class Docs:
                 f"(update_doc) Parameter `doc` => Model `{doc_class_name}` "
                 f"does not match collection `{collection_name}`!"
             )
-            logger.error(msg)
+            logging.error(msg)
             raise TypeError(msg)
         # The path to cell of collection.
         leaf_path, prepared_key = await self._get_leaf_path(doc.key)
+        # Update a `updated_at` field
+        doc.updated_at = datetime.now(ZoneInfo("UTC"))
+        # Convert doc to json
         doc_json: str = doc.model_dump_json()
         # Update the existing key.
         if await leaf_path.exists():
@@ -93,17 +105,18 @@ class Docs:
                 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.")
-            raise KeyError()
+            msg: str = f"`update_doc` - The key `{doc.key}` is missing!"
+            logging.error(msg)
+            raise KeyError(msg)
 
-    async def get_key(self, key: str) -> Any:
-        """Asynchronous method for getting value of key from collection.
+    async def get_doc(self, key: str) -> Any:
+        """Asynchronous method for getting document from collection the by key.
 
         Args:
-            key: Key name.
+            key (str): Key name.
 
         Returns:
             Value of key or KeyError.
@@ -116,15 +129,15 @@ class Docs:
             data: dict = orjson.loads(data_json) or {}
             obj: Any = self._class_model.model_validate_json(data[prepared_key])
             return obj
-        msg: str = "`get_key` - The unacceptable key value."
-        logger.error(msg)
-        raise KeyError()
+        msg: str = f"`get_doc` - The key `{key}` is missing!"
+        logging.error(msg)
+        raise KeyError(msg)
 
     async def has_key(self, key: str) -> bool:
         """Asynchronous method for checking presence of key in collection.
 
         Args:
-            key: Key name.
+            key (str): Key name.
 
         Returns:
             True, if the key is present.
@@ -142,11 +155,11 @@ class Docs:
                 return False
         return False
 
-    async def delete_key(self, key: str) -> None:
-        """Asynchronous method for deleting key from collection.
+    async def delete_doc(self, key: str) -> None:
+        """Asynchronous method for deleting document from collection the by key.
 
         Args:
-            key: Key name.
+            key (str): Key name.
 
         Returns:
             None.
@@ -161,6 +174,6 @@ class Docs:
             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()
+        msg: str = f"`delete_doc` - The key `{key}` is missing!"
+        logging.error(msg)
+        raise KeyError(msg)

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.
@@ -63,33 +62,33 @@ class Update[T]:
 
     async def update_many(
         self,
-        filter_fn: Callable,
         new_data: dict[str, Any],
-        max_workers: int | None = None,
+        filter_fn: Callable = lambda _: True,
     ) -> int:
-        """Updates one or more documents matching the filter.
+        """Updates 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.
+        Attention:
+            - For a complex case, a custom task may be needed.
+            - See documentation on creating custom tasks.
+            - The search is based on the effect of a quantum loop.
+            - The search effectiveness depends on the number of processor threads.
 
         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.
+            filter_fn (Callable): A function that execute the conditions of filtering.
+            new_data (dict[str, Any]): New data for the fields that need to be updated.
 
         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(self._max_number_branch)
         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.26.0.dist-info → scruby-0.30.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scruby
-Version: 0.26.0
+Version: 0.30.2
 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
@@ -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
@@ -98,6 +99,15 @@ Online browsable documentation is available at [https://kebasyaty.github.io/scru
 uv add scruby
 ```
 
+## Run
+
+```shell
+# Run Development:
+uv run python main.py
+# Run Production:
+uv run python -OOP main.py
+```
+
 ## Usage
 
 See more examples here [https://kebasyaty.github.io/scruby/latest/pages/usage/](https://kebasyaty.github.io/scruby/latest/pages/usage/ "Examples").
@@ -106,23 +116,25 @@ See more examples here [https://kebasyaty.github.io/scruby/latest/pages/usage/](
 """Working with keys."""
 
 import anyio
-import datetime
+from datetime import datetime
+from zoneinfo import ZoneInfo
 from typing import Annotated
-from pydantic import BaseModel, EmailStr, Field
+from pydantic import EmailStr, Field
 from pydantic_extra_types.phone_numbers import PhoneNumber, PhoneNumberValidator
-from scruby import Scruby, constants
+from scruby import Scruby, ScrubyModel, 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):
+class User(ScrubyModel):
     """User model."""
     first_name: str = Field(strict=True)
     last_name: str = Field(strict=True)
-    birthday: datetime.datetime = Field(strict=True)
+    birthday: 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 is always at bottom
     key: str = Field(
         strict=True,
         frozen=True,
@@ -132,13 +144,13 @@ class User(BaseModel):
 
 async def main() -> None:
     """Example."""
-    # Get collection of `User`.
+    # Get collection `User`.
     user_coll = await Scruby.collection(User)
 
     user = User(
         first_name="John",
         last_name="Smith",
-        birthday=datetime.datetime(1970, 1, 1),
+        birthday=datetime.datetime(1970, 1, 1, tzinfo=ZoneInfo("UTC")),
         email="John_Smith@gmail.com",
         phone="+447986123456",
     )
@@ -147,15 +159,15 @@ async def main() -> None:
 
     await user_coll.update_doc(user)
 
-    await user_coll.get_key("+447986123456")  # => user
-    await user_coll.get_key("key missing")  # => KeyError
+    await user_coll.get_doc("+447986123456")  # => user
+    await user_coll.get_doc("key missing")  # => KeyError
 
     await user_coll.has_key("+447986123456")  # => True
     await user_coll.has_key("key missing")  # => False
 
-    await user_coll.delete_key("+447986123456")
-    await user_coll.delete_key("+447986123456")  # => KeyError
-    await user_coll.delete_key("key missing")  # => KeyError
+    await user_coll.delete_doc("+447986123456")
+    await user_coll.delete_doc("+447986123456")  # => KeyError
+    await user_coll.delete_doc("key missing")  # => KeyError
 
     # Full database deletion.
     # Hint: The main purpose is tests.
@@ -167,31 +179,31 @@ 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 datetime import datetime
 from typing import Annotated
-from pydantic import BaseModel, Field
-from scruby import Scruby, constants
+from pydantic import Field
+from scruby import Scruby, ScrubyModel, 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):
+class Phone(ScrubyModel):
     """Phone model."""
     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 is always at bottom
     key: str = Field(
         strict=True,
         frozen=True,
@@ -201,7 +213,7 @@ class Phone(BaseModel):
 
 async def main() -> None:
     """Example."""
-    # Get collection of `Phone`.
+    # Get collection `Phone`.
     phone_coll = await Scruby.collection(Phone)
 
     # Create phone.
@@ -243,31 +255,31 @@ 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 datetime import datetime
 from typing import Annotated
-from pydantic import BaseModel, Field
-from scruby import Scruby, constants
+from pydantic import Field
+from scruby import Scruby, ScrubyModel, 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):
+class Car(ScrubyModel):
     """Car model."""
     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 is always at bottom
     key: str = Field(
         strict=True,
         frozen=True,
@@ -277,11 +289,11 @@ class Car(BaseModel):
 
 async def main() -> None:
     """Example."""
-    # Get collection of `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}",
@@ -299,9 +311,23 @@ async def main() -> None:
     else:
         print("No cars!")
 
-    # Get collection list.
-    collection_list = await Scruby.collection_list()
-    print(collection_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.30.2.dist-info/RECORD

@@ -0,0 +1,18 @@
+scruby/__init__.py,sha256=WuIA27d3uUK0Vo0fXg92hge7i6v_2DBndhfepK16_y8,1046
+scruby/aggregation.py,sha256=bd70J1Xye6faNHD8LS3lVQoHWKtPdPV_cqT_i7oui38,3491
+scruby/db.py,sha256=4bSPMh0fYil0j9qhHhRu1g4U_0WaCuaGPthnmi2QpBI,8376
+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=YHjonxAtroSc5AlbDX1vpCvbe3vsTD0LfYnjEDB001A,2089
+scruby/mixins/custom_task.py,sha256=ENr3FkCsPWRblOWv8jGMkkGKw4hvp9mMP2YjQvIeqzE,2246
+scruby/mixins/delete.py,sha256=b7RYiTLUqVu70ep15CN1VTyKs13P7f-1YDGRc3ke-2g,3085
+scruby/mixins/find.py,sha256=-rpILkxhfywJ5E3ceYo9dSPabma47ouceGajUVNh23Q,5396
+scruby/mixins/keys.py,sha256=waxye5n0-oTWIhdDXGQkUTGaV9vLSCc9lCryTCuexkw,6179
+scruby/mixins/update.py,sha256=WeNk2qZToQS3-r1_ahazBc2ErLMU9K5RRNgCxbu3JMg,3416
+scruby-0.30.2.dist-info/METADATA,sha256=OgV4Foj3-X97NKFLpw_8Qb_osGwmYIINO2UZkgdLaY0,11032
+scruby-0.30.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+scruby-0.30.2.dist-info/licenses/LICENSE,sha256=mS0Wz0yGNB63gEcWEnuIb_lldDYV0sjRaO-o_GL6CWE,1074
+scruby-0.30.2.dist-info/RECORD,,

scruby-0.26.0.dist-info/RECORD

@@ -1,18 +0,0 @@
-scruby/__init__.py,sha256=iYjvi002DeRh-U_ND2cCOHlbX2xwxN8IIhsposeotNw,1504
-scruby/aggregation.py,sha256=SYGcnMy2eq9vJb-pW3xR9LLAQIQ55TK-LGW_yKQ-7sU,3318
-scruby/constants.py,sha256=KInSZ_4dsQNXilrs7DvtQXevKEYibnNzl69a7XiWG4k,1099
-scruby/db.py,sha256=06GjnhN9lKvZo585nxKFd4z8Ox858Ep08c7eCbMA99k,6462
-scruby/errors.py,sha256=aj1zQlfxGwZC-bZZ07DRX2vHx31SpyWPqXHMpQ9kRVY,1124
-scruby/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-scruby/mixins/__init__.py,sha256=w1Be13FHAGSkdRfXcmoZ-eDn5Q8cFsPRAV7k1tXkIwY,454
-scruby/mixins/collection.py,sha256=kqUgzJbgG9pTZhlP7OD5DsOaArRzu0fl6fVibLAdNtk,1260
-scruby/mixins/count.py,sha256=Wcn6CeWrYSgsTTmYQ4J-CEiM4630rUSwRP9iKwbCl6c,2193
-scruby/mixins/custom_task.py,sha256=DL-pQZninz7CJUyRYlVV7SNPC60qMD3ZQyMLnC3zVTM,2294
-scruby/mixins/delete.py,sha256=BmfQH68iX7kzC20w16xzFcLO3uLxYKdNyqZqIbXb1M0,3240
-scruby/mixins/docs.py,sha256=UHawXUjIkDBtik6MIQwbPF3DZKSOG8WI4Da9_i_-9R4,5533
-scruby/mixins/find.py,sha256=va1hTm6Poua7_TMcZW2iqI-xmL1HcCUOx8pkKvTvu6U,5063
-scruby/mixins/update.py,sha256=A9V4PjA3INnqLTGoBxIvC8y8Wo-nLxlFejkPUhsebzQ,3428
-scruby-0.26.0.dist-info/METADATA,sha256=CluDLzRgB952ZDbbxdsXuHGE598BzIiF5eYXpGaNdj4,10483
-scruby-0.26.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-scruby-0.26.0.dist-info/licenses/LICENSE,sha256=mS0Wz0yGNB63gEcWEnuIb_lldDYV0sjRaO-o_GL6CWE,1074
-scruby-0.26.0.dist-info/RECORD,,