From 3c1223e5f457c27788442722e067f89aa721fee5 Mon Sep 17 00:00:00 2001 From: Rouven Bauer Date: Thu, 18 Aug 2022 09:02:13 +0200 Subject: [PATCH 1/2] Improve doc string around tx functions `session.read_transaction` and `session.write_transaction` were slightly wrong about the tx class passed to the tx function. Furthermore, they are now more explicit about the idempotency required from tx funcs. --- neo4j/_async/work/session.py | 27 ++++++++++++++------------- neo4j/_sync/work/session.py | 27 ++++++++++++++------------- 2 files changed, 28 insertions(+), 26 deletions(-) diff --git a/neo4j/_async/work/session.py b/neo4j/_async/work/session.py index 283aa23cd..dc3b18a36 100644 --- a/neo4j/_async/work/session.py +++ b/neo4j/_async/work/session.py @@ -543,11 +543,11 @@ async def read_transaction( This does not necessarily imply access control, see the session configuration option :ref:`default-access-mode-ref`. - This transaction will automatically be committed unless an exception is thrown during query execution or by the user code. - Note, that this function perform retries and that the supplied `transaction_function` might get invoked more than once. - - Managed transactions should not generally be explicitly committed - (via ``await tx.commit()``). + This transaction will automatically be committed when the function + returns, unless an exception is thrown during query execution or by + the user code. Note, that this function performs retries and that the + supplied `transaction_function` might get invoked more than once. + Therefore, it needs to be idempotent (i.e., have no side effects). Example:: @@ -582,8 +582,8 @@ async def get_two_tx(tx): :param transaction_function: a function that takes a transaction as an argument and does work with the transaction. `transaction_function(tx, *args, **kwargs)` where `tx` is a - :class:`.AsyncTransaction`. - :param args: arguments for the `transaction_function` + :class:`.AsyncManagedTransaction`. + :param args: additional arguments for the `transaction_function` :param kwargs: key word arguments for the `transaction_function` :raises SessionError: if the session has been closed. @@ -607,10 +607,11 @@ async def write_transaction( This does not necessarily imply access control, see the session configuration option :ref:`default-access-mode-ref`. - This transaction will automatically be committed unless an exception is thrown during query execution or by the user code. - Note, that this function perform retries and that the supplied `transaction_function` might get invoked more than once. - - Managed transactions should not generally be explicitly committed (via tx.commit()). + This transaction will automatically be committed when the function + returns unless, an exception is thrown during query execution or by + the user code. Note, that this function performs retries and that the + supplied `transaction_function` might get invoked more than once. + Therefore, it needs to be idempotent (i.e., have no side effects). Example:: @@ -626,8 +627,8 @@ async def create_node_tx(tx, name): :param transaction_function: a function that takes a transaction as an argument and does work with the transaction. `transaction_function(tx, *args, **kwargs)` where `tx` is a - :class:`.AsyncTransaction`. - :param args: key word arguments for the `transaction_function` + :class:`.AsyncManagedTransaction`. + :param args: additional arguments for the `transaction_function` :param kwargs: key word arguments for the `transaction_function` :raises SessionError: if the session has been closed. diff --git a/neo4j/_sync/work/session.py b/neo4j/_sync/work/session.py index 9e0102bdd..6ee43d58a 100644 --- a/neo4j/_sync/work/session.py +++ b/neo4j/_sync/work/session.py @@ -543,11 +543,11 @@ def read_transaction( This does not necessarily imply access control, see the session configuration option :ref:`default-access-mode-ref`. - This transaction will automatically be committed unless an exception is thrown during query execution or by the user code. - Note, that this function perform retries and that the supplied `transaction_function` might get invoked more than once. - - Managed transactions should not generally be explicitly committed - (via ``tx.commit()``). + This transaction will automatically be committed when the function + returns, unless an exception is thrown during query execution or by + the user code. Note, that this function performs retries and that the + supplied `transaction_function` might get invoked more than once. + Therefore, it needs to be idempotent (i.e., have no side effects). Example:: @@ -582,8 +582,8 @@ def get_two_tx(tx): :param transaction_function: a function that takes a transaction as an argument and does work with the transaction. `transaction_function(tx, *args, **kwargs)` where `tx` is a - :class:`.Transaction`. - :param args: arguments for the `transaction_function` + :class:`.ManagedTransaction`. + :param args: additional arguments for the `transaction_function` :param kwargs: key word arguments for the `transaction_function` :raises SessionError: if the session has been closed. @@ -607,10 +607,11 @@ def write_transaction( This does not necessarily imply access control, see the session configuration option :ref:`default-access-mode-ref`. - This transaction will automatically be committed unless an exception is thrown during query execution or by the user code. - Note, that this function perform retries and that the supplied `transaction_function` might get invoked more than once. - - Managed transactions should not generally be explicitly committed (via tx.commit()). + This transaction will automatically be committed when the function + returns unless, an exception is thrown during query execution or by + the user code. Note, that this function performs retries and that the + supplied `transaction_function` might get invoked more than once. + Therefore, it needs to be idempotent (i.e., have no side effects). Example:: @@ -626,8 +627,8 @@ def create_node_tx(tx, name): :param transaction_function: a function that takes a transaction as an argument and does work with the transaction. `transaction_function(tx, *args, **kwargs)` where `tx` is a - :class:`.Transaction`. - :param args: key word arguments for the `transaction_function` + :class:`.ManagedTransaction`. + :param args: additional arguments for the `transaction_function` :param kwargs: key word arguments for the `transaction_function` :raises SessionError: if the session has been closed. From 157381329539f58bfb83fa5c2fa264278f386937 Mon Sep 17 00:00:00 2001 From: Rouven Bauer Date: Thu, 18 Aug 2022 13:22:49 +0200 Subject: [PATCH 2/2] Improve explanation of idempotency --- neo4j/_async/work/session.py | 6 ++++-- neo4j/_sync/work/session.py | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/neo4j/_async/work/session.py b/neo4j/_async/work/session.py index dc3b18a36..567ea5f7c 100644 --- a/neo4j/_async/work/session.py +++ b/neo4j/_async/work/session.py @@ -547,7 +547,8 @@ async def read_transaction( returns, unless an exception is thrown during query execution or by the user code. Note, that this function performs retries and that the supplied `transaction_function` might get invoked more than once. - Therefore, it needs to be idempotent (i.e., have no side effects). + Therefore, it needs to be idempotent (i.e., have the same effect, + regardless if called once or many times). Example:: @@ -611,7 +612,8 @@ async def write_transaction( returns unless, an exception is thrown during query execution or by the user code. Note, that this function performs retries and that the supplied `transaction_function` might get invoked more than once. - Therefore, it needs to be idempotent (i.e., have no side effects). + Therefore, it needs to be idempotent (i.e., have the same effect, + regardless if called once or many times). Example:: diff --git a/neo4j/_sync/work/session.py b/neo4j/_sync/work/session.py index 6ee43d58a..57ee78fde 100644 --- a/neo4j/_sync/work/session.py +++ b/neo4j/_sync/work/session.py @@ -547,7 +547,8 @@ def read_transaction( returns, unless an exception is thrown during query execution or by the user code. Note, that this function performs retries and that the supplied `transaction_function` might get invoked more than once. - Therefore, it needs to be idempotent (i.e., have no side effects). + Therefore, it needs to be idempotent (i.e., have the same effect, + regardless if called once or many times). Example:: @@ -611,7 +612,8 @@ def write_transaction( returns unless, an exception is thrown during query execution or by the user code. Note, that this function performs retries and that the supplied `transaction_function` might get invoked more than once. - Therefore, it needs to be idempotent (i.e., have no side effects). + Therefore, it needs to be idempotent (i.e., have the same effect, + regardless if called once or many times). Example::