objectbox: added docstrings #52

- box/entity/store
- properties: conditions and hnsw components
- toplevel:
   - module docstring
   - added PropertyQueryCondition and HnswFlags
- c: DebugFlags documentation #52
- PropertyQueryCondition: docstring improvements
- VectorDistanceType: changed enum elements docstrings

Author: dan-obx

objectbox/__init__.py

@@ -12,14 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""ObjectBox Python Bindings Public API"""
 
 from objectbox.store import Store
 from objectbox.box import Box
 from objectbox.model.entity import Entity
-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, HnswIndex, VectorDistanceType
+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, HnswIndex, VectorDistanceType, HnswFlags
 from objectbox.model.model import Model
 from objectbox.c import NotFoundException, version_core, DebugFlags
 from objectbox.version import Version
+from objectbox.condition import PropertyQueryCondition
 from objectbox.builder import Builder
 from objectbox.objectbox import ObjectBox
 
@@ -65,7 +67,9 @@
     'NotFoundException',
     'version',
     'version_info',
-    'DebugFlags'
+    'DebugFlags',
+    'PropertyQueryCondition',
+    'HnswFlags',
 ]
 
 # Python binding version

objectbox/box.py

@@ -31,11 +31,13 @@ def __init__(self, store: Store, entity: _Entity):
         self._c_box = obx_box(store._c_store, entity._id)
 
     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)
@@ -110,6 +112,7 @@ def _put_many(self, objects) -> None:
             self._entity._set_object_id(objects[k], ids[k])
 
     def get(self, id: int):
+        """Get object by given Id or None if not found."""
         with self._store.read_tx():
             c_data = ctypes.c_void_p()
             c_size = ctypes.c_size_t()
@@ -123,6 +126,7 @@ def get(self, id: int):
             return self._entity._unmarshal(data)
 
     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)
@@ -143,6 +147,7 @@ def get_all(self) -> list:
                 obx_bytes_array_free(c_bytes_array_p)
 
     def remove(self, id_or_object) -> bool:
+        """Remove object by id or object."""
         if isinstance(id_or_object, self._entity._user_type):
             id = self._entity._get_object_id(id_or_object)
         else:
@@ -155,6 +160,7 @@ def remove(self, id_or_object) -> bool:
         return True
 
     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)
@@ -166,7 +172,7 @@ def query(self, condition: Optional[QueryCondition] = None) -> QueryBuilder:
             If given, applies the given high-level condition to the new QueryBuilder object.
             Useful for a user-friendly API design; for example:
             
-            ``box.query(name_property.equals("Johnny")).build()``
+            ``box.query(MyEntity.name.equals("Johnny")).build()``
         """
         qb = QueryBuilder(self._store, self)
         if condition is not None:

objectbox/c.py

@@ -86,15 +86,33 @@ def shlib_name(library: str) -> str:
 OBXBackupRestoreFlags = ctypes.c_int
 
 class DebugFlags(IntEnum):
+    """Debug flags"""
+    
     NONE = 0,
+    
     LOG_TRANSACTIONS_READ = 1,
+    """ Log read transactions """
+    
     LOG_TRANSACTIONS_WRITE = 2,
+    """ Log write transactions """
+    
     LOG_QUERIES = 3,
+    """ Log queries """
+    
     LOG_QUERY_PARAMETERS = 8,
+    """ Log query parameters """
+    
     LOG_ASYNC_QUEUE = 16,
+    """ Log async queue """
+    
     LOG_CACHE_HITS = 32,
+    """ Log cache hits """
+    
     LOG_CACHE_ALL = 64,
+    """ Log cache hits """
+    
     LOG_TREE = 128
+    """ Log tree operations """
 
 
 class OBX_model(ctypes.Structure):

objectbox/condition.py

@@ -11,10 +11,12 @@
 
 class QueryCondition:
     def and_(self, other: QueryCondition) -> QueryCondition:
+        """*and* logic condition or using ``&`` operator"""
         return LogicQueryCondition(self, other, LogicQueryConditionOp.AND)
     __and__ = and_
 
     def or_(self, other: QueryCondition) -> QueryCondition:
+        """*or* logic condition or using ``|`` operator"""
         return LogicQueryCondition(self, other, LogicQueryConditionOp.OR)
     __or__ = or_
 
@@ -74,7 +76,11 @@ class PropertyQueryConditionOp(Enum):
 
 
 class PropertyQueryCondition(QueryCondition):
-    """ A QueryCondition describing an operation to be applied on a property (e.g. name == "John", age == 24) """
+    """
+    Query condition 
+    
+    Query conditions describe operations to be applied on a property (e.g. name == "John", age == 24)
+    """
 
     _OP_MAP: Dict[PropertyQueryConditionOp, str] = {
         PropertyQueryConditionOp.EQ: "_apply_eq",

objectbox/model/entity.py

@@ -282,8 +282,15 @@ def Entity(uid: int = 0, model: str = "default") -> _Entity:
     """
     Entity decorator for user classes using syntax ``@Entity([uid=])`` 
     
-    Wraps user classes and returns a ``_Entity`` wrapper.
-    Use allow @Entity(id=, uid=); i.e. no class arguments. 
+    Example::
+    
+        @Entity()
+        class MyEntity:
+            id = Id
+            name = String(index=Index)
+
+       
+    Wraps the given user classes as an ``_Entity`` helper class.
     """
 
     def wrapper(class_) -> Callable[[Type], _Entity]: