scruby 0.6.3__py3-none-any.whl → 0.7.1__py3-none-any.whl

scruby/constants.py

@@ -3,18 +3,18 @@
 The module contains the following variables:
 
 - `DB_ROOT` - Path to root directory of database. `By default = "ScrubyDB"` (*in root of project*).
-- `LENGTH_SEPARATED_HASH` - Length of separated hash for create path inside collection.
-    - `2` - 256 branches (main purpose is tests).
-    - `4` - 65536 branches.
-    - `6` - 16777216 branches.
-    - `8` - 4294967296 branches (by default).
+- `LENGTH_REDUCTION_HASH` - The length of the hash reduction on the left side.
+    - `0` - 4294967296 keys (by default).
+    - `2` - 16777216 keys.
+    - `4` - 65536 keys.
+    - `6` - 256 keys (main purpose is tests).
 """
 
 from __future__ import annotations
 
 __all__ = (
     "DB_ROOT",
-    "LENGTH_SEPARATED_HASH",
+    "LENGTH_REDUCTION_HASH",
 )
 
 from typing import Literal
@@ -23,10 +23,9 @@ from typing import Literal
 # By default = "ScrubyDB" (in root of project).
 DB_ROOT: str = "ScrubyDB"
 
-# Length of separated hash for create path inside collection.
-# By default = 8
-# 2 = 256 branches (main purpose is tests).
-# 4 = 65536 branches.
-# 6 = 16777216 branches.
-# 8 = 4294967296 branches (by default).
-LENGTH_SEPARATED_HASH: Literal[2, 4, 6, 8] = 8
+# The length of the hash reduction on the left side.
+# 0 = 4294967296 keys (by default).
+# 2 = 16777216 keys.
+# 4 = 65536 keys.
+# 6 = 256 keys (main purpose is tests).
+LENGTH_REDUCTION_HASH: Literal[0, 2, 4, 6] = 0

scruby/db.py

@@ -4,10 +4,13 @@ from __future__ import annotations
 
 __all__ = ("Scruby",)
 
+import concurrent.futures
 import contextlib
 import zlib
+from collections.abc import Callable
+from pathlib import Path as SyncPath
 from shutil import rmtree
-from typing import TypeVar
+from typing import Any, Never, TypeVar, assert_never
 
 import orjson
 from anyio import Path, to_thread
@@ -29,6 +32,20 @@ class Scruby[T]:
         class_model: T,
     ) -> None:
         self.__class_model = class_model
+        self.__db_root = constants.DB_ROOT
+        self.__length_reduction_hash = constants.LENGTH_REDUCTION_HASH
+        # The maximum number of keys.
+        match self.__length_reduction_hash:
+            case 0:
+                self.__max_num_keys = 4294967296
+            case 2:
+                self.__max_num_keys = 16777216
+            case 4:
+                self.__max_num_keys = 65536
+            case 6:
+                self.__max_num_keys = 256
+            case _ as unreachable:
+                assert_never(Never(unreachable))
 
     async def get_leaf_path(self, key: str) -> Path:
         """Asynchronous method for getting path to collection cell by key.
@@ -40,16 +57,14 @@ class Scruby[T]:
             raise KeyError("The key is not a type of `str`.")
         if len(key) == 0:
             raise KeyError("The key should not be empty.")
-        # Get length of hash.
-        length_hash = constants.LENGTH_SEPARATED_HASH
         # Key to crc32 sum.
-        key_as_hash: str = f"{zlib.crc32(key.encode('utf-8')):08x}"[0:length_hash]
+        key_as_hash: str = f"{zlib.crc32(key.encode('utf-8')):08x}"[self.__length_reduction_hash :]
         # Convert crc32 sum in the segment of path.
         separated_hash: str = "/".join(list(key_as_hash))
         # The path of the branch to the database.
         branch_path: Path = Path(
             *(
-                constants.DB_ROOT,
+                self.__db_root,
                 self.__class_model.__name__,
                 separated_hash,
             ),
@@ -138,8 +153,8 @@ class Scruby[T]:
             return
         raise KeyError()
 
-    @classmethod
-    async def napalm(cls) -> None:
+    @staticmethod
+    async def napalm() -> None:
         """Asynchronous method for full database deletion.
 
         The main purpose is tests.
@@ -150,3 +165,71 @@ class Scruby[T]:
         with contextlib.suppress(FileNotFoundError):
             await to_thread.run_sync(rmtree, constants.DB_ROOT)
         return
+
+    @staticmethod
+    def search_task(
+        key: int,
+        filter_fn: Callable,
+        length_reduction_hash: str,
+        db_root: str,
+        class_model: T,
+    ) -> dict[str, Any] | None:
+        """Search task."""
+        key_as_hash: str = f"{key:08x}"[length_reduction_hash:]
+        separated_hash: str = "/".join(list(key_as_hash))
+        leaf_path: SyncPath = SyncPath(
+            *(
+                db_root,
+                class_model.__name__,
+                separated_hash,
+                "leaf.json",
+            ),
+        )
+        if leaf_path.exists():
+            data_json: bytes = leaf_path.read_bytes()
+            data: dict[str, str] = orjson.loads(data_json) or {}
+            for _, val in data.items():
+                doc = class_model.model_validate_json(val)
+                if filter_fn(doc):
+                    return doc
+        return None
+
+    def find_one(
+        self,
+        filter_fn: Callable,
+        max_workers: int | None = None,
+        timeout: float | None = None,
+    ) -> T | None:
+        """Find a single document.
+
+        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 streams are required.
+
+        Args:
+            filter_fn: A function that execute the conditions of filtering.
+            max_workers: The maximum number of processes that can be used to
+                         execute the given calls. If None or not given then as many
+                         worker processes will be created as the machine has processors.
+            timeout: The number of seconds to wait for the result if the future isn't done.
+                     If None, then there is no limit on the wait time.
+        """
+        keys: range = range(1, self.__max_num_keys)
+        search_task_fn: Callable = self.search_task
+        length_reduction_hash: int = self.__length_reduction_hash
+        db_root: str = self.__db_root
+        class_model: T = self.__class_model
+        with concurrent.futures.ThreadPoolExecutor(max_workers) as executor:
+            for key in keys:
+                future = executor.submit(
+                    search_task_fn,
+                    key,
+                    filter_fn,
+                    length_reduction_hash,
+                    db_root,
+                    class_model,
+                )
+                result = future.result(timeout)
+                if result is not None:
+                    return result
+        return None

{scruby-0.6.3.dist-info → scruby-0.7.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scruby
-Version: 0.6.3
+Version: 0.7.1
 Summary: A fast key-value storage library.
 Project-URL: Homepage, https://github.com/kebasyaty/scruby
 Project-URL: Repository, https://github.com/kebasyaty/scruby
@@ -104,6 +104,8 @@ uv add scruby
 ## Usage
 
 ```python
+"""Working with keys."""
+
 import anyio
 import datetime
 from pydantic import BaseModel, EmailStr
@@ -153,6 +155,75 @@ if __name__ == "__main__":
     anyio.run(main)
 ```
 
+```python
+"""Find a single document.
+
+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 streams are required.
+"""
+
+import anyio
+import datetime
+from pydantic import BaseModel, EmailStr
+from pydantic_extra_types.phone_numbers import PhoneNumber
+from scruby import Scruby, constants
+from pprint import pprint as pp
+
+constants.DB_ROOT = "ScrubyDB"  # By default = "ScrubyDB"
+constants.LENGTH_REDUCTION_HASH = 6  # 256 keys (main purpose is tests).
+
+class User(BaseModel):
+    """Model of User."""
+    first_name: str
+    last_name: str
+    birthday: datetime.datetime
+    email: EmailStr
+    phone: PhoneNumber
+
+async def main() -> None:
+    """Example."""
+    # Get collection of `User`.
+    user_coll = Scruby(User)
+
+    # Create user.
+    user = User(
+        first_name="John",
+        last_name="Smith",
+        birthday=datetime.datetime(1970, 1, 1),
+        email="John_Smith@gmail.com",
+        phone="+447986123456",
+    )
+
+    # Add user to collection.
+    await user_coll.set_key("+447986123456", user)
+
+    # Find user by email.
+    user_details: User | None = user_coll.find_one(
+        filter_fn=lambda doc: doc.email == "John_Smith@gmail.com",
+    )
+    if user_details is not None:
+        pp(user_details)
+    else:
+        print("No User!")
+
+    # Find user by birthday.
+    user_details: User | None = user_coll.find_one(
+        filter_fn=lambda doc: doc.birthday == datetime.datetime(1970, 1, 1),
+    )
+    if user_details is not None:
+        pp(user_details)
+    else:
+        print("No User!")
+
+    # Full database deletion.
+    # Hint: The main purpose is tests.
+    await Scruby.napalm()
+
+if __name__ == "__main__":
+    anyio.run(main)
+```
+
 ## Changelog
 
 [View the change history](https://github.com/kebasyaty/scruby/blob/v0/CHANGELOG.md "Changelog").

scruby-0.7.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+scruby/__init__.py,sha256=myX7sG-7oAQZGdgfZtTGXYCCraTeuwi7SjBoltftpnM,648
+scruby/constants.py,sha256=XcBbK_gkDC0makWE34M8gUotwj3smi2sWY4mMnfzUt4,874
+scruby/db.py,sha256=FkYBsVYERtauTlWjl8b8cDTTIaH1w7lOzAneWUtNLDE,8114
+scruby/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scruby-0.7.1.dist-info/METADATA,sha256=qkiNaSRnF2pnWMImFLsAz16MMRD_amaDImy9DbFwNoM,8616
+scruby-0.7.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+scruby-0.7.1.dist-info/licenses/LICENSE,sha256=2zZINd6m_jNYlowdQImlEizyhSui5cBAJZRhWQURcEc,1095
+scruby-0.7.1.dist-info/RECORD,,

scruby-0.6.3.dist-info/RECORD

@@ -1,8 +0,0 @@
-scruby/__init__.py,sha256=myX7sG-7oAQZGdgfZtTGXYCCraTeuwi7SjBoltftpnM,648
-scruby/constants.py,sha256=7Px7BDQozlvfSKSAN4Rme4uJHLY_OsT3H0Wq6A_810k,942
-scruby/db.py,sha256=Rt9YDe0lSJwtREHFiqdQ6CQ664FL6YRyczbgKFhpsa4,4871
-scruby/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-scruby-0.6.3.dist-info/METADATA,sha256=8TTKyS4FsDr9PEvL7U5DKtAuRSxUR-s_cMiJ9F7Wwzw,6813
-scruby-0.6.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-scruby-0.6.3.dist-info/licenses/LICENSE,sha256=2zZINd6m_jNYlowdQImlEizyhSui5cBAJZRhWQURcEc,1095
-scruby-0.6.3.dist-info/RECORD,,