Merge pull request #86 from CaliLuke/feat/driver-injection

feat: Driver injection, FunctionQuery, and generator fixes

Author: ds1sqe

README.md

@@ -23,7 +23,7 @@ type-bridge provides Pythonic/TypeScript abstractions over TypeDB's native TypeQ
 
 | Package | Version | Install |
 |---------|---------|---------|
-| [Python](./packages/python) | 1.1.0 | `pip install type-bridge` |
+| [Python](./packages/python) | 1.2.2 | `pip install type-bridge` |
 | [TypeScript](./packages/typescript) | 0.1.0 | `npm install @type-bridge/type-bridge` |
 
 ## Quick Start

packages/python/docs/api/crud.md

@@ -1381,6 +1381,87 @@ count = user_manager.filter(Age.gt(Age(65))).delete()  # Returns count
 # Use filter().delete() instead for filter-based deletion
 ```
 
+## Database Configuration
+
+### Basic Connection
+
+```python
+from type_bridge import Database
+
+# Default connection
+db = Database()  # localhost:1729, database="typedb"
+
+# Custom connection
+db = Database(
+    address="192.168.1.100:1729",
+    database="mydb",
+    username="admin",
+    password="secret"
+)
+db.connect()
+
+# Context manager (auto-connects and closes)
+with Database(database="mydb") as db:
+    person_manager = Person.manager(db)
+    # ... operations ...
+```
+
+### Driver Injection
+
+For advanced use cases, you can inject an external `Driver` instance instead of having `Database` create one internally. This enables:
+
+- **Connection sharing** across multiple `Database` instances
+- **Resource pooling** with custom driver management
+- **Easier testing** via mock driver injection
+
+```python
+from typedb.driver import TypeDB, Credentials, DriverOptions
+
+# Create a shared driver
+driver = TypeDB.driver(
+    "localhost:1729",
+    Credentials("admin", "password"),
+    DriverOptions()
+)
+
+# Multiple databases share one connection
+db1 = Database(database="project_a", driver=driver)
+db2 = Database(database="project_b", driver=driver)
+
+# Use both databases
+with db1.transaction("write") as tx:
+    Person.manager(tx).insert(alice)
+
+with db2.transaction("read") as tx:
+    results = Artifact.manager(tx).all()
+
+# Close databases (only clears references, doesn't close driver)
+db1.close()
+db2.close()
+
+# Close driver when done (caller's responsibility)
+driver.close()
+```
+
+**Ownership semantics:**
+- `driver=None` (default): `Database` creates and owns the driver, `close()` closes it
+- `driver=<Driver>`: `Database` uses but doesn't own it, `close()` only clears the reference
+
+### Testing with Mock Driver
+
+```python
+from unittest.mock import MagicMock
+
+def test_database_operations():
+    mock_driver = MagicMock()
+    mock_driver.databases.contains.return_value = True
+
+    db = Database(database="test_db", driver=mock_driver)
+
+    assert db.database_exists() is True
+    mock_driver.databases.contains.assert_called_with("test_db")
+```
+
 ## See Also
 
 - [Entities](entities.md) - Entity definition

packages/python/docs/api/generator.md

@@ -243,8 +243,8 @@ relation authoring sub contribution,
 relation review,
     relates reviewer,
     relates reviewed,
-    owns score,
-    owns timestamp;
+    owns score @card(1),      // Required attribute
+    owns timestamp;           // Optional (no @card = 0..1)
 
 // Cardinality constraints on roles
 relation social-relation @abstract,
@@ -277,8 +277,8 @@ class Authoring(Contribution):
 
 class Review(Relation):
     flags = TypeFlags(name="review")
-    score: attributes.Score
-    timestamp: attributes.Timestamp
+    score: attributes.Score                      # Required (@card(1))
+    timestamp: attributes.Timestamp | None = None  # Optional (no @card)
     reviewer: Role[entities.User] = Role("reviewer", entities.User)
     reviewed: Role[entities.Publication] = Role("reviewed", entities.Publication)
 ```
@@ -375,6 +375,8 @@ relation friendship,
 
 ## Cardinality Mapping
 
+The following cardinality rules apply to attributes on both **entities** and **relations**:
+
 | TypeQL | Python Type | Default |
 |--------|-------------|---------|
 | `@card(1)` or `@card(1..1)` | `Type` | Required |
@@ -385,6 +387,8 @@ relation friendship,
 | `@key` | `Type = Flag(Key)` | Key (implies required) |
 | `@unique` | `Type = Flag(Unique)` | Unique (implies required) |
 
