Merge branch '6.x' into remove-read-write-transaction

Author: robsdedude

CHANGELOG.md

@@ -52,13 +52,49 @@ See also https://github.com/neo4j/neo4j-python-driver/wiki for a full changelog.
       errors.
     - 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.
 - 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.
 - Remove deprecated class `neo4j.Bookmark` in favor of `neo4j.Bookmarks`.
 - Remove deprecated class `session.last_bookmark()` in favor of `last_bookmarks()`.
-- Make undocumented classes `ResolvedAddress`, `ResolvedIPv4Address`, and `ResolvedIPv6Address` private.
+- Remove deprecated driver configuration option `trust`.  
+  Use `trusted_certificates` instead.
+  - Remove the associated constants `neo4j.TRUST_ALL_CERTIFICATES` and `neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES`.
 - Remove deprecated `session.read_transaction` and `session.write_transaction`.
   Instead, use `session.execute_read` and  `session.execute_write` respectively.
+- Make undocumented classes `ResolvedAddress`, `ResolvedIPv4Address`, and `ResolvedIPv6Address` private.
+- Rework `PreviewWarning`.
+  - Remove `ExperimentalWarning` and turn the few left instances of it into `PreviewWarning`.
+  - Deprecate importing `PreviewWarning` from `neo4j`.  
+    Import it from `neo4j.warnings` instead.
+- Make undocumented internal constants private:
+  - `neo4j.api`
+    - `DRIVER_BOLT`
+    - `DRIVER_NEO4J`
+    - `SECURITY_TYPE_NOT_SECURE`
+    - `SECURITY_TYPE_SECURE`
+    - `SECURITY_TYPE_SELF_SIGNED_CERTIFICATE`
+  - `neo4j.exceptions`
+    - `CLASSIFICATION_CLIENT`
+    - `CLASSIFICATION_DATABASE`
+    - `CLASSIFICATION_TRANSIENT`
+    - `ERROR_REWRITE_MAP`
+    - `client_errors`
+    - `transient_errors`
+- Raise `ConfigurationError` instead of ignoring the routing context (URI query parameters) when creating a direct
+  driver ("bolt[+s[sc]]://" scheme).
+- Change behavior of closed drivers:
+    - Raise `DriverError` on using the closed driver.
+    - Calling `driver.close()` again is now a no-op.
+- No longer implicitly closing drivers and sessions in `__del__()` (finalizer/destructor).
+  Make sure to call `.close()` on them explicitly or use them in a `with` statement.
 
 
 ## Version 5.28

docs/source/api.rst

@@ -370,6 +370,8 @@ Closing a driver will immediately shut down all connections in the pool.
         :returns: the result of the ``result_transformer_``
         :rtype: T
 
+        :raises DriverError: if the driver has been closed.
+
         .. versionadded:: 5.5
 
         .. versionchanged:: 5.8
@@ -384,6 +386,9 @@ Closing a driver will immediately shut down all connections in the pool.
             The ``query_`` parameter now also accepts a :class:`.Query` object
             instead of only :class:`str`.
 
+        .. versionchanged:: 6.0
+            Raise :exc:`DriverError` if the driver has been closed.
+
 
 .. _driver-configuration-ref:
 
@@ -401,7 +406,6 @@ Additional configuration can be provided via the :class:`neo4j.Driver` construct
 + :ref:`max-connection-pool-size-ref`
 + :ref:`max-transaction-retry-time-ref`
 + :ref:`resolver-ref`
-+ :ref:`trust-ref`
 + :ref:`ssl-context-ref`
 + :ref:`trusted-certificates-ref`
 + :ref:`client-certificate-ref`
@@ -568,39 +572,6 @@ For example:
 :Default: :data:`None`
 
 
-.. _trust-ref:
-
-``trust``
----------
-Specify how to determine the authenticity of encryption certificates provided by the Neo4j instance on connection.
-
-This setting is only available for URI schemes ``bolt://`` and ``neo4j://`` (:ref:`uri-ref`).
-
-This setting does not have any effect if ``encrypted`` is set to ``False`` or a
-custom ``ssl_context`` is configured.
-
-:Type: ``neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES``, ``neo4j.TRUST_ALL_CERTIFICATES``
-
-.. py:attribute:: neo4j.TRUST_ALL_CERTIFICATES
-
-   Trust any server certificate (default). This ensures that communication
-   is encrypted but does not verify the server certificate against a
-   certificate authority. This option is primarily intended for use with
-   the default auto-generated server certificate.
-
-.. py:attribute:: neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES
-
-   Trust server certificates that can be verified against the system
-   certificate authority. This option is primarily intended for use with
-   full certificates.
-
-:Default: ``neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES``.
-
-.. deprecated:: 5.0
-    This configuration option is deprecated and will be removed in a future
-    release. Please use :ref:`trusted-certificates-ref` instead.
-
-
 .. _ssl-context-ref:
 
 ``ssl_context``
@@ -2217,9 +2188,9 @@ The Python Driver uses the built-in :class:`python:ResourceWarning` class to war
 .. _development mode: https://docs.python.org/3/library/devmode.html#devmode
 
 
-.. autoclass:: neo4j.PreviewWarning
-
-.. autoclass:: neo4j.ExperimentalWarning
+.. autoclass:: neo4j.warnings.PreviewWarning
+    :show-inheritance:
+    :members:
 
 .. autoclass:: neo4j.warnings.Neo4jWarning
     :show-inheritance:
@@ -2235,12 +2206,12 @@ The Python Driver uses the built-in :class:`python:ResourceWarning` class to war
 Filtering Warnings
 ==================
 
-This example shows how to suppress the :class:`neo4j.PreviewWarning` using the :func:`python:warnings.filterwarnings` function.
+This example shows how to suppress the :class:`neo4j.warnings.PreviewWarning` using the :func:`python:warnings.filterwarnings` function.
 
 .. code-block:: python
 
     import warnings
-    from neo4j import PreviewWarning
+    from neo4j.warnings import PreviewWarning
 
     ...
 
@@ -2250,7 +2221,7 @@ This example shows how to suppress the :class:`neo4j.PreviewWarning` using the :
 
     ...
 
-This will only mute the :class:`neo4j.PreviewWarning` for everything inside
+This will only mute the :class:`neo4j.warnings.PreviewWarning` for everything inside
 the ``with``-block. This is the preferred way to mute warnings, as warnings
 triggerd by new code will still be visible.
 
@@ -2263,7 +2234,7 @@ following code:
 .. code-block:: python
 
     import warnings
-    from neo4j import PreviewWarning
+    from neo4j.warnings import PreviewWarning
 
     warnings.filterwarnings("ignore", category=PreviewWarning)
 

docs/source/async_api.rst

@@ -352,6 +352,8 @@ Closing a driver will immediately shut down all connections in the pool.
         :returns: the result of the ``result_transformer_``
         :rtype: T
 
+        :raises DriverError: if the driver has been closed.
+
         .. versionadded:: 5.5
 
         .. versionchanged:: 5.8
@@ -366,6 +368,9 @@ Closing a driver will immediately shut down all connections in the pool.
             The ``query_`` parameter now also accepts a :class:`.Query` object
             instead of only :class:`str`.
 
+        .. versionchanged:: 6.0
+            Raise :exc:`DriverError` if the driver has been closed.
+
 
 .. _async-driver-configuration-ref:
 

src/neo4j/__init__.py

@@ -43,10 +43,7 @@
 )
 from ._data import Record
 from ._meta import (
-    ExperimentalWarning,
     get_user_agent,
-    preview_warn as _preview_warn,
-    PreviewWarning,
     version as __version__,
 )
 from ._sync.driver import (
@@ -61,6 +58,11 @@
     Session,
     Transaction,
 )
+from ._warnings import (
+    deprecation_warn as _deprecation_warn,
+    preview_warn as _preview_warn,
+    PreviewWarning as _PreviewWarning,
+)
 from ._work import (  # noqa: F401 dynamic attribute
     EagerResult,
     GqlStatusObject as _GqlStatusObject,
@@ -80,6 +82,7 @@
         GqlStatusObject,  # noqa: TCH004 false positive (dynamic attribute)
         NotificationClassification,  # noqa: TCH004 false positive (dynamic attribute)
     )
+    from ._warnings import PreviewWarning  # noqa: TCH004 false positive (dynamic attribute)
 
 from ._addressing import (
     Address,
@@ -100,8 +103,6 @@
     READ_ACCESS,
     ServerInfo,
     SYSTEM_DATABASE,
-    TRUST_ALL_CERTIFICATES,
-    TRUST_SYSTEM_CA_SIGNED_CERTIFICATES,
     WRITE_ACCESS,
 )
 
@@ -110,8 +111,6 @@
     "DEFAULT_DATABASE",
     "READ_ACCESS",
     "SYSTEM_DATABASE",
-    "TRUST_ALL_CERTIFICATES",
-    "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES",
     "WRITE_ACCESS",
     "Address",
     "AsyncBoltDriver",
@@ -128,7 +127,6 @@
     "Bookmarks",
     "Driver",
     "EagerResult",
-    "ExperimentalWarning",
     "GqlStatusObject",
     "GraphDatabase",
     "IPv4Address",
@@ -179,6 +177,14 @@ def __getattr__(name) -> _t.Any:
             stack_level=2,
         )
         return globals()[f"_{name}"]
+    # TODO: 7.0 - remove this
+    if name == "PreviewWarning":
+        _deprecation_warn(
+            f"Importing {name} from `neo4j` is deprecated and will be removed"
+            f"in a future version. Import it from `neo4j.warnings` instead.",
+            stack_level=2,
+        )
+        return _PreviewWarning
     raise AttributeError(f"module {__name__} has no attribute {name}")
 
 

src/neo4j/_api.py

@@ -25,6 +25,11 @@
 
 
 __all__ = [
+    "DRIVER_BOLT",
+    "DRIVER_NEO4J",
+    "SECURITY_TYPE_NOT_SECURE",
+    "SECURITY_TYPE_SECURE",
+    "SECURITY_TYPE_SELF_SIGNED_CERTIFICATE",
     "NotificationCategory",
     "NotificationClassification",
     "NotificationDisabledCategory",
@@ -36,6 +41,16 @@
 ]
 
 
+DRIVER_BOLT: te.Final[str] = "DRIVER_BOLT"
+DRIVER_NEO4J: te.Final[str] = "DRIVER_NEO4J"
+
+SECURITY_TYPE_NOT_SECURE: te.Final[str] = "SECURITY_TYPE_NOT_SECURE"
+SECURITY_TYPE_SELF_SIGNED_CERTIFICATE: te.Final[str] = (
+    "SECURITY_TYPE_SELF_SIGNED_CERTIFICATE"
+)
+SECURITY_TYPE_SECURE: te.Final[str] = "SECURITY_TYPE_SECURE"
+
+
 class NotificationMinimumSeverity(str, Enum):
     """
     Filter notifications returned by the server by minimum severity.

src/neo4j/_async/config.py

@@ -20,9 +20,7 @@
 
 from .._async_compat.concurrency import AsyncLock
 from .._conf import (
-    _trust_to_trusted_certificates,
     Config,
-    DeprecatedAlternative,
     TrustAll,
     TrustCustomCAs,
     TrustSystemCAs,
@@ -57,13 +55,6 @@ class AsyncPoolConfig(Config):
     # The maximum amount of time to wait for a TCP connection to be
     # established.
 
-    #: Trust
-    trust = DeprecatedAlternative(
-        "trusted_certificates", _trust_to_trusted_certificates
-    )
-    # Specify how to determine the authenticity of encryption certificates
-    # provided by the Neo4j instance on connection.
-
     #: Custom Resolver
     resolver = None
     # Custom resolver function, returning list of resolved addresses.