Changes to init syntax (#460)

Co-authored-by: Tomasz Wejroch <twejroch@dbzero.io>

Author: sigsegvdev

dbzero/dbzero/__init__.py

@@ -6,8 +6,8 @@
 from .storage_api import *
 from .atomic import *
 from .locked import *
-from .connection import *
 from .utilities import taggify
 from .decorators import *
 from .select import *
-from .compare import *
+from .compare import *
+from .initialization import init

dbzero/dbzero/connection.py

@@ -0,0 +1,53 @@
+"""dbzero initialization functions"""
+from .dbzero import _init, open as dbzero_open
+
+def init(dbzero_root: str, **kwargs) -> None:
+    """Initialize the dbzero environment in a specified directory and apply global configurations.
+
+    This function sets up the underlying state management engine.
+    It must be called once before interacting with any data.
+    If you need to switch to a different working directory, you should first call 
+    dbzero.close() and then dbzero.init() again with the new path.
+
+    Parameters
+    ----------
+    dbzero_root : str
+        The path to dbzero data files directory. If the directory doesn't exist, 
+        it will be created.
+    **kwargs : dict
+        Additional keyword arguments:
+        * prefix (str) shortcut to open a prefix after initialization
+        * read_write (bool, default True) set the open mode for the prefix
+        
+        Configure global dbzero behavior:
+        * autocommit (bool, default True) to enable automatic commits
+        * autocommit_interval (int, default 250) for commit interval in milliseconds  
+        * cache_size (int, default 2 GiB) for main object cache size in bytes
+        * lang_cache_size (int, default 1024) for language model data cache size
+        * lock_flags (dict) to configure locking behavior when opening the prefix in read-write mode
+
+        Lock flags (dict):
+        * blocking (bool, default False) wait when trying to acquire the lock
+        * timeout (int) maximum waiting time in seconds when blocking wait is enabled
+        * force_unlock (bool, default False) force unlocking of existing lock
+    """
+
+    init_kwargs = {}
+
+    config_keys = ("autocommit", "autocommit_interval", "cache_size", "lang_cache_size")
+    config = {}
+    for key in config_keys:
+        if key in kwargs:
+            config[key] = kwargs[key]
+
+    if config:
+        init_kwargs["config"] = config
+
+    if "lock_flags" in kwargs:
+        init_kwargs["lock_flags"] = kwargs["lock_flags"]
+
+    _init(dbzero_root, **init_kwargs)
+
+    if "prefix" in kwargs:
+        open_mode = "rw" if kwargs.get("read_write", True) else "r"
+        dbzero_open(kwargs["prefix"], open_mode=open_mode)

dbzero/dbzero/initialization.py

@@ -18,7 +18,7 @@ def get_prefixes() -> Iterator[PrefixMetaData]:
     Discovering and opening all available prefixes:
 
     >>> # First, initialize the dbzero environment
-    >>> dbzero.init(path="/path/to/my/data")
+    >>> dbzero.init(dbzero_root="/path/to/my/data")
     >>> 
     >>> # Discover all available prefixes
     >>> all_prefixes = dbzero.get_prefixes()

dbzero/dbzero/storage_api.py

@@ -51,10 +51,11 @@ def db0_slab_size(request):
         shutil.rmtree(DB0_DIR)
     # create empty directory
     os.mkdir(DB0_DIR)
-    db0.init(DB0_DIR, config = {
-        "autocommit": request.param.get("autocommit", True),
-        "autocommit_interval": request.param.get("autocommit_interval", 250),
-        })
+    db0.init(
+        DB0_DIR,
+        autocommit=request.param.get("autocommit", True),
+        autocommit_interval=request.param.get("autocommit_interval", 250),
+    )
     db0.open("my-test-prefix", slab_size=request.param["slab_size"])
     yield db0     
     gc.collect()
@@ -72,7 +73,7 @@ def db0_autocommit_fixture(request):
         shutil.rmtree(DB0_DIR)
     # create empty directory
     os.mkdir(DB0_DIR)
-    db0.init(DB0_DIR, config = {"autocommit": True, "autocommit_interval": request.param})
+    db0.init(DB0_DIR, autocommit=True, autocommit_interval=request.param)
     db0.open("my-test-prefix")
     yield db0    
     gc.collect()
@@ -91,7 +92,7 @@ def db0_no_autocommit():
     # create empty directory
     os.mkdir(DB0_DIR)
     # disable autocommit on all prefixes
-    db0.init(DB0_DIR, config = {"autocommit": False})
+    db0.init(DB0_DIR, autocommit=False)
     db0.open("my-test-prefix")
     yield db0    
     db0.close()    
@@ -160,7 +161,7 @@ def db0_metaio_fixture():
         shutil.rmtree(DB0_DIR)
     # create empty directory
     os.mkdir(DB0_DIR)
-    db0.init(DB0_DIR, config = {"autocommit": False})
+    db0.init(DB0_DIR, autocommit=False)
     db0.open("my-test-prefix", meta_io_step_size=16)
     yield db0
     gc.collect()

python_tests/conftest.py

@@ -33,7 +33,7 @@ def __init__(self):
 
 def start():
     # Configure the dbzero connection without connecting yet
-    db0.init(os.path.join(os.getcwd(), "app-data"), config=config)
+    db0.init(os.path.join(os.getcwd(), "app-data"), **config)
     db0.open(config["prefix"])
     root = Root([])
     for _ in range(10):

python_tests/migration2_init.py

@@ -35,7 +35,7 @@ def __init__(self):
 
 def start():
     # Configure the dbzero connection without connecting yet
-    db0.init(os.path.join(os.getcwd(), "app-data"), config=config)
+    db0.init(os.path.join(os.getcwd(), "app-data"), **config)
     db0.open(config["prefix"])
     root = Root()
     print(f"Root has: {len(root.value)} items")

python_tests/migration2_test.py

@@ -23,7 +23,7 @@ def __init__(self, value):
 
 def start():
     # Configure the dbzero connection without connecting yet
-    db0.init(os.path.join(os.getcwd(), "app-data"), config=config)
+    db0.init(os.path.join(os.getcwd(), "app-data") **config)
     db0.open(config["prefix"])
     obj = MySingleton(123)    
     db0.close()

python_tests/migration_init.py

@@ -33,7 +33,7 @@ def items(self):
 
 def start():
     # Configure the dbzero connection without connecting yet
-    db0.init(os.path.join(os.getcwd(), "app-data"), config=config)
+    db0.init(os.path.join(os.getcwd(), "app-data"), **config)
     db0.open(config["prefix"])
     obj = MySingleton(123)
     print(f"int param: {obj.int_param}")

python_tests/migration_test_1.py

@@ -43,7 +43,7 @@ def str_items(self):
 
 def start():
     # Configure the dbzero connection without connecting yet
-    db0.init(os.path.join(os.getcwd(), "app-data"), config=config)
+    db0.init(os.path.join(os.getcwd(), "app-data"), **config)
     db0.open(config["prefix"])
     obj = MySingleton(123)
     print(f"int param: {obj.int_param}")