+**Inheritance:** Child types inherit cardinality constraints from parent types. A child can override inherited constraints by redeclaring the attribute with a different `@card`.
+
 ## Comments
 
 The parser supports both `#` (shell-style) and `//` (C-style) comments:

packages/python/tests/unit/generator/test_generator.py

@@ -255,6 +255,152 @@ def test_relation_with_owns(self) -> None:
 
         assert "since: attributes.Since" in source
 
+    def test_relation_optional_attribute(self) -> None:
+        """Render relation with optional attribute (no @card constraint)."""
+        schema = parse_tql_schema("""
+            define
+            attribute sequence_index, value integer;
+            entity milestone,
+                plays task_grouping:milestone;
+            entity task,
+                plays task_grouping:task;
+
+            define
+            relation task_grouping,
+                relates milestone @card(1),
+                relates task @card(0..),
+                owns sequence_index;
+        """)
+        attr_names = build_class_name_map(schema.attributes)
+        entity_names = build_class_name_map(schema.entities)
+        relation_names = build_class_name_map(schema.relations)
+        source = render_relations(schema, attr_names, entity_names, relation_names)
+
+        # Without @card constraint, attribute should be optional
+        assert "sequence_index: attributes.Sequence_index | None = None" in source
+
+    def test_relation_required_attribute(self) -> None:
+        """Render relation with required attribute (@card(1))."""
+        schema = parse_tql_schema("""
+            define
+            attribute weight, value double;
+            entity node,
+                plays edge:endpoint;
+
+            define
+            relation edge,
+                relates endpoint,
+                owns weight @card(1);
+        """)
+        attr_names = build_class_name_map(schema.attributes)
+        entity_names = build_class_name_map(schema.entities)
+        relation_names = build_class_name_map(schema.relations)
+        source = render_relations(schema, attr_names, entity_names, relation_names)
+
+        # With @card(1), attribute should be required (no | None = None)
+        assert "weight: attributes.Weight" in source
+        assert "weight: attributes.Weight | None" not in source
+
+    def test_relation_key_attribute(self) -> None:
+        """Render relation with @key attribute."""
+        schema = parse_tql_schema("""
+            define
+            attribute edge_id, value string;
+            entity node,
+                plays connection:endpoint;
+
+            define
+            relation connection,
+                relates endpoint,
+                owns edge_id @key;
+        """)
+        attr_names = build_class_name_map(schema.attributes)
+        entity_names = build_class_name_map(schema.entities)
+        relation_names = build_class_name_map(schema.relations)
+        source = render_relations(schema, attr_names, entity_names, relation_names)
+
+        # With @key, attribute should use Flag(Key)
+        assert "edge_id: attributes.Edge_id = Flag(Key)" in source
+        assert "from type_bridge import" in source
+        assert "Flag" in source
+        assert "Key" in source
+
+    def test_relation_multi_value_attribute(self) -> None:
+        """Render relation with multi-value attribute (@card(0..))."""
+        schema = parse_tql_schema("""
+            define
+            attribute tag, value string;
+            entity item,
+                plays tagging:item;
+
+            define
+            relation tagging,
+                relates item,
+                owns tag @card(0..);
+        """)
+        attr_names = build_class_name_map(schema.attributes)
+        entity_names = build_class_name_map(schema.entities)
+        relation_names = build_class_name_map(schema.relations)
+        source = render_relations(schema, attr_names, entity_names, relation_names)
+
+        # With @card(0..), attribute should be a list
+        assert "list[attributes.Tag]" in source
+        assert "Card" in source
+
+    def test_relation_inherits_key_from_parent(self) -> None:
+        """Child relation inherits @key constraint from parent."""
+        schema = parse_tql_schema("""
+            define
+            attribute rel_id, value string;
+            entity node,
+                plays base_rel:endpoint,
+                plays child_rel:endpoint;
+
+            define
+            relation base_rel @abstract,
+                relates endpoint,
+                owns rel_id @key;
+
+            define
+            relation child_rel sub base_rel;
+        """)
+        attr_names = build_class_name_map(schema.attributes)
+        entity_names = build_class_name_map(schema.entities)
+        relation_names = build_class_name_map(schema.relations)
+        source = render_relations(schema, attr_names, entity_names, relation_names)
+
+        # Child should inherit @key from parent
+        assert "class Child_rel(Base_rel):" in source
+        assert "rel_id: attributes.Rel_id = Flag(Key)" in source
+
+    def test_relation_inherits_cardinality_from_parent(self) -> None:
+        """Child relation inherits cardinality constraint from parent."""
+        schema = parse_tql_schema("""
+            define
+            attribute weight, value double;
+            entity node,
+                plays base_edge:endpoint,
+                plays weighted_edge:endpoint;
+
+            define
+            relation base_edge @abstract,
+                relates endpoint,
+                owns weight @card(1);
+
+            define
+            relation weighted_edge sub base_edge;
+        """)
+        attr_names = build_class_name_map(schema.attributes)
+        entity_names = build_class_name_map(schema.entities)
+        relation_names = build_class_name_map(schema.relations)
+        source = render_relations(schema, attr_names, entity_names, relation_names)
+
+        # Child should inherit required cardinality from parent
+        # The parent declares weight as required, child should not have it optional
+        assert "class Weighted_edge(Base_edge):" in source
+        # weight should NOT be in child since it's inherited from parent
+        # But if it were re-declared, it should still be required
+
 
 class TestComingSoonAnnotationStubs:
     """Tests for coming-soon annotation stubs (TODO comments in generated code)."""

