diff --git a/CHANGELOG.md b/CHANGELOG.md index ffe36b39f..ba40b95a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -76,11 +76,9 @@ It now raises a `ResultConsumedError`. - New method `Result.closed()` can be used to check for this condition if necessary. -- `driver.verify_connectivity()` - - All keyword arguments have been deprecated (they were experimental). - They are now ignored and will be removed in a future release. - - The undocumented return value has been removed. If you need information - about the remote server, use `driver.get_server_info()` instead. +- The undocumented return value of `driver.verify_connectivity()` has been + removed. If you need information about the remote server, use + `driver.get_server_info()` instead. - Transaction functions (a.k.a. managed transactions): The first argument of transaction functions is now a `ManagedTransaction` object. It behaves exactly like a regular `Transaction` object, except it diff --git a/neo4j/_async/driver.py b/neo4j/_async/driver.py index 254742ca0..4d171f0db 100644 --- a/neo4j/_async/driver.py +++ b/neo4j/_async/driver.py @@ -16,6 +16,8 @@ # limitations under the License. +import warnings + from .._async_compat.util import AsyncUtil from .._conf import ( TrustAll, @@ -36,6 +38,8 @@ from ..meta import ( deprecation_warn, experimental, + experimental_warn, + ExperimentalWarning, unclosed_resource_warn, ) @@ -310,22 +314,34 @@ async def verify_connectivity(self, **config): Even if this method raises an exception, the driver still needs to be closed via :meth:`close` to free up all resources. + :param config: accepts the same configuration key-word arguments as + :meth:`session`. + + .. warning:: + All configuration key-word arguments are experimental. + They might be changed or removed in any future version without + prior notice. + :raises DriverError: if the driver cannot connect to the remote. Use the exception to further understand the cause of the connectivity problem. - .. versionchanged:: 5.0 the config parameters will be removed in - version 6 0. It has no effect starting with version 5.0. + .. versionchanged:: 5.0 + The undocumented return value has been removed. + If you need information about the remote server, use + :meth:`get_server_info` instead. """ if config: - deprecation_warn( - "verify_connectivity() will not accept any configuration " - "parameters starting with version 6.0." + experimental_warn( + "All configuration key-word arguments to " + "verify_connectivity() are experimental. They might be " + "changed or removed in any future version without prior " + "notice." ) + async with self.session(**config) as session: + await session._get_server_info() - await self.get_server_info() - - async def get_server_info(self): + async def get_server_info(self, **config): """Get information about the connected Neo4j server. Try to establish a working read connection to the remote server or a @@ -339,6 +355,14 @@ async def get_server_info(self): Even if this method raises an exception, the driver still needs to be closed via :meth:`close` to free up all resources. + :param config: accepts the same configuration key-word arguments as + :meth:`session`. + + .. warning:: + All configuration key-word arguments are experimental. + They might be changed or removed in any future version without + prior notice. + :rtype: ServerInfo :raises DriverError: if the driver cannot connect to the remote. @@ -347,7 +371,14 @@ async def get_server_info(self): .. versionadded:: 5.0 """ - async with self.session() as session: + if config: + experimental_warn( + "All configuration key-word arguments to " + "verify_connectivity() are experimental. They might be " + "changed or removed in any future version without prior " + "notice." + ) + async with self.session(**config) as session: return await session._get_server_info() @experimental("Feature support query, based on Bolt protocol version and Neo4j server version will change in the future.") diff --git a/neo4j/_sync/driver.py b/neo4j/_sync/driver.py index 975c7048f..e413197ff 100644 --- a/neo4j/_sync/driver.py +++ b/neo4j/_sync/driver.py @@ -16,6 +16,8 @@ # limitations under the License. +import warnings + from .._async_compat.util import Util from .._conf import ( TrustAll, @@ -36,6 +38,8 @@ from ..meta import ( deprecation_warn, experimental, + experimental_warn, + ExperimentalWarning, unclosed_resource_warn, ) @@ -310,22 +314,34 @@ def verify_connectivity(self, **config): Even if this method raises an exception, the driver still needs to be closed via :meth:`close` to free up all resources. + :param config: accepts the same configuration key-word arguments as + :meth:`session`. + + .. warning:: + All configuration key-word arguments are experimental. + They might be changed or removed in any future version without + prior notice. + :raises DriverError: if the driver cannot connect to the remote. Use the exception to further understand the cause of the connectivity problem. - .. versionchanged:: 5.0 the config parameters will be removed in - version 6 0. It has no effect starting with version 5.0. + .. versionchanged:: 5.0 + The undocumented return value has been removed. + If you need information about the remote server, use + :meth:`get_server_info` instead. """ if config: - deprecation_warn( - "verify_connectivity() will not accept any configuration " - "parameters starting with version 6.0." + experimental_warn( + "All configuration key-word arguments to " + "verify_connectivity() are experimental. They might be " + "changed or removed in any future version without prior " + "notice." ) + with self.session(**config) as session: + session._get_server_info() - self.get_server_info() - - def get_server_info(self): + def get_server_info(self, **config): """Get information about the connected Neo4j server. Try to establish a working read connection to the remote server or a @@ -339,6 +355,14 @@ def get_server_info(self): Even if this method raises an exception, the driver still needs to be closed via :meth:`close` to free up all resources. + :param config: accepts the same configuration key-word arguments as + :meth:`session`. + + .. warning:: + All configuration key-word arguments are experimental. + They might be changed or removed in any future version without + prior notice. + :rtype: ServerInfo :raises DriverError: if the driver cannot connect to the remote. @@ -347,7 +371,14 @@ def get_server_info(self): .. versionadded:: 5.0 """ - with self.session() as session: + if config: + experimental_warn( + "All configuration key-word arguments to " + "verify_connectivity() are experimental. They might be " + "changed or removed in any future version without prior " + "notice." + ) + with self.session(**config) as session: return session._get_server_info() @experimental("Feature support query, based on Bolt protocol version and Neo4j server version will change in the future.") diff --git a/neo4j/meta.py b/neo4j/meta.py index 0e487c2e2..644c3536b 100644 --- a/neo4j/meta.py +++ b/neo4j/meta.py @@ -77,6 +77,10 @@ class ExperimentalWarning(Warning): """ +def experimental_warn(message, stack_level=2): + warn(message, category=ExperimentalWarning, stacklevel=stack_level) + + def experimental(message): """ Decorator for tagging experimental functions and methods. @@ -92,16 +96,14 @@ def decorator(f): if asyncio.iscoroutinefunction(f): @wraps(f) async def inner(*args, **kwargs): - from warnings import warn - warn(message, category=ExperimentalWarning, stacklevel=2) + experimental_warn(message, stack_level=3) return await f(*args, **kwargs) return inner else: @wraps(f) def inner(*args, **kwargs): - from warnings import warn - warn(message, category=ExperimentalWarning, stacklevel=2) + experimental_warn(message, stack_level=3) return f(*args, **kwargs) return inner diff --git a/tests/unit/async_/test_driver.py b/tests/unit/async_/test_driver.py index 9d5b500a7..0b89e45b0 100644 --- a/tests/unit/async_/test_driver.py +++ b/tests/unit/async_/test_driver.py @@ -24,6 +24,7 @@ AsyncBoltDriver, AsyncGraphDatabase, AsyncNeo4jDriver, + ExperimentalWarning, TRUST_ALL_CERTIFICATES, TRUST_SYSTEM_CA_SIGNED_CERTIFICATES, TrustAll, @@ -224,18 +225,42 @@ async def test_verify_connectivity(uri, mocker): "neo4j://127.0.0.1:9000", )) @pytest.mark.parametrize("kwargs", ( - {"access_mode": WRITE_ACCESS}, - {"access_mode": READ_ACCESS}, + {"default_access_mode": WRITE_ACCESS}, + {"default_access_mode": READ_ACCESS}, {"fetch_size": 69}, )) @mark_async_test -async def test_verify_connectivity_parameters_are_deprecated(uri, kwargs, - mocker): +async def test_verify_connectivity_parameters_are_experimental( + uri, kwargs, mocker +): driver = AsyncGraphDatabase.driver(uri) mocker.patch.object(driver, "_pool", autospec=True) try: - with pytest.warns(DeprecationWarning, match="configuration"): + with pytest.warns(ExperimentalWarning, match="configuration"): await driver.verify_connectivity(**kwargs) finally: await driver.close() + + +@pytest.mark.parametrize("uri", ( + "bolt://127.0.0.1:9000", + "neo4j://127.0.0.1:9000", +)) +@pytest.mark.parametrize("kwargs", ( + {"default_access_mode": WRITE_ACCESS}, + {"default_access_mode": READ_ACCESS}, + {"fetch_size": 69}, +)) +@mark_async_test +async def test_get_server_info_parameters_are_experimental( + uri, kwargs, mocker +): + driver = AsyncGraphDatabase.driver(uri) + mocker.patch.object(driver, "_pool", autospec=True) + + try: + with pytest.warns(ExperimentalWarning, match="configuration"): + await driver.get_server_info(**kwargs) + finally: + await driver.close() diff --git a/tests/unit/sync/test_driver.py b/tests/unit/sync/test_driver.py index 918d36f9e..588a7a4f3 100644 --- a/tests/unit/sync/test_driver.py +++ b/tests/unit/sync/test_driver.py @@ -22,6 +22,7 @@ from neo4j import ( BoltDriver, + ExperimentalWarning, GraphDatabase, Neo4jDriver, TRUST_ALL_CERTIFICATES, @@ -224,18 +225,42 @@ def test_verify_connectivity(uri, mocker): "neo4j://127.0.0.1:9000", )) @pytest.mark.parametrize("kwargs", ( - {"access_mode": WRITE_ACCESS}, - {"access_mode": READ_ACCESS}, + {"default_access_mode": WRITE_ACCESS}, + {"default_access_mode": READ_ACCESS}, {"fetch_size": 69}, )) @mark_sync_test -def test_verify_connectivity_parameters_are_deprecated(uri, kwargs, - mocker): +def test_verify_connectivity_parameters_are_experimental( + uri, kwargs, mocker +): driver = GraphDatabase.driver(uri) mocker.patch.object(driver, "_pool", autospec=True) try: - with pytest.warns(DeprecationWarning, match="configuration"): + with pytest.warns(ExperimentalWarning, match="configuration"): driver.verify_connectivity(**kwargs) finally: driver.close() + + +@pytest.mark.parametrize("uri", ( + "bolt://127.0.0.1:9000", + "neo4j://127.0.0.1:9000", +)) +@pytest.mark.parametrize("kwargs", ( + {"default_access_mode": WRITE_ACCESS}, + {"default_access_mode": READ_ACCESS}, + {"fetch_size": 69}, +)) +@mark_sync_test +def test_get_server_info_parameters_are_experimental( + uri, kwargs, mocker +): + driver = GraphDatabase.driver(uri) + mocker.patch.object(driver, "_pool", autospec=True) + + try: + with pytest.warns(ExperimentalWarning, match="configuration"): + driver.get_server_info(**kwargs) + finally: + driver.close()