From 12cdb6a12aa8b3c527c3a4ac6b1de855afbb08b4 Mon Sep 17 00:00:00 2001 From: Robsdedude Date: Tue, 13 Feb 2024 17:24:10 +0100 Subject: [PATCH] API docs: fix broken/outdated cross references --- docs/source/api.rst | 6 +-- docs/source/async_api.rst | 6 +-- src/neo4j/_api.py | 25 ++++++------ src/neo4j/_async/auth_management.py | 6 +-- src/neo4j/_async/driver.py | 16 ++++---- src/neo4j/_async/work/result.py | 54 +++++++++++++------------- src/neo4j/_async/work/transaction.py | 2 +- src/neo4j/_async/work/workspace.py | 2 +- src/neo4j/_async_compat/concurrency.py | 2 +- src/neo4j/_auth_management.py | 14 +++---- src/neo4j/_data.py | 9 +++-- src/neo4j/_sync/auth_management.py | 6 +-- src/neo4j/_sync/driver.py | 16 ++++---- src/neo4j/_sync/work/result.py | 54 +++++++++++++------------- src/neo4j/_sync/work/transaction.py | 2 +- src/neo4j/_sync/work/workspace.py | 2 +- src/neo4j/addressing.py | 2 +- src/neo4j/api.py | 9 ++--- src/neo4j/debug.py | 4 +- src/neo4j/exceptions.py | 17 +++----- src/neo4j/time/__init__.py | 7 ++-- 21 files changed, 128 insertions(+), 133 deletions(-) diff --git a/docs/source/api.rst b/docs/source/api.rst index 755ac225..b5c133ea 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -896,7 +896,7 @@ To construct a :class:`neo4j.Session` use the :meth:`neo4j.Driver.session` metho ``bookmarks`` ------------- Optional :class:`neo4j.Bookmarks`. Use this to causally chain sessions. -See :meth:`Session.last_bookmarks` or :meth:`AsyncSession.last_bookmarks` for +See :meth:`.Session.last_bookmarks` or :meth:`.AsyncSession.last_bookmarks` for more information. :Default: :data:`None` @@ -984,7 +984,7 @@ Specifically, the following applies: Name of the user to impersonate. This means that all actions in the session will be executed in the security context of the impersonated user. For this, the user for which the -:class:`Driver` has been created needs to have the appropriate permissions. +:class:`.Driver` has been created needs to have the appropriate permissions. .. Note:: @@ -1862,8 +1862,6 @@ Server-side errors * :class:`neo4j.exceptions.TokenExpired` - * :class:`neo4j.exceptions.TokenExpiredRetryable` - * :class:`neo4j.exceptions.Forbidden` * :class:`neo4j.exceptions.DatabaseError` diff --git a/docs/source/async_api.rst b/docs/source/async_api.rst index 0a52240b..ba06e8c2 100644 --- a/docs/source/async_api.rst +++ b/docs/source/async_api.rst @@ -381,7 +381,7 @@ Async Driver Configuration driver accepts * a sync as well as an async custom resolver function (see :ref:`async-resolver-ref`) - * as sync as well as an async auth token manager (see :class:`neo4j.AsyncAuthManager`). + * as sync as well as an async auth token manager (see :class:`.AsyncAuthManager`). .. _async-resolver-ref: @@ -643,7 +643,7 @@ accepts either a :class:`neo4j.api.BookmarkManager` object or a Specify a bookmark manager for the driver to use. If present, the bookmark manager is used to keep all work on the driver causally consistent. -See :class:`BookmarkManager` for more information. +See :class:`.BookmarkManager` for more information. .. warning:: Enabling the BookmarkManager can have a negative impact on performance since @@ -654,7 +654,7 @@ See :class:`BookmarkManager` for more information. group a series of queries together that will be causally chained automatically. -:Type: :data:`None`, :class:`BookmarkManager`, or :class:`AsyncBookmarkManager` +:Type: :data:`None`, :class:`.BookmarkManager`, or :class:`.AsyncBookmarkManager` :Default: :data:`None` .. versionchanged:: 5.8 Stabilized from experimental. diff --git a/src/neo4j/_api.py b/src/neo4j/_api.py index 4e419c7c..97dfc25d 100644 --- a/src/neo4j/_api.py +++ b/src/neo4j/_api.py @@ -37,8 +37,9 @@ class NotificationMinimumSeverity(str, Enum): """Filter notifications returned by the server by minimum severity. - Inherits from :class:`str` and :class:`Enum`. Every driver API accepting a - :class:`.NotificationMinimumSeverity` value will also accept a string:: + Inherits from :class:`str` and :class:`enum.Enum`. + Every driver API accepting a :class:`.NotificationMinimumSeverity` value + will also accept a string:: >>> NotificationMinimumSeverity.OFF == "OFF" True @@ -74,8 +75,8 @@ class NotificationMinimumSeverity(str, Enum): class NotificationSeverity(str, Enum): """Server-side notification severity. - Inherits from :class:`str` and :class:`Enum`. Hence, can also be compared - to its string value:: + Inherits from :class:`str` and :class:`enum.Enum`. + Hence, can also be compared to its string value:: >>> NotificationSeverity.WARNING == "WARNING" True @@ -125,8 +126,9 @@ class NotificationSeverity(str, Enum): class NotificationDisabledCategory(str, Enum): """Filter notifications returned by the server by category. - Inherits from :class:`str` and :class:`Enum`. Every driver API accepting a - :class:`.NotificationDisabledCategory` value will also accept a string:: + Inherits from :class:`str` and :class:`enum.Enum`. + Every driver API accepting a :class:`.NotificationDisabledCategory` value + will also accept a string:: >>> NotificationDisabledCategory.UNRECOGNIZED == "UNRECOGNIZED" True @@ -176,8 +178,8 @@ class NotificationDisabledCategory(str, Enum): class NotificationCategory(str, Enum): """Server-side notification category. - Inherits from :class:`str` and :class:`Enum`. Hence, can also be compared - to its string value:: + Inherits from :class:`str` and :class:`enum.Enum`. + Hence, can also be compared to its string value:: >>> NotificationCategory.DEPRECATION == "DEPRECATION" True @@ -211,8 +213,9 @@ class NotificationCategory(str, Enum): class RoutingControl(str, Enum): """Selection which cluster members to route a query connect to. - Inherits from :class:`str` and :class:`Enum`. Every driver API accepting a - :class:`.RoutingControl` value will also accept a string + Inherits from :class:`str` and :class:`enum.Enum`. + Every driver API accepting a :class:`.RoutingControl` value will also + accept a string:: >>> RoutingControl.READ == "r" True @@ -220,7 +223,7 @@ class RoutingControl(str, Enum): True .. seealso:: - :attr:`.AsyncDriver.execute_query`, :attr:`.Driver.execute_query` + :meth:`.AsyncDriver.execute_query`, :meth:`.Driver.execute_query` .. versionadded:: 5.5 diff --git a/src/neo4j/_async/auth_management.py b/src/neo4j/_async/auth_management.py index 54d66210..492e5eec 100644 --- a/src/neo4j/_async/auth_management.py +++ b/src/neo4j/_async/auth_management.py @@ -222,9 +222,9 @@ def bearer( This factory wraps the provider function in an auth manager implementation that caches the provides auth info until either the - ``ExpiringAuth.expires_at`` is exceeded the server notifies the driver - that the auth info is expired (by returning an error that indicates - that the bearer auth token has expired). + :attr:`.ExpiringAuth.expires_at` is exceeded the server notifies the + driver that the auth info is expired (by returning an error that + indicates that the bearer auth token has expired). .. warning:: diff --git a/src/neo4j/_async/driver.py b/src/neo4j/_async/driver.py index 1bba68ba..57312ac9 100644 --- a/src/neo4j/_async/driver.py +++ b/src/neo4j/_async/driver.py @@ -344,7 +344,7 @@ def bookmark_manager( internal bookmark set. It will receive the new set of bookmarks as a :class:`.Bookmarks` object and return :data:`None`. - :returns: A default implementation of :class:`AsyncBookmarkManager`. + :returns: A default implementation of :class:`.AsyncBookmarkManager`. .. versionadded:: 5.0 @@ -909,7 +909,7 @@ async def example(driver: neo4j.AsyncDriver) -> neo4j.Record:: def execute_query_bookmark_manager(self) -> AsyncBookmarkManager: """The driver's default query bookmark manager. - This is the default :class:`AsyncBookmarkManager` used by + This is the default :class:`.AsyncBookmarkManager` used by :meth:`.execute_query`. This can be used to causally chain :meth:`.execute_query` calls and sessions. Example:: @@ -1089,8 +1089,8 @@ async def supports_multi_db(self) -> bool: .. note:: Feature support query based solely on the Bolt protocol version. The feature might still be disabled on the server side even if this - function return :const:`True`. It just guarantees that the driver - won't throw a :exc:`ConfigurationError` when trying to use this + function return :data:`True`. It just guarantees that the driver + won't throw a :exc:`.ConfigurationError` when trying to use this driver feature. """ self._check_state() @@ -1141,9 +1141,9 @@ async def verify_authentication( a member of a cluster and exchange some data. In a cluster, there is no guarantee about which server will be contacted. If the data exchange is successful and the authentication information is valid, - :const:`True` is returned. Otherwise, the error will be matched + :data:`True` is returned. Otherwise, the error will be matched against a list of known authentication errors. If the error is on - that list, :const:`False` is returned indicating that the + that list, :data:`False` is returned indicating that the authentication information is invalid. Otherwise, the error is re-raised. @@ -1201,8 +1201,8 @@ async def supports_session_auth(self) -> bool: .. note:: Feature support query based solely on the Bolt protocol version. The feature might still be disabled on the server side even if this - function return :const:`True`. It just guarantees that the driver - won't throw a :exc:`ConfigurationError` when trying to use this + function return :data:`True`. It just guarantees that the driver + won't throw a :exc:`.ConfigurationError` when trying to use this driver feature. .. versionadded:: 5.8 diff --git a/src/neo4j/_async/work/result.py b/src/neo4j/_async/work/result.py index 447e7ff6..4f172a0c 100644 --- a/src/neo4j/_async/work/result.py +++ b/src/neo4j/_async/work/result.py @@ -424,7 +424,7 @@ async def get_two_tx(tx): was obtained has been closed. .. versionchanged:: 5.0 - Can raise :exc:`ResultConsumedError`. + Can raise :exc:`.ResultConsumedError`. """ if self._out_of_scope: raise ResultConsumedError(self, _RESULT_OUT_OF_SCOPE_ERROR) @@ -452,24 +452,24 @@ async def single(self, strict: bool = False) -> t.Optional[Record]: Calling this method always exhausts the result. - If ``strict`` is :const:`True`, this method will raise an exception if + If ``strict`` is :data:`True`, this method will raise an exception if there is not exactly one record left. - If ``strict`` is :const:`False`, fewer than one record will make this + If ``strict`` is :data:`False`, fewer than one record will make this method return :data:`None`, more than one record will make this method emit a warning and return the first record. :param strict: - If :const:`True`, raise a :class:`neo4j.ResultNotSingleError` - instead of returning None if there is more than one record or - warning if there are more than 1 record. - :const:`False` by default. + 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. + :data:`False` by default. :type strict: bool :returns: the next :class:`neo4j.Record` or :data:`None` if none remain :warns: if more than one record is available and - ``strict`` is :const:`False` + ``strict`` is :data:`False` :raises ResultNotSingleError: If ``strict=True`` and not exactly one record is available. @@ -480,7 +480,7 @@ async def single(self, strict: bool = False) -> t.Optional[Record]: .. versionchanged:: 5.0 * Added ``strict`` parameter. - * Can raise :exc:`ResultConsumedError`. + * Can raise :exc:`.ResultConsumedError`. """ await self._buffer(2) buffer = self._record_buffer @@ -545,7 +545,7 @@ async def peek(self) -> t.Optional[Record]: consumed. .. versionchanged:: 5.0 - Can raise :exc:`ResultConsumedError`. + Can raise :exc:`.ResultConsumedError`. """ await self._buffer(1) if self._record_buffer: @@ -554,14 +554,14 @@ async def peek(self) -> t.Optional[Record]: @AsyncNonConcurrentMethodChecker.non_concurrent_method async def graph(self) -> Graph: - """Turn the result into a :class:`neo4j.Graph`. + """Turn the result into a :class:`.Graph`. - Return a :class:`neo4j.graph.Graph` instance containing all the graph - objects in the result. This graph will also contain already consumed - records. + Return a :class:`.Graph` instance containing all the graph objects in + the result. + This graph will also contain already consumed records. - After calling this method, the result becomes - detached, buffering all remaining records. + After calling this method, the result becomes detached, buffering all + remaining records. :returns: a result graph @@ -570,7 +570,7 @@ async def graph(self) -> Graph: consumed. .. versionchanged:: 5.0 - Can raise :exc:`ResultConsumedError`. + Can raise :exc:`.ResultConsumedError`. """ await self._buffer_all() return self._hydration_scope.get_graph() @@ -591,7 +591,7 @@ async def value( consumed. .. versionchanged:: 5.0 - Can raise :exc:`ResultConsumedError`. + Can raise :exc:`.ResultConsumedError`. .. seealso:: :meth:`.Record.value` """ @@ -612,7 +612,7 @@ async def values( consumed. .. versionchanged:: 5.0 - Can raise :exc:`ResultConsumedError`. + Can raise :exc:`.ResultConsumedError`. .. seealso:: :meth:`.Record.values` """ @@ -641,7 +641,7 @@ async def data(self, *keys: _TResultKey) -> t.List[t.Dict[str, t.Any]]: consumed. .. versionchanged:: 5.0 - Can raise :exc:`ResultConsumedError`. + Can raise :exc:`.ResultConsumedError`. .. seealso:: :meth:`.Record.data` """ @@ -690,7 +690,7 @@ async def to_df( for instance will return a DataFrame with two columns: ``n`` and ``m`` and 10 rows. - :param expand: If :const:`True`, some structures in the result will be + :param expand: If :data:`True`, some structures in the result will be recursively expanded (flattened out into multiple columns) like so (everything inside ``<...>`` is a placeholder): @@ -720,21 +720,21 @@ async def to_df( * ``->.type`` (str) the relationship's type. See :attr:`.Relationship.type`. - * :const:`list` objects under any variable ```` will be expanded + * :class:`list` objects under any variable ```` will be expanded into * ``[].0`` (any) the 1st list element * ``[].1`` (any) the 2nd list element * ... - * :const:`dict` objects under any variable ```` will be expanded + * :class:`dict` objects under any variable ```` will be expanded into * ``{}.`` (any) the 1st key of the dict * ``{}.`` (any) the 2nd key of the dict * ... - * :const:`list` and :const:`dict` objects are expanded recursively. + * :class:`list` and :class:`dict` objects are expanded recursively. Example:: variable x: [{"foo": "bar", "baz": [42, 0]}, "foobar"] @@ -751,10 +751,10 @@ async def to_df( * Everything else (including :class:`.Path` objects) will not be flattened. - :const:`dict` keys and variable names that contain ``.`` or ``\`` + :class:`dict` keys and variable names that contain ``.`` or ``\`` will be escaped with a backslash (``\.`` and ``\\`` respectively). :param parse_dates: - If :const:`True`, columns that exclusively contain + If :data:`True`, columns that exclusively contain :class:`time.DateTime` objects, :class:`time.Date` objects, or :data:`None`, will be converted to :class:`pandas.Timestamp`. @@ -818,7 +818,7 @@ def closed(self) -> bool: result cannot be used to acquire further records. In such case, all methods that need to access the Result's records, - will raise a :exc:`ResultConsumedError` when called. + will raise a :exc:`.ResultConsumedError` when called. :returns: whether the result is closed. diff --git a/src/neo4j/_async/work/transaction.py b/src/neo4j/_async/work/transaction.py index 7d2a1810..b34d4103 100644 --- a/src/neo4j/_async/work/transaction.py +++ b/src/neo4j/_async/work/transaction.py @@ -241,7 +241,7 @@ class AsyncTransaction(AsyncTransactionBase): Container for multiple Cypher queries to be executed within a single context. :class:`AsyncTransaction` objects can be used as a context - manager (:py:const:`async with` block) where the transaction is committed + manager (``async with`` block) where the transaction is committed or rolled back based on whether an exception is raised:: async with await session.begin_transaction() as tx: diff --git a/src/neo4j/_async/work/workspace.py b/src/neo4j/_async/work/workspace.py index cc1ee246..05ff77c5 100644 --- a/src/neo4j/_async/work/workspace.py +++ b/src/neo4j/_async/work/workspace.py @@ -201,7 +201,7 @@ async def close(self) -> None: def closed(self) -> bool: """Indicate whether the session has been closed. - :returns: :const:`True` if closed, :const:`False` otherwise. + :returns: :data:`True` if closed, :data:`False` otherwise. """ return self._closed diff --git a/src/neo4j/_async_compat/concurrency.py b/src/neo4j/_async_compat/concurrency.py index 24a20040..ddf6e7b3 100644 --- a/src/neo4j/_async_compat/concurrency.py +++ b/src/neo4j/_async_compat/concurrency.py @@ -53,7 +53,7 @@ class AsyncRLock(asyncio.Lock): .. warning:: In async Python there are no threads. This implementation uses - :meth:`asyncio.current_task()` to determine the owner of the lock. This + :meth:`asyncio.current_task` to determine the owner of the lock. This means that the owner changes when using :meth:`asyncio.wait_for` or any other method that wraps the work in a new :class:`asyncio.Task`. """ diff --git a/src/neo4j/_auth_management.py b/src/neo4j/_auth_management.py index b69cf2fe..65a62369 100644 --- a/src/neo4j/_auth_management.py +++ b/src/neo4j/_auth_management.py @@ -32,8 +32,8 @@ class ExpiringAuth: """Represents potentially expiring authentication information. - This class is used with :meth:`.AuthManagers.expiration_based` and - :meth:`.AsyncAuthManagers.expiration_based`. + This class is used with :meth:`.AuthManagers.bearer` and + :meth:`.AsyncAuthManagers.bearer`. :param auth: The authentication information. :param expires_at: @@ -43,8 +43,8 @@ class ExpiringAuth: expire until the server explicitly indicates so. .. seealso:: - :meth:`.AuthManagers.expiration_based`, - :meth:`.AsyncAuthManagers.expiration_based` + :meth:`.AuthManagers.bearer`, + :meth:`.AsyncAuthManagers.bearer` .. versionadded:: 5.8 @@ -155,7 +155,7 @@ def handle_security_exception( The error returned by the server. :returns: - Whether the error was handled (:const:`True`), in which case the + Whether the error was handled (:data:`True`), in which case the driver will mark the error as retryable (see :meth:`.Neo4jError.is_retryable`). @@ -188,8 +188,8 @@ async def get_auth(self) -> _TAuth: async def handle_security_exception( self, auth: _TAuth, error: Neo4jError ) -> bool: - """Async version of :meth:`.AuthManager.on_auth_expired`. + """Async version of :meth:`.AuthManager.handle_security_exception`. - .. seealso:: :meth:`.AuthManager.on_auth_expired` + .. seealso:: :meth:`.AuthManager.handle_security_exception` """ ... diff --git a/src/neo4j/_data.py b/src/neo4j/_data.py index a4323823..554c623c 100644 --- a/src/neo4j/_data.py +++ b/src/neo4j/_data.py @@ -52,10 +52,11 @@ class Record(tuple, Mapping): - """ A :class:`.Record` is an immutable ordered collection of key-value - pairs. It is generally closer to a :py:class:`namedtuple` than to a - :py:class:`OrderedDict` in as much as iteration of the collection will - yield values rather than keys. + """ A :class:`.Record` is an immutable, ordered collection of key-value + pairs. + It is generally closer to a :func:`collections.namedtuple` than to a + :class:`OrderedDict` in as much as iteration of the collection will yield + values rather than keys. """ __keys: t.Tuple[str] diff --git a/src/neo4j/_sync/auth_management.py b/src/neo4j/_sync/auth_management.py index 408f2382..f075eac8 100644 --- a/src/neo4j/_sync/auth_management.py +++ b/src/neo4j/_sync/auth_management.py @@ -222,9 +222,9 @@ def bearer( This factory wraps the provider function in an auth manager implementation that caches the provides auth info until either the - ``ExpiringAuth.expires_at`` is exceeded the server notifies the driver - that the auth info is expired (by returning an error that indicates - that the bearer auth token has expired). + :attr:`.ExpiringAuth.expires_at` is exceeded the server notifies the + driver that the auth info is expired (by returning an error that + indicates that the bearer auth token has expired). .. warning:: diff --git a/src/neo4j/_sync/driver.py b/src/neo4j/_sync/driver.py index 4273c405..3db70201 100644 --- a/src/neo4j/_sync/driver.py +++ b/src/neo4j/_sync/driver.py @@ -343,7 +343,7 @@ def bookmark_manager( internal bookmark set. It will receive the new set of bookmarks as a :class:`.Bookmarks` object and return :data:`None`. - :returns: A default implementation of :class:`BookmarkManager`. + :returns: A default implementation of :class:`.BookmarkManager`. .. versionadded:: 5.0 @@ -908,7 +908,7 @@ def example(driver: neo4j.Driver) -> neo4j.Record:: def execute_query_bookmark_manager(self) -> BookmarkManager: """The driver's default query bookmark manager. - This is the default :class:`BookmarkManager` used by + This is the default :class:`.BookmarkManager` used by :meth:`.execute_query`. This can be used to causally chain :meth:`.execute_query` calls and sessions. Example:: @@ -1088,8 +1088,8 @@ def supports_multi_db(self) -> bool: .. note:: Feature support query based solely on the Bolt protocol version. The feature might still be disabled on the server side even if this - function return :const:`True`. It just guarantees that the driver - won't throw a :exc:`ConfigurationError` when trying to use this + function return :data:`True`. It just guarantees that the driver + won't throw a :exc:`.ConfigurationError` when trying to use this driver feature. """ self._check_state() @@ -1140,9 +1140,9 @@ def verify_authentication( a member of a cluster and exchange some data. In a cluster, there is no guarantee about which server will be contacted. If the data exchange is successful and the authentication information is valid, - :const:`True` is returned. Otherwise, the error will be matched + :data:`True` is returned. Otherwise, the error will be matched against a list of known authentication errors. If the error is on - that list, :const:`False` is returned indicating that the + that list, :data:`False` is returned indicating that the authentication information is invalid. Otherwise, the error is re-raised. @@ -1200,8 +1200,8 @@ def supports_session_auth(self) -> bool: .. note:: Feature support query based solely on the Bolt protocol version. The feature might still be disabled on the server side even if this - function return :const:`True`. It just guarantees that the driver - won't throw a :exc:`ConfigurationError` when trying to use this + function return :data:`True`. It just guarantees that the driver + won't throw a :exc:`.ConfigurationError` when trying to use this driver feature. .. versionadded:: 5.8 diff --git a/src/neo4j/_sync/work/result.py b/src/neo4j/_sync/work/result.py index 72bfa52a..4714b691 100644 --- a/src/neo4j/_sync/work/result.py +++ b/src/neo4j/_sync/work/result.py @@ -424,7 +424,7 @@ def get_two_tx(tx): was obtained has been closed. .. versionchanged:: 5.0 - Can raise :exc:`ResultConsumedError`. + Can raise :exc:`.ResultConsumedError`. """ if self._out_of_scope: raise ResultConsumedError(self, _RESULT_OUT_OF_SCOPE_ERROR) @@ -452,24 +452,24 @@ def single(self, strict: bool = False) -> t.Optional[Record]: Calling this method always exhausts the result. - If ``strict`` is :const:`True`, this method will raise an exception if + If ``strict`` is :data:`True`, this method will raise an exception if there is not exactly one record left. - If ``strict`` is :const:`False`, fewer than one record will make this + If ``strict`` is :data:`False`, fewer than one record will make this method return :data:`None`, more than one record will make this method emit a warning and return the first record. :param strict: - If :const:`True`, raise a :class:`neo4j.ResultNotSingleError` - instead of returning None if there is more than one record or - warning if there are more than 1 record. - :const:`False` by default. + 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. + :data:`False` by default. :type strict: bool :returns: the next :class:`neo4j.Record` or :data:`None` if none remain :warns: if more than one record is available and - ``strict`` is :const:`False` + ``strict`` is :data:`False` :raises ResultNotSingleError: If ``strict=True`` and not exactly one record is available. @@ -480,7 +480,7 @@ def single(self, strict: bool = False) -> t.Optional[Record]: .. versionchanged:: 5.0 * Added ``strict`` parameter. - * Can raise :exc:`ResultConsumedError`. + * Can raise :exc:`.ResultConsumedError`. """ self._buffer(2) buffer = self._record_buffer @@ -545,7 +545,7 @@ def peek(self) -> t.Optional[Record]: consumed. .. versionchanged:: 5.0 - Can raise :exc:`ResultConsumedError`. + Can raise :exc:`.ResultConsumedError`. """ self._buffer(1) if self._record_buffer: @@ -554,14 +554,14 @@ def peek(self) -> t.Optional[Record]: @NonConcurrentMethodChecker.non_concurrent_method def graph(self) -> Graph: - """Turn the result into a :class:`neo4j.Graph`. + """Turn the result into a :class:`.Graph`. - Return a :class:`neo4j.graph.Graph` instance containing all the graph - objects in the result. This graph will also contain already consumed - records. + Return a :class:`.Graph` instance containing all the graph objects in + the result. + This graph will also contain already consumed records. - After calling this method, the result becomes - detached, buffering all remaining records. + After calling this method, the result becomes detached, buffering all + remaining records. :returns: a result graph @@ -570,7 +570,7 @@ def graph(self) -> Graph: consumed. .. versionchanged:: 5.0 - Can raise :exc:`ResultConsumedError`. + Can raise :exc:`.ResultConsumedError`. """ self._buffer_all() return self._hydration_scope.get_graph() @@ -591,7 +591,7 @@ def value( consumed. .. versionchanged:: 5.0 - Can raise :exc:`ResultConsumedError`. + Can raise :exc:`.ResultConsumedError`. .. seealso:: :meth:`.Record.value` """ @@ -612,7 +612,7 @@ def values( consumed. .. versionchanged:: 5.0 - Can raise :exc:`ResultConsumedError`. + Can raise :exc:`.ResultConsumedError`. .. seealso:: :meth:`.Record.values` """ @@ -641,7 +641,7 @@ def data(self, *keys: _TResultKey) -> t.List[t.Dict[str, t.Any]]: consumed. .. versionchanged:: 5.0 - Can raise :exc:`ResultConsumedError`. + Can raise :exc:`.ResultConsumedError`. .. seealso:: :meth:`.Record.data` """ @@ -690,7 +690,7 @@ def to_df( for instance will return a DataFrame with two columns: ``n`` and ``m`` and 10 rows. - :param expand: If :const:`True`, some structures in the result will be + :param expand: If :data:`True`, some structures in the result will be recursively expanded (flattened out into multiple columns) like so (everything inside ``<...>`` is a placeholder): @@ -720,21 +720,21 @@ def to_df( * ``->.type`` (str) the relationship's type. See :attr:`.Relationship.type`. - * :const:`list` objects under any variable ```` will be expanded + * :class:`list` objects under any variable ```` will be expanded into * ``[].0`` (any) the 1st list element * ``[].1`` (any) the 2nd list element * ... - * :const:`dict` objects under any variable ```` will be expanded + * :class:`dict` objects under any variable ```` will be expanded into * ``{}.`` (any) the 1st key of the dict * ``{}.`` (any) the 2nd key of the dict * ... - * :const:`list` and :const:`dict` objects are expanded recursively. + * :class:`list` and :class:`dict` objects are expanded recursively. Example:: variable x: [{"foo": "bar", "baz": [42, 0]}, "foobar"] @@ -751,10 +751,10 @@ def to_df( * Everything else (including :class:`.Path` objects) will not be flattened. - :const:`dict` keys and variable names that contain ``.`` or ``\`` + :class:`dict` keys and variable names that contain ``.`` or ``\`` will be escaped with a backslash (``\.`` and ``\\`` respectively). :param parse_dates: - If :const:`True`, columns that exclusively contain + If :data:`True`, columns that exclusively contain :class:`time.DateTime` objects, :class:`time.Date` objects, or :data:`None`, will be converted to :class:`pandas.Timestamp`. @@ -818,7 +818,7 @@ def closed(self) -> bool: result cannot be used to acquire further records. In such case, all methods that need to access the Result's records, - will raise a :exc:`ResultConsumedError` when called. + will raise a :exc:`.ResultConsumedError` when called. :returns: whether the result is closed. diff --git a/src/neo4j/_sync/work/transaction.py b/src/neo4j/_sync/work/transaction.py index 8314c55c..4eef039f 100644 --- a/src/neo4j/_sync/work/transaction.py +++ b/src/neo4j/_sync/work/transaction.py @@ -241,7 +241,7 @@ class Transaction(TransactionBase): Container for multiple Cypher queries to be executed within a single context. :class:`Transaction` objects can be used as a context - manager (:py:const:`with` block) where the transaction is committed + manager (``with`` block) where the transaction is committed or rolled back based on whether an exception is raised:: with session.begin_transaction() as tx: diff --git a/src/neo4j/_sync/work/workspace.py b/src/neo4j/_sync/work/workspace.py index 31f5bd11..18cd112e 100644 --- a/src/neo4j/_sync/work/workspace.py +++ b/src/neo4j/_sync/work/workspace.py @@ -201,7 +201,7 @@ def close(self) -> None: def closed(self) -> bool: """Indicate whether the session has been closed. - :returns: :const:`True` if closed, :const:`False` otherwise. + :returns: :data:`True` if closed, :data:`False` otherwise. """ return self._closed diff --git a/src/neo4j/addressing.py b/src/neo4j/addressing.py index 66645aba..ae62b9b9 100644 --- a/src/neo4j/addressing.py +++ b/src/neo4j/addressing.py @@ -249,7 +249,7 @@ def port_number(self) -> int: """The port part of the address as an integer. First try to resolve the port as an integer, using - :meth:`socket.getservbyname`. If that fails, fall back to parsing the + :func:`socket.getservbyname`. If that fails, fall back to parsing the port as an integer. >>> Address(("localhost", 7687)).port_number diff --git a/src/neo4j/api.py b/src/neo4j/api.py index cbd22546..4306bb98 100644 --- a/src/neo4j/api.py +++ b/src/neo4j/api.py @@ -320,11 +320,10 @@ def address(self) -> Address: return self._address @property - def protocol_version(self) -> Version: + def protocol_version(self) -> t.Tuple[int, int]: """ Bolt protocol version with which the remote server - communicates. This is returned as a :class:`.Version` - object, which itself extends a simple 2-tuple of - (major, minor) integers. + communicates. This is returned as a 2-tuple:class:`tuple` (subclass) of + ``(major, minor)`` integers. """ return self._protocol_version @@ -404,7 +403,7 @@ class BookmarkManager(_Protocol, metaclass=abc.ABCMeta): This class is just an abstract base class that defines the required interface. Create a child class to implement a specific bookmark manager or make use of the default implementation provided by the driver through - :meth:`.GraphDatabase.bookmark_manager()`. + :meth:`.GraphDatabase.bookmark_manager`. .. note:: All methods must be concurrency safe. diff --git a/src/neo4j/debug.py b/src/neo4j/debug.py index 8e2ee48d..100e8244 100644 --- a/src/neo4j/debug.py +++ b/src/neo4j/debug.py @@ -100,9 +100,9 @@ class Watcher: :param colour: Whether the log levels should be indicated with ANSI colour codes. :param thread_info: whether to include information about the current - thread in the log message. Defaults to :const:`True`. + thread in the log message. Defaults to :data:`True`. :param task_info: whether to include information about the current - async task in the log message. Defaults to :const:`True`. + async task in the log message. Defaults to :data:`True`. .. versionchanged:: 5.3 diff --git a/src/neo4j/exceptions.py b/src/neo4j/exceptions.py index 56786a4a..4371e1b3 100644 --- a/src/neo4j/exceptions.py +++ b/src/neo4j/exceptions.py @@ -210,8 +210,8 @@ def is_retriable(self) -> bool: See :meth:`.is_retryable`. - :returns: :const:`True` if the error is retryable, - :const:`False` otherwise. + :returns: :data:`True` if the error is retryable, + :data:`False` otherwise. .. deprecated:: 5.0 This method will be removed in a future version. @@ -226,8 +226,8 @@ def is_retryable(self) -> bool: retry. This method makes mostly sense when implementing a custom retry policy in conjunction with :ref:`explicit-transactions-ref`. - :returns: :const:`True` if the error is retryable, - :const:`False` otherwise. + :returns: :data:`True` if the error is retryable, + :data:`False` otherwise. .. versionadded:: 5.0 """ @@ -314,11 +314,6 @@ class AuthError(ClientError): # Neo4jError > ClientError > AuthError > TokenExpired class TokenExpired(AuthError): """ Raised when the authentication token has expired. - - A new driver instance with a fresh authentication token needs to be - created, unless the driver was configured using a non-static - :class:`.AuthManager`. In that case, the error will be - :exc:`.TokenExpiredRetryable` instead. """ @@ -414,8 +409,8 @@ def is_retryable(self) -> bool: retry. This method makes mostly sense when implementing a custom retry policy in conjunction with :ref:`explicit-transactions-ref`. - :returns: :const:`True` if the error is retryable, - :const:`False` otherwise. + :returns: :data:`True` if the error is retryable, + :data:`False` otherwise. .. versionadded:: 5.0 """ diff --git a/src/neo4j/time/__init__.py b/src/neo4j/time/__init__.py index de01deea..89dde16a 100644 --- a/src/neo4j/time/__init__.py +++ b/src/neo4j/time/__init__.py @@ -23,7 +23,6 @@ from __future__ import annotations import re -import typing import typing as t from datetime import ( date, @@ -751,8 +750,8 @@ class Date(date_base_class, metaclass=DateType): desirable outcome than would otherwise be produced. Externally, the day number is always the same as would be written on a calendar. - :param year: the year. Minimum :attr:`.MIN_YEAR` (0001), maximum - :attr:`.MAX_YEAR` (9999). + :param year: the year. Minimum :data:`.MIN_YEAR` (0001), maximum + :data:`.MAX_YEAR` (9999). :type year: int :param month: the month. Minimum 1, maximum 12. :type month: int @@ -761,7 +760,7 @@ class Date(date_base_class, metaclass=DateType): :type day: int A zero date can also be acquired by passing all zeroes to the - :class:`neo4j.time.Date` constructor or by using the :attr:`ZeroDate` + :class:`.Date` constructor or by using the :data:`ZeroDate` constant. """