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

[uesleilima]

Summary

Two enhancements to the Python driver's public API:

1. Public API for connection pooling / external connection management (#2369)

The Age class creates and owns a single connection internally. There's no supported way to register agtype adapters on externally-managed connections (e.g., from psycopg_pool.ConnectionPool).

Solution: Add configure_connection(conn, graph_name=None, skip_load=False) that:

• Sets search_path to ag_catalog
• Fetches agtype OIDs and registers AgeLoader
• Optionally checks/creates the graph
• Does not call LOAD 'age' by default (suitable for managed PostgreSQL services)

Also explicitly exports AgeLoader, ClientCursor, and configure_connection as public symbols in age/__init__.py, eliminating the need for # type: ignore when accessing driver internals.

Usage with connection pool:

from age import configure_connection, ClientCursor
from psycopg_pool import ConnectionPool

pool = ConnectionPool(
    conninfo="host=localhost dbname=mydb",
    configure=configure_connection,
    kwargs={"cursor_factory": ClientCursor},
)

2. Vertex/Edge/Path model classes dict/JSON conversion (#2371)

The driver's model classes lack conversion to plain Python data structures, forcing every consumer to write custom normalization.

Solution: Add to_dict() methods:

• Vertex.to_dict() → {"id", "label", "properties"}
• Edge.to_dict() → {"id", "label", "start_id", "end_id", "properties"}
• Path.to_dict() → list of to_dict() results

All return plain dicts/lists that work directly with json.dumps().

Tests

Added 8 new unit tests (no DB required):

• TestModelToDict (5 tests): vertex, edge, path to_dict(), empty properties, JSON serializability
• TestPublicImports (3 tests): verify configure_connection, AgeLoader, ClientCursor are importable

Closes

• Closes Python driver: No public API for connection pooling / external connection management #2369
• Closes Python driver: Vertex/Edge/Path model classes should provide dict/JSON serialization #2371

[tcolo]

@uesleilima thanks a lot for your patch. I let Claude code review run over the patch. Can you please address the issues ?

Code Review

Summary

Adds two useful features to the Python driver: a configure_connection() function for externally-managed connection pools, and to_dict() serialization methods on graph model classes. The overall approach is sound and the test coverage is solid. A few correctness and consistency issues are worth addressing before merging.

---

🔴 Critical Issues

#	File	Issue
1	age/age.py	TypeInfo.fetch() is called outside the with conn.cursor() block. In setUpAge it lives inside the block. If the connection is in autocommit=False mode the SET search_path change may not be visible to TypeInfo.fetch depending on transaction isolation. Move TypeInfo.fetch inside the cursor block (or at least after conn.commit()).
2	age/age.py	load_from_plugins=True without load=True is silently ignored. A caller who passes load_from_plugins=True expecting plugins-path loading will get no LOAD at all and no warning. Raise a ValueError or at least emit a warning.

---

🟡 Suggestions

#	File	Suggestion	Category
1	age/age.py	Add type annotations consistent with the rest of the file (conn: psycopg.connection, graph_name: Optional[str] = None, etc.).	Maintainability
2	age/age.py	Consider adding __all__ to age.py to cleanly control the public surface instead of double-importing in __init__.py.	Maintainability
3	age/models.py	Path.to_dict() falls back to else e for non-AGObj entities — this may return non-JSON-serializable objects. Add a comment or use str(e) as a safe fallback.	Correctness
4	age/models.py	dict(self.properties) is a shallow copy. Nested mutable values will still be shared references. Document this or use copy.deepcopy if full JSON safety is the goal.	Correctness
5	test_age_py.py	Missing test: AgeNotSet is raised when TypeInfo.fetch returns None. This is a key code path in configure_connection with no coverage.	Testing
6	test_age_py.py	No test asserting that load_from_plugins=True, load=False does not execute any LOAD. Ties directly to the silent-ignore issue above.	Testing
7	test_age_py.py	Asserting "LOAD" not in str(call_args) is fragile — depends on Python's internal repr. Prefer explicit assert_called_with(...) checks.	Testing

---

✅ What Looks Good

• The configure_connection docstring is clear and explicitly explains the managed-PostgreSQL use case (Azure, AWS RDS) — genuinely useful.
• Default load=False is the right choice for a connection-pool scenario and the rationale is well communicated.
• to_dict() implementations are clean, simple, and consistent across Vertex, Edge, and Path.
• TestConfigureConnection correctly uses unittest.mock to test without a live database.
• test_registers_agtype_adapters asserts adapter registration by OID — precise and correct.
• TestPublicImports is a lightweight but effective guard against accidental API regressions.

---

Verdict: Request Changes — The silent load_from_plugins ignore and the TypeInfo.fetch cursor-scope issue are real correctness risks worth fixing. The feature direction is right and most of the code is clean.

[tcolo]

please check the comment I made

[Copilot]

Pull request overview

Adds new public APIs to the Python driver to better support external connection management (e.g., pooled connections) and to make model objects easier to serialize/consume in downstream apps.

Changes:

• Introduces configure_connection() as a public API to configure an existing psycopg connection for AGE (search_path, agtype loaders, optional LOAD, optional graph check).
• Adds to_dict() helpers to Vertex, Edge, and Path for plain-Python dict/list conversion.
• Exports AgeLoader, ClientCursor, and configure_connection from age/__init__.py and adds accompanying tests.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
drivers/python/age/age.py	Adds the new configure_connection() API for externally-managed connections.
drivers/python/age/models.py	Adds to_dict() methods for Path, Vertex, and Edge.
drivers/python/age/init.py	Exposes new public symbols at the package top-level.
drivers/python/test_age_py.py	Adds unit tests for to_dict() and configure_connection() and importability checks.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[uesleilima]

All review feedback has been addressed:

tcolo's review:

• ✅ Moved TypeInfo.fetch() inside the cursor block so search_path change is visible regardless of transaction isolation.
• ✅ ValueError raised when load_from_plugins=True but load=False.
• ✅ Added type annotations to configure_connection signature.
• ✅ Documented shallow-copy semantics in Vertex.to_dict() and Edge.to_dict().
• ✅ Added test for AgeNotSet when TypeInfo.fetch returns None.
• ✅ Replaced fragile string assertions with assert_called_with / assert_any_call.

Copilot review:

• ✅ Fixed Path.to_dict(): JSON-native types (dict, list, str, int, float, bool, None) now pass through unchanged; str() is only used as a safety net for non-serializable objects. Also handles entities=None safely.
• ✅ Added TestModelToDict, TestPublicImports, TestConfigureConnection to the __main__ suite so they run via direct script execution.
• ⚠️ configure_connection() duplicating setUpAge(): Valid observation but refactoring scope is too large for this PR. Happy to address in a follow-up.
• ⚠️ PR description mentions skip_load but API uses load: This is intentional — configure_connection(load=False) uses positive opt-in semantics (load=True to enable), unlike setUpAge(skip_load=True) which uses opt-out. The distinction is documented in the docstring.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

configure_connection() uses PEP 604 union syntax (str | None) in its public signature. This is a syntax error on Python 3.9, but the package metadata declares requires-python = ">=3.9" (drivers/python/pyproject.toml:25). Either adjust the type hints to be 3.9-compatible (e.g., Optional[str] / Union[...]) or bump the declared minimum Python version to 3.10+ so users on 3.9 don’t break at import time.

[uesleilima]

Fixed in 1d92c31: graph_name is now Optional[str] with from typing import Optional so the module parses on Python 3.9 while keeping requires-python >= 3.9. Also aligned SET search_path with "$user" and updated tests.

[jrgemignani]

@uesleilima Please see Copilot's last one.