diff --git a/CHANGELOG.md b/CHANGELOG.md index dbfee64be..69cc2bbd4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -53,13 +53,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 diff --git a/README.rst b/README.rst index 543ee378a..8c44ae607 100644 --- a/README.rst +++ b/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. diff --git a/docs/source/api.rst b/docs/source/api.rst index b9a7fb6b8..4f5a9ec7e 100644 --- a/docs/source/api.rst +++ b/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 @@ -1379,7 +1379,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. diff --git a/docs/source/async_api.rst b/docs/source/async_api.rst index bf277a00a..fc0097287 100644 --- a/docs/source/async_api.rst +++ b/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. diff --git a/docs/source/index.rst b/docs/source/index.rst index 6480c91f8..2f04ddf65 100644 --- a/docs/source/index.rst +++ b/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`). diff --git a/src/neo4j/_addressing.py b/src/neo4j/_addressing.py index fbaa5d91d..3593048df 100644 --- a/src/neo4j/_addressing.py +++ b/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 diff --git a/src/neo4j/_async/config.py b/src/neo4j/_async/config.py index 962f66773..5468d20d8 100644 --- a/src/neo4j/_async/config.py +++ b/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("", ...)`: + # * ``neo4j.TrustSystemCAs()``: Use system trust store. (default) + # * ``neo4j.TrustAll()``: Trust any certificate. + # * ``neo4j.TrustCustomCAs("", ...)``: # 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) diff --git a/src/neo4j/_async/driver.py b/src/neo4j/_async/driver.py index 8f9543967..ea82d37bf 100644 --- a/src/neo4j/_async/driver.py +++ b/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("") - await result1.consume() - # READ_QUERY is guaranteed to see what WRITE_QUERY wrote. - result2 = await session2.run("") - await result2.consume() + default_access_mode=neo4j.READ_ACCESS, + ) as session2, + ): + result1 = await session1.run("") + await result1.consume() + # READ_QUERY is guaranteed to see what WRITE_QUERY wrote. + result2 = await session2.run("") + 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 diff --git a/src/neo4j/_async/io/__init__.py b/src/neo4j/_async/io/__init__.py index 7c950834e..e7a27cba3 100644 --- a/src/neo4j/_async/io/__init__.py +++ b/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__ = [ diff --git a/src/neo4j/_async/io/_pool.py b/src/neo4j/_async/io/_pool.py index 58eeafdaf..0c6f09096 100644 --- a/src/neo4j/_async/io/_pool.py +++ b/src/neo4j/_async/io/_pool.py @@ -963,7 +963,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. @@ -1062,7 +1062,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()): diff --git a/src/neo4j/_async/work/result.py b/src/neo4j/_async/work/result.py index 5f6c40e2b..da6d5e1b4 100644 --- a/src/neo4j/_async/work/result.py +++ b/src/neo4j/_async/work/result.py @@ -435,7 +435,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. @@ -589,9 +589,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 @@ -817,7 +818,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. :: @@ -897,7 +898,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. diff --git a/src/neo4j/_async/work/session.py b/src/neo4j/_async/work/session.py index dbe64b745..90484f469 100644 --- a/src/neo4j/_async/work/session.py +++ b/src/neo4j/_async/work/session.py @@ -73,7 +73,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: @@ -604,7 +604,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). @@ -644,12 +644,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. @@ -683,7 +683,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). @@ -705,9 +705,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 diff --git a/src/neo4j/_async/work/transaction.py b/src/neo4j/_async/work/transaction.py index 459cb6ec4..528ddba67 100644 --- a/src/neo4j/_async/work/transaction.py +++ b/src/neo4j/_async/work/transaction.py @@ -143,8 +143,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}) diff --git a/src/neo4j/_async_compat/network/_util.py b/src/neo4j/_async_compat/network/_util.py index 00ec54199..5d599876f 100644 --- a/src/neo4j/_async_compat/network/_util.py +++ b/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 """ diff --git a/src/neo4j/_auth_management.py b/src/neo4j/_auth_management.py index 98182a1ed..c73a584fa 100644 --- a/src/neo4j/_auth_management.py +++ b/src/neo4j/_auth_management.py @@ -121,7 +121,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` for such use-cases. @@ -132,7 +132,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. @@ -151,9 +151,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` - for such use-cases. + Switching identities using the ``AuthManager`` is undefined + behavior. You may use + :ref:`session-level authentication` for such + use-cases. """ ... @@ -165,7 +166,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: diff --git a/src/neo4j/_codec/hydration/v1/temporal.py b/src/neo4j/_codec/hydration/v1/temporal.py index 0657859a0..f613763cc 100644 --- a/src/neo4j/_codec/hydration/v1/temporal.py +++ b/src/neo4j/_codec/hydration/v1/temporal.py @@ -55,7 +55,7 @@ def get_datetime_unix_epoch_utc(): def hydrate_date(days): """ - Hydrator for `Date` values. + Hydrator for ``Date`` values. :param days: :returns: Date @@ -65,7 +65,7 @@ def hydrate_date(days): def dehydrate_date(value): """ - Dehydrator for `date` values. + Dehydrator for ``date`` values. :param value: :type value: Date @@ -78,7 +78,7 @@ def dehydrate_date(value): def hydrate_time(nanoseconds, tz=None): """ - Hydrator for `Time` and `LocalTime` values. + Hydrator for ``Time`` and ``LocalTime`` values. :param nanoseconds: :param tz: @@ -99,7 +99,7 @@ def hydrate_time(nanoseconds, tz=None): def dehydrate_time(value): """ - Dehydrator for `time` values. + Dehydrator for ``time`` values. :param value: :type value: Time @@ -128,7 +128,7 @@ def dehydrate_time(value): def hydrate_datetime(seconds, nanoseconds, tz=None): """ - Hydrator for `DateTime` and `LocalDateTime` values. + Hydrator for ``DateTime`` and ``LocalDateTime`` values. :param seconds: :param nanoseconds: @@ -159,7 +159,7 @@ def hydrate_datetime(seconds, nanoseconds, tz=None): def dehydrate_datetime(value): """ - Dehydrator for `datetime` values. + Dehydrator for ``datetime`` values. :param value: :type value: datetime or DateTime @@ -208,7 +208,7 @@ def seconds_and_nanoseconds(dt): def dehydrate_np_datetime(value): """ - Dehydrator for `numpy.datetime64` values. + Dehydrator for ``numpy.datetime64`` values. :param value: :type value: numpy.datetime64 @@ -235,7 +235,7 @@ def dehydrate_np_datetime(value): def dehydrate_pandas_datetime(value): """ - Dehydrator for `pandas.Timestamp` values. + Dehydrator for ``pandas.Timestamp`` values. :param value: :type value: pandas.Timestamp @@ -257,13 +257,13 @@ def dehydrate_pandas_datetime(value): def hydrate_duration(months, days, seconds, nanoseconds): """ - Hydrator for `Duration` values. + Hydrator for ``Duration`` values. :param months: :param days: :param seconds: :param nanoseconds: - :returns: `duration` namedtuple + :returns: ``duration`` namedtuple """ return Duration( months=months, days=days, seconds=seconds, nanoseconds=nanoseconds @@ -272,7 +272,7 @@ def hydrate_duration(months, days, seconds, nanoseconds): def dehydrate_duration(value): """ - Dehydrator for `duration` values. + Dehydrator for ``duration`` values. :param value: :type value: Duration @@ -285,7 +285,7 @@ def dehydrate_duration(value): def dehydrate_timedelta(value): """ - Dehydrator for `timedelta` values. + Dehydrator for ``timedelta`` values. :param value: :type value: timedelta @@ -314,7 +314,7 @@ def dehydrate_timedelta(value): def dehydrate_np_timedelta(value): """ - Dehydrator for `numpy.timedelta64` values. + Dehydrator for ``numpy.timedelta64`` values. :param value: :type value: numpy.timedelta64 @@ -337,7 +337,7 @@ def dehydrate_np_timedelta(value): def dehydrate_pandas_timedelta(value): """ - Dehydrator for `pandas.Timedelta` values. + Dehydrator for ``pandas.Timedelta`` values. :param value: :type value: pandas.Timedelta diff --git a/src/neo4j/_codec/hydration/v2/temporal.py b/src/neo4j/_codec/hydration/v2/temporal.py index 4d8555a9f..ca38ca461 100644 --- a/src/neo4j/_codec/hydration/v2/temporal.py +++ b/src/neo4j/_codec/hydration/v2/temporal.py @@ -32,7 +32,7 @@ def hydrate_datetime(seconds, nanoseconds, tz=None): # type: ignore[no-redef] """ - Hydrator for `DateTime` and `LocalDateTime` values. + Hydrator for ``DateTime`` and ``LocalDateTime`` values. :param seconds: :param nanoseconds: @@ -61,7 +61,7 @@ def hydrate_datetime(seconds, nanoseconds, tz=None): # type: ignore[no-redef] def dehydrate_datetime(value): # type: ignore[no-redef] """ - Dehydrator for `datetime` values. + Dehydrator for ``datetime`` values. :param value: :type value: datetime @@ -113,7 +113,7 @@ def seconds_and_nanoseconds(dt): def dehydrate_pandas_datetime(value): """ - Dehydrator for `pandas.Timestamp` values. + Dehydrator for ``pandas.Timestamp`` values. :param value: :type value: pandas.Timestamp diff --git a/src/neo4j/_conf.py b/src/neo4j/_conf.py index 6f3966c9f..58d3c5245 100644 --- a/src/neo4j/_conf.py +++ b/src/neo4j/_conf.py @@ -34,9 +34,9 @@ def iter_items(iterable): """ Iterate through key-value pairs of a dict-like object. - If the object has a `keys` method, this is used along with `__getitem__` - to yield each pair in turn. If no `keys` method exists, each iterable - element is assumed to be a 2-tuple of key and value. + If the object has a ``keys`` method, this is used along with + ``__getitem__`` to yield each pair in turn. If no ``keys`` method exists, + each iterable element is assumed to be a 2-tuple of key and value. """ if hasattr(iterable, "keys"): for key in iterable: diff --git a/src/neo4j/_meta.py b/src/neo4j/_meta.py index eeb851806..c654f5d22 100644 --- a/src/neo4j/_meta.py +++ b/src/neo4j/_meta.py @@ -29,7 +29,7 @@ # Can be automatically overridden in builds package = "neo4j" -version = "5.28.dev0" +version = "6.0.dev0" def _compute_bolt_agent() -> dict[str, str]: diff --git a/src/neo4j/_sync/config.py b/src/neo4j/_sync/config.py index 5eb389e25..e528ab074 100644 --- a/src/neo4j/_sync/config.py +++ b/src/neo4j/_sync/config.py @@ -67,9 +67,9 @@ class PoolConfig(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("", ...)`: + # * ``neo4j.TrustSystemCAs()``: Use system trust store. (default) + # * ``neo4j.TrustAll()``: Trust any certificate. + # * ``neo4j.TrustCustomCAs("", ...)``: # Trust the specified certificate(s). #: Certificate to use for mTLS as 2nd authentication factor. @@ -78,7 +78,7 @@ class PoolConfig(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) diff --git a/src/neo4j/_sync/driver.py b/src/neo4j/_sync/driver.py index 70f0f478e..36d7fb3c3 100644 --- a/src/neo4j/_sync/driver.py +++ b/src/neo4j/_sync/driver.py @@ -300,18 +300,18 @@ def bookmark_manager( driver = neo4j.GraphDatabase.driver(...) bookmark_manager = neo4j.GraphDatabase.bookmark_manager(...) - with driver.session( - bookmark_manager=bookmark_manager - ) as session1: - with driver.session( + with ( + driver.session(bookmark_manager=bookmark_manager) as session1, + driver.session( bookmark_manager=bookmark_manager, - access_mode=neo4j.READ_ACCESS - ) as session2: - result1 = session1.run("") - result1.consume() - # READ_QUERY is guaranteed to see what WRITE_QUERY wrote. - result2 = session2.run("") - result2.consume() + default_access_mode=neo4j.READ_ACCESS, + ) as session2, + ): + result1 = session1.run("") + result1.consume() + # READ_QUERY is guaranteed to see what WRITE_QUERY wrote. + result2 = session2.run("") + 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 diff --git a/src/neo4j/_sync/io/__init__.py b/src/neo4j/_sync/io/__init__.py index 775fd504d..5a66c1feb 100644 --- a/src/neo4j/_sync/io/__init__.py +++ b/src/neo4j/_sync/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__ = [ diff --git a/src/neo4j/_sync/io/_pool.py b/src/neo4j/_sync/io/_pool.py index 1819ad08c..787ef3046 100644 --- a/src/neo4j/_sync/io/_pool.py +++ b/src/neo4j/_sync/io/_pool.py @@ -960,7 +960,7 @@ 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. @@ -1059,7 +1059,8 @@ 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. """ with self.refresh_lock: for database_ in list(self.routing_tables.keys()): diff --git a/src/neo4j/_sync/work/result.py b/src/neo4j/_sync/work/result.py index 865cffd9f..5c104a60e 100644 --- a/src/neo4j/_sync/work/result.py +++ b/src/neo4j/_sync/work/result.py @@ -435,7 +435,7 @@ def _attach(self): 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. @@ -589,9 +589,10 @@ 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 @@ -817,7 +818,7 @@ 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. :: @@ -897,7 +898,7 @@ 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. diff --git a/src/neo4j/_sync/work/session.py b/src/neo4j/_sync/work/session.py index 1db33478a..d416a087e 100644 --- a/src/neo4j/_sync/work/session.py +++ b/src/neo4j/_sync/work/session.py @@ -73,7 +73,7 @@ class Session(Workspace): 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:: with driver.session(database="neo4j") as session: @@ -604,7 +604,7 @@ 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). @@ -644,12 +644,12 @@ def get_two_tx(tx): :class:`.ManagedTransaction`. :type transaction_function: typing.Callable[[ManagedTransaction, P], typing.Union[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. @@ -683,7 +683,7 @@ 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). @@ -705,9 +705,9 @@ def create_node_tx(tx, name): :class:`.ManagedTransaction`. :type transaction_function: typing.Callable[[ManagedTransaction, P], typing.Union[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 diff --git a/src/neo4j/_sync/work/transaction.py b/src/neo4j/_sync/work/transaction.py index aef7a6738..2bc22d966 100644 --- a/src/neo4j/_sync/work/transaction.py +++ b/src/neo4j/_sync/work/transaction.py @@ -143,8 +143,8 @@ 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 = tx.run(query, {"name": "Alice", "age": 33}) diff --git a/src/neo4j/_work/summary.py b/src/neo4j/_work/summary.py index 6e101c7aa..707e484bd 100644 --- a/src/neo4j/_work/summary.py +++ b/src/neo4j/_work/summary.py @@ -61,8 +61,8 @@ class ResultSummary: parameters: dict[str, t.Any] | None #: A string that describes the type of query - # ``'r'`` = read-only, ``'rw'`` = read/write, ``'w'`` = write-only, - # ``'s'`` = schema. + #: ``'r'`` = read-only, ``'rw'`` = read/write, ``'w'`` = write-only, + #: ``'s'`` = schema. query_type: t.Literal["r", "rw", "w", "s"] | None #: A :class:`neo4j.SummaryCounters` instance. Counters for operations the @@ -85,10 +85,10 @@ class ResultSummary: #: see :attr:`.notifications` _notifications: list[dict] | None - # cache for property `summary_notifications` + # cache for property ``summary_notifications`` _summary_notifications: tuple[SummaryNotification, ...] - # cache for property `summary_notifications` + # cache for property ``summary_notifications`` _gql_status_objects: tuple[GqlStatusObject, ...] _had_key: bool diff --git a/src/neo4j/api.py b/src/neo4j/api.py index 0f7955a7a..e5e70c89b 100644 --- a/src/neo4j/api.py +++ b/src/neo4j/api.py @@ -296,8 +296,8 @@ def protocol_version(self) -> tuple[int, int]: """ Bolt protocol version with which the remote server communicates. - This is returned as a 2-tuple:class:`tuple` (subclass) of - ``(major, minor)`` integers. + This is returned as a 2-tuple:class:`tuple` of ``(major, minor)`` + integers. """ return self._protocol_version diff --git a/src/neo4j/time/__init__.py b/src/neo4j/time/__init__.py index 2c7afa93d..caf958625 100644 --- a/src/neo4j/time/__init__.py +++ b/src/neo4j/time/__init__.py @@ -206,15 +206,15 @@ def _normalize_day(year, month, day): # TODO: 7.0 - make private class ClockTime(tuple): """ - A count of `seconds` and `nanoseconds`. + A count of ``seconds`` and ``nanoseconds``. This class can be used to mark a particular point in time, relative to an externally-specified epoch. - The `seconds` and `nanoseconds` values provided to the constructor can + The ``seconds`` and ``nanoseconds`` values provided to the constructor can can have any sign but will be normalized internally into a positive or - negative `seconds` value along with a positive `nanoseconds` value - between `0` and `999,999,999`. Therefore, ``ClockTime(-1, -1)`` is + negative ``seconds`` value along with a positive ``nanoseconds`` value + between ``0`` and ``999,999,999``. Therefore, ``ClockTime(-1, -1)`` is normalized to ``ClockTime(-2, 999999999)``. Note that the structure of a :class:`.ClockTime` object is similar to @@ -328,7 +328,7 @@ def precision(cls): The precision of this clock implementation, represented as a number of decimal places. Therefore, for a nanosecond precision - clock, this function returns `9`. + clock, this function returns ``9``. """ raise NotImplementedError("No clock implementation selected") @@ -357,8 +357,8 @@ def local_offset(cls): :raises OverflowError: """ # Adding and subtracting two days to avoid passing a pre-epoch time to - # `mktime`, which can cause a `OverflowError` on some platforms (e.g., - # Windows). + # ``mktime``, which can cause a ``OverflowError`` on some platforms + # (e.g., Windows). return _ClockTime(-int(_mktime(_gmtime(172800))) + 172800) def local_time(self): @@ -399,11 +399,12 @@ class Duration( # type: ignore[misc] r""" A difference between two points in time. - A :class:`.Duration` represents the difference between two points in time. - Duration objects store a composite value of `months`, `days`, `seconds`, - and `nanoseconds`. Unlike :class:`datetime.timedelta` however, days, and - seconds/nanoseconds are never interchanged. All values except seconds and - nanoseconds are applied separately in calculations (element-wise). + A :class:`.Duration` represents the difference between two points in + time. Duration objects store a composite value of ``months``, ``days``, + ``seconds``, and ``nanoseconds``. Unlike :class:`datetime.timedelta` + however, days, and seconds/nanoseconds are never interchanged. All values + except seconds and nanoseconds are applied separately in calculations + (element-wise). A :class:`.Duration` stores four primary instance attributes internally: ``months``, ``days``, ``seconds`` and ``nanoseconds``. These are maintained @@ -425,16 +426,17 @@ class Duration( # type: ignore[misc] This value must be between -(2\ :sup:`63`) and (2\ :sup:`63` - 1) inclusive. - :param years: will be added times 12 to `months` - :param months: will be truncated to :class:`int` (`int(months)`) - :param weeks: will be added times 7 to `days` - :param days: will be truncated to :class:`int` (`int(days)`) - :param hours: will be added times 3,600,000,000,000 to `nanoseconds` - :param minutes: will be added times 60,000,000,000 to `nanoseconds` - :param seconds: will be added times 1,000,000,000 to `nanoseconds`` - :param milliseconds: will be added times 1,000,000 to `nanoseconds` - :param microseconds: will be added times 1,000 to `nanoseconds` - :param nanoseconds: will be truncated to :class:`int` (`int(nanoseconds)`) + :param years: will be added times 12 to ``months`` + :param months: will be truncated to :class:`int` (``int(months)``) + :param weeks: will be added times 7 to ``days`` + :param days: will be truncated to :class:`int` (``int(days)``) + :param hours: will be added times 3,600,000,000,000 to ``nanoseconds`` + :param minutes: will be added times 60,000,000,000 to ``nanoseconds`` + :param seconds: will be added times 1,000,000,000 to ``nanoseconds`` + :param milliseconds: will be added times 1,000,000 to ``nanoseconds`` + :param microseconds: will be added times 1,000 to ``nanoseconds`` + :param nanoseconds: + will be truncated to :class:`int` (``int(nanoseconds)``) :raises ValueError: the components exceed the limits as described above. """ @@ -819,13 +821,13 @@ class Date(_date_base_class, metaclass=_DateType): `proleptic Gregorian Calendar `_. - Years between `0001` and `9999` are supported, with additional support for - the "zero date" used in some contexts. + Years between ``0001`` and ``9999`` are supported, with additional + support for the "zero date" used in some contexts. - Each date is based on a proleptic Gregorian ordinal, which models - 1 Jan 0001 as `day 1` and counts each subsequent day up to, and including, - 31 Dec 9999. The standard `year`, `month` and `day` value of each date is - also available. + Each date is based on a proleptic Gregorian ordinal, which models 1 Jan + 0001 as ``day 1`` and counts each subsequent day up to, and including, + 31 Dec 9999. The standard ``year``, ``month`` and ``day`` value of each + date is also available. Internally, the day of the month is always stored as-is, except for the last three days of that month. These are always stored as -1, -2 and -3 @@ -915,7 +917,7 @@ def utc_from_timestamp(cls, timestamp: float) -> Date: """ Construct :class:`.Date` from a time stamp (seconds since unix epoch). - :returns: the `Date` as local date `Date` in UTC. + :returns: the :class:`Date` as local date :class:`Date` in UTC. """ return cls._from_clock_time((timestamp, 0), UnixEpoch) @@ -924,7 +926,7 @@ def from_ordinal(cls, ordinal: int) -> Date: """ Construct :class:`.Date` from the proleptic Gregorian ordinal. - `0001-01-01` has ordinal 1 and `9999-12-31` has ordinal 3,652,059. + ``0001-01-01`` has ordinal 1 and ``9999-12-31`` has ordinal 3,652,059. Values outside of this range trigger a :exc:`ValueError`. The corresponding instance method for the reverse date-to-ordinal transformation is :meth:`.to_ordinal`. @@ -987,7 +989,7 @@ def from_iso_format(cls, s: str) -> Date: @classmethod def from_native(cls, d: _date) -> Date: """ - Convert from a native Python `datetime.date` value. + Convert from a native Python :class:`datetime.date` value. :param d: the date to convert. """ @@ -1009,7 +1011,7 @@ def from_clock_time( :param clock_time: the clock time as :class:`.ClockTime` or as tuple of (seconds, nanoseconds) - :param epoch: the epoch to which `clock_time` is relative + :param epoch: the epoch to which ``clock_time`` is relative .. deprecated:: 6.0 :class:`ClockTime` is an implementation detail. @@ -1036,11 +1038,11 @@ def _from_clock_time( @classmethod def is_leap_year(cls, year: int) -> bool: """ - Indicate whether `year` is a leap year. + Indicate whether ``year`` is a leap year. :param year: the year to look up - :raises ValueError: if `year` is out of range: + :raises ValueError: if ``year`` is out of range: :attr:`MIN_YEAR` <= year <= :attr:`MAX_YEAR` """ if year < MIN_YEAR or year > MAX_YEAR: @@ -1050,11 +1052,11 @@ def is_leap_year(cls, year: int) -> bool: @classmethod def days_in_year(cls, year: int) -> int: """ - Return the number of days in `year`. + Return the number of days in ``year``. :param year: the year to look up - :raises ValueError: if `year` is out of range: + :raises ValueError: if ``year`` is out of range: :attr:`MIN_YEAR` <= year <= :attr:`MAX_YEAR` """ if year < MIN_YEAR or year > MAX_YEAR: @@ -1064,12 +1066,12 @@ def days_in_year(cls, year: int) -> int: @classmethod def days_in_month(cls, year: int, month: int) -> int: """ - Return the number of days in `month` of `year`. + Return the number of days in ``month`` of ``year``. :param year: the year to look up :param month: the month to look up - :raises ValueError: if `year` or `month` is out of range: + :raises ValueError: if ``year`` or ``month`` is out of range: :attr:`MIN_YEAR` <= year <= :attr:`MAX_YEAR`; 1 <= year <= 12 """ @@ -1167,7 +1169,7 @@ def year_week_day(self) -> tuple[int, int, int]: """ 3-tuple of (year, week_of_year, day_of_week) describing the date. - `day_of_week` will be 1 for Monday and 7 for Sunday. + ``day_of_week`` will be 1 for Monday and 7 for Sunday. """ ordinal = self.__ordinal year = self.__year @@ -1202,7 +1204,7 @@ def year_day(self) -> tuple[int, int]: 2-tuple of (year, day_of_the_year) describing the date. This is the number of the day relative to the start of the year, - with `1 Jan` corresponding to `1`. + with ``1 Jan`` corresponding to ``1``. """ return ( self.__year, @@ -1343,11 +1345,11 @@ def replace(self, **kwargs) -> Date: :Keyword Arguments: * **year** (:class:`typing.SupportsIndex`): - overwrite the year - default: `self.year` + overwrite the year - default: ``self.year`` * **month** (:class:`typing.SupportsIndex`): - overwrite the month - default: `self.month` + overwrite the month - default: ``self.month`` * **day** (:class:`typing.SupportsIndex`): - overwrite the day - default: `self.day` + overwrite the day - default: ``self.day`` """ return Date( int(kwargs.get("year", self.__year)), @@ -1389,7 +1391,7 @@ def to_ordinal(self) -> int: ) def to_clock_time(self, epoch: Date | DateTime) -> ClockTime: """ - Convert the date to :class:`ClockTime` relative to `epoch`'s date. + Convert the date to :class:`ClockTime` relative to ``epoch``'s date. :param epoch: the epoch to which the date is relative @@ -1481,8 +1483,8 @@ def iso_calendar(self) -> tuple[int, int, int]: ... Date.max = Date.from_ordinal(3652059) # type: ignore Date.resolution = Duration(days=1) # type: ignore -#: A :class:`neo4j.time.Date` instance set to `0000-00-00`. -#: This has an ordinal value of `0`. +#: A :class:`neo4j.time.Date` instance set to ``0000-00-00``. +#: This has an ordinal value of ``0``. ZeroDate = object.__new__(Date) @@ -1544,8 +1546,8 @@ class Time(_time_base_class, metaclass=_TimeType): :class:`neo4j.time.Time` objects introduce the concept of ``ticks``. This is simply a count of the number of nanoseconds since midnight, in many ways analogous to the :class:`neo4j.time.Date` ordinal. - `ticks` values are integers, with a minimum value of `0` and a maximum - of `86_399_999_999_999`. + ``ticks`` values are integers, with a minimum value of ``0`` and a maximum + of ``86_399_999_999_999``. Local times are represented by :class:`.Time` with no ``tzinfo``. @@ -1749,7 +1751,7 @@ def from_clock_time( :param clock_time: the clock time as :class:`.ClockTime` or as tuple of (seconds, nanoseconds) - :param epoch: the epoch to which `clock_time` is relative + :param epoch: the epoch to which ``clock_time`` is relative .. deprecated:: 6.0 :class:`ClockTime` is an implementation detail. @@ -1996,15 +1998,15 @@ def replace(self, **kwargs) -> Time: :Keyword Arguments: * **hour** (:class:`typing.SupportsIndex`): - overwrite the hour - default: `self.hour` + overwrite the hour - default: ``self.hour`` * **minute** (:class:`typing.SupportsIndex`): - overwrite the minute - default: `self.minute` + overwrite the minute - default: ``self.minute`` * **second** (:class:`typing.SupportsIndex`): - overwrite the second - default: `int(self.second)` + overwrite the second - default: ``int(self.second)`` * **nanosecond** (:class:`typing.SupportsIndex`): - overwrite the nanosecond - default: `self.nanosecond` - * **tzinfo** (:class:`datetime.tzinfo` or `None`): - overwrite the timezone - default: `self.tzinfo` + overwrite the nanosecond - default: ``self.nanosecond`` + * **tzinfo** (:class:`datetime.tzinfo` or :data:`None`): + overwrite the timezone - default: ``self.tzinfo`` """ return Time( hour=int(kwargs.get("hour", self.__hour)), @@ -2039,11 +2041,11 @@ def utc_offset(self) -> _timedelta | None: Return the UTC offset of this time. :returns: None if this is a local time (:attr:`.tzinfo` is None), else - returns `self.tzinfo.utcoffset(self)`. + returns ``self.tzinfo.utcoffset(self)``. - :raises ValueError: if `self.tzinfo.utcoffset(self)` is not None and a - :class:`timedelta` with a magnitude greater equal 1 day or that is - not a whole number of minutes. + :raises ValueError: if ``self.tzinfo.utcoffset(self)`` is not None and + a :class:`timedelta` with a magnitude greater equal 1 day or that + is not a whole number of minutes. :raises TypeError: if `self.tzinfo.utcoffset(self)` does return anything but :data:`None` or a :class:`datetime.timedelta`. """ @@ -2054,13 +2056,13 @@ def dst(self) -> _timedelta | None: Get the daylight saving time adjustment (DST). :returns: None if this is a local time (:attr:`.tzinfo` is None), else - returns `self.tzinfo.dst(self)`. + returns ``self.tzinfo.dst(self)``. - :raises ValueError: if `self.tzinfo.dst(self)` is not None and a + :raises ValueError: if ``self.tzinfo.dst(self)`` is not None and a :class:`timedelta` with a magnitude greater equal 1 day or that is not a whole number of minutes. - :raises TypeError: if `self.tzinfo.dst(self)` does return anything but - None or a :class:`datetime.timedelta`. + :raises TypeError: if ``self.tzinfo.dst(self)`` does return anything + but None or a :class:`datetime.timedelta`. """ return _dst(self.tzinfo, None) @@ -2069,7 +2071,7 @@ def tzname(self) -> str | None: Get the name of the :class:`.Time`'s timezone. :returns: None if the time is local (i.e., has no timezone), else - return `self.tzinfo.tzname(self)` + return ``self.tzinfo.tzname(self)`` """ return _tz_name(self.tzinfo, None) @@ -2096,7 +2098,7 @@ def _to_clock_time(self) -> ClockTime: def to_native(self) -> _time: """ - Convert to a native Python `datetime.time` value. + Convert to a native Python :class:`datetime.time` value. This conversion is lossy as the native time implementation only supports a resolution of microseconds instead of nanoseconds. @@ -2176,12 +2178,12 @@ def isoformat(self) -> str: # type: ignore[override] nanoseconds=1 ) -#: A :class:`.Time` instance set to `00:00:00`. -#: This has a :attr:`.ticks` value of `0`. +#: A :class:`.Time` instance set to ``00:00:00``. +#: This has a :attr:`.ticks` value of ``0``. Midnight: _t.Final[Time] = Time.min -#: A :class:`.Time` instance set to `12:00:00`. -#: This has a :attr:`.ticks` value of `43200000000000`. +#: A :class:`.Time` instance set to ``12:00:00``. +#: This has a :attr:`.ticks` value of ``43200000000000``. Midday: _t.Final[Time] = Time(hour=12) @@ -2206,17 +2208,18 @@ class DateTime(_date_time_base_class, metaclass=_DateTimeType): A :class:`.DateTime` object is fully compatible with the Python time zone library `pytz `_. Functions such as - `normalize` and `localize` can be used in the same way as they are with the - standard library classes. + ``normalize`` and ``localize`` can be used in the same way as they are with + the standard library classes. Regular construction of a :class:`.DateTime` object requires at - least the `year`, `month` and `day` arguments to be supplied. The - optional `hour`, `minute` and `second` arguments default to zero and - `tzinfo` defaults to :data:`None`. + least the ``year``, ``month`` and ``day`` arguments to be supplied. The + optional ``hour``, ``minute`` and ``second`` arguments default to zero and + ``tzinfo`` defaults to :data:`None`. - `year`, `month`, and `day` are passed to the constructor of :class:`.Date`. - `hour`, `minute`, `second`, `nanosecond`, and `tzinfo` are passed to the - constructor of :class:`.Time`. See their documentation for more details. + ``year``, ``month``, and ``day`` are passed to the constructor of + :class:`.Date`. ``hour``, ``minute``, ``second``, ``nanosecond``, and + ``tzinfo`` are passed to the constructor of :class:`.Time`. See their + documentation for more details. >>> dt = DateTime(2018, 4, 30, 12, 34, 56, 789123456); dt neo4j.time.DateTime(2018, 4, 30, 12, 34, 56, 789123456) @@ -2331,7 +2334,7 @@ def utc_from_timestamp(cls, timestamp: float) -> DateTime: """ :class:`.DateTime` from a time stamp (seconds since unix epoch). - Returns the `DateTime` as local date `DateTime` in UTC. + Returns the :class:`.DateTime` as local date :class:`.DateTime` in UTC. """ return cls._from_clock_time((timestamp, 0), UnixEpoch) @@ -2398,9 +2401,9 @@ def from_clock_time( :param clock_time: the clock time as :class:`.ClockTime` or as tuple of (seconds, nanoseconds) - :param epoch: the epoch to which `clock_time` is relative + :param epoch: the epoch to which ``clock_time`` is relative - :raises ValueError: if `clock_time` is invalid. + :raises ValueError: if ``clock_time`` is invalid. .. deprecated:: 6.0 :class:`ClockTime` is an implementation detail. @@ -2968,9 +2971,9 @@ def iso_format(self, sep: str = "T") -> str: """ Return the :class:`.DateTime` as ISO formatted string. - This method joins `self.date().iso_format()` (see - :meth:`.Date.iso_format`) and `self.timetz().iso_format()` (see - :meth:`.Time.iso_format`) with `sep` in between. + This method joins ``self.date().iso_format()`` (see + :meth:`.Date.iso_format`) and ``self.timetz().iso_format()`` (see + :meth:`.Time.iso_format`) with ``sep`` in between. :param sep: the separator between the formatted date and time. """ @@ -3061,11 +3064,11 @@ def iso_format(self, sep: str = "T") -> str: # type: ignore[override] DateTime.max = DateTime.combine(Date.max, Time.max) # type: ignore DateTime.resolution = Time.resolution # type: ignore -#: A :class:`.DateTime` instance set to `0000-00-00T00:00:00`. +#: A :class:`.DateTime` instance set to ``0000-00-00T00:00:00``. #: This has a :class:`.Date` component equal to :attr:`ZeroDate` and a Never = DateTime.combine(ZeroDate, Midnight) -#: A :class:`.DateTime` instance set to `1970-01-01T00:00:00`. +#: A :class:`.DateTime` instance set to ``1970-01-01T00:00:00``. UnixEpoch = DateTime(1970, 1, 1, 0, 0, 0) diff --git a/testkitbackend/test_config.json b/testkitbackend/test_config.json index 0c784bc78..70cd4836f 100644 --- a/testkitbackend/test_config.json +++ b/testkitbackend/test_config.json @@ -8,8 +8,6 @@ "Flaky: test requires the driver to contact servers in a specific order", "'stub.session_run_parameters.test_session_run_parameters.TestSessionRunParameters.test_empty_query'": "Driver rejects empty queries before sending it to the server", - "'stub.server_side_routing.test_server_side_routing.TestServerSideRouting.test_direct_connection_with_url_params'": - "Driver emits deprecation warning. Behavior will be unified in 6.0.", "'neo4j.datatypes.test_temporal_types.TestDataTypes.test_should_echo_all_timezone_ids'": "test_subtest_skips.dt_conversion", "'neo4j.datatypes.test_temporal_types.TestDataTypes.test_date_time_cypher_created_tz_id'": diff --git a/tests/unit/async_/fixtures/fake_connection.py b/tests/unit/async_/fixtures/fake_connection.py index 42caf6168..22e22dfbb 100644 --- a/tests/unit/async_/fixtures/fake_connection.py +++ b/tests/unit/async_/fixtures/fake_connection.py @@ -157,23 +157,23 @@ def set_script(self, callbacks): Set a scripted sequence of callbacks. :param callbacks: The callbacks. They should be a list of 2-tuples. - `("name_of_message", {"callback_name": arguments})`. E.g., - ``` - [ - ("run", {"on_success": ({},), "on_summary": None}), - ("pull", { - "on_records": ([some_record],), - "on_success": None, - "on_summary": None, - }) - # use any exception to throw it instead of calling handlers - ("commit", RuntimeError("oh no!")) - ] - ``` - Note that arguments can be `None`. In this case, + ``("name_of_message", {"callback_name": arguments})``. E.g., :: + + [ + ("run", {"on_success": ({},), "on_summary": None}), + ("pull", { + "on_records": ([some_record],), + "on_success": None, + "on_summary": None, + }) + # use any exception to throw it instead of calling handlers + ("commit", RuntimeError("oh no!")) + ] + + Note that arguments can be :data:`None`. In this case, ScriptedConnection will make a guess on best-suited default arguments. - """ + """ # noqa: E501 example code isn't too long self._script = callbacks self._script_pos = 0 diff --git a/tests/unit/sync/fixtures/fake_connection.py b/tests/unit/sync/fixtures/fake_connection.py index d487a02e6..df2618862 100644 --- a/tests/unit/sync/fixtures/fake_connection.py +++ b/tests/unit/sync/fixtures/fake_connection.py @@ -157,23 +157,23 @@ def set_script(self, callbacks): Set a scripted sequence of callbacks. :param callbacks: The callbacks. They should be a list of 2-tuples. - `("name_of_message", {"callback_name": arguments})`. E.g., - ``` - [ - ("run", {"on_success": ({},), "on_summary": None}), - ("pull", { - "on_records": ([some_record],), - "on_success": None, - "on_summary": None, - }) - # use any exception to throw it instead of calling handlers - ("commit", RuntimeError("oh no!")) - ] - ``` - Note that arguments can be `None`. In this case, + ``("name_of_message", {"callback_name": arguments})``. E.g., :: + + [ + ("run", {"on_success": ({},), "on_summary": None}), + ("pull", { + "on_records": ([some_record],), + "on_success": None, + "on_summary": None, + }) + # use any exception to throw it instead of calling handlers + ("commit", RuntimeError("oh no!")) + ] + + Note that arguments can be :data:`None`. In this case, ScriptedConnection will make a guess on best-suited default arguments. - """ + """ # noqa: E501 example code isn't too long self._script = callbacks self._script_pos = 0