Merge branch '5.0' into bolt-utc-datetimes-refactoring

Author: robsdedude

CHANGELOG.md

@@ -76,11 +76,9 @@
     It now raises a `ResultConsumedError`.
   - New method `Result.closed()` can be used to check for this condition if
     necessary.
-- `driver.verify_connectivity()`
-  - All keyword arguments have been deprecated (they were experimental).
-    They are now ignored and will be removed in a future release.
-  - The undocumented return value has been removed. If you need information
-    about the remote server, use `driver.get_server_info()` instead.
+- The undocumented return value of `driver.verify_connectivity()` has been
+  removed. If you need information about the remote server, use
+  `driver.get_server_info()` instead.
 - Transaction functions (a.k.a. managed transactions):  
   The first argument of transaction functions is now a `ManagedTransaction`
   object. It behaves exactly like a regular `Transaction` object, except it

docs/source/api.rst

@@ -666,16 +666,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

@@ -91,7 +91,7 @@ To deactivate the current active virtual environment, use:
 Quick Example
 *************
 
-Creating nodes.
+Creating nodes and relationships.
 
 .. code-block:: python
 
@@ -100,15 +100,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()
@@ -126,8 +128,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/_async/driver.py

@@ -28,6 +28,7 @@
 from .._meta import (
     deprecation_warn,
     experimental,
+    experimental_warn,
     unclosed_resource_warn,
 )
 from ..addressing import Address
@@ -309,22 +310,34 @@ async def verify_connectivity(self, **config):
             Even if this method raises an exception, the driver still needs to
             be closed via :meth:`close` to free up all resources.
 
+        :param config: accepts the same configuration key-word arguments as
+            :meth:`session`.
+
+            .. warning::
+                All configuration key-word arguments are experimental.
+                They might be changed or removed in any future version without
+                prior notice.
+
         :raises DriverError: if the driver cannot connect to the remote.
             Use the exception to further understand the cause of the
             connectivity problem.
 
-        .. versionchanged:: 5.0 the config parameters will be removed in
-            version 6 0. It has no effect starting with version 5.0.
+        .. versionchanged:: 5.0
+            The undocumented return value has been removed.
+            If you need information about the remote server, use
+            :meth:`get_server_info` instead.
         """
         if config:
-            deprecation_warn(
-                "verify_connectivity() will not accept any configuration "
-                "parameters starting with version 6.0."
+            experimental_warn(
+                "All configuration key-word arguments to "
+                "verify_connectivity() are experimental. They might be "
+                "changed or removed in any future version without prior "
+                "notice."
             )
+        async with self.session(**config) as session:
+            await session._get_server_info()
 
-        await self.get_server_info()
-
-    async def get_server_info(self):
+    async def get_server_info(self, **config):
         """Get information about the connected Neo4j server.
 
         Try to establish a working read connection to the remote server or a
@@ -338,6 +351,14 @@ async def get_server_info(self):
             Even if this method raises an exception, the driver still needs to
             be closed via :meth:`close` to free up all resources.
 
+        :param config: accepts the same configuration key-word arguments as
+            :meth:`session`.
+
+            .. warning::
+                All configuration key-word arguments are experimental.
+                They might be changed or removed in any future version without
+                prior notice.
+
         :rtype: ServerInfo
 
         :raises DriverError: if the driver cannot connect to the remote.
@@ -346,7 +367,14 @@ async def get_server_info(self):
 
         .. versionadded:: 5.0
         """
-        async with self.session() as session:
+        if config:
+            experimental_warn(
+                "All configuration key-word arguments to "
+                "verify_connectivity() are experimental. They might be "
+                "changed or removed in any future version without prior "
+                "notice."
+            )
+        async with self.session(**config) as session:
             return await session._get_server_info()
 
     @experimental("Feature support query, based on Bolt protocol version and Neo4j server version will change in the future.")

neo4j/_async/work/session.py

@@ -440,6 +440,11 @@ async def _run_transaction(
 
     async 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.
 
@@ -490,6 +495,11 @@ async def get_two_tx(tx):
 
     async 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.
 

neo4j/_meta.py

@@ -77,6 +77,10 @@ class ExperimentalWarning(Warning):
     """
 
 
