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.

src/neo4j/_async/work/session.py

@@ -75,7 +75,7 @@ class AsyncSession(AsyncWorkspace):
     Therefore, a session should generally be short-lived, and must not
     span multiple threads/asynchronous Tasks.
 
-    In general, sessions will be created and destroyed within a `with`
+    In general, sessions will be created and destroyed within a ``with``
     context. For example::
 
         async with driver.session(database="neo4j") as session:
@@ -606,7 +606,7 @@ async def execute_read(
         This transaction will automatically be committed when the function
         returns, unless an exception is thrown during query execution or by
         the user code. Note, that this function performs retries and that the
-        supplied `transaction_function` might get invoked more than once.
+        supplied ``transaction_function`` might get invoked more than once.
         Therefore, it needs to be idempotent (i.e., have the same effect,
         regardless if called once or many times).
 
@@ -646,12 +646,12 @@ async def get_two_tx(tx):
             :class:`.AsyncManagedTransaction`.
         :type transaction_function:
             typing.Callable[[AsyncManagedTransaction, P], typing.Awaitable[R]]
-        :param args: additional arguments for the `transaction_function`
+        :param args: additional arguments for the ``transaction_function``
         :type args: P
-        :param kwargs: key word arguments for the `transaction_function`
+        :param kwargs: key word arguments for the ``transaction_function``
         :type kwargs: P
 
-        :returns: whatever the given `transaction_function` returns
+        :returns: whatever the given ``transaction_function`` returns
         :rtype: R
 
         :raises SessionError: if the session has been closed.
@@ -685,7 +685,7 @@ async def execute_write(
         This transaction will automatically be committed when the function
         returns unless, an exception is thrown during query execution or by
         the user code. Note, that this function performs retries and that the
-        supplied `transaction_function` might get invoked more than once.
+        supplied ``transaction_function`` might get invoked more than once.
         Therefore, it needs to be idempotent (i.e., have the same effect,
         regardless if called once or many times).
 
@@ -707,9 +707,9 @@ async def create_node_tx(tx, name):
             :class:`.AsyncManagedTransaction`.
         :type transaction_function:
             typing.Callable[[AsyncManagedTransaction, P], typing.Awaitable[R]]
-        :param args: additional arguments for the `transaction_function`
+        :param args: additional arguments for the ``transaction_function``
         :type args: P
-        :param kwargs: key word arguments for the `transaction_function`
+        :param kwargs: key word arguments for the ``transaction_function``
         :type kwargs: P
 
         :returns: a result as returned by the given unit of work

src/neo4j/_async/work/transaction.py

@@ -147,8 +147,8 @@ async def run(
         Cypher is typically expressed as a query template plus a
         set of named parameters. In Python, parameters may be expressed
         through a dictionary of parameters, through individual parameter
-        arguments, or as a mixture of both. For example, the `run`
-        queries below are all equivalent::
+        arguments, or as a mixture of both. For example, the ``run``
+        calls below are all equivalent::
 
             query = "CREATE (a:Person { name: $name, age: $age })"
             result = await tx.run(query, {"name": "Alice", "age": 33})

src/neo4j/_async_compat/network/_util.py

@@ -88,7 +88,7 @@ async def resolve_address(address, family=0, resolver=None):
 
         :param address: the Address to resolve
         :param family: optional address family to filter resolved
-                       addresses by (e.g. `socket.AF_INET6`)
+                       addresses by (e.g. ``socket.AF_INET6``)
         :param resolver: optional customer resolver function to be
                          called before regular DNS resolution
         """
@@ -170,7 +170,7 @@ def resolve_address(address, family=0, resolver=None):
 
         :param address: the Address to resolve
         :param family: optional address family to filter resolved
-                       addresses by (e.g. `socket.AF_INET6`)
+                       addresses by (e.g. ``socket.AF_INET6``)
         :param resolver: optional customer resolver function to be
                          called before regular DNS resolution
         """

src/neo4j/_auth_management.py

@@ -117,7 +117,7 @@ class AuthManager(metaclass=abc.ABCMeta):
         Furthermore, the manager is expected to be thread-safe.
 
         The token returned must always belong to the same identity.
-        Switching identities using the `AuthManager` is undefined behavior.
+        Switching identities using the ``AuthManager`` is undefined behavior.
         You may use :ref:`session-level authentication<session-auth-ref>`
         for such use-cases.
 
@@ -128,7 +128,7 @@ class AuthManager(metaclass=abc.ABCMeta):
     .. versionchanged:: 5.12
         ``on_auth_expired`` was removed from the interface and replaced by
         :meth:`handle_security_exception`. The new method is called when the
-        server returns any `Neo.ClientError.Security.*` error. Its signature
+        server returns any ``Neo.ClientError.Security.*`` error. Its signature
         differs in that it additionally receives the error returned by the
         server and returns a boolean indicating whether the error was handled.
 
@@ -147,9 +147,10 @@ def get_auth(self) -> _TAuth:
 
             The method must only ever return auth information belonging to the
             same identity.
-            Switching identities using the `AuthManager` is undefined behavior.
-            You may use :ref:`session-level authentication<session-auth-ref>`
-            for such use-cases.
+            Switching identities using the ``AuthManager`` is undefined
+            behavior. You may use
+            :ref:`session-level authentication<session-auth-ref>` for such
+            use-cases.
         """
         ...
 
@@ -161,7 +162,7 @@ def handle_security_exception(
         Handle the server indicating authentication failure.
 
         The driver will call this method when the server returns any
-        `Neo.ClientError.Security.*` error. The error will then be processed
+        ``Neo.ClientError.Security.*`` error. The error will then be processed
         further as usual.
 
         :param auth: