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

Author: robsdedude

CHANGELOG.md

@@ -6,8 +6,8 @@
 - Python 3.6 support has been dropped.
 - `Result`, `Session`, and `Transaction` can no longer be imported from
   `neo4j.work`. They should've been imported from `neo4j` all along.  
-  Remark: It's recommended to import everything needed directly from `noe4j`,
-  not its submodules or subpackages.
+  Remark: It's recommended to import everything needed directly from `noe4j` if
+  available, not its submodules or subpackages.
 - Experimental pipelines feature has been removed.
 - Experimental async driver has been added.
 - `ResultSummary.server.version_info` has been removed.  
@@ -51,9 +51,9 @@
       Use `hour_minute_second_nanosecond` instead.
     - The property `second` returns an `int` instead of a `float`.  
       Use `nanosecond` to get the sub-second information.
-- Creation of a driver with `bolt[+s[sc]]://` scheme has been deprecated and
-  will raise an error in the Future. The routing context was and will be
-  silently ignored until then.
+- Creation of a driver with `bolt[+s[sc]]://` scheme and a routing context has
+  been deprecated and will raise an error in the Future. The routing context was
+  and will be silently ignored until then.
 - Bookmarks
   - `Session.last_bookmark` was deprecated. Its behaviour is partially incorrect
     and cannot be fixed without breaking its signature.  
@@ -94,6 +94,10 @@
 - `ServerInfo.connection_id` has been deprecated and will be removed in a
   future release. There is no replacement as this is considered internal
   information.
+- Output of logging helper `neo4j.debug.watch` changes
+  - ANSI colour codes for log output are now opt-in
+  - Prepend log format with log-level (if colours are disabled)
+  - Prepend log format with thread name and id
 
 
 ## Version 4.4

docs/source/api.rst

@@ -275,8 +275,8 @@ For example:
            raise gaierror("Unexpected socket address %r" % socket_address)
 
    driver = GraphDatabase.driver("neo4j://example.com:9999",
-                auth=("neo4j", "password"),
-                resolver=custom_resolver)
+                                 auth=("neo4j", "password"),
+                                 resolver=custom_resolver)
 
 
 :Default: :const:`None`
@@ -541,9 +541,9 @@ Name of the database to query.
 
 
 .. py:attribute:: neo4j.DEFAULT_DATABASE
-   :noindex:
+    :noindex:
 
-   This will use the default database on the Neo4j instance.
+    This will use the default database on the Neo4j instance.
 
 
 .. Note::
@@ -558,9 +558,10 @@ Name of the database to query.
 
 .. code-block:: python
 
-   from neo4j import GraphDatabase
-   driver = GraphDatabase.driver(uri, auth=(user, password))
-   session = driver.session(database="system")
+    from neo4j import GraphDatabase
+
+    driver = GraphDatabase.driver(uri, auth=(user, password))
+    session = driver.session(database="system")
 
 
 :Default: ``neo4j.DEFAULT_DATABASE``
@@ -593,9 +594,10 @@ context of the impersonated user. For this, the user for which the
 
 .. code-block:: python
 
-   from neo4j import GraphDatabase
-   driver = GraphDatabase.driver(uri, auth=(user, password))
-   session = driver.session(impersonated_user="alice")
+    from neo4j import GraphDatabase
+
+    driver = GraphDatabase.driver(uri, auth=(user, password))
+    session = driver.session(impersonated_user="alice")
 
 
 :Default: :const:`None`
@@ -740,8 +742,8 @@ Example:
     def set_person_name(tx, node_id, name):
         query = "MATCH (a:Person) WHERE id(a) = $id SET a.name = $name"
         result = tx.run(query, id=node_id, name=name)
-        info = result.consume()
-        # use the info for logging etc.
+        summary = result.consume()
+        # use the summary for logging etc.
 
 .. _managed-transactions-ref:
 
@@ -1350,6 +1352,49 @@ following code:
     ...
 
 
