Clean up docs & bump meta data for 6.0

Author: robsdedude

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).                                                           |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -799,9 +799,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.
@@ -959,7 +958,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:
@@ -980,7 +980,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
@@ -1378,7 +1378,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.
 
@@ -2001,7 +2001,7 @@ Server-side errors
 
 .. autoexception:: neo4j.exceptions.Neo4jError()
     :show-inheritance:
-    :members: message, code, is_retriable, is_retryable
+    :members: message, code, is_retryable
 
 .. autoexception:: neo4j.exceptions.ClientError()
     :show-inheritance:

docs/source/async_api.rst

@@ -837,7 +837,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

@@ -10,7 +10,6 @@ Bolt protocol versions supported:
 .. # [bolt-version-bump] search tag when changing bolt version support
 
 * Bolt 5.0 - 5.8
-* Bolt 4.4
 
 See https://7687.org/bolt-compatibility/ for what Neo4j DBMS versions support which Bolt versions.
 See https://neo4j.com/developer/kb/neo4j-supported-versions/ for a driver-server compatibility matrix.

requirements-dev.txt

@@ -10,7 +10,7 @@ unasync==0.5.0
 pre-commit>=4.2.0
 isort>=6.0.1
 mypy>=1.15.0
-typing-extensions>=4.13.2
+#typing-extensions>=4.13.2
 types-pytz>=2025.2.0.20250326
 ruff>=0.11.6
 

src/neo4j/_async/config.py

@@ -68,9 +68,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.
@@ -79,7 +79,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

@@ -312,18 +312,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

@@ -965,7 +965,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.
 
@@ -1064,7 +1064,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()):

src/neo4j/_async/work/result.py

@@ -432,7 +432,7 @@ async def _attach(self):
 
     async def _buffer(self, n=None):
         """
-        Try to fill `self._record_buffer` with n records.
+        Try to fill ``self._record_buffer`` with n records.
 
         Might end up with more records in the buffer if the fetch size makes it
         overshoot.
@@ -586,9 +586,10 @@ async def single(self, strict: bool = False) -> Record | None:
         emit a warning and return the first record.
 
         :param strict:
-            If :data:`True`, raise a :exc:`.ResultNotSingleError` instead of
-            returning :data:`None` if there is more than one record or warning
-            if there is more than 1 record.
+            If :data:`False`, return :data:`None` if there is no record and
+            emit a warning if there is more than 1 record.
+            If :data:`True`, raise a :exc:`.ResultNotSingleError` if there is
+            not exactly one record.
             :data:`False` by default.
         :type strict: bool
 
@@ -814,7 +815,7 @@ async def to_df(
         r"""
         Convert (the rest of) the result to a pandas DataFrame.
 
-        This method is only available if the `pandas` library is installed.
+        This method is only available if the ``pandas`` library is installed.
 
         ::
 
@@ -894,7 +895,7 @@ async def to_df(
             If :data:`False`, columns of the above types will be left as driver
             types (dtype ``object``).
 
-        :raises ImportError: if `pandas` library is not available.
+        :raises ImportError: if the ``pandas`` library is not available.
         :raises ResultConsumedError: if the transaction from which this result
             was obtained has been closed or the Result has been explicitly
             consumed.