API docs: result transformer must be idempotent (#895)

Add note to the docs that `Driver.execute_query`'s result_transformer_ argument
must be an idempotent function as the driver might retry the underlying
transaction.

Author: robsdedude

docs/source/api.rst

@@ -273,6 +273,15 @@ Closing a driver will immediately shut down all connections in the pool.
                 The transformer function must **not** return the
                 :class:`neo4j.Result` itself.
 
+
+            .. warning::
+
+                N.B. the driver might retry the underlying transaction so the
+                transformer might get invoked more than once (with different
+                :class:`neo4j.Result` objects).
+                Therefore, it needs to be idempotent (i.e., have the same
+                effect, regardless if called once or many times).
+
             Example transformer that checks that exactly one record is in the
             result stream, then returns the record and the result summary::
 

docs/source/async_api.rst

@@ -255,6 +255,14 @@ Closing a driver will immediately shut down all connections in the pool.
                 The transformer function must **not** return the
                 :class:`neo4j.AsyncResult` itself.
 
+            .. warning::
+
+                N.B. the driver might retry the underlying transaction so the
+                transformer might get invoked more than once (with different
+                :class:`neo4j.AsyncResult` objects).
+                Therefore, it needs to be idempotent (i.e., have the same
+                effect, regardless if called once or many times).
+
             Example transformer that checks that exactly one record is in the
             result stream, then returns the record and the result summary::
 

src/neo4j/_async/driver.py

@@ -686,6 +686,14 @@ async def example(driver: neo4j.AsyncDriver) -> int:
                 The transformer function must **not** return the
                 :class:`neo4j.AsyncResult` itself.
 
+            .. warning::
+
+                N.B. the driver might retry the underlying transaction so the
+                transformer might get invoked more than once (with different
+                :class:`neo4j.AsyncResult` objects).
+                Therefore, it needs to be idempotent (i.e., have the same
+                effect, regardless if called once or many times).
+
             Example transformer that checks that exactly one record is in the
             result stream, then returns the record and the result summary::
 

src/neo4j/_sync/driver.py

@@ -684,6 +684,14 @@ def example(driver: neo4j.Driver) -> int:
                 The transformer function must **not** return the
                 :class:`neo4j.Result` itself.
 
+            .. warning::
+
+                N.B. the driver might retry the underlying transaction so the
+                transformer might get invoked more than once (with different
+                :class:`neo4j.Result` objects).
+                Therefore, it needs to be idempotent (i.e., have the same
+                effect, regardless if called once or many times).
+
             Example transformer that checks that exactly one record is in the
             result stream, then returns the record and the result summary::