keldb 0.1.0__tar.gz

keldb-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <https://unlicense.org>

keldb-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: keldb
+Version: 0.1.0
+Summary: KelDB is a simple node-based database for asyncio applications.
+Author-email: TriangularDev <triangle@dylsplazy.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiofiles>=22.1.0
+Dynamic: license-file
+
+
+# KelDB
+[![Latest PyPI package version](https://badge.fury.io/py/keldb.svg)](https://pypi.org/project/keldb) [![Latest Read The Docs](https://readthedocs.org/projects/keldb/badge/?version=latest)](https://keldb.readthedocs.io/en/latest/)
+
+KelDB is a simple node-based database for asyncio applications.
+## Dynamics
+KelDB is organised into **nodes**. A node is a container that can hold a value and/or other **subnodes**. The database itself is the root node, and every piece of data is a subnode of it.
+## Usage
+KelDB is quite flexible. There's only a few commands to learn.
+
+    import asyncio
+    import keldb
+    
+    # Create a default KelDB database (or load an existing database)
+    database = keldb.KelDB(keldb.FileStoreHook("./testdb/"))
+    
+    async def main():
+        # Create subnodes (lazy creation - no actual subnodes are created yet)
+        foo = await database.get_subnode("foo")
+        bar = await database.get_subnode("bar")
+        baz = await database.get_subnode("baz")
+    
+        await bar.set_value("This can be any json-serializable object.") # Set a value (now "bar" is actually created)
+        
+        await baz.set_value({"type": "user", "name": "Gabe Newell"}) # Now "baz" is actually created
+    
+        text_subnode = await foo.get_subnode("text")
+    
+        await text_subnode.set_value("If you are reading this, this data saved correctly!") # Write text in a subnode's subnode. (now both "foo" and "foo/text" are created)
+    
+        print(await text_subnode.get_value()) # Read a value from the database
+    
+        await foo.delete() # Delete a subnode (do note that this also recursively deletes any subnodes under it)
+    
+        async for subnode in database.list_subnodes(): # Iterate over subnodes
+            print(subnode.path)
+    
+        await database.set_value("Even the database itself is technically a node!")
+    
+    asyncio.run(main())
+

keldb-0.1.0/README.md

@@ -0,0 +1,41 @@
+
+# KelDB
+[![Latest PyPI package version](https://badge.fury.io/py/keldb.svg)](https://pypi.org/project/keldb) [![Latest Read The Docs](https://readthedocs.org/projects/keldb/badge/?version=latest)](https://keldb.readthedocs.io/en/latest/)
+
+KelDB is a simple node-based database for asyncio applications.
+## Dynamics
+KelDB is organised into **nodes**. A node is a container that can hold a value and/or other **subnodes**. The database itself is the root node, and every piece of data is a subnode of it.
+## Usage
+KelDB is quite flexible. There's only a few commands to learn.
+
+    import asyncio
+    import keldb
+    
+    # Create a default KelDB database (or load an existing database)
+    database = keldb.KelDB(keldb.FileStoreHook("./testdb/"))
+    
+    async def main():
+        # Create subnodes (lazy creation - no actual subnodes are created yet)
+        foo = await database.get_subnode("foo")
+        bar = await database.get_subnode("bar")
+        baz = await database.get_subnode("baz")
+    
+        await bar.set_value("This can be any json-serializable object.") # Set a value (now "bar" is actually created)
+        
+        await baz.set_value({"type": "user", "name": "Gabe Newell"}) # Now "baz" is actually created
+    
+        text_subnode = await foo.get_subnode("text")
+    
+        await text_subnode.set_value("If you are reading this, this data saved correctly!") # Write text in a subnode's subnode. (now both "foo" and "foo/text" are created)
+    
+        print(await text_subnode.get_value()) # Read a value from the database
+    
+        await foo.delete() # Delete a subnode (do note that this also recursively deletes any subnodes under it)
+    
+        async for subnode in database.list_subnodes(): # Iterate over subnodes
+            print(subnode.path)
+    
+        await database.set_value("Even the database itself is technically a node!")
+    
+    asyncio.run(main())
+

keldb-0.1.0/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "keldb"
+version = "0.1.0"
+description = "KelDB is a simple node-based database for asyncio applications."
+authors = [{ name="TriangularDev", email="triangle@dylsplazy.com" }]
+readme = "README.md"
+requires-python = ">=3.7"
+
+dependencies = ["aiofiles>=22.1.0"]

keldb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

keldb-0.1.0/src/keldb/__init__.py

@@ -0,0 +1,258 @@
+"""
+KelDB
+
+An asynchronous hierarchical key-value database abstraction.
+
+KelDB organizes data as a tree of nodes. Each node can store a value and have subnodes. Storage is delegated to a backend Hook.
+
+Core Components:
+    - Node: Represents a node in the database tree.
+    - Hook: Backend abstraction interface for custom setups.
+    - FileStoreHook: Filesystem-backed implementation.
+    - KelDB: Root database node.
+"""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Optional
+import aiofiles
+import asyncio
+import pathlib
+import base64
+import shutil
+import json
+import os
+
+
+# =========================
+# Node
+# =========================
+
+class Node:
+    """
+    Represents a singular node.
+
+    This object is a lightweight reference to a database path. It can store a value and contain subnodes.
+
+    Attributes:
+        root (KelDB): Root database instance.
+        parent (Node | None): Parent node.
+        name (str | None): Node name.
+        path (str | None): Full database path.
+    """
+
+    def __init__(self) -> None:
+        self.root: Optional["KelDB"] = None
+        self.parent: Optional["Node"] = None
+        self.name: Optional[str] = None
+        self.path: Optional[str] = None
+
+    async def get_value(self) -> Any:
+        """
+        Get the value of this node.
+
+        Returns:
+            Any: Stored value or None.
+        """
+        return await self.root.hook.get_path_value(
+            self.path,
+            cached=self.root.cache_enabled,
+        )
+
+    async def set_value(self, value: Any) -> None:
+        """
+        Set the value of this node.
+
+        Args:
+            value (Any): JSON-serializable value.
+        """
+        await self.root.hook.set_path_value(
+            self.path,
+            value,
+            cached=self.root.cache_enabled,
+        )
+
+    async def list_subnodes(self) -> AsyncIterator["Node"]:
+        """
+        Iterate over subnodes.
+
+        Yields:
+            Node: Subnode objects.
+        """
+        if not await self.exists():
+            return
+
+        async for subnode_name in self.root.hook.list_path_subpaths(
+            self.path,
+            cached=self.root.cache_enabled,
+        ):
+            subnode = Node()
+            subnode.root = self.root
+            subnode.parent = self
+            subnode.name = subnode_name
+            subnode.path = self.path + f"{subnode_name}/"
+            yield subnode
+
+    async def get_subnode(self, subnode_name: str) -> "Node":
+        """
+        Get a reference to a subnode.
+
+        Args:
+            subnode_name (str): Name of subnode.
+
+        Returns:
+            Node: Subnode reference.
+        """
+        subnode = Node()
+        subnode.root = self.root
+        subnode.parent = self
+        subnode.name = subnode_name
+        subnode.path = self.path + f"{subnode_name}/"
+        return subnode
+
+    async def exists(self) -> bool:
+        """
+        Check if this node exists.
+
+        Returns:
+            bool: True if exists.
+        """
+        return await self.root.hook.check_path_exists(
+            self.path,
+            cached=self.root.cache_enabled,
+        )
+
+    async def delete(self) -> None:
+        """
+        Recursively delete this node and all subnodes.
+        """
+        if await self.exists():
+            await self.root.hook.delete_path(
+                self.path,
+                cached=self.root.cache_enabled,
+            )
+
+
+# =========================
+# Hook Interface
+# =========================
+
+class Hook:
+    """
+    Abstract storage backend interface.
+    """
+
+    async def get_path_value(self, path: str, cached: bool = False) -> Any:
+        raise NotImplementedError
+
+    async def set_path_value(self, path: str, value: Any, cached: bool = False) -> Any:
+        raise NotImplementedError
+
+    async def list_path_subpaths(
+        self, path: str, cached: bool = False
+    ) -> AsyncIterator[str]:
+        raise NotImplementedError
+
+    async def check_path_exists(self, path: str, cached: bool = False) -> bool:
+        raise NotImplementedError
+
+    async def delete_path(self, path: str, cached: bool = False) -> None:
+        raise NotImplementedError
+
+
+# =========================
+# File Store Hook
+# =========================
+
+class FileStoreHook(Hook):
+    """
+    Filesystem-backed storage implementation.
+
+    Each node is stored as a directory. The value is stored in value.json inside the directory.
+    """
+
+    def __init__(self, dir: str) -> None:
+        self.dir = pathlib.Path(dir).absolute()
+        self.locks = [asyncio.Lock() for _ in range(100)]
+
+    async def get_directory_lock(self, directory: str) -> asyncio.Lock:
+        return self.locks[hash(directory) % len(self.locks)]
+
+    async def get_path_directory(self, path: str, file: str = "") -> str:
+        parts = (
+            self.dir,
+            *[
+                base64.urlsafe_b64encode(x.encode()).decode()
+                for x in path.split("/")
+                if x
+            ],
+            file,
+        )
+        return os.path.join(*parts)
+
+    async def get_path_value(self, path: str, cached: bool = False) -> Any:
+        file_path = await self.get_path_directory(path, "value.json")
+
+        async with await self.get_directory_lock(path):
+            if not os.path.isfile(file_path):
+                return None
+
+            async with aiofiles.open(file_path, "r") as f:
+                return json.loads(await f.read())
+
+    async def set_path_value(self, path: str, value: Any, cached: bool = False) -> None:
+        directory = await self.get_path_directory(path)
+
+        async with await self.get_directory_lock(path):
+            os.makedirs(directory, exist_ok=True)
+
+            file_path = await self.get_path_directory(path, "value.json")
+            async with aiofiles.open(file_path, "w") as f:
+                await f.write(json.dumps(value))
+
+    async def list_path_subpaths(
+        self, path: str, cached: bool = False
+    ) -> AsyncIterator[str]:
+        directory = await self.get_path_directory(path)
+
+        async with await self.get_directory_lock(path):
+            if not os.path.isdir(directory):
+                return
+
+            with os.scandir(directory) as entries:
+                for entry in entries:
+                    if entry.is_dir():
+                        try:
+                            yield base64.urlsafe_b64decode(entry.name.encode()).decode()
+                        except Exception:
+                            continue
+
+    async def check_path_exists(self, path: str, cached: bool = False) -> bool:
+        directory = await self.get_path_directory(path)
+
+        async with await self.get_directory_lock(path):
+            return os.path.isdir(directory)
+
+    async def delete_path(self, path: str, cached: bool = False) -> None:
+        directory = await self.get_path_directory(path)
+
+        async with await self.get_directory_lock(path):
+            shutil.rmtree(directory, ignore_errors=True)
+
+
+# =========================
+# KelDB Root
+# =========================
+
+class KelDB(Node):
+    """
+    Root database object.
+    """
+
+    def __init__(self, hook: Hook) -> None:
+        self.root = self
+        self.parent = None
+        self.name = ""
+        self.path = "/"
+        self.hook = hook
+        self.cache_enabled = True

keldb-0.1.0/src/keldb.egg-info/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: keldb
+Version: 0.1.0
+Summary: KelDB is a simple node-based database for asyncio applications.
+Author-email: TriangularDev <triangle@dylsplazy.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiofiles>=22.1.0
+Dynamic: license-file
+
+
+# KelDB
+[![Latest PyPI package version](https://badge.fury.io/py/keldb.svg)](https://pypi.org/project/keldb) [![Latest Read The Docs](https://readthedocs.org/projects/keldb/badge/?version=latest)](https://keldb.readthedocs.io/en/latest/)
+
+KelDB is a simple node-based database for asyncio applications.
+## Dynamics
+KelDB is organised into **nodes**. A node is a container that can hold a value and/or other **subnodes**. The database itself is the root node, and every piece of data is a subnode of it.
+## Usage
+KelDB is quite flexible. There's only a few commands to learn.
+
+    import asyncio
+    import keldb
+    
+    # Create a default KelDB database (or load an existing database)
+    database = keldb.KelDB(keldb.FileStoreHook("./testdb/"))
+    
+    async def main():
+        # Create subnodes (lazy creation - no actual subnodes are created yet)
+        foo = await database.get_subnode("foo")
+        bar = await database.get_subnode("bar")
+        baz = await database.get_subnode("baz")
+    
+        await bar.set_value("This can be any json-serializable object.") # Set a value (now "bar" is actually created)
+        
+        await baz.set_value({"type": "user", "name": "Gabe Newell"}) # Now "baz" is actually created
+    
+        text_subnode = await foo.get_subnode("text")
+    
+        await text_subnode.set_value("If you are reading this, this data saved correctly!") # Write text in a subnode's subnode. (now both "foo" and "foo/text" are created)
+    
+        print(await text_subnode.get_value()) # Read a value from the database
+    
+        await foo.delete() # Delete a subnode (do note that this also recursively deletes any subnodes under it)
+    
+        async for subnode in database.list_subnodes(): # Iterate over subnodes
+            print(subnode.path)
+    
+        await database.set_value("Even the database itself is technically a node!")
+    
+    asyncio.run(main())
+

keldb-0.1.0/src/keldb.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+src/keldb/__init__.py
+src/keldb.egg-info/PKG-INFO
+src/keldb.egg-info/SOURCES.txt
+src/keldb.egg-info/dependency_links.txt
+src/keldb.egg-info/requires.txt
+src/keldb.egg-info/top_level.txt

keldb-0.1.0/src/keldb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

keldb-0.1.0/src/keldb.egg-info/requires.txt

@@ -0,0 +1 @@
+aiofiles>=22.1.0

keldb-0.1.0/src/keldb.egg-info/top_level.txt

@@ -0,0 +1 @@
+keldb