ic-python-db 0.9.0__tar.gz → 0.10.0__tar.gz

{ic_python_db-0.9.0/ic_python_db.egg-info → ic_python_db-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ic-python-db
-Version: 0.9.0
+Version: 0.10.0
 Summary: A lightweight key-value database written in Python, intended for use on the Internet Computer (IC)
 Home-page: https://github.com/smart-social-contracts/ic-python-db
 Author: Smart Social Contracts

{ic_python_db-0.9.0 → ic_python_db-0.10.0}/ic_python_db/__init__.py

@@ -20,7 +20,7 @@ from .schema import SchemaIncompatibleError, build_schema, diff_schemas, schema_
 from .storage import MemoryStorage, Storage
 from .system_time import SystemTime
 
-__version__ = "0.9.0"
+__version__ = "0.10.0"
 __all__ = [
     "Database",
     "Entity",

{ic_python_db-0.9.0 → ic_python_db-0.10.0}/ic_python_db/db_engine.py

@@ -426,6 +426,68 @@ class Database:
         if self._db_storage.get(key) is not None:
             self._db_storage.remove(key)
 
+    # Reverse counters (unidirectional relations)
+    # Key format: "_rc:{parent_type}:{parent_id}:{relation_name}"
+    # Value: integer count of related entities.
+    #
+    # Used by unidirectional ManyToMany relations: the owning side keeps its
+    # normal (small) index while the target side maintains only an O(1)
+    # counter instead of an ID array that would grow with every relation
+    # (e.g. a UserProfile referenced by 100k users).
+
+    def _rc_key(self, parent_type: str, parent_id: str, relation_name: str) -> str:
+        return f"_rc:{parent_type}:{parent_id}:{relation_name}"
+
+    def reverse_count_get(
+        self, parent_type: str, parent_id: str, relation_name: str
+    ) -> int:
+        """Read the reverse counter for a parent entity's relation.
+
+        Falls back to the length of a legacy reverse-index array (from when
+        the relation was bidirectional) if no counter exists yet.
+        """
+        key = self._rc_key(parent_type, parent_id, relation_name)
+        raw = self._db_storage.get(key)
+        if raw is not None:
+            return int(raw)
+        legacy = self._db_storage.get(
+            self._ri_key(parent_type, parent_id, relation_name)
+        )
+        if legacy:
+            return len(json.loads(legacy))
+        return 0
+
+    def reverse_count_add(
+        self, parent_type: str, parent_id: str, relation_name: str, delta: int
+    ) -> None:
+        """Adjust the reverse counter by delta (never below zero).
+
+        On first write, seeds the counter from a legacy reverse-index array
+        (if present) and drops the array — lazy, exactly-once migration of
+        relations converted from bidirectional to unidirectional.
+        """
+        key = self._rc_key(parent_type, parent_id, relation_name)
+        raw = self._db_storage.get(key)
+        if raw is not None:
+            current = int(raw)
+        else:
+            legacy_key = self._ri_key(parent_type, parent_id, relation_name)
+            legacy = self._db_storage.get(legacy_key)
+            if legacy:
+                current = len(json.loads(legacy))
+                self._db_storage.remove(legacy_key)
+            else:
+                current = 0
+        self._db_storage.insert(key, str(max(0, current + delta)))
+
+    def reverse_count_delete(
+        self, parent_type: str, parent_id: str, relation_name: str
+    ) -> None:
+        """Delete a reverse counter entry (used when the parent is deleted)."""
+        key = self._rc_key(parent_type, parent_id, relation_name)
+        if self._db_storage.get(key) is not None:
+            self._db_storage.remove(key)
+
     def get_audit(
         self, id_from: Optional[int] = None, id_to: Optional[int] = None
     ) -> Dict[str, str]:

{ic_python_db-0.9.0 → ic_python_db-0.10.0}/ic_python_db/entity.py

@@ -513,6 +513,20 @@ class Entity:
         count = db.load("_system", count_key)
         return int(count) if count else 0
 
+    def reverse_count(self, relation_name: str) -> int:
+        """Number of entities referencing this one via a unidirectional
+        ManyToMany relation.
+
+        ``relation_name`` is the ``reverse_name`` declared on the owning
+        side, e.g. with ``User.profiles = ManyToMany('UserProfile', 'users',
+        unidirectional=True)`` a profile's holder count is
+        ``profile.reverse_count('users')``.
+
+        Falls back to the legacy bidirectional index length when the
+        relation was converted and no write has migrated the counter yet.
+        """
+        return self.db().reverse_count_get(self._type, self._id, relation_name)
+
     @classmethod
     def max_id(cls: Type[T]) -> int:
         """Get the maximum ID assigned to entities of this type.
@@ -623,21 +637,61 @@ class Entity:
                     db.reverse_index_delete(self._type, self._id, attr_name)
                 elif isinstance(attr_value, ManyToMany):
                     # Remove self from each related entity's reverse index
+                    # (or decrement its counter for unidirectional relations)
                     related_ids = db.reverse_index_get(self._type, self._id, attr_name)
                     for related_id in related_ids:
                         for type_name in attr_value._get_allowed_types():
                             entity_class = db._entity_types.get(type_name)
                             if entity_class and db.load(type_name, related_id):
-                                db.reverse_index_remove(
-                                    type_name,
-                                    related_id,
-                                    attr_value.reverse_name,
-                                    self._id,
-                                )
+                                if attr_value.unidirectional:
+                                    db.reverse_count_add(
+                                        type_name,
+                                        related_id,
+                                        attr_value.reverse_name,
+                                        -1,
+                                    )
+                                else:
+                                    db.reverse_index_remove(
+                                        type_name,
+                                        related_id,
+                                        attr_value.reverse_name,
+                                        self._id,
+                                    )
                                 break
                     # Delete own index
                     db.reverse_index_delete(self._type, self._id, attr_name)
 
+        # Clean up reverse counters other entity types keep on *this* entity
+        # via unidirectional ManyToMany relations targeting our type. Their
+        # forward indexes may retain a dangling ID (skipped on load); the
+        # counter itself must not outlive us.
+        seen_classes = set()
+        for entity_class in db._entity_types.values():
+            if entity_class in seen_classes or not isinstance(entity_class, type):
+                continue
+            seen_classes.add(entity_class)
+            for cls in reversed(entity_class.__mro__):
+                for attr_name, attr_value in cls.__dict__.items():
+                    if attr_name.startswith("_"):
+                        continue
+                    if (
+                        isinstance(attr_value, ManyToMany)
+                        and attr_value.unidirectional
+                    ):
+                        my_short = (
+                            self._type.split("::")[-1]
+                            if "::" in self._type
+                            else self._type
+                        )
+                        targets = [
+                            t.split("::")[-1] if "::" in t else t
+                            for t in attr_value._get_allowed_types()
+                        ]
+                        if my_short in targets:
+                            db.reverse_count_delete(
+                                self._type, self._id, attr_value.reverse_name
+                            )
+
         db.delete(self._type, self._id)
 
         # Remove from entity registry

{ic_python_db-0.9.0 → ic_python_db-0.10.0}/ic_python_db/properties.py

@@ -526,6 +526,100 @@ class OneToOne(Relation[E]):
             obj._save()
 
 
+class ManyToManyList(list):
+    """List subclass returned by ManyToMany.__get__ that supports .add() and .remove()."""
+
+    def __init__(self, items, owner, prop):
+        super().__init__(items)
+        self._owner = owner
+        self._prop = prop
+
+    def add(self, entity):
+        """Add an entity to this many-to-many relationship."""
+        from .db_engine import Database
+        from .entity import Entity
+
+        if isinstance(entity, (str, int)):
+            resolved = self._prop.resolve_entity(self._owner, entity)
+        elif isinstance(entity, Entity):
+            resolved = entity
+        else:
+            raise TypeError(f"Cannot add {type(entity)} to ManyToMany relation")
+
+        self._prop.validate_entity(resolved)
+        db = Database.get_instance()
+
+        existing = db.reverse_index_get(
+            self._owner._type, self._owner._id, self._prop.name
+        )
+        if resolved._id not in existing:
+            db.reverse_index_add(
+                self._owner._type, self._owner._id, self._prop.name, resolved._id
+            )
+            if self._prop.unidirectional:
+                db.reverse_count_add(
+                    resolved._type, resolved._id, self._prop.reverse_name, 1
+                )
+            else:
+                db.reverse_index_add(
+                    resolved._type,
+                    resolved._id,
+                    self._prop.reverse_name,
+                    self._owner._id,
+                )
+            if not self._owner._do_not_save:
+                self._owner._save()
+        self.append(resolved)
+
+    def discard(self, entity):
+        """Remove an entity from this many-to-many relationship (no error if absent)."""
+        from .db_engine import Database
+        from .entity import Entity
+
+        if isinstance(entity, Entity):
+            entity_id = entity._id
+            entity_type = entity._type
+        else:
+            entity_id = str(entity)
+            entity_type = None
+
+        db = Database.get_instance()
+        was_present = entity_id in db.reverse_index_get(
+            self._owner._type, self._owner._id, self._prop.name
+        )
+        db.reverse_index_remove(
+            self._owner._type, self._owner._id, self._prop.name, entity_id
+        )
+        if self._prop.unidirectional:
+            if was_present:
+                if entity_type is None:
+                    for type_name in self._prop._get_allowed_types():
+                        if db.load(type_name, entity_id):
+                            entity_type = type_name
+                            break
+                if entity_type:
+                    db.reverse_count_add(
+                        entity_type, entity_id, self._prop.reverse_name, -1
+                    )
+        elif entity_type:
+            db.reverse_index_remove(
+                entity_type, entity_id, self._prop.reverse_name, self._owner._id
+            )
+        else:
+            for type_name in self._prop._get_allowed_types():
+                db.reverse_index_remove(
+                    type_name, entity_id, self._prop.reverse_name, self._owner._id
+                )
+
+        self[:] = [e for e in self if getattr(e, "_id", None) != entity_id]
+        if not self._owner._do_not_save:
+            self._owner._save()
+
+    def remove(self, entity):
+        """Remove an entity from this many-to-many relationship."""
+        self.discard(entity)
+
+
 class ManyToMany(Relation[E]):
     """Many-to-many relationship with bidirectional reverse indexes.
 
@@ -537,10 +631,32 @@ class ManyToMany(Relation[E]):
 
         class Course(Entity):
             students = ManyToMany('Student', 'courses')
+
+    Unidirectional mode (``unidirectional=True``) is for relations whose
+    reverse side would fan out to huge cardinalities (e.g. a profile shared
+    by 100k users). Declare it on the owning (small) side only — the target
+    entity declares nothing. The owning side keeps its normal index, while
+    the target side maintains only an O(1) counter instead of an ID array
+    that would be rewritten on every add/remove:
+
+        class User(Entity):
+            profiles = ManyToMany('UserProfile', 'users', unidirectional=True)
+
+        profile.reverse_count('users')   # number of users holding it
+
+    The counter lazily migrates from a legacy bidirectional index on first
+    write (the old ID array is dropped). Reverse *listing* is intentionally
+    unsupported — scan the owning entities instead.
     """
 
-    def __init__(self, entity_types: Union[str, List[str]], reverse_name: str):
+    def __init__(
+        self,
+        entity_types: Union[str, List[str]],
+        reverse_name: str,
+        unidirectional: bool = False,
+    ):
         super().__init__(entity_types, reverse_name)
+        self.unidirectional = unidirectional
 
     def __get__(
         self, obj: object, objtype: Optional[type] = None
@@ -562,7 +678,7 @@ class ManyToMany(Relation[E]):
                     if entity:
                         entities.append(entity)
                         break
-        return entities  # type: ignore[return-value]
+        return ManyToManyList(entities, obj, self)  # type: ignore[return-value]
 
     def __set__(self, obj, values):
         from .db_engine import Database
@@ -592,15 +708,28 @@ class ManyToMany(Relation[E]):
             for type_name in self._get_allowed_types():
                 entity_class = db._entity_types.get(type_name)
                 if entity_class and db.load(type_name, old_id):
-                    db.reverse_index_remove(
-                        type_name, old_id, self.reverse_name, obj._id
-                    )
+                    if self.unidirectional:
+                        db.reverse_count_add(type_name, old_id, self.reverse_name, -1)
+                    else:
+                        db.reverse_index_remove(
+                            type_name, old_id, self.reverse_name, obj._id
+                        )
                     break
 
-        # Add new relations to both sides' indexes
+        # Add new relations to both sides' indexes (dedupe: the forward index
+        # ignores repeats, so the reverse side must too)
+        seen_ids = set()
         for entity in resolved:
+            if entity._id in seen_ids:
+                continue
+            seen_ids.add(entity._id)
             db.reverse_index_add(obj._type, obj._id, self.name, entity._id)
-            db.reverse_index_add(entity._type, entity._id, self.reverse_name, obj._id)
+            if self.unidirectional:
+                db.reverse_count_add(entity._type, entity._id, self.reverse_name, 1)
+            else:
+                db.reverse_index_add(
+                    entity._type, entity._id, self.reverse_name, obj._id
+                )
 
         if not obj._do_not_save:
             obj._save()

{ic_python_db-0.9.0 → ic_python_db-0.10.0}/ic_python_db/schema.py

@@ -73,6 +73,8 @@ def build_field_descriptor(prop) -> Dict[str, Any]:
         if prop.reverse_name:
             desc["inverse"] = prop.reverse_name
         desc["many"] = prop.many
+        if isinstance(prop, ManyToMany) and prop.unidirectional:
+            desc["unidirectional"] = True
         return desc
 
     desc["kind"] = "property"

{ic_python_db-0.9.0 → ic_python_db-0.10.0/ic_python_db.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ic-python-db
-Version: 0.9.0
+Version: 0.10.0
 Summary: A lightweight key-value database written in Python, intended for use on the Internet Computer (IC)
 Home-page: https://github.com/smart-social-contracts/ic-python-db
 Author: Smart Social Contracts

{ic_python_db-0.9.0 → ic_python_db-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ic-python-db"
-version = "0.9.0"
+version = "0.10.0"
 description = "A lightweight key-value database written in Python, intended for use on the Internet Computer (IC)"
 readme = "README.md"
 authors = [

{ic_python_db-0.9.0 → ic_python_db-0.10.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="ic-python-db",
-    version="0.9.0",
+    version="0.10.0",
     author="Smart Social Contracts",
     author_email="smartsocialcontracts@gmail.com",
     description="A lightweight key-value database with entity relationships and audit logging",