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

scruby/__init__.py

@@ -1,8 +1,7 @@
-"""A fast key-value storage library.
+"""Asynchronous library for building and managing a hybrid database, by scheme of key-value.
 
-Scruby is a fast key-value storage asynchronous library that provides an
-ordered mapping from string keys to string values.
-The library uses fractal-tree addressing.
+The library uses fractal-tree addressing and
+the search for documents based on the effect of a quantum loop.
 
 The database consists of collections.
 The maximum size of the one collection is 16**8=4294967296 branches,
@@ -11,7 +10,8 @@ each branch can store one or more keys.
 The value of any key in collection can be obtained in 8 steps,
 thereby achieving high performance.
 
-In the future, to search by value of key, the use of a quantum loop is supposed.
+The effectiveness of the search for documents based on a quantum loop,
+requires a large number of processor threads.
 """
 
 from __future__ import annotations

scruby/db.py

@@ -11,7 +11,7 @@ import zlib
 from collections.abc import Callable
 from pathlib import Path as SyncPath
 from shutil import rmtree
-from typing import Any, Literal, Never, TypeVar, assert_never
+from typing import Any, Never, TypeVar, assert_never
 
 import orjson
 from anyio import Path, to_thread
@@ -48,13 +48,13 @@ class Scruby[T]:
         # The maximum number of keys.
         match self.__hash_reduce_left:
             case 0:
-                self.__max_num_keys = 4294967296
+                self.__max_branch_number = 4294967296
             case 2:
-                self.__max_num_keys = 16777216
+                self.__max_branch_number = 16777216
             case 4:
-                self.__max_num_keys = 65536
+                self.__max_branch_number = 65536
             case 6:
-                self.__max_num_keys = 256
+                self.__max_branch_number = 256
             case _ as unreachable:
                 msg: str = f"{unreachable} - Unacceptable value for HASH_REDUCE_LEFT."
                 logger.critical(msg)
@@ -68,8 +68,8 @@ class Scruby[T]:
 
         This method is for internal use.
         """
-        key: int = 0
-        key_as_hash: str = f"{key:08x}"[self.__hash_reduce_left :]
+        branch_number: int = 0
+        key_as_hash: str = f"{branch_number:08x}"[self.__hash_reduce_left :]
         separated_hash: str = "/".join(list(key_as_hash))
         branch_path = SyncPath(
             *(
@@ -92,9 +92,9 @@ class Scruby[T]:
 
         This method is for internal use.
         """
-        key: int = 0
-        key_as_hash: str = f"{key:08x}"[self.__hash_reduce_left :]
-        separated_hash: str = "/".join(list(key_as_hash))
+        branch_number: int = 0
+        branch_number_as_hash: str = f"{branch_number:08x}"[self.__hash_reduce_left :]
+        separated_hash: str = "/".join(list(branch_number_as_hash))
         return Path(
             *(
                 self.__db_root,
@@ -123,16 +123,43 @@ class Scruby[T]:
         meta_json = meta.model_dump_json()
         await meta_path.write_text(meta_json, "utf-8")
 
-    async def _counter_documents(self, step: Literal[1, -1]) -> None:
+    async def _counter_documents(self, number: int) -> None:
+        """Asynchronous method for management of documents in metadata of collection.
+
+        This method is for internal use.
+        """
+        meta_path = await self._get_meta_path()
+        meta_json = await meta_path.read_text("utf-8")
+        meta: _Meta = self.__meta.model_validate_json(meta_json)
+        meta.counter_documents += number
+        if meta.counter_documents < 0:
+            meta.counter_documents = 0
+        meta_json = meta.model_dump_json()
+        await meta_path.write_text(meta_json, "utf-8")
+
+    def _sync_counter_documents(self, number: int) -> None:
         """Management of documents in metadata of collection.
 
         This method is for internal use.
         """
-        meta = await self._get_meta()
-        meta.counter_documents += step
+        branch_number: int = 0
+        branch_number_as_hash: str = f"{branch_number:08x}"[self.__hash_reduce_left :]
+        separated_hash: str = "/".join(list(branch_number_as_hash))
+        meta_path = SyncPath(
+            *(
+                self.__db_root,
+                self.__class_model.__name__,
+                separated_hash,
+                "meta.json",
+            ),
+        )
+        meta_json = meta_path.read_text("utf-8")
+        meta: _Meta = self.__meta.model_validate_json(meta_json)
+        meta.counter_documents += number
         if meta.counter_documents < 0:
             meta.counter_documents = 0
-        await self._set_meta(meta)
+        meta_json = meta.model_dump_json()
+        meta_path.write_text(meta_json, "utf-8")
 
     async def _get_leaf_path(self, key: str) -> Path:
         """Asynchronous method for getting path to collection cell by key.
@@ -267,18 +294,18 @@ class Scruby[T]:
 
     @staticmethod
     def _task_find(
-        key: int,
+        branch_number: int,
         filter_fn: Callable,
-        HASH_REDUCE_LEFT: str,
+        hash_reduce_left: str,
         db_root: str,
         class_model: T,
     ) -> dict[str, Any] | None:
-        """Task for searching for documents.
+        """Task for find documents.
 
         This method is for internal use.
         """
-        key_as_hash: str = f"{key:08x}"[HASH_REDUCE_LEFT:]
-        separated_hash: str = "/".join(list(key_as_hash))
+        branch_number_as_hash: str = f"{branch_number:08x}"[hash_reduce_left:]
+        separated_hash: str = "/".join(list(branch_number_as_hash))
         leaf_path: SyncPath = SyncPath(
             *(
                 db_root,
@@ -302,7 +329,7 @@ class Scruby[T]:
         max_workers: int | None = None,
         timeout: float | None = None,
     ) -> T | None:
-        """Find a single document matching the filter.
+        """Finds a single document matching the filter.
 
         The search is based on the effect of a quantum loop.
         The search effectiveness depends on the number of processor threads.
@@ -316,18 +343,18 @@ class Scruby[T]:
             timeout: The number of seconds to wait for the result if the future isn't done.
                      If None, then there is no limit on the wait time.
         """
-        keys: range = range(1, self.__max_num_keys)
+        branch_numbers: range = range(1, self.__max_branch_number)
         search_task_fn: Callable = self._task_find
-        HASH_REDUCE_LEFT: int = self.__hash_reduce_left
+        hash_reduce_left: int = self.__hash_reduce_left
         db_root: str = self.__db_root
         class_model: T = self.__class_model
         with concurrent.futures.ThreadPoolExecutor(max_workers) as executor:
-            for key in keys:
+            for branch_number in branch_numbers:
                 future = executor.submit(
                     search_task_fn,
-                    key,
+                    branch_number,
                     filter_fn,
-                    HASH_REDUCE_LEFT,
+                    hash_reduce_left,
                     db_root,
                     class_model,
                 )
@@ -336,14 +363,14 @@ class Scruby[T]:
                     return doc
         return None
 
-    def find(
+    def find_many(
         self,
         filter_fn: Callable,
         db_query_docs_limit: int = 1000,
         max_workers: int | None = None,
         timeout: float | None = None,
     ) -> list[T] | None:
-        """Find one or more documents matching the filter.
+        """Finds 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.
@@ -358,22 +385,22 @@ class Scruby[T]:
             timeout: The number of seconds to wait for the result if the future isn't done.
                      If None, then there is no limit on the wait time.
         """
-        keys: range = range(1, self.__max_num_keys)
+        branch_numbers: range = range(1, self.__max_branch_number)
         search_task_fn: Callable = self._task_find
-        HASH_REDUCE_LEFT: int = self.__hash_reduce_left
+        hash_reduce_left: int = self.__hash_reduce_left
         db_root: str = self.__db_root
         class_model: T = self.__class_model
         counter: int = 0
         with concurrent.futures.ThreadPoolExecutor(max_workers) as executor:
             results = []
-            for key in keys:
+            for branch_number in branch_numbers:
                 if counter == db_query_docs_limit:
                     break
                 future = executor.submit(
                     search_task_fn,
-                    key,
+                    branch_number,
                     filter_fn,
-                    HASH_REDUCE_LEFT,
+                    hash_reduce_left,
                     db_root,
                     class_model,
                 )
@@ -416,22 +443,99 @@ class Scruby[T]:
             timeout: The number of seconds to wait for the result if the future isn't done.
                      If None, then there is no limit on the wait time.
         """
-        keys: range = range(1, self.__max_num_keys)
+        branch_numbers: range = range(1, self.__max_branch_number)
         search_task_fn: Callable = self._task_find
-        HASH_REDUCE_LEFT: int = self.__hash_reduce_left
+        hash_reduce_left: int = self.__hash_reduce_left
         db_root: str = self.__db_root
         class_model: T = self.__class_model
         counter: int = 0
         with concurrent.futures.ThreadPoolExecutor(max_workers) as executor:
-            for key in keys:
+            for branch_number in branch_numbers:
                 future = executor.submit(
                     search_task_fn,
-                    key,
+                    branch_number,
                     filter_fn,
-                    HASH_REDUCE_LEFT,
+                    hash_reduce_left,
                     db_root,
                     class_model,
                 )
                 if future.result(timeout) is not None:
                     counter += 1
         return counter
+
+    @staticmethod
+    def _task_delete(
+        branch_number: int,
+        filter_fn: Callable,
+        hash_reduce_left: str,
+        db_root: str,
+        class_model: T,
+    ) -> int:
+        """Task for find and delete documents.
+
+        This method is for internal use.
+        """
+        branch_number_as_hash: str = f"{branch_number:08x}"[hash_reduce_left:]
+        separated_hash: str = "/".join(list(branch_number_as_hash))
+        leaf_path: SyncPath = SyncPath(
+            *(
+                db_root,
+                class_model.__name__,
+                separated_hash,
+                "leaf.json",
+            ),
+        )
+        counter: int = 0
+        if leaf_path.exists():
+            data_json: bytes = leaf_path.read_bytes()
+            data: dict[str, str] = orjson.loads(data_json) or {}
+            new_data: dict[str, str] = {}
+            for key, val in data.items():
+                doc = class_model.model_validate_json(val)
+                if filter_fn(doc):
+                    counter -= 1
+                else:
+                    new_data[key] = val
+            leaf_path.write_bytes(orjson.dumps(new_data))
+        return counter
+
+    def find_many_and_delete(
+        self,
+        filter_fn: Callable,
+        max_workers: int | None = None,
+        timeout: float | None = None,
+    ) -> int:
+        """Finds one or more documents matching the filter and deletes their.
+
+        The search is based on the effect of a quantum loop.
+        The search effectiveness depends on the number of processor threads.
+        Ideally, hundreds and even thousands of threads are required.
+
+        Args:
+            filter_fn: A function that execute the conditions of filtering.
+            max_workers: The maximum number of processes that can be used to
+                         execute the given calls. If None or not given then as many
+                         worker processes will be created as the machine has processors.
+            timeout: The number of seconds to wait for the result if the future isn't done.
+                     If None, then there is no limit on the wait time.
+        """
+        branch_numbers: range = range(1, self.__max_branch_number)
+        search_task_fn: Callable = self._task_delete
+        hash_reduce_left: int = self.__hash_reduce_left
+        db_root: str = self.__db_root
+        class_model: T = self.__class_model
+        counter: int = 0
+        with concurrent.futures.ThreadPoolExecutor(max_workers) as executor:
+            for branch_number in branch_numbers:
+                future = executor.submit(
+                    search_task_fn,
+                    branch_number,
+                    filter_fn,
+                    hash_reduce_left,
+                    db_root,
+                    class_model,
+                )
+                counter += future.result(timeout)
+        if counter < 0:
+            self._sync_counter_documents(counter)
+        return abs(counter)

{scruby-0.10.4.dist-info → scruby-0.11.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scruby
-Version: 0.10.4
+Version: 0.11.1
 Summary: A fast key-value storage library.
 Project-URL: Homepage, https://github.com/kebasyaty/scruby
 Project-URL: Repository, https://github.com/kebasyaty/scruby
@@ -43,7 +43,7 @@ Description-Content-Type: text/markdown
   </p>
   <p>
     <h1>Scruby</h1>
-    <h3>A fast key-value storage library.</h3>
+    <h3>Asynchronous library for building and managing a hybrid database,<br>by scheme of key-value.</h3>
     <p align="center">
       <a href="https://github.com/kebasyaty/scruby/actions/workflows/test.yml" alt="Build Status"><img src="https://github.com/kebasyaty/scruby/actions/workflows/test.yml/badge.svg" alt="Build Status"></a>
       <a href="https://kebasyaty.github.io/scruby/" alt="Docs"><img src="https://img.shields.io/badge/docs-available-brightgreen.svg" alt="Docs"></a>
@@ -65,20 +65,23 @@ Description-Content-Type: text/markdown
       <a href="https://github.com/kebasyaty/scruby/releases/" alt="GitHub release"><img src="https://img.shields.io/github/release/kebasyaty/scruby" alt="GitHub release"></a>
     </p>
     <p align="center">
-      Scruby is a fast key-value storage asynchronous library that provides an
-      <br>
-      ordered mapping from string keys to string values.
-      <br>
-      The library uses fractal-tree addressing.
-      <br>
-      The database consists of collections.
-      <br>
-      The maximum size of the one collection is 16**8=4294967296 branches,
-      each branch can store one or more keys.
-      <br>
-      The value of any key in collection can be obtained in 8 steps, thereby achieving high performance.
-      <br>
-      In the future, to search by value of key, the use of a quantum loop is supposed.
+        The library uses fractal-tree addressing and
+        <br>
+        the search for documents based on the effect of a quantum loop.
+        <br>
+        The database consists of collections.
+        <br>
+        The maximum size of the one collection is 16\*\*8=4294967296 branches,
+        <br>
+        each branch can store one or more keys.
+        <br>
+        The value of any key in collection can be obtained in 8 steps,
+        <br>
+        thereby achieving high performance.
+        <br>
+        The effectiveness of the search for documents based on a quantum loop,
+        <br>
+        requires a large number of processor threads.
     </p>
   </p>
 </div>
@@ -274,7 +277,7 @@ async def main() -> None:
         await db.set_key(f"+44798612345{num}", user)
 
     # Find users by email.
-    users: list[User] | None = user_coll.find(
+    users: list[User] | None = user_coll.find_many(
         filter_fn=lambda doc: doc.email == "John_Smith_5@gmail.com" or doc.email == "John_Smith_8@gmail.com",
     )
     if users is not None:

scruby-0.11.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+scruby/__init__.py,sha256=GOVcjXmcOEDBbJQJDJlQq-x3M-VGJaMSN278EXsl2po,884
+scruby/constants.py,sha256=3LZfcxcuRqwzoB0-iogLMjKBZRdxfWJmTbyPwVRhQgY,1007
+scruby/db.py,sha256=Q7J4OKS2emiF0KzZClSjpBBLjohnccZ81T4pgoWNxqA,20269
+scruby/errors.py,sha256=aHQri4LNcFVQrSHwjyzb1fL8O49SwjYEU4QgMOo4uyA,622
+scruby/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scruby-0.11.1.dist-info/METADATA,sha256=Dn9WBqLzI312HlhMx4PGIVpmysCc6IUSPqXjXDuAOQY,10926
+scruby-0.11.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+scruby-0.11.1.dist-info/licenses/LICENSE,sha256=2zZINd6m_jNYlowdQImlEizyhSui5cBAJZRhWQURcEc,1095
+scruby-0.11.1.dist-info/RECORD,,

scruby-0.10.4.dist-info/RECORD

@@ -1,9 +0,0 @@
-scruby/__init__.py,sha256=wFwUS1KcLxfIopXOVS8gPue9fNzIIU2cVj_RgK5drz4,849
-scruby/constants.py,sha256=3LZfcxcuRqwzoB0-iogLMjKBZRdxfWJmTbyPwVRhQgY,1007
-scruby/db.py,sha256=k_I2rphHG7Y5vq8oGDoimlKEwPEwmYzkqn7_DO0M6ic,15853
-scruby/errors.py,sha256=aHQri4LNcFVQrSHwjyzb1fL8O49SwjYEU4QgMOo4uyA,622
-scruby/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-scruby-0.10.4.dist-info/METADATA,sha256=oJLzRBPPatu6dsq7EQyxf-UHQn4uJ1kF3C7Q-heqVNw,10819
-scruby-0.10.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-scruby-0.10.4.dist-info/licenses/LICENSE,sha256=2zZINd6m_jNYlowdQImlEizyhSui5cBAJZRhWQURcEc,1095
-scruby-0.10.4.dist-info/RECORD,,