Merge branch '44-deprecate-Builder-enrich-Store-constructor' into 'dev'

Deprecate Builder / Store constructor with optional parameters

Closes #44

See merge request objectbox/objectbox-python!33

Author: dan-obx

README.md

@@ -61,23 +61,23 @@ class Person:
 
 ### Using ObjectBox
 
-To actually use the database, you launch (or "build") it with the model you've just defined.
-Afterwards, you can reuse the instance (`ob` in the example below) and use it to access "Entity Boxes" which hold your objects.
+To actually use the database, you create a Store with the model you've just defined.
+Afterwards, you can reuse the instance (`store` in the example below) and use it to access "Entity Boxes" which hold your objects.
 
 #### program.py
 
 ```python
 import objectbox
 # from mypackage.model import Person
 
-# Configure ObjectBox: should be done only once in the whole program and the "ob" variable should be kept around
+# Configure ObjectBox: should be done only once in the whole program and the "store" variable should be kept around
 model = objectbox.Model()
 model.entity(Person, last_property_id=objectbox.model.IdUid(10, 1010))
 model.last_entity_id = objectbox.model.IdUid(1, 1)
-ob = objectbox.Builder().model(model).directory("db").build()
+store = objectbox.Store(model=model)
 
 # Open the box of "Person" entity. This can be called many times but you can also pass the variable around
-box = objectbox.Box(ob, Person)
+box = store.box(Person)
 
 person = Person()
 person.name = "Joe Green"

benchmark.py

@@ -10,8 +10,8 @@ class ObjectBoxPerf:
     """
 
     def __init__(self):
-        self.ob = load_empty_test_default_store()
-        self.box = objectbox.Box(self.ob, TestEntity)
+        self.store = load_empty_test_default_store()
+        self.box = store.box(TestEntity)
 
     def remove_all(self):
         self.box.remove_all()

example/tasks/__main__.py

@@ -15,8 +15,8 @@ def format_date(timestamp_ms: int) -> str:
 
 class TasklistCmd(Cmd):
     prompt = "> "
-    _ob = objectbox.Builder().model(get_objectbox_model()).directory("tasklist-db").build()
-    _box = objectbox.Box(_ob, Task)
+    _store = objectbox.Store(model=get_objectbox_model(), directory="tasklist-db")
+    _box = _store.box(Task)
 
     def do_ls(self, _):
         """list tasks"""

example/vectorsearch-cities/__main__.py

@@ -23,8 +23,8 @@ def __init__(self, *args):
         Cmd.__init__(self, *args)
         dbdir = "cities-db"
         new_db = not os.path.exists(dbdir)
-        self._ob = objectbox.Builder().model(get_objectbox_model()).directory(dbdir).build()
-        self._box = objectbox.Box(self._ob, City)
+        self._store = objectbox.Store(model=get_objectbox_model(),directory=dbdir)
+        self._box = _store.box(City)
         self._name_prop: Property = City.get_property("name")
         self._location_prop: Property = City.get_property("location")
         if new_db: 

objectbox/__init__.py

@@ -18,7 +18,7 @@
 from objectbox.model import Model
 from objectbox.store import Store
 from objectbox.objectbox import ObjectBox
-from objectbox.c import NotFoundException, version_core
+from objectbox.c import NotFoundException, version_core, DebugFlags
 from objectbox.version import Version
 
 __all__ = [
@@ -30,6 +30,7 @@
     'NotFoundException',
     'version',
     'version_info',
+    'DebugFlags'
 ]
 
 # Python binding version

objectbox/builder.py

@@ -17,37 +17,25 @@
 from objectbox.model import Model
 from objectbox.store import Store
 from objectbox.store_options import StoreOptions
-
+from warnings import warn
 
 class Builder:
     def __init__(self):
-        self._model = Model()
-        self._directory = None
-        self._max_db_size_in_kb = None
+        """This throws a deprecation warning on initialization."""
+        warn(f'Using {self.__class__.__name__} is deprecated, please use Store(model=, directory= ...) from objectbox.store.', DeprecationWarning, stacklevel=2)
+        self._kwargs = { }
 
     def directory(self, path: str) -> 'Builder':
-        self._directory = path
+        self._kwargs['directory'] = path
         return self
 
     def max_db_size_in_kb(self, size_in_kb: int) -> 'Builder':
-        self._max_db_size_in_kb = size_in_kb
+        self._kwargs['max_db_size_in_kb'] = size_in_kb
         return self
 
     def model(self, model: Model) -> 'Builder':
-        self._model = model
-        self._model._finish()
+        self._kwargs['model'] = model
         return self
 
     def build(self) -> 'Store':
-        options = StoreOptions()
-        try:
-            if self._directory:
-                options.directory(self._directory)
-            if self._max_db_size_in_kb:
-                options.max_db_size_in_kb(self._max_db_size_in_kb)
-            options.model(self._model)
-        except CoreException:
-            options._free()
-            raise
-        c_store = obx_store_open(options._c_handle)
-        return Store(c_store)
+        return Store(**self._kwargs)

objectbox/c.py

@@ -19,6 +19,7 @@
 from objectbox.version import Version
 from typing import *
 import numpy as np
+from enum import IntEnum
 
 # This file contains C-API bindings based on lib/objectbox.h, linking to the 'objectbox' shared library.
 # The bindings are implementing using ctypes, see https://docs.python.org/dev/library/ctypes.html for introduction.
@@ -84,6 +85,17 @@ def shlib_name(library: str) -> str:
 OBXValidateOnOpenKvFlags = ctypes.c_int
 OBXBackupRestoreFlags = ctypes.c_int
 
+class DebugFlags(IntEnum):
+    NONE = 0,
+    LOG_TRANSACTIONS_READ = 1,
+    LOG_TRANSACTIONS_WRITE = 2,
+    LOG_QUERIES = 3,
+    LOG_QUERY_PARAMETERS = 8,
+    LOG_ASYNC_QUEUE = 16,
+    LOG_CACHE_HITS = 32,
+    LOG_CACHE_ALL = 64,
+    LOG_TREE = 128
+
 
 class OBX_model(ctypes.Structure):
     pass

objectbox/objectbox.py

@@ -17,7 +17,7 @@
 from warnings import warn
 
 class ObjectBox(objectbox.store.Store):
-    def __init__(self, *args, **kwargs):
+    def __init__(self, c_store):
         """This throws a deprecation warning on initialization."""
         warn(f'{self.__class__.__name__} will be deprecated, use Store from objectbox.store.', DeprecationWarning, stacklevel=2)
-        super().__init__(*args, **kwargs)
+        super().__init__(c_store=c_store)

objectbox/store.py

@@ -13,16 +13,173 @@
 # limitations under the License.
 
 
-from objectbox.c import *
+import objectbox.c as c
 import objectbox.transaction
-
+from objectbox.store_options import StoreOptions
+import objectbox
+from objectbox.model.entity import _Entity
+from typing import *
 
 class Store:
-    def __init__(self, c_store: OBX_store_p):
-        self._c_store = c_store
+    def __init__(self, 
+                 model : Optional[objectbox.model.Model] = None, 
+                 directory : Optional[str] = None, 
+                 max_db_size_in_kb : Optional[int] = None,
+                 max_data_size_in_kb: Optional[int] = None,
+                 file_mode: Optional[int] = None,
+                 max_readers: Optional[int] = None,
+                 no_reader_thread_locals: Optional[bool] = None,
+                 model_bytes: Optional[bytes] = None,
+                 model_bytes_direct: Optional[bytes] = None,
+                 read_schema: Optional[bool] = None,
+                 use_previous_commit: Optional[bool] = None,
+                 read_only: Optional[bool] = None,
+                 debug_flags: Optional[c.DebugFlags] = None,
+                 async_max_queue_length: Optional[int] = None,
+                 async_throttle_at_queue_length: Optional[int] = None,
+                 async_throttle_micros: Optional[int] = None,
+                 async_max_in_tx_duration: Optional[int] = None,
+                 async_max_in_tx_operations: Optional[int] = None,
+                 async_pre_txn_delay: Optional[int] = None,
+                 async_post_txn_delay: Optional[int] = None,
+                 async_minor_refill_threshold: Optional[int] = None,
+                 async_minor_refill_max_count: Optional[int] = None,
+                 async_object_bytes_max_cache_size: Optional[int] = None,
+                 async_object_bytes_max_size_to_cache: Optional[int] = None,
+                 c_store : Optional[c.OBX_store_p] = None):
+        
+        """Opens an ObjectBox database Store
+
+        :param model:
+            Database schema model.
+        :param directory:
+            Store directory. Defaults to "objectbox". 
+            Use prefix "memory:" to open an in-memory database, e.g. "memory:myapp"
+        :param max_db_size_in_kb:
+            Maximum database size. Defaults to one gigabyte.
+        :param max_data_size_in_kb:
+            Maximum data in database size tracking. Defaults to being disabled.
+            This is a more involved size tacking.
+            Recommended only if stricter accurate limit is required.
+            Data size must be below database size. 
+        :param file_mode:
+            Unix-style file mode options. Defaults to "int('644',8)". 
+            This option is ignored on Windows platforms.
+        :param max_readers:
+            Maximum number of readers (related to read transactions).
+            Default value (currently 126) is suitable for most applications.
+        :param no_reader_thread_locals:
+            Disables the usage of thread locals for "readers" related to read transactions.
+            This can make sense if you are using a lot of threads that are kept alive.
+        :param model_bytes:
+            Database schema model given by flatbuffers bytes serialized model. 
+        :param model_bytes_direct:
+            Database schema model given by flatbuffers bytes serialized model without copying.
+        :param read_schema:
+            Advanced settings.
+        :param use_previous_commit:
+            Advanced setting recommended to set with read_only to ensure no data is lost.
+        :param read_only:
+            Open store in read-only mode: no schema update, no write transactions. Defaults to false.
+        :param debug_flags:
+            Set debug flags. Defaults to DebugFlags.NONE.
+        :param async_max_queue_length:
+            Maximum size of the queue before new transactions will be rejected.
+        :param async_throttle_at_queue_length:
+            Throttle queue submitter when hitting this water mark.
+        :param async_throttle_micros:
+            Sleeping time for throttled queue submitter.
+        :param async_max_in_tx_duration:
+            Maximum duration spent in a transaction before queue enforces a commit.
+        :param async_max_in_tx_operations:
+            Maximum number of operations performed in a transaction before queye enforces a commit.
+        :param async_pre_txn_delay:
+            Delay (in micro seconds) before queue is triggered by new element.
+        :param async_post_txn_delay:
+            Delay (in micro seconds) after a transaction was committed.
+        :param async_minor_refill_threshold:
+            Number of operations to be considered a "minor refill". 
+        :param async_minor_refill_max_count:
+            If set, allows "minor refills" with small batches that came in (off by default).
+        :param async_object_bytes_max_cache_size:
+            Total cache size. Defaults to 0.5 mega bytes.
+        :param async_object_bytes_max_size_to_cache:
+            Maximum size for an object to be cached.
+        :param c_store:
+            Internal parameter for deprecated ObjectBox interface. Do not use it; other options would be ignored if passed.
+        """ 
+        
+        self._c_store = None
+        if not c_store:
+            options = StoreOptions()
+            try:
+                if model is not None:
+                    options.model(model)
+                if directory is not None:
+                    options.directory(directory)
+                if max_db_size_in_kb is not None:
+                    options.max_db_size_in_kb(max_db_size_in_kb)
+                if max_data_size_in_kb is not None:
+                    options.max_data_size_in_kb(max_data_size_in_kb)
+                if file_mode is not None:
+                    options.file_mode(file_mode)
+                if max_readers is not None:
+                    options.max_readers(max_readers)
+                if no_reader_thread_locals is not None:
+                    options.no_reader_thread_locals(no_reader_thread_locals)
+                if model_bytes is not None:
+                    options.model_bytes(model_bytes)
+                if model_bytes_direct is not None:
+                    options.model_bytes_direct(model_bytes_direct)
+                if read_schema is not None:
+                    options.read_schema(read_schema)
+                if use_previous_commit is not None:
+                    options.use_previous_commit(use_previous_commit)
+                if read_only is not None:
+                    options.read_only(read_only)
+                if debug_flags is not None:
+                    options.debug_flags(debug_flags)
+                if async_max_queue_length is not None:
+                    options.async_max_queue_length(async_max_queue_length)
+                if async_throttle_at_queue_length is not None:
+                    options.async_throttle_at_queue_length(async_throttle_at_queue_length)
+                if async_throttle_micros is not None:
+                    options.async_throttle_micros(async_throttle_micros)
+                if async_max_in_tx_duration is not None:
+                    options.async_max_in_tx_duration(async_max_in_tx_duration)
+                if async_max_in_tx_operations is not None:
+                    options.async_max_in_tx_operations(async_max_in_tx_operations)
+                if async_pre_txn_delay is not None:
+                    options.async_pre_txn_delay(async_pre_txn_delay)
+                if async_post_txn_delay is not None:
+                    options.async_post_txn_delay(async_post_txn_delay)
+                if async_minor_refill_threshold is not None:
+                    options.async_minor_refill_threshold(async_minor_refill_threshold)
+                if async_minor_refill_max_count is not None:
+                    options.async_minor_refill_max_count(async_minor_refill_max_count)
+                if async_object_bytes_max_cache_size is not None:
+                    options.async_object_bytes_max_cache_size(async_object_bytes_max_cache_size)
+                if async_object_bytes_max_size_to_cache is not None:
+                    options.async_object_bytes_max_size_to_cache(async_object_bytes_max_size_to_cache)    
+                
+            except c.CoreException:
+                options._free()
+                raise
+            self._c_store = c.obx_store_open(options._c_handle)                 
+        else:
+            self._c_store = c_store
 
     def __del__(self):
         self.close()
+    
+    def box(self, entity: _Entity) -> 'objectbox.Box':
+        """
+        Open a box for an entity.
+        
+        :param entity:
+            Entity type of the model
+        """
+        return objectbox.Box(self, entity)
 
     def read_tx(self):
         return objectbox.transaction.read(self)
@@ -34,4 +191,13 @@ def close(self):
         c_store_to_close = self._c_store
         if c_store_to_close:
             self._c_store = None
-            obx_store_close(c_store_to_close)
+            c.obx_store_close(c_store_to_close)
+
+    def remove_db_files(dir):
+        """
+        Remove Database files
+        
+        :param dir:
+            Path to directory.
+        """
+        c.obx_remove_db_files(c.c_str(dir))