+def experimental_warn(message, stack_level=1):
+    warn(message, category=ExperimentalWarning, stacklevel=stack_level + 1)
+
+
 def experimental(message):
     """ Decorator for tagging experimental functions and methods.
 
@@ -92,16 +96,14 @@ def decorator(f):
         if asyncio.iscoroutinefunction(f):
             @wraps(f)
             async def inner(*args, **kwargs):
-                from warnings import warn
-                warn(message, category=ExperimentalWarning, stacklevel=2)
+                experimental_warn(message, stack_level=2)
                 return await f(*args, **kwargs)
 
             return inner
         else:
             @wraps(f)
             def inner(*args, **kwargs):
-                from warnings import warn
-                warn(message, category=ExperimentalWarning, stacklevel=2)
+                experimental_warn(message, stack_level=2)
                 return f(*args, **kwargs)
 
             return inner

neo4j/_sync/driver.py

@@ -28,6 +28,7 @@
 from .._meta import (
     deprecation_warn,
     experimental,
+    experimental_warn,
     unclosed_resource_warn,
 )
 from ..addressing import Address
@@ -309,22 +310,34 @@ def verify_connectivity(self, **config):
             Even if this method raises an exception, the driver still needs to
             be closed via :meth:`close` to free up all resources.
 
+        :param config: accepts the same configuration key-word arguments as
+            :meth:`session`.
+
+            .. warning::
+                All configuration key-word arguments are experimental.
+                They might be changed or removed in any future version without
+                prior notice.
+
         :raises DriverError: if the driver cannot connect to the remote.
             Use the exception to further understand the cause of the
             connectivity problem.
 
-        .. versionchanged:: 5.0 the config parameters will be removed in
-            version 6 0. It has no effect starting with version 5.0.
+        .. versionchanged:: 5.0
+            The undocumented return value has been removed.
+            If you need information about the remote server, use
+            :meth:`get_server_info` instead.
         """
         if config:
-            deprecation_warn(
-                "verify_connectivity() will not accept any configuration "
-                "parameters starting with version 6.0."
+            experimental_warn(
+                "All configuration key-word arguments to "
+                "verify_connectivity() are experimental. They might be "
+                "changed or removed in any future version without prior "
+                "notice."
             )
+        with self.session(**config) as session:
+            session._get_server_info()
 
-        self.get_server_info()
-
-    def get_server_info(self):
+    def get_server_info(self, **config):
         """Get information about the connected Neo4j server.
 
         Try to establish a working read connection to the remote server or a
@@ -338,6 +351,14 @@ def get_server_info(self):
             Even if this method raises an exception, the driver still needs to
             be closed via :meth:`close` to free up all resources.
 
+        :param config: accepts the same configuration key-word arguments as
+            :meth:`session`.
+
+            .. warning::
+                All configuration key-word arguments are experimental.
+                They might be changed or removed in any future version without
+                prior notice.
+
         :rtype: ServerInfo
 
         :raises DriverError: if the driver cannot connect to the remote.
@@ -346,7 +367,14 @@ def get_server_info(self):
 
         .. versionadded:: 5.0
         """
-        with self.session() as session:
+        if config:
+            experimental_warn(
+                "All configuration key-word arguments to "
+                "verify_connectivity() are experimental. They might be "
+                "changed or removed in any future version without prior "
+                "notice."
+            )
+        with self.session(**config) as session:
             return session._get_server_info()
 
     @experimental("Feature support query, based on Bolt protocol version and Neo4j server version will change in the future.")

neo4j/_sync/work/session.py

@@ -440,6 +440,11 @@ def _run_transaction(
 
     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.
 
@@ -490,6 +495,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.
 

tests/unit/async_/test_driver.py

@@ -251,18 +251,42 @@ async def test_verify_connectivity(uri, mocker):
     "neo4j://127.0.0.1:9000",
 ))
 @pytest.mark.parametrize("kwargs", (
-    {"access_mode": WRITE_ACCESS},
-    {"access_mode": READ_ACCESS},
+    {"default_access_mode": WRITE_ACCESS},
+    {"default_access_mode": READ_ACCESS},
     {"fetch_size": 69},
 ))
 @mark_async_test
-async def test_verify_connectivity_parameters_are_deprecated(uri, kwargs,
-                                                             mocker):
+async def test_verify_connectivity_parameters_are_deprecated(
+    uri, kwargs, mocker
+):
     driver = create_driver(uri)
     mocker.patch.object(driver, "_pool", autospec=True)
 
     try:
-        with pytest.warns(DeprecationWarning, match="configuration"):
+        with pytest.warns(ExperimentalWarning, match="configuration"):
             await driver.verify_connectivity(**kwargs)
     finally:
         await driver.close()
+
+
+@pytest.mark.parametrize("uri", (
+    "bolt://127.0.0.1:9000",
+    "neo4j://127.0.0.1:9000",
+))
+@pytest.mark.parametrize("kwargs", (
+    {"default_access_mode": WRITE_ACCESS},
+    {"default_access_mode": READ_ACCESS},
+    {"fetch_size": 69},
+))
+@mark_async_test
+async def test_get_server_info_parameters_are_experimental(
+    uri, kwargs, mocker
+):
+    driver = create_driver(uri)
+    mocker.patch.object(driver, "_pool", autospec=True)
+
+    try:
+        with pytest.warns(ExperimentalWarning, match="configuration"):
+            await driver.get_server_info(**kwargs)
+    finally:
+        await driver.close()