objectbox-api 5.0.0__py3-none-any.whl

objectbox/__init__.py

@@ -0,0 +1,145 @@
+# Copyright 2019-2024 ObjectBox Ltd. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""ObjectBox Python API"""
+
+from objectbox.store import Store
+from objectbox.box import Box
+from objectbox.model.entity import Entity, SyncEntity
+from objectbox.model.properties import Id, String, Index, Bool, Int8, Int16, Int32, Int64, Float32, Float64, Bytes, BoolVector, Int8Vector, Int16Vector, Int32Vector, Int64Vector, Float32Vector, Float64Vector, CharVector, BoolList, Int8List, Int16List, Int32List, Int64List, Float32List, Float64List, CharList, Date, DateNano, Flex, Relation, IndexType, Unique, ConflictStrategy, HnswIndex, VectorDistanceType, HnswFlags, SyncClock, SyncPrecedence
+from objectbox.model.model import Model
+from objectbox.c import version_core, DebugFlags
+# The exceptions most likely handled by applications (all are in objectbox.exceptions; its TimeoutError is not
+# exported here, as it would shadow the built-in TimeoutError on "from objectbox import *")
+from objectbox.exceptions import (DbError, IllegalArgumentError, IllegalStateError, UniqueViolatedError,
+                                  ConstraintViolatedError, NonUniqueResultError, IdNotFoundError,
+                                  FeatureNotAvailableError, SchemaError, DbFullError, MaxDataSizeExceededError,
+                                  MaxReadersExceededError, StoreMustShutdownError, FileCorruptError,
+                                  FilePagesCorruptError, NumericOverflowError)
+from objectbox.version import Version
+from objectbox.condition import PropertyQueryCondition
+from objectbox.query import Query, ObjectWithScore, IdWithScore
+from objectbox.query_builder import QueryBuilder
+from objectbox.builder import Builder
+from objectbox.objectbox import ObjectBox
+from objectbox.query_builder import OrderFlags
+
+__all__ = [
+    'Box',
+    'Builder',
+    'Model',
+    'Entity',
+    'Id',
+    'Bool',
+    'Int8',
+    'Int16',
+    'Int32',
+    'Int64',
+    'Float32',
+    'Float64',
+    'Bytes',
+    'String',
+    'BoolVector',
+    'Int8Vector',
+    'Int16Vector',
+    'Int32Vector',
+    'Int64Vector',
+    'Float32Vector',
+    'Float64Vector',
+    'CharVector',
+    'BoolList',
+    'Int8List',
+    'Int16List',
+    'Int32List',
+    'Int64List',
+    'Float32List',
+    'Float64List',
+    'CharList',
+    'Date',
+    'DateNano',
+    'Flex',
+    'Relation',
+    'Index',
+    'IndexType',
+    'Unique',
+    'ConflictStrategy',
+    'HnswIndex',
+    'VectorDistanceType',
+    'Store',
+    'ObjectBox',
+    'DbError',
+    'IllegalArgumentError',
+    'IllegalStateError',
+    'UniqueViolatedError',
+    'ConstraintViolatedError',
+    'NonUniqueResultError',
+    'IdNotFoundError',
+    'FeatureNotAvailableError',
+    'SchemaError',
+    'DbFullError',
+    'MaxDataSizeExceededError',
+    'MaxReadersExceededError',
+    'StoreMustShutdownError',
+    'FileCorruptError',
+    'FilePagesCorruptError',
+    'NumericOverflowError',
+    'version',
+    'version_info',
+    'DebugFlags',
+    'PropertyQueryCondition',
+    'HnswFlags',
+    'Query',
+    'ObjectWithScore',
+    'IdWithScore',
+    'QueryBuilder',
+    'SyncEntity',
+    'SyncClock',
+    'SyncPrecedence',
+    'OrderFlags',
+    # Sync (loaded on first use; see __getattr__)
+    'Sync',
+    'SyncClient',
+    'SyncCredentials',
+    'SyncState',
+    'SyncRequestUpdatesMode',
+    'SyncFlags',
+    'SyncStats',
+    'SyncCode',
+    'SyncChange',
+    'SyncListener',
+    'SyncLoginListener',
+    'SyncConnectionListener',
+    'SyncCompletedListener',
+    'SyncTimeListener',
+    'SyncChangeListener',
+]
+
+_sync_names = frozenset(__all__[__all__.index('Sync'):])
+
+
+def __getattr__(name: str):
+    # Sync names are imported on first use: importing objectbox.sync takes a few milliseconds, also for apps without
+    # Sync (a module __getattr__, PEP 562; also used by "from objectbox import *")
+    if name in _sync_names:
+        import objectbox.sync
+        return getattr(objectbox.sync, name)
+    raise AttributeError(f"module 'objectbox' has no attribute '{name}'")
+
+# Python binding version
+version = Version(5, 0, 0)
+"""ObjectBox Python package version"""
+
+def version_info():
+    """Returns a string with Python and core version information."""
+    return "ObjectBox Python version " + str(version) + " using dynamic library version " + str(version_core)

