Merge branch '5.0' into feature/remove-null-tests-for-ids

Author: thelonelyvulpes

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

@@ -160,7 +160,8 @@ Driver Configuration
 
 Additional configuration can be provided via the :class:`neo4j.Driver` constructor.
 
-
++ :ref:`session-connection-timeout-ref`
++ :ref:`update-routing-table-timeout-ref`
 + :ref:`connection-acquisition-timeout-ref`
 + :ref:`connection-timeout-ref`
 + :ref:`encrypted-ref`
@@ -175,12 +176,63 @@ Additional configuration can be provided via the :class:`neo4j.Driver` construct
 + :ref:`user-agent-ref`
 
 
+.. _session-connection-timeout-ref:
+
+``session_connection_timeout``
+------------------------------
+The maximum amount of time in seconds the session will wait when trying to
+establish a usable read/write connection to the remote host.
+This encompasses *everything* that needs to happen for this, including,
+if necessary, updating the routing table, fetching a connection from the pool,
+and, if necessary fully establishing a new connection with the reader/writer.
+
+Since this process may involve updating the routing table, acquiring a
+connection from the pool, or establishing a new connection, it should be chosen
+larger than :ref:`update-routing-table-timeout-ref`,
+:ref:`connection-acquisition-timeout-ref`, and :ref:`connection-timeout-ref`.
+
+:Type: ``float``
+:Default: ``120.0``
+
+.. versionadded:: 4.4.5
+
+.. versionchanged:: 5.0
+
+    The default value was changed from ``float("inf")`` to ``120.0``.
+
+
+.. _update-routing-table-timeout-ref:
+
+``update_routing_table_timeout``
+--------------------------------
+The maximum amount of time in seconds the driver will attempt to fetch a new
+routing table. This encompasses *everything* that needs to happen for this,
+including fetching connections from the pool, performing handshakes, and
+requesting and receiving a fresh routing table.
+
+Since this process may involve acquiring a connection from the pool, or
+establishing a new connection, it should be chosen larger than
+:ref:`connection-acquisition-timeout-ref` and :ref:`connection-timeout-ref`.
+
+This setting only has an effect for :ref:`neo4j-driver-ref`, but not for
+:ref:`bolt-driver-ref` as it does no routing at all.
+
+:Type: ``float``
+:Default: ``90.0``
+
+.. versionadded:: 4.4.5
+
+
 .. _connection-acquisition-timeout-ref:
 
 ``connection_acquisition_timeout``
 ----------------------------------
-The maximum amount of time in seconds a session will wait when requesting a connection from the connection pool.
-Since the process of acquiring a connection may involve creating a new connection, ensure that the value of this configuration is higher than the configured :ref:`connection-timeout-ref`.
+The maximum amount of time in seconds the driver will wait to either acquire an
+idle connection from the pool (including potential liveness checks) or create a
+new connection when the pool is not full and all existing connection are in use.
+
+Since this process may involve opening a new connection including handshakes,
+it should be chosen larger than :ref:`connection-timeout-ref`.
 
 :Type: ``float``
 :Default: ``60.0``
@@ -190,7 +242,11 @@ Since the process of acquiring a connection may involve creating a new connectio
 
 ``connection_timeout``
 ----------------------
-The maximum amount of time in seconds to wait for a TCP connection to be established.
+The maximum amount of time in seconds to wait for a TCP connection to be
+established.
+
+This *does not* include any handshake(s), or authentication required before the
+connection can be used to perform database related work.
 
 :Type: ``float``
 :Default: ``30.0``
@@ -224,7 +280,6 @@ Specify whether TCP keep-alive should be enabled.
 
 ``max_connection_lifetime``
 ---------------------------
-
 The maximum duration in seconds that the driver will keep a connection for before being removed from the pool.
 
 :Type: ``float``
@@ -611,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

@@ -16,6 +16,8 @@
 # limitations under the License.
 
 
+import warnings
+
 from .._async_compat.util import AsyncUtil
 from .._conf import (
     TrustAll,
@@ -36,6 +38,8 @@
 from ..meta import (
     deprecation_warn,
     experimental,
+    experimental_warn,
+    ExperimentalWarning,
     unclosed_resource_warn,
 )
 
@@ -310,22 +314,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
@@ -339,6 +355,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.
@@ -347,7 +371,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/io/_bolt.py

@@ -264,7 +264,7 @@ async def ping(cls, address, *, timeout=None, **config):
         except (ServiceUnavailable, SessionExpired, BoltHandshakeError):
             return None
         else:
-            AsyncBoltSocket.close_socket(s)
+            await AsyncBoltSocket.close_socket(s)
             return protocol_version
 
     @classmethod
@@ -357,11 +357,6 @@ def time_remaining():
             connection.socket.set_deadline(time_remaining())
             try:
                 await connection.hello()
-            except SocketDeadlineExceeded as e:
-                # connection._defunct = True
-                raise ServiceUnavailable(
-                    "Timeout during initial handshake occurred"
-                ) from e
             finally:
                 connection.socket.set_deadline(None)
         except Exception:
@@ -484,7 +479,7 @@ async def reset(self):
 
     @abc.abstractmethod
     def goodbye(self):
-        """Append a GOODBYE message to the outgoing queued."""
+        """Append a GOODBYE message to the outgoing queue."""
         pass
 
     def _append(self, signature, fields=(), response=None):
@@ -594,7 +589,7 @@ async def _set_defunct(self, message, error=None, silent=False):
         direct_driver = isinstance(self.pool, AsyncBoltPool)
 
         if error:
-            log.debug("[#%04X] %s", self.socket.getsockname()[1], error)
+            log.debug("[#%04X]  %r", self.socket.getsockname()[1], error)
         log.error(message)
         # We were attempting to receive data but the connection
         # has unexpectedly terminated. So, we need to close the

neo4j/_async/io/_common.py

@@ -23,6 +23,7 @@
 from struct import pack as struct_pack
 
 from ..._async_compat.util import AsyncUtil
+from ..._exceptions import SocketDeadlineExceeded
 from ...exceptions import (
     Neo4jError,
     ServiceUnavailable,
@@ -70,7 +71,7 @@ async def _yield_messages(self, sock):
                     # Reset for new message
                     unpacker.reset()
 
-        except (OSError, socket.timeout) as error:
+        except (OSError, socket.timeout, SocketDeadlineExceeded) as error:
             await AsyncUtil.callback(self.on_error, error)
 
     async def pop(self):