Clean-ups and meta data bump for 6.0 (#1200)

Co-authored-by: Max Gustafsson <[email protected]>

Author: robsdedude

CHANGELOG.md

@@ -56,13 +56,13 @@ See also https://github.com/neo4j/neo4j-python-driver/wiki for a full changelog.
     - It is now the same error raised as when trying to start an explicit transaction while another explicit transaction
       is already active.
 - Slightly change `Neo4jError` and `ClientError`:
-    - Properties `message` and `code` are always a `str` (instead of `str | None`).
-    - Remove possibility to override/set `message` and `code` properties.
-    - Remove undocumented, internal methods `Neo4jError.hydrate`, `Neo4jError.invalidates_all_connections`,
-      and `Neo4jError.is_fatal_during_discovery`.
-    - Remove deprecated method `Neo4jError.is_retriable`.  
-      Use `Neo4jError.is_retryable` instead.
-    - Change string representation of `Neo4jError` to include GQL error information.
+  - Properties `message` and `code` are always a `str` (instead of `str | None`).
+  - Remove possibility to override/set `message` and `code` properties.
+  - Remove undocumented, internal methods `Neo4jError.hydrate`, `Neo4jError.invalidates_all_connections`,
+    and `Neo4jError.is_fatal_during_discovery`.
+  - Remove deprecated method `Neo4jError.is_retriable`.  
+    Use `Neo4jError.is_retryable` instead.
+  - Change string representation of `Neo4jError` to include GQL error information.
 - Remove deprecated `Record.__getslice__`. This magic method has been removed in Python 3.0.  
   If you were calling it directly, please use `Record.__getitem__(slice(...))` or simply `record[...]` instead.
 - Bookmarks

README.rst

@@ -4,17 +4,10 @@ Neo4j Bolt Driver for Python
 
 This repository contains the official Neo4j driver for Python.
 
-Starting with 5.0, the Neo4j Drivers will be moving to a monthly release
-cadence. A minor version will be released on the last Friday of each month so
-as to maintain versioning consistency with the core product (Neo4j DBMS) which
-has also moved to a monthly cadence.
+Driver upgrades within a major version will never contain breaking API changes.
 
-As a policy, patch versions will not be released except on rare occasions. Bug
-fixes and updates will go into the latest minor version and users should
-upgrade to that. Driver upgrades within a major version will never contain
-breaking API changes.
-
-See also: https://neo4j.com/developer/kb/neo4j-supported-versions/
+For version compatibility with Neo4j server, please refer to:
+https://neo4j.com/developer/kb/neo4j-supported-versions/
 
 + Python 3.13 supported.
 + Python 3.12 supported.

docs/source/api.rst

@@ -82,13 +82,13 @@ Each supported scheme maps to a particular :class:`neo4j.Driver` subclass that i
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 | URI Scheme             | Driver Object and Setting                                                                                                             |
 +========================+=======================================================================================================================================+
-| bolt                   | :ref:`bolt-driver-ref` with no encryption.                                                                                            |
+| bolt                   | :ref:`bolt-driver-ref` with no encryption or with custom encryption configuration, see :ref:`driver-configuration-ref`.               |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 | bolt+ssc               | :ref:`bolt-driver-ref` with encryption (accepts self signed certificates).                                                            |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 | bolt+s                 | :ref:`bolt-driver-ref` with encryption (accepts only certificates signed by a certificate authority), full certificate checks.        |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| neo4j                  | :ref:`neo4j-driver-ref` with no encryption.                                                                                           |
+| neo4j                  | :ref:`neo4j-driver-ref` with no encryption or with custom encryption configuration, see :ref:`driver-configuration-ref`.              |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 | neo4j+ssc              | :ref:`neo4j-driver-ref` with encryption (accepts self signed certificates).                                                           |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -804,9 +804,8 @@ For example:
             self.driver.close()
 
 Connection details held by the :class:`neo4j.Driver` are immutable.
-Therefore if, for example, a password is changed, a replacement :class:`neo4j.Driver` object must be created.
-More than one :class:`.Driver` may be required if connections to multiple remotes, or connections as multiple users, are required,
-unless when using impersonation (:ref:`impersonated-user-ref`).
+Therefore if, for example, the server URI is changed, a replacement :class:`neo4j.Driver` object must be created.
+More than one :class:`.Driver` may be required if connections to multiple remotes.
 
 :class:`neo4j.Driver` objects are thread-safe but cannot be shared across processes.
 Therefore, ``multithreading`` should generally be preferred over ``multiprocessing`` for parallel database access.
@@ -964,7 +963,8 @@ more information.
     :class:`neo4j.Bookmarks` object instead.
 
 .. versionchanged:: 6.0
-    Only accepts :class:`neo4j.Bookmarks` objects or :data:`None`.
+    No longer accepts an iterable of strings.
+    Pass a :class:`neo4j.Bookmarks` objects or :data:`None` instead.
 
 
 .. _database-ref:
@@ -985,7 +985,7 @@ Name of the database to query.
     straightforward way and potentially simplifies driver logic as well as
     reduces network communication resulting in better performance.
 
-    Usage of Cypher clauses like `USE` is not a replacement for this option.
+    Usage of Cypher clauses like ``USE`` is not a replacement for this option.
     The driver does not parse any Cypher.
 
 When no explicit name is set, the driver behavior depends on the connection
@@ -1384,7 +1384,7 @@ Example:
 
 .. _managed-transactions-ref:
 
-Managed Transactions (`transaction functions`)
+Managed Transactions (*transaction functions*)
 ==============================================
 Transaction functions are the most powerful form of transaction, providing access mode override and retry capabilities.
 

docs/source/async_api.rst

@@ -95,13 +95,13 @@ Each supported scheme maps to a particular :class:`neo4j.AsyncDriver` subclass t
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
 | URI Scheme             | Driver Object and Setting                                                                                                                   |
 +========================+=============================================================================================================================================+
-| bolt                   | :ref:`async-bolt-driver-ref` with no encryption.                                                                                            |
+| bolt                   | :ref:`async-bolt-driver-ref` with no encryption or with custom encryption configuration, see :ref:`async-driver-configuration-ref`.         |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
 | bolt+ssc               | :ref:`async-bolt-driver-ref` with encryption (accepts self signed certificates).                                                            |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
 | bolt+s                 | :ref:`async-bolt-driver-ref` with encryption (accepts only certificates signed by a certificate authority), full certificate checks.        |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
-| neo4j                  | :ref:`async-neo4j-driver-ref` with no encryption.                                                                                           |
+| neo4j                  | :ref:`async-neo4j-driver-ref` with no encryption or with custom encryption configuration, see :ref:`async-driver-configuration-ref`.         |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
 | neo4j+ssc              | :ref:`async-neo4j-driver-ref` with encryption (accepts self signed certificates).                                                           |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
@@ -487,9 +487,7 @@ For example:
             await self.driver.close()
 
 Connection details held by the :class:`neo4j.AsyncDriver` are immutable.
-Therefore if, for example, a password is changed, a replacement :class:`neo4j.AsyncDriver` object must be created.
-More than one :class:`.AsyncDriver` may be required if connections to multiple remotes, or connections as multiple users, are required,
-unless when using impersonation (:ref:`impersonated-user-ref`).
+Therefore if, for example, the server URI is changed, a replacement :class:`neo4j.AsyncDriver` object must be created.
 
 :class:`neo4j.AsyncDriver` objects are safe to be used in concurrent coroutines.
 They are not thread-safe.
@@ -837,7 +835,7 @@ Example:
 .. _async-managed-transactions-ref:
 
 
-Managed Transactions (`transaction functions`)
+Managed Transactions (*transaction functions*)
 ==============================================
 Transaction functions are the most powerful form of transaction, providing access mode override and retry capabilities.
 

docs/source/index.rst

@@ -126,7 +126,6 @@ Specifically for this driver, this will:
  * enable :class:`DeprecationWarning`, which the driver emits if deprecated APIs are used.
  * enable the driver's debug mode (this can also be achieved by setting the environment variable ``PYTHONNEO4JDEBUG``):
 
-     It might be changed or removed any time even without prior notice.
    * the driver will raise an exception if non-concurrency-safe methods are used concurrently.
    * the driver will emit warnings if the server sends back notification
      (see also :ref:`driver-warn-notification-severity-ref`).

src/neo4j/_addressing.py

@@ -341,7 +341,6 @@ def __str__(self) -> str:
         return "[{}]:{}".format(*self)
 
 
-# TODO: 6.0 - make this class private
 class ResolvedAddress(Address):
     _unresolved_host_name: str
 
@@ -360,11 +359,9 @@ def __new__(cls, iterable, *, host_name: str) -> ResolvedAddress:
         return new
 
 
-# TODO: 6.0 - make this class private
 class ResolvedIPv4Address(IPv4Address, ResolvedAddress):
     pass
 
 
-# TODO: 6.0 - make this class private
 class ResolvedIPv6Address(IPv6Address, ResolvedAddress):
     pass

src/neo4j/_async/config.py

@@ -67,9 +67,9 @@ class AsyncPoolConfig(Config):
     trusted_certificates = TrustSystemCAs()
     # Specify how to determine the authenticity of encryption certificates
     # provided by the Neo4j instance on connection.
-    # * `neo4j.TrustSystemCAs()`: Use system trust store. (default)
-    # * `neo4j.TrustAll()`: Trust any certificate.
-    # * `neo4j.TrustCustomCAs("<path>", ...)`:
+    # * ``neo4j.TrustSystemCAs()``: Use system trust store. (default)
+    # * ``neo4j.TrustAll()``: Trust any certificate.
+    # * ``neo4j.TrustCustomCAs("<path>", ...)``:
     #       Trust the specified certificate(s).
 
     #: Certificate to use for mTLS as 2nd authentication factor.
@@ -78,7 +78,7 @@ class AsyncPoolConfig(Config):
     #: Custom SSL context to use for wrapping sockets
     ssl_context = None
     # Use any custom SSL context to wrap sockets.
-    # Overwrites `trusted_certificates` and `encrypted`.
+    # Overwrites ``trusted_certificates`` and ``encrypted``.
     # The use of this option is strongly discouraged.
 
     #: User Agent (Python Driver Specific)

src/neo4j/_async/driver.py

@@ -301,18 +301,18 @@ def bookmark_manager(
             driver = neo4j.AsyncGraphDatabase.driver(...)
             bookmark_manager = neo4j.AsyncGraphDatabase.bookmark_manager(...)
 
-            async with driver.session(
-                bookmark_manager=bookmark_manager
-            ) as session1:
-                async with driver.session(
+            async with (
+                driver.session(bookmark_manager=bookmark_manager) as session1,
+                driver.session(
                     bookmark_manager=bookmark_manager,
-                    access_mode=neo4j.READ_ACCESS
-                ) as session2:
-                    result1 = await session1.run("<WRITE_QUERY>")
-                    await result1.consume()
-                    # READ_QUERY is guaranteed to see what WRITE_QUERY wrote.
-                    result2 = await session2.run("<READ_QUERY>")
-                    await result2.consume()
+                    default_access_mode=neo4j.READ_ACCESS,
+                ) as session2,
+            ):
+                result1 = await session1.run("<WRITE_QUERY>")
+                await result1.consume()
+                # READ_QUERY is guaranteed to see what WRITE_QUERY wrote.
+                result2 = await session2.run("<READ_QUERY>")
+                await result2.consume()
 
         This is a very contrived example, and in this particular case, having
         both queries in the same session has the exact same effect and might

src/neo4j/_async/io/__init__.py

@@ -17,8 +17,8 @@
 """
 Low-level functionality required for speaking Bolt.
 
-It is not intended to be used directly by driver users. Instead, the `session`
-module provides the main user-facing abstractions.
+It is not intended to be used directly by driver users. Instead, the
+``session`` module provides the main user-facing abstractions.
 """
 
 __all__ = [

src/neo4j/_async/io/_pool.py

@@ -964,7 +964,7 @@ async def update_routing_table(
         :param acquisition_timeout: connection acquisition timeout
         :param database_callback: A callback function that will be called with
             the database name as only argument when a new routing table has
-            been acquired. This database name might different from `database`
+            been acquired. This database name might different from ``database``
             if that was None and the underlying protocol supports reporting
             back the actual database.
 
@@ -1065,7 +1065,8 @@ async def ensure_routing_table_is_fresh(
 
         This method is thread-safe.
 
-        :returns: `True` if an update was required, `False` otherwise.
+        :returns:
+            :data:`True` if an update was required, :data:`False` otherwise.
         """
         async with self.refresh_lock:
             for database_ in list(self.routing_tables.keys()):