objectbox/box.py

@@ -0,0 +1,294 @@
+# Copyright 2019-2024 ObjectBox Ltd. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from objectbox.model.entity import _Entity
+from objectbox.store import Store
+from objectbox.query_builder import QueryBuilder
+from objectbox.condition import QueryCondition
+from objectbox.c import *
+from objectbox.exceptions import DbError, IllegalArgumentError, IllegalStateError
+
+
+class Box:
+    """Interface to Entities"""
+    def __init__(self, store: Store, entity: _Entity):
+        if not isinstance(entity, _Entity):
+            raise TypeError(f"Expected an entity (a class decorated with @Entity()), got {entity!r}")
+
+        self._store = store
+        self._entity = entity
+        self._c_box_of_open_store = obx_box(store._c_store, entity._id)
+
+    @property
+    def _c_box(self):
+        if self._store._c_store_or_none is None:  # The C box would be invalid
+            raise IllegalStateError("Store is closed")
+        return self._c_box_of_open_store
+
+    def contains(self, object_id: int) -> bool:
+        """Checks whether the box contains the given object ID."""
+        contained = ctypes.c_bool()
+        obx_box_contains(self._c_box, object_id, ctypes.byref(contained))
+        return bool(contained.value)
+
+    def is_empty(self) -> bool:
+        """Returns true if box is empty (i.e. no objects of entity type are available)."""
+        is_empty = ctypes.c_bool()
+        obx_box_is_empty(self._c_box, ctypes.byref(is_empty))
+        return bool(is_empty.value)
+
+    def count(self, limit: int = 0) -> int:
+        """Returns the count of existing objects."""
+        count = ctypes.c_uint64()
+        obx_box_count(self._c_box, limit, ctypes.byref(count))
+        return int(count.value)
+
+    def put(self, *objects):
+        """Puts an object and returns its ID; puts a list (or tuple) of objects, or several objects passed as
+        arguments, in one transaction and returns their IDs (a list, in the same order).
+
+        A new object has the ID 0 and gets its ID assigned (set on the object). An object with a non-zero ID is
+        updated (or inserted if it does not exist, e.g. was removed); its ID must have been assigned by ObjectBox
+        before (else raises IllegalArgumentError), unless the ID property is ``Id(assignable=True)``."""
+
+        if len(objects) != 1:
+            return self._put_many(objects)
+        elif isinstance(objects[0], (list, tuple)):
+            return self._put_many(objects[0])
+        else:
+            return self._put_one(objects[0])
+
+    def _put_one(self, obj) -> int:
+        # A new object (ID 0) gets its ID assigned while putting (saves a C call to reserve it); this writes the ID
+        # into the data, so it must be a writable copy. A non-zero ID must have been assigned by ObjectBox before
+        # (the C library checks it), unless the ID property is assignable.
+        self._check_type(obj)
+        id = self._entity._get_object_id(obj)
+        if id:  # The C library does not write into the data (the ID is set)
+            data = bytes(self._entity._marshal(obj, id))
+            return obx_box_put_object4(self._c_box, data, len(data), OBXPutMode_PUT)
+        data = self._entity._marshal(obj, 0)
+        size = len(data)
+        id = obx_box_put_object4(self._c_box, ctypes.create_string_buffer(bytes(data), size), size, OBXPutMode_PUT)
+        self._entity._set_object_id(obj, id)
+        return id
+
+    def _put_many(self, objects) -> List[int]:
+        if not objects:
+            return []
+        # retrieve IDs from the objects (to distinguish new objects and updates)
+        new = {}
+        ids = {}
+        for k in range(len(objects)):
+            self._check_type(objects[k])
+            id = self._entity._get_object_id(objects[k])
+            if not id:
+                new[k] = 0
+            ids[k] = id
+
+        with self._store.write_tx():  # One transaction for checking/reserving the IDs and putting
+            self._put_many_in_tx(objects, new, ids)
+
+        # assign new IDs on the object
+        for k in new.keys():
+            self._entity._set_object_id(objects[k], ids[k])
+        return list(ids.values())
+
+    def _put_many_in_tx(self, objects, new, ids) -> None:
+        # Check the given IDs: obx_box_put_many() takes them as reserved; obx_box_id_for_put() raises for an ID not
+        # assigned by ObjectBox before (and advances the ID sequence for assignable IDs). Checking the highest ID
+        # covers all: lower IDs were assigned before, too.
+        max_id = max(ids.values(), default=0)
+        if max_id:
+            obx_box_id_for_put(self._c_box, max_id)
+
+        # acquire IDs for the new objects and set them
+        if len(new) > 0:
+            c_next_id = obx_id()
+            obx_box_ids_for_put(self._c_box, len(new), ctypes.byref(c_next_id))
+            next_id = c_next_id.value
+            for k in new.keys():
+                ids[k] = next_id
+                next_id += 1
+
+        # allocate a C bytes array structure where we will push the object data
+        # OBX_bytes_array with .count = len(objects)
+        c_bytes_array_p = obx_bytes_array(len(objects))
+
+        try:
+            # we need to keep the data around until put_many is executed because obx_bytes_array_set doesn't do a copy
+            data = {}
+            for k in range(len(objects)):
+                data[k] = bytes(self._entity._marshal(objects[k], ids[k]))
+                key = ctypes.c_size_t(k)
+
+                # OBX_bytes_array.data[k] = data
+                obx_bytes_array_set(c_bytes_array_p, key,
+                                    data[k], len(data[k]))
+
+            c_ids = (obx_id * len(ids))(*ids.values())
+            obx_box_put_many(self._c_box, c_bytes_array_p,
+                             c_ids, OBXPutMode_PUT)
+
+        finally:
+            obx_bytes_array_free(c_bytes_array_p)
+
+    def update(self, object_):
+        """Updates the existing object having the same ID as the given object.
+
+        Raises if the object has no ID (i.e. it was never put) or the ID doesn't match any stored object."""
+        self._check_type(object_)
+        object_id = self._entity._get_object_id(object_)
+        if not object_id:
+            raise IllegalArgumentError("Cannot update an object without an ID; use put() for new objects")
+        data = self._entity._marshal(object_, object_id)
+        obx_box_update(self._c_box, object_id, bytes(data), len(data))
+
+    def get(self, id: int):
+        """Get object by given Id or None if not found."""
+        c_box = self._c_box  # Raises if the store is closed
+        tx = obx_txn_read(self._store._c_store_or_none)  # not via read_tx(): less overhead for this hot path
+        try:
+            c_data = ctypes.c_void_p()
+            c_size = ctypes.c_size_t()
+            code : obx_err = obx_box_get(c_box, id, ctypes.byref(
+                    c_data), ctypes.byref(c_size))
+            if code == 404:
+                return None
+            elif code != 0:
+                raise DbError.from_code(code)
+            data = c_voidp_as_bytes(c_data, c_size.value)
+        finally:
+            obx_txn_close(tx)
+        return self._entity._unmarshal(data)
+
+    def get_many(self, id_array: List[int]) -> list:
+        """Gets objects matching the given ID list.
+
+        :return: objects matching the ID list, preserving the order.
+            If an invalid ID is supplied, the corresponding object is None.
+        """
+
+        if not id_array:  # Empty
+            return []
+
+        c_ids = (obx_id * len(id_array))(*id_array)
+        c_id_array = OBX_id_array(ctypes.cast(c_ids, ctypes.POINTER(obx_id)), len(id_array))
+
+        with self._store.read_tx():
+            c_bytes_array_p = obx_box_get_many(self._c_box, ctypes.byref(c_id_array))
+
+            result = []
+            try:
+                c_bytes_array = c_bytes_array_p.contents
+                for i in range(c_bytes_array.count):
+                    c_bytes = c_bytes_array.data[i]
+                    if c_bytes.data is None or c_bytes.size == 0:  # User supplied an invalid ID
+                        result.append(None)
+                    else:
+                        data = c_voidp_as_bytes(c_bytes.data, c_bytes.size)
+                        result.append(self._entity._unmarshal(data))
+            finally:
+                obx_bytes_array_free(c_bytes_array_p)
+            return result
+
+    def get_all(self) -> list:
+        """Get all objects."""
+        with self._store.read_tx():
+            # OBX_bytes_array*
+            c_bytes_array_p = obx_box_get_all(self._c_box)
+
+            try:
+                # OBX_bytes_array
+                c_bytes_array = c_bytes_array_p.contents
+
+                result = list()
+                for i in range(c_bytes_array.count):
+                    # OBX_bytes
+                    c_bytes = c_bytes_array.data[i]
+                    data = c_voidp_as_bytes(c_bytes.data, c_bytes.size)
+                    result.append(self._entity._unmarshal(data))
+
+                return result
+            finally:
+                obx_bytes_array_free(c_bytes_array_p)
+
+    def remove(self, id_or_object) -> bool:
+        """Removes the object with the given ID (or the given object); returns False if it did not exist.
+        See :meth:`remove_many` for several objects."""
+        if isinstance(id_or_object, (list, tuple)):
+            raise TypeError("remove() takes one ID or object; use remove_many() for several")
+        id = self._id_of(id_or_object)
+        code : obx_err = obx_box_remove(self._c_box, id)
+        if code == 404:
+            return False
+        elif code != 0:
+            raise DbError.from_code(code)
+        return True
+
+    def remove_many(self, ids_or_objects) -> int:
+        """Removes the objects with the given IDs (or the given objects) in one transaction; IDs that do not exist
+        are skipped. Returns the number of removed objects."""
+        ids = [self._id_of(item) for item in ids_or_objects]
+        if not ids:
+            return 0
+        c_ids = (obx_id * len(ids))(*ids)
+        c_id_array = OBX_id_array(ctypes.cast(c_ids, ctypes.POINTER(obx_id)), len(ids))
+        count = ctypes.c_uint64()
+        obx_box_remove_many(self._c_box, ctypes.byref(c_id_array), ctypes.byref(count))
+        return int(count.value)
+
+    def _id_of(self, id_or_object) -> int:
+        if self._is_entity_object(id_or_object):
+            return self._entity._get_object_id(id_or_object)
+        if not isinstance(id_or_object, int) or isinstance(id_or_object, bool):
+            raise TypeError(f"Expected an ID (int) or an object of entity {self._entity._name}, got {id_or_object!r}")
+        return id_or_object
+
+    def _check_type(self, obj):
+        if not self._is_entity_object(obj):
+            raise TypeError(f"Expected an object of entity {self._entity._name}, got {obj!r}")
+
+    def _is_entity_object(self, obj) -> bool:
+        # Also accepts the same class defined again, e.g. by re-running a notebook cell
+        user_type = self._entity._user_type
+        return isinstance(obj, user_type) or type(obj).__name__ == user_type.__name__
+
+    def remove_all(self) -> int:
+        """Removes all objects and returns number of removed."""
+        count = ctypes.c_uint64()
+        obx_box_remove_all(self._c_box, ctypes.byref(count))
+        return int(count.value)
+
+    def query(self, condition: Optional[QueryCondition] = None) -> QueryBuilder:
+        """ Initiates Query creation for the Entity associated by this Box.
+        Technically, it creates a QueryBuilder object, and you have to call build() on it to get the Query object.
+
+        :param condition:
+            Applies the given condition(s) to the new QueryBuilder object.
+            For example, assuming you defined an @Entity called "MyEntity" with a string property "name":
+            
+            ``query = box.query(MyEntity.name.equals("Johnny")).build()``
+
+            It's also possible to pass multiple conditions:
+
+            ``query = box.query(MyEntity.name.equals("Johnny") & MyEntity.age.greater_than(21)).build()``
+
+            Note: ``&`` is the logical AND operator, and ``|`` is the logical OR operator.
+        """
+        qb = QueryBuilder(self._store, self)
+        if condition is not None:
+            condition.apply(qb)
+        return qb

objectbox/builder.py

@@ -0,0 +1,42 @@
+# Copyright 2019-2024 ObjectBox Ltd. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from objectbox.c import *
+from objectbox.model.model import Model
+from objectbox.store import Store
+from objectbox.store_options import StoreOptions
+from warnings import warn
+
+class Builder:
+    """*Deprecated Interface*"""
+    def __init__(self):
+        """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._kwargs['directory'] = path
+        return self
+
+    def max_db_size_in_kb(self, size_in_kb: int) -> 'Builder':
+        self._kwargs['max_db_size_in_kb'] = size_in_kb
+        return self
+
+    def model(self, model: Model) -> 'Builder':
+        self._kwargs['model'] = model
+        return self
+
+    def build(self) -> 'Store':
+        return Store(**self._kwargs)