feat(python-driver): add public API for connection pooling and model dict conversion (#2374)

* feat(python-driver): add public API for connection pooling and model dict conversion

Add two enhancements to the Python driver's public API:

1. Add configure_connection() function that registers AGE agtype adapters
   on an existing psycopg connection without creating a new one. This
   enables use with external connection pools (e.g. psycopg_pool) and
   managed PostgreSQL services where LOAD 'age' may be restricted.
   Also explicitly export AgeLoader and ClientCursor as public symbols
   in age/__init__.py. (#2369)

2. Add to_dict() methods to Vertex, Edge, and Path model classes for
   conversion to plain Python dicts. This enables direct JSON
   serialization with json.dumps() without requiring custom conversion
   logic. (#2371)

   - Vertex.to_dict() returns {id, label, properties}
   - Edge.to_dict() returns {id, label, start_id, end_id, properties}
   - Path.to_dict() returns a list of to_dict() results

Closes #2369
Closes #2371

* Fix configure_connection: correct parameter semantics, add load_from_plugins

- Replace confusing `skip_load` (double-negative) with `load` (positive
  boolean, default False). The default now correctly matches the intent:
  no LOAD by default for connection pool / managed PostgreSQL use cases.
- Add `load_from_plugins` parameter for parity with setUpAge().
- Fix docstring to accurately describe parameter behavior.
- Add 6 unit tests for configure_connection covering: default no-load,
  explicit load, load_from_plugins, search_path always set, adapter
  registration, and graph_name check delegation.

Made-with: Cursor

* Address review feedback for configure_connection and to_dict

- Move TypeInfo.fetch() inside cursor block so search_path change is
  visible regardless of transaction isolation mode
- Raise ValueError when load_from_plugins=True but load=False
- Add type annotations to configure_connection signature
- Document shallow-copy semantics in Vertex/Edge to_dict()
- Path.to_dict() uses str() fallback for non-AGObj entities to
  guarantee JSON-serializable output
- Add test for AgeNotSet when TypeInfo.fetch returns None
- Add test for load_from_plugins=True without load=True
- Replace fragile string assertions with assert_called_with/assert_any_call

Made-with: Cursor

* Fix Path.to_dict() to preserve JSON-native types, add tests to suite

- Path.to_dict(): leave dict/list/str/int/float/bool/None unchanged
  instead of converting to str(); handle entities=None safely
- Add TestModelToDict, TestPublicImports, TestConfigureConnection to
  the __main__ suite so they run via direct script execution

Made-with: Cursor

* fix(python-driver): Python 3.9-safe hints and correct $user in search_path

- Use Optional[str] for configure_connection graph_name (PEP 604 unions are
  invalid on Python 3.9).
- Import Any/Optional from typing for annotations.
- Quote $user in SET search_path; align unit test expectations.

Made-with: Cursor

* test(python-driver): add configure_connection + to_dict integration test

Existing tests for the new public API are unit-only:
- TestConfigureConnection mocks the psycopg connection, so it never
  proves that AgeLoader actually registers against real agtype OIDs.
- TestModelToDict hand-constructs Vertex/Edge/Path via kwargs, so it
  never serialises objects produced by the ANTLR parser.

Add a single TestAgeBasic.testConfigureConnection that:
- opens a raw psycopg connection (bypassing age.connect()),
- calls configure_connection(..., load=True) on it,
- runs a Cypher CREATE/RETURN through the configured connection,
- asserts the returned values are real Vertex/Edge instances and that
  their to_dict() output is JSON-serialisable with the expected
  label/start_id/end_id/properties shape,
- repeats the round-trip for a Path returned by MATCH.

This is the smallest test that proves the configure_connection +
to_dict pipeline works end-to-end against a live AGE database.

Made-with: Cursor

Author: uesleilima

drivers/python/age/__init__.py

@@ -16,6 +16,7 @@
 import psycopg.conninfo as conninfo
 from . import age
 from .age import *
+from .age import AgeLoader, ClientCursor, configure_connection
 from .models import *
 from .builder import ResultHandler, DummyResultHandler, parseAgeValue, newResultHandler
 from . import VERSION 

drivers/python/age/age.py

@@ -14,6 +14,8 @@
 # under the License.
 
 import re
+from typing import Any, Optional
+
 import psycopg
 from psycopg.types import TypeInfo
 from psycopg import sql
@@ -170,6 +172,71 @@ def setUpAge(conn:psycopg.connection, graphName:str, load_from_plugins:bool=Fals
         if graphName != None:
             checkGraphCreated(conn, graphName)
 
+
+def configure_connection(
+    conn: psycopg.connection,
+    graph_name: Optional[str] = None,
+    load: bool = False,
+    load_from_plugins: bool = False,
+) -> None:
+    """Register AGE agtype adapters on an existing connection.
+
+    This enables use of AGE with externally-managed connections, such as
+    those from psycopg_pool.ConnectionPool.  By default the function does
+    **not** execute ``LOAD 'age'``, making it safe for managed PostgreSQL
+    services (Azure, AWS RDS) where the extension is pre-loaded via
+    ``shared_preload_libraries``.
+
+    Performs:
+    - ``SET search_path`` to include ``ag_catalog``
+    - Fetches agtype OIDs and registers ``AgeLoader``
+    - Optionally loads the AGE extension (``load=True``)
+    - Optionally checks/creates the graph
+
+    Args:
+        conn: An existing psycopg connection.
+        graph_name: Optional graph name to check/create.
+        load: If True, execute ``LOAD 'age'`` (or the plugins path).
+            Default False — suitable for environments where AGE is
+            already loaded.
+        load_from_plugins: If True (and ``load=True``), use
+            ``LOAD '$libdir/plugins/age'`` instead of ``LOAD 'age'``.
+
+    Raises:
+        ValueError: If ``load_from_plugins=True`` but ``load=False``.
+        AgeNotSet: If the agtype type is not found in the database.
+    """
+    if load_from_plugins and not load:
+        raise ValueError(
+            "load_from_plugins=True requires load=True. "
+            "Set load=True to enable extension loading."
+        )
+
+    with conn.cursor() as cursor:
+        if load:
+            if load_from_plugins:
+                cursor.execute("LOAD '$libdir/plugins/age';")
+            else:
+                cursor.execute("LOAD 'age';")
+
+        cursor.execute('SET search_path = ag_catalog, "$user", public;')
+
+        ag_info = TypeInfo.fetch(conn, 'agtype')
+
+    if not ag_info:
+        raise AgeNotSet(
+            "AGE agtype type not found. Ensure the AGE extension is "
+            "installed and loaded in the current database. "
+            "Run CREATE EXTENSION age; first."
+        )
+
+    conn.adapters.register_loader(ag_info.oid, AgeLoader)
+    conn.adapters.register_loader(ag_info.array_oid, AgeLoader)
+
+    if graph_name is not None:
+        checkGraphCreated(conn, graph_name)
+
+
 # Create the graph, if it does not exist
 def checkGraphCreated(conn:psycopg.connection, graphName:str):
     validate_graph_name(graphName)

drivers/python/age/models.py

@@ -118,6 +118,20 @@ def toJson(self) -> str:
 
         return buf.getvalue()
 
+    def to_dict(self) -> list:
+        # AGObj elements are recursively converted; JSON-native types
+        # (dict, list, str, int, float, bool, None) pass through unchanged.
+        # Non-serializable objects fall back to str() as a safety net.
+        result = []
+        for e in (self.entities or []):
+            if isinstance(e, AGObj):
+                result.append(e.to_dict())
+            elif isinstance(e, (dict, list, str, int, float, bool, type(None))):
+                result.append(e)
+            else:
+                result.append(str(e))
+        return result
+
 
 
 
@@ -146,6 +160,18 @@ def __str__(self) -> str:
     def __repr__(self) -> str:
         return self.toString()
 
+    def to_dict(self) -> dict:
+        """Return a plain dict suitable for JSON serialization.
+
+        Properties are shallow-copied; nested mutable values will share
+        references with the original Vertex.
+        """
+        return {
+            "id": self.id,
+            "label": self.label,
+            "properties": dict(self.properties) if self.properties else {},
+        }
+
     def toString(self) -> str: 
         return nodeToString(self)
 
@@ -186,6 +212,20 @@ def __str__(self) -> str:
     def __repr__(self) -> str:
         return self.toString()
 
+    def to_dict(self) -> dict:
+        """Return a plain dict suitable for JSON serialization.
+
+        Properties are shallow-copied; nested mutable values will share
+        references with the original Edge.
+        """
+        return {
+            "id": self.id,
+            "label": self.label,
+            "start_id": self.start_id,
+            "end_id": self.end_id,
+            "properties": dict(self.properties) if self.properties else {},
+        }
+
     def extraStrFormat(node, buf):
         if node.start_id != None:
             buf.write(", start_id:")