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

scruby/errors.py

@@ -0,0 +1,39 @@
+"""Scruby Exceptions."""
+
+from __future__ import annotations
+
+__all__ = (
+    "ScrubyException",
+    "MetadataValueError",
+)
+
+
+class ScrubyException(Exception):
+    """Root Custom Exception."""
+
+    def __init__(self, *args, **kwargs) -> None:  # type: ignore[no-untyped-def]  # noqa: D107
+        super().__init__(*args, **kwargs)
+
+
+class MetadataValueError(ScrubyException):
+    """Exception is raised if value of variable in metadata does not matching expected."""
+
+    def __init__(self, message: str) -> None:  # noqa: D107
+        self.message = message
+        super().__init__(self.message)
+
+
+class KeyAlreadyExistsError(ScrubyException):
+    """Exception is raised if the key already exists."""
+
+    def __init__(self) -> None:
+        self.message = "The key already exists."
+        super().__init__(self.message)
+
+
+class KeyNotExistsError(ScrubyException):
+    """Exception is raised If the key is not exists."""
+
+    def __init__(self) -> None:
+        self.message = "The key not exists."
+        super().__init__(self.message)

{scruby-0.9.0.dist-info → scruby-0.17.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scruby
-Version: 0.9.0
+Version: 0.17.0
 Summary: A fast key-value storage library.
 Project-URL: Homepage, https://github.com/kebasyaty/scruby
 Project-URL: Repository, https://github.com/kebasyaty/scruby
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Database
 Classifier: Typing :: Typed
@@ -43,7 +44,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>
@@ -51,34 +52,30 @@ 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://github.com/kebasyaty/scruby/issues"><img src="https://img.shields.io/github/issues/kebasyaty/scruby.svg" alt="GitHub issues"></a>
-      <a href="https://pepy.tech/projects/scruby"><img src="https://static.pepy.tech/badge/scruby" alt="PyPI Downloads"></a>
-      <a href="https://github.com/kebasyaty/scruby/blob/main/LICENSE" alt="GitHub license"><img src="https://img.shields.io/github/license/kebasyaty/scruby" alt="GitHub license"></a>
       <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://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://github.com/kebasyaty/scruby" alt="PyPI implementation"><img src="https://img.shields.io/pypi/implementation/scruby" alt="PyPI implementation"></a>
-      <br>
       <a href="https://pypi.org/project/scruby"><img src="https://img.shields.io/pypi/format/scruby" alt="Format"></a>
-      <a href="https://github.com/kebasyaty/scruby"><img src="https://img.shields.io/github/languages/top/kebasyaty/scruby" alt="Top"></a>
-      <a href="https://github.com/kebasyaty/scruby"><img src="https://img.shields.io/github/repo-size/kebasyaty/scruby" alt="Size"></a>
-      <a href="https://github.com/kebasyaty/scruby"><img src="https://img.shields.io/github/last-commit/kebasyaty/scruby/main" alt="Last commit"></a>
-      <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>
+      <a href="https://pepy.tech/projects/scruby"><img src="https://static.pepy.tech/badge/scruby" alt="PyPI Downloads"></a>
+      <a href="https://github.com/kebasyaty/scruby/blob/main/LICENSE" alt="GitHub license"><img src="https://img.shields.io/github/license/kebasyaty/scruby" alt="GitHub license"></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>
@@ -103,6 +100,8 @@ uv add scruby
 
 ## Usage
 
+See more examples here [https://kebasyaty.github.io/scruby/latest/pages/usage/](https://kebasyaty.github.io/scruby/latest/pages/usage/ "Examples").
+
 ```python
 """Working with keys."""
 
@@ -115,6 +114,7 @@ from scruby import Scruby, constants
 
 constants.DB_ROOT = "ScrubyDB"  # By default = "ScrubyDB"
 
+
 class User(BaseModel):
     """Model of User."""
     first_name: str
@@ -123,6 +123,7 @@ class User(BaseModel):
     email: EmailStr
     phone: Annotated[PhoneNumber, PhoneNumberValidator(number_format="E164")]
 
+
 async def main() -> None:
     """Example."""
     # Get collection of `User`.
@@ -136,7 +137,9 @@ async def main() -> None:
         phone="+447986123456",
     )
 
-    await user_coll.set_key("+447986123456", user)
+    await user_coll.add_key(user.phone, user)
+
+    await user_coll.update_key(user.phone, user)
 
     await user_coll.get_key("+447986123456")  # => user
     await user_coll.get_key("key missing")  # => KeyError
@@ -152,12 +155,13 @@ async def main() -> None:
     # Hint: The main purpose is tests.
     await Scruby.napalm()
 
+
 if __name__ == "__main__":
     anyio.run(main)
 ```
 
 ```python
-"""Find a single document.
+"""Find 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.
@@ -173,8 +177,9 @@ from scruby import Scruby, constants
 from pprint import pprint as pp
 
 constants.DB_ROOT = "ScrubyDB"  # By default = "ScrubyDB"
-constants.LENGTH_REDUCTION_HASH = 6  # 256 branches in collection
-                                     # (main purpose is tests).
+constants.HASH_REDUCE_LEFT = 6  # 256 branches in collection
+                                # (main purpose is tests).
+
 
 class User(BaseModel):
     """Model of User."""
@@ -184,6 +189,7 @@ class User(BaseModel):
     email: EmailStr
     phone: Annotated[PhoneNumber, PhoneNumberValidator(number_format="E164")]
 
+
 async def main() -> None:
     """Example."""
     # Get collection of `User`.
@@ -199,7 +205,7 @@ async def main() -> None:
     )
 
     # Add user to collection.
-    await user_coll.set_key("+447986123456", user)
+    await user_coll.add_key(user.phone, user)
 
     # Find user by email.
     user_details: User | None = user_coll.find_one(
@@ -223,12 +229,13 @@ async def main() -> None:
     # Hint: The main purpose is tests.
     await Scruby.napalm()
 
+
 if __name__ == "__main__":
     anyio.run(main)
 ```
 
 ```python
-"""Find documents.
+"""Find 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.
@@ -244,8 +251,9 @@ from scruby import Scruby, constants
 from pprint import pprint as pp
 
 constants.DB_ROOT = "ScrubyDB"  # By default = "ScrubyDB"
-constants.LENGTH_REDUCTION_HASH = 6  # 256 branches in collection
-                                     # (main purpose is tests).
+constants.HASH_REDUCE_LEFT = 6  # 256 branches in collection
+                                # (main purpose is tests).
+
 
 class User(BaseModel):
     """Model of User."""
@@ -255,6 +263,7 @@ class User(BaseModel):
     email: EmailStr
     phone: Annotated[PhoneNumber, PhoneNumberValidator(number_format="E164")]
 
+
 async def main() -> None:
     """Example."""
     # Get collection of `User`.
@@ -269,7 +278,7 @@ async def main() -> None:
             email=f"John_Smith_{num}@gmail.com",
             phone=f"+44798612345{num}",
         )
-        await db.set_key(f"+44798612345{num}", user)
+        await user_coll.add_key(user.phone, user)
 
     # Find users by email.
     users: list[User] | None = user_coll.find_many(
@@ -284,41 +293,6 @@ async def main() -> None:
     # Hint: The main purpose is tests.
     await Scruby.napalm()
 
-if __name__ == "__main__":
-    anyio.run(main)
-```
-
-```python
-"""Get collection name."""
-
-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
-
-constants.DB_ROOT = "ScrubyDB"  # By default = "ScrubyDB"
-
-class User(BaseModel):
-    """Model of User."""
-    first_name: str
-    last_name: str
-    birthday: datetime.datetime
-    email: EmailStr
-    phone: Annotated[PhoneNumber, PhoneNumberValidator(number_format="E164")]
-
-async def main() -> None:
-    """Example."""
-    # Get collection of `User`.
-    user_coll = Scruby(User)
-
-    print(user_coll.collection_name())  # "User"
-    print(user_coll.collection_full_name())  # "ScrubyDB/User"
-
-    # Full database deletion.
-    # Hint: The main purpose is tests.
-    await Scruby.napalm()
 
 if __name__ == "__main__":
     anyio.run(main)

scruby-0.17.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+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,,

{scruby-0.9.0.dist-info → scruby-0.17.0.dist-info}/licenses/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Gennady Kostyunin
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Gennady Kostyunin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scruby-0.9.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-scruby/__init__.py,sha256=myX7sG-7oAQZGdgfZtTGXYCCraTeuwi7SjBoltftpnM,648
-scruby/constants.py,sha256=GbB-O0qaVdi5EHUp-zRAppFXLR-oHxpXUFVAOCpS0C8,1022
-scruby/db.py,sha256=1tfDCwoKwUx0a6DfEOpPAV8NYuifmmrX8Q9gU3K6l58,10407
-scruby/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-scruby-0.9.0.dist-info/METADATA,sha256=7Durmb2_VtJ4plz-OM-vhzfLAM8QGYkmVTRX1KFfOYY,11533
-scruby-0.9.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-scruby-0.9.0.dist-info/licenses/LICENSE,sha256=2zZINd6m_jNYlowdQImlEizyhSui5cBAJZRhWQURcEc,1095
-scruby-0.9.0.dist-info/RECORD,,