+*******
+Logging
+*******
+
+The driver offers logging for debugging purposes. It is not recommended to
+enable logging for anything other than debugging. For instance, if the driver is
+not able to connect to the database server or if undesired behavior is observed.
+
+There are different ways of enabling logging as listed below.
+
+Simple Approach
+===============
+
+.. autofunction:: neo4j.debug.watch(*logger_names, level=logging.DEBUG, out=sys.stderr, colour=False)
+
+Context Manager
+===============
+
+.. autoclass:: neo4j.debug.Watcher(*logger_names, default_level=logging.DEBUG, default_out=sys.stderr, colour=False)
+    :members:
+    :special-members: __enter__, __exit__
+
+Full Controll
+=============
+
+.. code-block:: python
+
+    import logging
+    import sys
+
+    # create a handler, e.g. to log to stdout
+    handler = logging.StreamHandler(sys.stdout)
+    # configure the handler to your liking
+    handler.setFormatter(logging.Formatter(
+        "%(threadName)s(%(thread)d) %(asctime)s  %(message)s"
+    ))
+    # add the handler to the driver's logger
+    logging.getLogger("neo4j").addHandler(handler)
+    # make sure the logger logs on the desired log level
+    logging.getLogger("neo4j").setLevel(logging.DEBUG)
+    # from now on, DEBUG logging to stderr is enabled in the driver
+
+
 *********
 Bookmarks
 *********

docs/source/async_api.rst

@@ -446,8 +446,8 @@ Example:
     async def set_person_name(tx, node_id, name):
         query = "MATCH (a:Person) WHERE id(a) = $id SET a.name = $name"
         result = await tx.run(query, id=node_id, name=name)
-        info = await result.consume()
-        # use the info for logging etc.
+        summary = await result.consume()
+        # use the summary for logging etc.
 
 .. _async-managed-transactions-ref:
 

docs/source/conf.py

@@ -57,7 +57,7 @@
 
 # General information about the project.
 project = 'Neo4j Python Driver'
-copyright = '2002-2020 Neo4j, Inc.'
+copyright = 'Neo4j, Inc.'
 author = 'Neo4j, Inc.'
 
 # The version info for the project you're documenting, acts as replacement for

docs/source/types/spatial.rst

@@ -12,7 +12,7 @@ Point
 
 .. autoclass:: neo4j.spatial.Point
     :show-inheritance:
-    :members: srid
+    :members:
 
 
 CartesianPoint
@@ -21,9 +21,6 @@ CartesianPoint
 .. autoclass:: neo4j.spatial.CartesianPoint
     :show-inheritance:
 
-    .. property:: srid
-        :type: int
-
     .. property:: x
         :type: float
 
@@ -39,24 +36,28 @@ CartesianPoint
 
         Same value as ``point[2]``.
 
-        Only available if the point is in space.
+        Only available if the point is in 3D space.
 
 
 Examples
 --------
 
 .. code-block:: python
 
