From 68cc2a7a2c850957a2b643c745185c61a9d52219 Mon Sep 17 00:00:00 2001 From: Robsdedude Date: Wed, 28 May 2025 10:51:11 +0200 Subject: [PATCH 1/2] Clean up docs & bump meta data for 6.0 --- README.rst | 13 +- docs/source/api.rst | 18 +- docs/source/async_api.rst | 2 +- docs/source/index.rst | 1 - requirements-dev.txt | 2 +- src/neo4j/_async/config.py | 8 +- src/neo4j/_async/driver.py | 22 +-- src/neo4j/_async/io/__init__.py | 4 +- src/neo4j/_async/io/_pool.py | 5 +- src/neo4j/_async/work/result.py | 13 +- src/neo4j/_async/work/session.py | 16 +- src/neo4j/_async/work/transaction.py | 4 +- src/neo4j/_async_compat/network/_util.py | 4 +- src/neo4j/_auth_management.py | 13 +- src/neo4j/_codec/hydration/v1/temporal.py | 28 +-- src/neo4j/_codec/hydration/v2/temporal.py | 6 +- src/neo4j/_conf.py | 6 +- src/neo4j/_meta.py | 2 +- src/neo4j/_sync/config.py | 8 +- src/neo4j/_sync/driver.py | 22 +-- src/neo4j/_sync/io/__init__.py | 4 +- src/neo4j/_sync/io/_pool.py | 5 +- src/neo4j/_sync/work/result.py | 13 +- src/neo4j/_sync/work/session.py | 16 +- src/neo4j/_sync/work/transaction.py | 4 +- src/neo4j/_work/summary.py | 8 +- src/neo4j/api.py | 4 +- src/neo4j/time/__init__.py | 173 +++++++++--------- tests/unit/async_/fixtures/fake_connection.py | 30 +-- tests/unit/sync/fixtures/fake_connection.py | 30 +-- 30 files changed, 242 insertions(+), 242 deletions(-) diff --git a/README.rst b/README.rst index 543ee378..8c44ae60 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 dbd34e9d..f9364e5b 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 @@ -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: diff --git a/docs/source/async_api.rst b/docs/source/async_api.rst index bf277a00..ffbe797d 100644 --- a/docs/source/async_api.rst +++ b/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. diff --git a/docs/source/index.rst b/docs/source/index.rst index 185fbaeb..b9476493 100644 --- a/docs/source/index.rst +++ b/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. diff --git a/requirements-dev.txt b/requirements-dev.txt index 03cf6c4f..69d69317 100644 --- a/requirements-dev.txt +++ b/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 diff --git a/src/neo4j/_async/config.py b/src/neo4j/_async/config.py index 962f6677..5468d20d 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 c7c0778e..5444bc95 100644 --- a/src/neo4j/_async/driver.py +++ b/src/neo4j/_async/driver.py @@ -306,18 +306,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 fddadd1d..47188f7d 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 48031bad..2417ed0b 100644 --- a/src/neo4j/_async/io/_pool.py +++ b/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()): diff --git a/src/neo4j/_async/work/result.py b/src/neo4j/_async/work/result.py index eb969020..7804cb4c 100644 --- a/src/neo4j/_async/work/result.py +++ b/src/neo4j/_async/work/result.py @@ -428,7 +428,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. @@ -582,9 +582,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 @@ -810,7 +811,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. :: @@ -890,7 +891,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 bd0db02c..5b33ec6f 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 d357bf58..cddf7bf5 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 00ec5419..5d599876 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 ea383f84..efe48b72 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 5a01b0d9..9809255a 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 @@ -236,7 +236,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 @@ -258,13 +258,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 @@ -273,7 +273,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 @@ -286,7 +286,7 @@ def dehydrate_duration(value): def dehydrate_timedelta(value): """ - Dehydrator for `timedelta` values. + Dehydrator for ``timedelta`` values. :param value: :type value: timedelta @@ -315,7 +315,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 @@ -338,7 +338,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 4d8555a9..ca38ca46 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 6f3966c9..58d3c524 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 bce2c5b9..12359132 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 5eb389e2..e528ab07 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 c5e1ceb4..49d9422e 100644 --- a/src/neo4j/_sync/driver.py +++ b/src/neo4j/_sync/driver.py @@ -305,18 +305,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 c6fc7c49..07b1fc57 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 bea9eb67..8e7af541 100644 --- a/src/neo4j/_sync/io/_pool.py +++ b/src/neo4j/_sync/io/_pool.py @@ -962,7 +962,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. @@ -1061,7 +1061,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 e6806a25..9c194dd4 100644 --- a/src/neo4j/_sync/work/result.py +++ b/src/neo4j/_sync/work/result.py @@ -428,7 +428,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. @@ -582,9 +582,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 @@ -810,7 +811,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. :: @@ -890,7 +891,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 768e1613..a37776a9 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 166212df..8922cedc 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 d32e4262..0d114900 100644 --- a/src/neo4j/_work/summary.py +++ b/src/neo4j/_work/summary.py @@ -59,8 +59,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 @@ -95,10 +95,10 @@ class ResultSummary: # cache for notifications _notifications_set: bool = False - # 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 e605ffc5..4110cd91 100644 --- a/src/neo4j/api.py +++ b/src/neo4j/api.py @@ -294,8 +294,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 b830dd53..b1591d9a 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 eacch + 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, @@ -1372,11 +1374,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)), @@ -1418,7 +1420,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 @@ -1510,8 +1512,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) @@ -1573,8 +1575,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``. @@ -1778,7 +1780,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. @@ -2020,15 +2022,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)), @@ -2063,11 +2065,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`. """ @@ -2078,13 +2080,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) @@ -2093,7 +2095,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) @@ -2120,7 +2122,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. @@ -2200,12 +2202,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) @@ -2230,17 +2232,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) @@ -2355,7 +2358,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) @@ -2422,9 +2425,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. @@ -2994,9 +2997,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. """ @@ -3087,11 +3090,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/tests/unit/async_/fixtures/fake_connection.py b/tests/unit/async_/fixtures/fake_connection.py index 98c40df6..7c120123 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 ca9a5c80..beed5db6 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 From fc334b8302ab49d8ec3c91b5bbe3024135e7a9c6 Mon Sep 17 00:00:00 2001 From: Robsdedude Date: Fri, 13 Jun 2025 10:44:08 +0200 Subject: [PATCH 2/2] Clean up left-over docs line --- docs/source/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 30fa9945..bcf5dd6f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -125,7 +125,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`).