Merge branch '4.4' into bolt-utc-datetimes-4.4

Author: robsdedude

docs/source/api.rst

@@ -607,16 +607,21 @@ The default access mode.
 
 A session can be given a default access mode on construction.
 
-This applies only in clustered environments and determines whether transactions carried out within that session should be routed to a `read` or `write` server by default.
+This applies only in clustered environments and determines whether transactions
+carried out within that session should be routed to a ``read`` or ``write``
+server by default.
 
-Transactions (see :ref:`managed-transactions-ref`) within a session can override the access mode passed to that session on construction.
+Transactions (see :ref:`managed-transactions-ref`) within a session override the
+access mode passed to that session on construction.
 
 .. note::
-    The driver does not parse Cypher queries and cannot determine whether the access mode should be ``neo4j.ACCESS_WRITE`` or ``neo4j.ACCESS_READ``.
-    Since the access mode is not passed to the server, this can allow a ``neo4j.ACCESS_WRITE`` statement to be executed for a ``neo4j.ACCESS_READ`` call on a single instance.
-    Clustered environments are not susceptible to this loophole as cluster roles prevent it.
-    This behaviour should not be relied upon as the loophole may be closed in a future release.
-
+    The driver does not parse Cypher queries and cannot determine whether the
+    access mode should be ``neo4j.ACCESS_WRITE`` or ``neo4j.ACCESS_READ``.
+    This setting is only meant to enable the driver to perform correct routing,
+    *not* for enforcing access control. This means that, depending on the server
+    version and settings, the server or cluster might allow a write-statement to
+    be executed even when ``neo4j.ACCESS_READ`` is chosen. This behaviour should
+    not be relied upon as it can change with the server.
 
 :Type: ``neo4j.WRITE_ACCESS``, ``neo4j.READ_ACCESS``
 :Default: ``neo4j.WRITE_ACCESS``

docs/source/index.rst

@@ -97,7 +97,7 @@ To deactivate the current active virtual environment, use:
 Quick Example
 *************
 
-Creating nodes.
+Creating nodes and relationships.
 
 .. code-block:: python
 
@@ -106,15 +106,17 @@ Creating nodes.
     uri = "neo4j://localhost:7687"
     driver = GraphDatabase.driver(uri, auth=("neo4j", "password"))
 
+    def create_person(tx, name):
+        tx.run("CREATE (a:Person {name: $name})", name=name)
+
     def create_friend_of(tx, name, friend):
         tx.run("MATCH (a:Person) WHERE a.name = $name "
                "CREATE (a)-[:KNOWS]->(:Person {name: $friend})",
                name=name, friend=friend)
 
     with driver.session() as session:
+        session.write_transaction(create_person, "Alice")
         session.write_transaction(create_friend_of, "Alice", "Bob")
-
-    with driver.session() as session:
         session.write_transaction(create_friend_of, "Alice", "Carl")
 
     driver.close()
@@ -132,8 +134,8 @@ Finding nodes.
     def get_friends_of(tx, name):
         friends = []
         result = tx.run("MATCH (a:Person)-[:KNOWS]->(f) "
-                             "WHERE a.name = $name "
-                             "RETURN f.name AS friend", name=name)
+                        "WHERE a.name = $name "
+                        "RETURN f.name AS friend", name=name)
         for record in result:
             friends.append(record["friend"])
         return friends

neo4j/work/simple.py

@@ -355,6 +355,11 @@ def _run_transaction(self, access_mode, transaction_function, *args, **kwargs):
 
     def read_transaction(self, transaction_function, *args, **kwargs):
         """Execute a unit of work in a managed read transaction.
+
+        .. note::
+            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.
 
@@ -398,6 +403,11 @@ def get_two_tx(tx):
 
     def write_transaction(self, transaction_function, *args, **kwargs):
         """Execute a unit of work in a managed write transaction.
+
+        .. note::
+            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.