packages/python/tests/unit/session/test_session_unit.py

@@ -275,3 +275,104 @@ def test_connection_accepts_transaction_context(self):
         # Type checking - Connection should accept TransactionContext
         conn: Connection = ctx
         assert isinstance(conn, TransactionContext)
+
+
+class TestDriverInjection:
+    """Tests for external driver injection feature (issue #85)."""
+
+    def test_driver_none_by_default(self):
+        """Database should have no driver by default."""
+        db = Database()
+        assert db._driver is None
+        assert db._owns_driver is True  # Will own any driver it creates
+
+    def test_injected_driver_stored(self):
+        """Database should store injected driver."""
+        mock_driver = MagicMock()
+        db = Database(driver=mock_driver)
+        assert db._driver is mock_driver
+        assert db._owns_driver is False  # Does not own injected driver
+
+    def test_connect_skips_when_driver_injected(self):
+        """connect() should be a no-op when driver is injected."""
+        mock_driver = MagicMock()
+        db = Database(driver=mock_driver)
+
+        # connect() should not modify the driver
+        db.connect()
+        assert db._driver is mock_driver
+        assert db._owns_driver is False
+
+    def test_close_clears_reference_but_does_not_close_injected_driver(self):
+        """close() should clear reference but not close injected driver."""
+        mock_driver = MagicMock()
+        db = Database(driver=mock_driver)
+
+        db.close()
+
+        # Reference should be cleared
+        assert db._driver is None
+        # But close() should NOT have been called on the driver
+        mock_driver.close.assert_not_called()
+
+    def test_close_closes_owned_driver(self):
+        """close() should close driver when Database owns it."""
+        mock_driver = MagicMock()
+        db = Database()
+        # Simulate connect() creating a driver
+        db._driver = mock_driver
+        db._owns_driver = True
+
+        db.close()
+
+        # Driver should be closed
+        mock_driver.close.assert_called_once()
+        assert db._driver is None
+
+    def test_driver_property_returns_injected_driver(self):
+        """driver property should return injected driver without connecting."""
+        mock_driver = MagicMock()
+        db = Database(driver=mock_driver)
+
+        # Accessing driver property should return the injected driver
+        assert db.driver is mock_driver
+        # connect() should not have been called (no new driver created)
+        assert db._owns_driver is False
+
+    def test_context_manager_with_injected_driver(self):
+        """Context manager should work with injected driver."""
+        mock_driver = MagicMock()
+
+        with Database(driver=mock_driver) as db:
+            assert db._driver is mock_driver
+
+        # After exit, reference cleared but driver not closed
+        assert db._driver is None
+        mock_driver.close.assert_not_called()
+
+    def test_multiple_databases_share_driver(self):
+        """Multiple Database instances can share the same driver."""
+        mock_driver = MagicMock()
+
+        db1 = Database(database="db1", driver=mock_driver)
+        db2 = Database(database="db2", driver=mock_driver)
+
+        assert db1._driver is mock_driver
+        assert db2._driver is mock_driver
+        assert db1._owns_driver is False
+        assert db2._owns_driver is False
+
+        # Close both - driver should NOT be closed
+        db1.close()
+        db2.close()
+        mock_driver.close.assert_not_called()
+
+    def test_database_exists_with_injected_driver(self):
+        """database_exists() should work with injected driver."""
+        mock_driver = MagicMock()
+        mock_driver.databases.contains.return_value = True
+
+        db = Database(database="test_db", driver=mock_driver)
+
+        assert db.database_exists() is True
+        mock_driver.databases.contains.assert_called_with("test_db")