scruby 0.17.0__py3-none-any.whl → 0.27.2__py3-none-any.whl

scruby/mixins/update.py

@@ -0,0 +1,99 @@
+# 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
+
+__all__ = ("Update",)
+
+import concurrent.futures
+from collections.abc import Callable
+from typing import Any
+
+import orjson
+from anyio import Path
+
+
+class Update:
+    """Methods for updating documents."""
+
+    @staticmethod
+    async def _task_update(
+        branch_number: int,
+        filter_fn: Callable,
+        hash_reduce_left: str,
+        db_root: str,
+        class_model: Any,
+        new_data: dict[str, Any],
+    ) -> int:
+        """Task for find documents.
+
+        This method is for internal use.
+
+        Returns:
+            The number of updated documents.
+        """
+        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(
+            *(
+                db_root,
+                class_model.__name__,
+                separated_hash,
+                "leaf.json",
+            ),
+        )
+        counter: int = 0
+        if await leaf_path.exists():
+            data_json: bytes = await leaf_path.read_bytes()
+            data: dict[str, str] = orjson.loads(data_json) or {}
+            new_state: dict[str, str] = {}
+            for _, val in data.items():
+                doc = class_model.model_validate_json(val)
+                if filter_fn(doc):
+                    for key, value in new_data.items():
+                        doc.__dict__[key] = value
+                        new_state[key] = doc.model_dump_json()
+                    counter += 1
+            await leaf_path.write_bytes(orjson.dumps(new_state))
+        return counter
+
+    async def update_many(
+        self,
+        filter_fn: Callable,
+        new_data: dict[str, Any],
+    ) -> 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.
+
+        Returns:
+            The number of updated documents.
+        """
+        branch_numbers: range = range(1, self._max_branch_number)
+        update_task_fn: Callable = self._task_update
+        hash_reduce_left: int = self._hash_reduce_left
+        db_root: str = self._db_root
+        class_model: Any = self._class_model
+        counter: int = 0
+        with concurrent.futures.ThreadPoolExecutor(self._max_workers) as executor:
+            for branch_number in branch_numbers:
+                future = executor.submit(
+                    update_task_fn,
+                    branch_number,
+                    filter_fn,
+                    hash_reduce_left,
+                    db_root,
+                    class_model,
+                    new_data,
+                )
+                counter += await future.result()
+        return counter

scruby/settings.py

@@ -0,0 +1,44 @@
+# 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 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.
+    - `0` - 4294967296 branches in collection.
+    - `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
+
+__all__ = (
+    "DB_ROOT",
+    "HASH_REDUCE_LEFT",
+    "MAX_WORKERS",
+)
+
+from typing import Literal
+
+# Path to root directory of database
+# By default = "ScrubyDB" (in root of project).
+DB_ROOT: str = "ScrubyDB"
+
+# The length of the hash reduction on the left side.
+# 0 = 4294967296 branches in collection.
+# 2 = 16777216 branches in collection.
+# 4 = 65536 branches in collection.
+# 6 = 256 branches in collection (by default).
+# 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.17.0.dist-info → scruby-0.27.2.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: scruby
-Version: 0.17.0
-Summary: A fast key-value storage library.
-Project-URL: Homepage, https://github.com/kebasyaty/scruby
+Version: 0.27.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
 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
-
-constants.DB_ROOT = "ScrubyDB"  # By default = "ScrubyDB"
+from scruby import Scruby, settings
 
+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 = Scruby(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
@@ -153,7 +161,7 @@ async def main() -> None:
 
     # Full database deletion.
     # Hint: The main purpose is tests.
-    await Scruby.napalm()
+    Scruby.napalm()
 
 
 if __name__ == "__main__":
@@ -171,63 +179,66 @@ Ideally, hundreds and even thousands of threads are required.
 import anyio
 import datetime
 from typing import Annotated
-from pydantic import BaseModel, EmailStr
-from pydantic_extra_types.phone_numbers import PhoneNumber, PhoneNumberValidator
-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  # 256 branches in collection
-                                # (main purpose is tests).
-
-
-class User(BaseModel):
-    """Model of User."""
-    first_name: str
-    last_name: str
-    birthday: datetime.datetime
-    email: EmailStr
-    phone: Annotated[PhoneNumber, PhoneNumberValidator(number_format="E164")]
+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 = 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 `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",
+    # Get collection `Phone`.
+    phone_coll = await Scruby.collection(Phone)
+
+    # Create phone.
+    phone = Phone(
+        brand="Samsung",
+        model="Galaxy A26",
+        screen_diagonal=6.7,
+        matrix_type="Super AMOLED",
     )
 
-    # Add user to collection.
-    await user_coll.add_key(user.phone, user)
+    # Add phone to collection.
+    await phone_coll.add_doc(phone)
 
-    # Find user by email.
-    user_details: User | None = user_coll.find_one(
-        filter_fn=lambda doc: doc.email == "John_Smith@gmail.com",
+    # Find phone by brand.
+    phone_details: Phone | None = await phone_coll.find_one(
+        filter_fn=lambda doc: doc.brand == "Samsung",
     )
-    if user_details is not None:
-        pp(user_details)
+    if phone_details is not None:
+        pp(phone_details)
     else:
-        print("No User!")
+        print("No Phone!")
 
-    # Find user by birthday.
-    user_details: User | None = user_coll.find_one(
-        filter_fn=lambda doc: doc.birthday == datetime.datetime(1970, 1, 1),
+    # Find phone by model.
+    phone_details: Phone | None = await phone_coll.find_one(
+        filter_fn=lambda doc: doc.model == "Galaxy A26",
     )
-    if user_details is not None:
-        pp(user_details)
+    if phone_details is not None:
+        pp(phone_details)
     else:
-        print("No User!")
+        print("No Phone!")
 
     # Full database deletion.
     # Hint: The main purpose is tests.
-    await Scruby.napalm()
+    Scruby.napalm()
 
 
 if __name__ == "__main__":
@@ -245,53 +256,60 @@ Ideally, hundreds and even thousands of threads are required.
 import anyio
 import datetime
 from typing import Annotated
-from pydantic import BaseModel, EmailStr
-from pydantic_extra_types.phone_numbers import PhoneNumber, PhoneNumberValidator
-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  # 256 branches in collection
-                                # (main purpose is tests).
-
-
-class User(BaseModel):
-    """Model of User."""
-    first_name: str
-    last_name: str
-    birthday: datetime.datetime
-    email: EmailStr
-    phone: Annotated[PhoneNumber, PhoneNumberValidator(number_format="E164")]
+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 = 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 `User`.
-    user_coll = Scruby(User)
-
-    # Create users.
-    for num in range(1, 10):
-        user = User(
-            first_name="John",
-            last_name="Smith",
-            birthday=datetime.datetime(1970, 1, num),
-            email=f"John_Smith_{num}@gmail.com",
-            phone=f"+44798612345{num}",
+    # Get collection `Car`.
+    car_coll = await Scruby.collection(Car)
+
+    # Create cars.
+    for name in range(1, 10):
+        car = Car(
+            brand="Mazda",
+            model=f"EZ-6 {num}",
+            year=2025,
+            power_reserve=600,
         )
-        await user_coll.add_key(user.phone, user)
+        await car_coll.add_doc(car)
 
-    # Find users by email.
-    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",
+    # Find cars by brand and year.
+    car_list: list[Car] | None = await car_coll.find_many(
+        filter_fn=lambda doc: doc.brand == "Mazda" and doc.year == 2025,
     )
-    if users is not None:
-        pp(users)
+    if car_list is not None:
+        pp(car_list)
     else:
-        print("No users!")
+        print("No cars!")
+
+    # Get collection list.
+    collection_list = await Scruby.collection_list()
+    print(collection_list)  # ["Car"]
 
     # Full database deletion.
     # Hint: The main purpose is tests.
-    await Scruby.napalm()
+    Scruby.napalm()
 
 
 if __name__ == "__main__":

scruby-0.27.2.dist-info/RECORD

@@ -0,0 +1,18 @@
+scruby/__init__.py,sha256=IVQbFk2jKaRnHJQys_CcYXw3bvmN4igWFAQmzLxE1k0,1283
+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=jmRJHs1fcSIIFm-yz2fq81-dC3not3EW9lKzLe1Yr64,627
+scruby/mixins/collection.py,sha256=coF-IOhicV_EihDwnYf6SW5Mfi3nOFR0gAhCc619NmI,1382
+scruby/mixins/count.py,sha256=OyRznB7AfZcSka3uFy2miMMOt85aUmiJN1RjJlQOTPI,2059
+scruby/mixins/custom_task.py,sha256=BcSJfd0eUiyQ6RgTOSsTbJZvQ5ggXtp2YueXwPWgcd8,2386
+scruby/mixins/delete.py,sha256=f3xkaMOR6wBqfjee1NCcw98fU8imZRMhSjucrxFcbFU,3055
+scruby/mixins/docs.py,sha256=OUByWbHfNVWJVkUrhCsJZdVqf0zez_an6Gti2n5iKnM,5671
+scruby/mixins/find.py,sha256=T2MzbP_vinf5qaLm4iR5T3iMFbMQNkUbQPRx2C5e20E,5373
+scruby/mixins/update.py,sha256=oAfOxIPHl3ro8Vpjnzrdj8PSzIz5dIQO_AWSni5878Y,3238
+scruby-0.27.2.dist-info/METADATA,sha256=Ua5HIieo3iv00SOez0jFMjiC7G324ZtY20FH76x_Xgw,10659
+scruby-0.27.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+scruby-0.27.2.dist-info/licenses/LICENSE,sha256=mS0Wz0yGNB63gEcWEnuIb_lldDYV0sjRaO-o_GL6CWE,1074
+scruby-0.27.2.dist-info/RECORD,,

{scruby-0.17.0.dist-info → scruby-0.27.2.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

scruby/constants.py

@@ -1,31 +0,0 @@
-"""Constant variables.
-
-The module contains the following variables:
-
-- `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.
-    - `0` - 4294967296 branches in collection (by default).
-    - `2` - 16777216 branches in collectionю
-    - `4` - 65536 branches in collectionю
-    - `6` - 256 branches in collection (main purpose is tests).
-"""
-
-from __future__ import annotations
-
-__all__ = (
-    "DB_ROOT",
-    "HASH_REDUCE_LEFT",
-)
-
-from typing import Literal
-
-# Path to root directory of database
-# By default = "ScrubyDB" (in root of project).
-DB_ROOT: str = "ScrubyDB"
-
-# The length of the hash reduction on the left side.
-# 0 = 4294967296 branches in collection (by default).
-# 2 = 16777216 branches in collectionю
-# 4 = 65536 branches in collectionю
-# 6 = 256 branches in collection (main purpose is tests).
-HASH_REDUCE_LEFT: Literal[0, 2, 4, 6] = 0

scruby-0.17.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-scruby/__init__.py,sha256=elrW_AWMyl3kuTpEqGPaYFSpF8iVzjpivF6MxVNlqoQ,855
-scruby/aggregation.py,sha256=SYGcnMy2eq9vJb-pW3xR9LLAQIQ55TK-LGW_yKQ-7sU,3318
-scruby/constants.py,sha256=KRx7naXDNzT1WVKiYXFJ8uYxS9-aSqoiilsa4qR6y1Y,976
-scruby/db.py,sha256=Ml2A46bOX1P1sF4vKSyEFqklMAjoSpn1lGvj8VCtnSY,26323
-scruby/errors.py,sha256=nMhSLAKo7F3lTB_lgOZ5ksMuBtA1ugHqF8iyp1EY-sY,1042
-scruby/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-scruby-0.17.0.dist-info/METADATA,sha256=8RMszCN_EnAzMTN3wpDrIh8BrrdlxYTX__pLyy6siz8,10079
-scruby-0.17.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-scruby-0.17.0.dist-info/licenses/LICENSE,sha256=mS0Wz0yGNB63gEcWEnuIb_lldDYV0sjRaO-o_GL6CWE,1074
-scruby-0.17.0.dist-info/RECORD,,