scruby 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of scruby might be problematic. Click here for more details.
- scruby/__init__.py +209 -0
- scruby/py.typed +0 -0
- scruby-0.1.0.dist-info/METADATA +116 -0
- scruby-0.1.0.dist-info/RECORD +6 -0
- scruby-0.1.0.dist-info/WHEEL +4 -0
- scruby-0.1.0.dist-info/licenses/LICENSE +21 -0
scruby/__init__.py
ADDED
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
"""A fast key-value storage library.
|
|
2
|
+
|
|
3
|
+
Scruby is a fast key-value storage library that provides an ordered mapping from string keys to string values.
|
|
4
|
+
The library uses fractal-tree addressing.
|
|
5
|
+
|
|
6
|
+
The maximum size of the database is 16**32=340282366920938463463374607431768211456 branches,
|
|
7
|
+
each branch can store one or more keys.
|
|
8
|
+
|
|
9
|
+
The value of any key can be obtained in 32 steps, thereby achieving high performance.
|
|
10
|
+
There is no need to iterate through all the keys in search of the desired value.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
__all__ = ("Scruby",)
|
|
16
|
+
|
|
17
|
+
import hashlib
|
|
18
|
+
from shutil import rmtree
|
|
19
|
+
from typing import Literal
|
|
20
|
+
|
|
21
|
+
import orjson
|
|
22
|
+
from anyio import Path, to_thread
|
|
23
|
+
|
|
24
|
+
type ValueOfKey = str | int | float | list | dict | Literal[True] | Literal[False] | None
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class Scruby:
|
|
28
|
+
"""Creation and management of the database.
|
|
29
|
+
|
|
30
|
+
Example:
|
|
31
|
+
>>> from scruby import Scruby
|
|
32
|
+
>>> db = Scruby()
|
|
33
|
+
>>> await db.set_key("key name", "Some text")
|
|
34
|
+
None
|
|
35
|
+
>>> await db.get_key("key name")
|
|
36
|
+
"Some text"
|
|
37
|
+
>>> await db.has_key("key name")
|
|
38
|
+
True
|
|
39
|
+
>>> await db.delete_key("key name")
|
|
40
|
+
None
|
|
41
|
+
>>> await db.napalm()
|
|
42
|
+
None
|
|
43
|
+
|
|
44
|
+
Args:
|
|
45
|
+
db_path: Path to root directory of databases. Defaule by = "ScrubyDB" (in root of project)
|
|
46
|
+
"""
|
|
47
|
+
|
|
48
|
+
def __init__( # noqa: D107
|
|
49
|
+
self,
|
|
50
|
+
db_path: str = "ScrubyDB",
|
|
51
|
+
) -> None:
|
|
52
|
+
super().__init__()
|
|
53
|
+
self.__db_path = db_path
|
|
54
|
+
|
|
55
|
+
@property
|
|
56
|
+
def db_path(self) -> str:
|
|
57
|
+
"""Get database name."""
|
|
58
|
+
return self.__db_path
|
|
59
|
+
|
|
60
|
+
async def get_leaf_path(self, key: str) -> Path:
|
|
61
|
+
"""Get the path to the database cell by key.
|
|
62
|
+
|
|
63
|
+
Args:
|
|
64
|
+
key: Key name.
|
|
65
|
+
"""
|
|
66
|
+
# Key to md5 sum.
|
|
67
|
+
key_md5: str = hashlib.md5(key.encode("utf-8")).hexdigest() # noqa: S324
|
|
68
|
+
# Convert md5 sum in the segment of path.
|
|
69
|
+
segment_path_md5: str = "/".join(list(key_md5))
|
|
70
|
+
# The path of the branch to the database.
|
|
71
|
+
branch_path: Path = Path(
|
|
72
|
+
*(self.__db_path, segment_path_md5),
|
|
73
|
+
)
|
|
74
|
+
# If the branch does not exist, need to create it.
|
|
75
|
+
if not await branch_path.exists():
|
|
76
|
+
await branch_path.mkdir(parents=True)
|
|
77
|
+
# The path to the database cell.
|
|
78
|
+
leaf_path: Path = Path(*(branch_path, "leaf.json"))
|
|
79
|
+
return leaf_path
|
|
80
|
+
|
|
81
|
+
async def set_key(
|
|
82
|
+
self,
|
|
83
|
+
key: str,
|
|
84
|
+
value: ValueOfKey,
|
|
85
|
+
) -> None:
|
|
86
|
+
"""Asynchronous method for adding and updating keys to database.
|
|
87
|
+
|
|
88
|
+
Example:
|
|
89
|
+
>>> from scruby import Scruby
|
|
90
|
+
>>> db = Scruby()
|
|
91
|
+
>>> await db.set_key("key name", "Some text")
|
|
92
|
+
None
|
|
93
|
+
|
|
94
|
+
Args:
|
|
95
|
+
key: Key name.
|
|
96
|
+
value: Value of key.
|
|
97
|
+
"""
|
|
98
|
+
# The path to the database cell.
|
|
99
|
+
leaf_path: Path = await self.get_leaf_path(key)
|
|
100
|
+
# Write key-value to the database.
|
|
101
|
+
if await leaf_path.exists():
|
|
102
|
+
# Add new key or update existing.
|
|
103
|
+
data_json: bytes = await leaf_path.read_bytes()
|
|
104
|
+
data: dict = orjson.loads(data_json) or {}
|
|
105
|
+
data[key] = value
|
|
106
|
+
await leaf_path.write_bytes(orjson.dumps(data))
|
|
107
|
+
else:
|
|
108
|
+
# Add new key to a blank leaf.
|
|
109
|
+
await leaf_path.write_bytes(data=orjson.dumps({key: value}))
|
|
110
|
+
|
|
111
|
+
async def get_key(self, key: str) -> ValueOfKey:
|
|
112
|
+
"""Asynchronous method for getting key from database.
|
|
113
|
+
|
|
114
|
+
Example:
|
|
115
|
+
>>> from scruby import Scruby
|
|
116
|
+
>>> db = Scruby()
|
|
117
|
+
>>> await db.set_key("key name", "Some text")
|
|
118
|
+
None
|
|
119
|
+
>>> await db.get_key("key name")
|
|
120
|
+
"Some text"
|
|
121
|
+
>>> await db.get_key("key missing")
|
|
122
|
+
KeyError
|
|
123
|
+
|
|
124
|
+
Args:
|
|
125
|
+
key: Key name.
|
|
126
|
+
"""
|
|
127
|
+
# The path to the database cell.
|
|
128
|
+
leaf_path: Path = await self.get_leaf_path(key)
|
|
129
|
+
# Get value of key.
|
|
130
|
+
if await leaf_path.exists():
|
|
131
|
+
data_json: bytes = await leaf_path.read_bytes()
|
|
132
|
+
data: dict = orjson.loads(data_json) or {}
|
|
133
|
+
return data[key]
|
|
134
|
+
raise KeyError()
|
|
135
|
+
|
|
136
|
+
async def has_key(self, key: str) -> bool:
|
|
137
|
+
"""Asynchronous method for checking presence of key in database.
|
|
138
|
+
|
|
139
|
+
Example:
|
|
140
|
+
>>> from scruby import Scruby
|
|
141
|
+
>>> db = Scruby()
|
|
142
|
+
>>> await db.set_key("key name", "Some text")
|
|
143
|
+
None
|
|
144
|
+
>>> await db.has_key("key name")
|
|
145
|
+
True
|
|
146
|
+
>>> await db.has_key("key missing")
|
|
147
|
+
False
|
|
148
|
+
|
|
149
|
+
Args:
|
|
150
|
+
key: Key name.
|
|
151
|
+
"""
|
|
152
|
+
# The path to the database cell.
|
|
153
|
+
leaf_path: Path = await self.get_leaf_path(key)
|
|
154
|
+
# Checking whether there is a key.
|
|
155
|
+
if await leaf_path.exists():
|
|
156
|
+
data_json: bytes = await leaf_path.read_bytes()
|
|
157
|
+
data: dict = orjson.loads(data_json) or {}
|
|
158
|
+
try:
|
|
159
|
+
data[key]
|
|
160
|
+
return True
|
|
161
|
+
except KeyError:
|
|
162
|
+
return False
|
|
163
|
+
return False
|
|
164
|
+
|
|
165
|
+
async def delete_key(self, key: str) -> None:
|
|
166
|
+
"""Asynchronous method for deleting key from database.
|
|
167
|
+
|
|
168
|
+
Example:
|
|
169
|
+
>>> from scruby import Scruby
|
|
170
|
+
>>> db = Scruby()
|
|
171
|
+
>>> await db.set_key("key name", "Some text")
|
|
172
|
+
None
|
|
173
|
+
>>> await db.delete_key("key name")
|
|
174
|
+
None
|
|
175
|
+
>>> await db.delete_key("key missing")
|
|
176
|
+
KeyError
|
|
177
|
+
|
|
178
|
+
Args:
|
|
179
|
+
key: Key name.
|
|
180
|
+
"""
|
|
181
|
+
# The path to the database cell.
|
|
182
|
+
leaf_path: Path = await self.get_leaf_path(key)
|
|
183
|
+
# Deleting key.
|
|
184
|
+
if await leaf_path.exists():
|
|
185
|
+
data_json: bytes = await leaf_path.read_bytes()
|
|
186
|
+
data: dict = orjson.loads(data_json) or {}
|
|
187
|
+
del data[key]
|
|
188
|
+
await leaf_path.write_bytes(orjson.dumps(data))
|
|
189
|
+
return
|
|
190
|
+
raise KeyError()
|
|
191
|
+
|
|
192
|
+
async def napalm(self) -> None:
|
|
193
|
+
"""Asynchronous method for full database deletion (Arg: db_path).
|
|
194
|
+
|
|
195
|
+
Warning:
|
|
196
|
+
- `Be careful, this will remove all keys.`
|
|
197
|
+
|
|
198
|
+
Example:
|
|
199
|
+
>>> from scruby import Scruby
|
|
200
|
+
>>> db = Scruby()
|
|
201
|
+
>>> await db.set_key("key name", "Some text")
|
|
202
|
+
None
|
|
203
|
+
>>> await db.napalm()
|
|
204
|
+
None
|
|
205
|
+
>>> await db.napalm()
|
|
206
|
+
FileNotFoundError
|
|
207
|
+
"""
|
|
208
|
+
await to_thread.run_sync(rmtree, self.__db_path)
|
|
209
|
+
return
|
scruby/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: scruby
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A fast key-value storage library.
|
|
5
|
+
Project-URL: Homepage, https://github.com/kebasyaty/scruby
|
|
6
|
+
Project-URL: Repository, https://github.com/kebasyaty/scruby
|
|
7
|
+
Project-URL: Source, https://github.com/kebasyaty/scruby
|
|
8
|
+
Project-URL: Bug Tracker, https://github.com/kebasyaty/scruby/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/kebasyaty/scruby/blob/v0/CHANGELOG.md
|
|
10
|
+
Author-email: kebasyaty <kebasyaty@gmail.com>
|
|
11
|
+
License-Expression: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: database,db,scruby,store
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Operating System :: MacOS :: MacOS X
|
|
18
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
19
|
+
Classifier: Operating System :: POSIX
|
|
20
|
+
Classifier: Programming Language :: Python :: 3
|
|
21
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
25
|
+
Classifier: Topic :: Database
|
|
26
|
+
Classifier: Typing :: Typed
|
|
27
|
+
Requires-Python: <4.0,>=3.12
|
|
28
|
+
Requires-Dist: anyio>=4.10.0
|
|
29
|
+
Requires-Dist: orjson>=3.11.2
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
<div align="center">
|
|
33
|
+
<p align="center">
|
|
34
|
+
<a href="https://github.com/kebasyaty/scruby">
|
|
35
|
+
<img
|
|
36
|
+
height="90"
|
|
37
|
+
alt="Logo"
|
|
38
|
+
src="https://raw.githubusercontent.com/kebasyaty/scruby/main/assets/logo.svg">
|
|
39
|
+
</a>
|
|
40
|
+
</p>
|
|
41
|
+
<p>
|
|
42
|
+
<h1>Scruby</h1>
|
|
43
|
+
<h3>A fast key-value storage library.</h3>
|
|
44
|
+
<p align="center">
|
|
45
|
+
<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>
|
|
46
|
+
<a href="https://kebasyaty.github.io/scruby/" alt="Docs"><img src="https://img.shields.io/badge/docs-available-brightgreen.svg" alt="Docs"></a>
|
|
47
|
+
<a href="https://pypi.python.org/pypi/scruby/" alt="PyPI pyversions"><img src="https://img.shields.io/pypi/pyversions/scruby.svg" alt="PyPI pyversions"></a>
|
|
48
|
+
<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>
|
|
49
|
+
<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>
|
|
50
|
+
<br>
|
|
51
|
+
<a href="https://github.com/kebasyaty/scruby/issues"><img src="https://img.shields.io/github/issues/kebasyaty/scruby.svg" alt="GitHub issues"></a>
|
|
52
|
+
<a href="https://pepy.tech/projects/scruby"><img src="https://static.pepy.tech/badge/scruby" alt="PyPI Downloads"></a>
|
|
53
|
+
<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>
|
|
54
|
+
<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>
|
|
55
|
+
<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>
|
|
56
|
+
<a href="https://github.com/kebasyaty/scruby" alt="PyPI implementation"><img src="https://img.shields.io/pypi/implementation/scruby" alt="PyPI implementation"></a>
|
|
57
|
+
<br>
|
|
58
|
+
<a href="https://pypi.org/project/scruby"><img src="https://img.shields.io/pypi/format/scruby" alt="Format"></a>
|
|
59
|
+
<a href="https://github.com/kebasyaty/scruby"><img src="https://img.shields.io/github/languages/top/kebasyaty/scruby" alt="Top"></a>
|
|
60
|
+
<a href="https://github.com/kebasyaty/scruby"><img src="https://img.shields.io/github/repo-size/kebasyaty/scruby" alt="Size"></a>
|
|
61
|
+
<a href="https://github.com/kebasyaty/scruby"><img src="https://img.shields.io/github/last-commit/kebasyaty/scruby/main" alt="Last commit"></a>
|
|
62
|
+
<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>
|
|
63
|
+
</p>
|
|
64
|
+
<p align="center">
|
|
65
|
+
**Scruby** is a fast key-value storage library that provides an ordered mapping from string keys to string values.
|
|
66
|
+
<br>
|
|
67
|
+
The library uses fractal-tree addressing.
|
|
68
|
+
<br>
|
|
69
|
+
The maximum size of the database is 16^32=340282366920938463463374607431768211456 branches,
|
|
70
|
+
each branch can store one or more keys.
|
|
71
|
+
<br>
|
|
72
|
+
The value of any key can be obtained in 32 steps, thereby achieving high performance.
|
|
73
|
+
<br>
|
|
74
|
+
There is no need to iterate through all the keys in search of the desired value.
|
|
75
|
+
</p>
|
|
76
|
+
</p>
|
|
77
|
+
</div>
|
|
78
|
+
|
|
79
|
+
##
|
|
80
|
+
|
|
81
|
+
<p>
|
|
82
|
+
<a href="https://github.com/kebasyaty/scruby" alt="Project Status">
|
|
83
|
+
<img src="https://raw.githubusercontent.com/kebasyaty/scruby/v0/assets/project_status/project-status-pre-alpha.svg"
|
|
84
|
+
alt="Project Status">
|
|
85
|
+
</a>
|
|
86
|
+
</p>
|
|
87
|
+
|
|
88
|
+
## Documentation
|
|
89
|
+
|
|
90
|
+
Online browsable documentation is available at [https://kebasyaty.github.io/scruby/](https://kebasyaty.github.io/scruby/ "Documentation").
|
|
91
|
+
|
|
92
|
+
## Requirements
|
|
93
|
+
|
|
94
|
+
[View the list of requirements](https://github.com/kebasyaty/scruby/blob/v0/REQUIREMENTS.md "Requirements").
|
|
95
|
+
|
|
96
|
+
## Installation
|
|
97
|
+
|
|
98
|
+
```shell
|
|
99
|
+
uv add scruby
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Usage
|
|
103
|
+
|
|
104
|
+
[It is recommended to look at examples here](https://github.com/kebasyaty/scruby/tree/main/examples "Examples").
|
|
105
|
+
|
|
106
|
+
```python
|
|
107
|
+
import scruby
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Changelog
|
|
111
|
+
|
|
112
|
+
[View the change history](https://github.com/kebasyaty/scruby/blob/v0/CHANGELOG.md "Changelog").
|
|
113
|
+
|
|
114
|
+
## License
|
|
115
|
+
|
|
116
|
+
This project is licensed under the [MIT](https://github.com/kebasyaty/scruby/blob/main/LICENSE "MIT").
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
scruby/__init__.py,sha256=5_WsWLxxGQ8LYi0XrZc7S5P3HmaP1wfvb9VUdrVxvmM,6694
|
|
2
|
+
scruby/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
3
|
+
scruby-0.1.0.dist-info/METADATA,sha256=e0KkEerqyZngnSbMbXpV4BYcdz7gpye_m3alBOmIq4E,5694
|
|
4
|
+
scruby-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
|
|
5
|
+
scruby-0.1.0.dist-info/licenses/LICENSE,sha256=2zZINd6m_jNYlowdQImlEizyhSui5cBAJZRhWQURcEc,1095
|
|
6
|
+
scruby-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Gennady Kostyunin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|