Creating a Custom Hook

A Hook is the storage backend interface used by KelDB. It defines how data is stored, retrieved, listed, and deleted.

To extend KelDB, you implement a subclass of Hook and provide your own storage logic (database, cloud storage, in-memory store, etc.).

Why Hooks exist

Hooks separate:

• KelDB logic (tree structure, nodes, paths)

• Storage logic (filesystem, memory, remote APIs, databases)

This makes KelDB fully hot-pluggable, allowing you to connect the simplicity of KelDB to whatever your use case requires.

However, you bear the responsibility of storage, thread-safety, caching, and integration.

Basic structure

All hooks must implement the following methods:

class MyHook(Hook):
    async def __init__(self):
        self.locksystem = None # Always define the locksystem property and ensure it can be changed dynamically

    async def get_path_value(self, path, cached=False):
        pass # Return a JSON-serializable object, or None if it doesn't exist

    async def set_path_value(self, path, value, cached=False):
        pass # Return anything

    async def list_path_subpaths(self, path, cached=False):
        pass # Ideally, return an lazy iterator to save on memory

    async def check_path_exists(self, path, cached=False):
        pass # Return a boolean

    async def delete_path(self, path, cached=False):
        pass # Return anything

Your hook should never throw an exception unless an internal failure occurs, such as a disk I/O failure.

Using your hook

Once implemented, pass it into KelDB:

from keldb import KelDB

db = KelDB(MyHook())