-    point=CartesianPoint((1.23, 4.56)
+    from neo4j.spatial import CartesianPoint
 
-    print(point.x, point.y)
+    point = CartesianPoint((1.23, 4.56))
+    print(point.x, point.y, point.srid)
+    # 1.23 4.56 7203
 
 
 .. code-block:: python
 
-    point=CartesianPoint((1.23, 4.56, 7.89)
+    from neo4j.spatial import CartesianPoint
 
-    print(point.x, point.y, point.z)
+    point = CartesianPoint((1.23, 4.56, 7.89))
+    print(point.x, point.y, point.z, point.srid)
+    # 1.23 4.56 7.8 9157
 
 
 WGS84Point
@@ -65,9 +66,6 @@ WGS84Point
 .. autoclass:: neo4j.spatial.WGS84Point
     :show-inheritance:
 
-    .. property:: srid
-        :type: int
-
     .. property:: x
         :type: float
 
@@ -83,7 +81,7 @@ WGS84Point
 
         Same value as ``point[2]``.
 
-        Only available if the point is in space.
+        Only available if the point is in 3D space.
 
     .. property:: longitude
         :type: float
@@ -100,19 +98,25 @@ WGS84Point
 
         Alias for :attr:`.z`.
 
-        Only available if the point is in space.
+        Only available if the point is in 3D space.
 
 
 Examples
 --------
 
 .. code-block:: python
 
-    point=WGS84Point((1.23, 4.56))
-    print(point.longitude, point.latitude)
+    from neo4j.spatial import WGS84Point
+
+    point = WGS84Point((1.23, 4.56))
+    print(point.longitude, point.latitude, point.srid)
+    # 1.23 4.56 4326
 
 
 .. code-block:: python
 
-    point=WGS84Point((1.23, 4.56, 7.89))
-    print(point.longitude, point.latitude, point.height)
+    from neo4j.spatial import WGS84Point
+
+    point = WGS84Point((1.23, 4.56, 7.89))
+    print(point.longitude, point.latitude, point.height, point.srid)
+    # 1.23 4.56 7.89 4979

neo4j/_async/io/_bolt.py

@@ -100,6 +100,7 @@ def __init__(self, unresolved_address, sock, max_connection_lifetime, *,
                  auth=None, user_agent=None, routing_context=None):
         self.unresolved_address = unresolved_address
         self.socket = sock
+        self.local_port = self.socket.getsockname()[1]
         self.server_info = ServerInfo(Address(sock.getpeername()),
                                       self.PROTOCOL_VERSION)
         # so far `connection.recv_timeout_seconds` is the only available
@@ -379,11 +380,6 @@ def encrypted(self):
     def der_encoded_server_certificate(self):
         pass
 
-    @property
-    @abc.abstractmethod
-    def local_port(self):
-        pass
-
     @abc.abstractmethod
     async def hello(self):
         """ Appends a HELLO message to the outgoing queue, sends it and consumes

neo4j/_async/io/_bolt3.py

@@ -137,13 +137,6 @@ def encrypted(self):
     def der_encoded_server_certificate(self):
         return self.socket.getpeercert(binary_form=True)
 
-    @property
-    def local_port(self):
-        try:
-            return self.socket.getsockname()[1]
-        except OSError:
-            return 0
-
     def get_base_headers(self):
         return {
             "user_agent": self.user_agent,

neo4j/_async/io/_bolt4.py

@@ -90,13 +90,6 @@ def encrypted(self):
     def der_encoded_server_certificate(self):
         return self.socket.getpeercert(binary_form=True)
 
-    @property
-    def local_port(self):
-        try:
-            return self.socket.getsockname()[1]
-        except OSError:
-            return 0
-
     def get_base_headers(self):
         return {
             "user_agent": self.user_agent,

neo4j/_async/io/_bolt5.py

@@ -89,13 +89,6 @@ def encrypted(self):
     def der_encoded_server_certificate(self):
         return self.socket.getpeercert(binary_form=True)
 
-    @property
-    def local_port(self):
-        try:
-            return self.socket.getsockname()[1]
-        except OSError:
-            return 0
-
     def get_base_headers(self):
         headers = {"user_agent": self.user_agent}
         if self.routing_context is not None:

neo4j/_async/io/_common.py

@@ -42,6 +42,7 @@ class AsyncMessageInbox:
 
     def __init__(self, s, on_error):
         self.on_error = on_error
+        self._local_port = s.getsockname()[1]
         self._messages = self._yield_messages(s)
 
     async def _yield_messages(self, sock):
@@ -56,7 +57,7 @@ async def _yield_messages(self, sock):
                     await receive_into_buffer(sock, buffer, 2)
                     chunk_size = buffer.pop_u16()
                     if chunk_size == 0:
-                        log.debug("[#%04X]  S: <NOOP>", sock.getsockname()[1])
+                        log.debug("[#%04X]  S: <NOOP>", self._local_port)
 
                 await receive_into_buffer(sock, buffer, chunk_size + 2)
                 chunk_size = buffer.pop_u16()