From 97761aeb2c042522a2b673782f0e76ff8686ec63 Mon Sep 17 00:00:00 2001 From: martin bendsoe Date: Fri, 5 Jun 2020 15:16:02 +0200 Subject: [PATCH] update api documentation --- docs/source/api.rst | 37 +++++++++++++++++++++----------- docs/source/breaking_changes.rst | 21 ++++++++++++++++-- neo4j/work/simple.py | 13 ++++++----- neo4j/work/transaction.py | 33 +++++++++++++++++----------- 4 files changed, 72 insertions(+), 32 deletions(-) diff --git a/docs/source/api.rst b/docs/source/api.rst index 908120768..98797f4a6 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -384,7 +384,7 @@ Sessions will often be created with some configuration settings, see :ref:`sessi Session ******* -.. autoclass:: neo4j.Session +.. autoclass:: neo4j.Session() .. automethod:: close @@ -399,6 +399,13 @@ Session .. automethod:: write_transaction +Query +===== + +.. autoclass:: neo4j.Query + + + .. _session-configuration-ref: Session Configuration @@ -527,10 +534,12 @@ This creates a new :class:`neo4j.Transaction` object that can be used to run Cyp It also gives applications the ability to directly control `commit` and `rollback` activity. -.. autoclass:: neo4j.Transaction +.. autoclass:: neo4j.Transaction() .. automethod:: run + .. automethod:: close + .. automethod:: closed .. automethod:: commit @@ -538,7 +547,8 @@ It also gives applications the ability to directly control `commit` and `rollbac .. automethod:: rollback Closing an explicit transaction can either happen automatically at the end of a ``with`` block, -or can be explicitly controlled through the :py:meth:`neo4j.Transaction.commit` and :py:meth:`neo4j.Transaction.rollback` methods. +or can be explicitly controlled through the :py:meth:`neo4j.Transaction.commit`, :py:meth:`neo4j.Transaction.rollback` or :py:meth:`neo4j.Transaction.close` methods. + Explicit transactions are most useful for applications that need to distribute Cypher execution across multiple functions for the same transaction. .. code-block:: python @@ -607,7 +617,7 @@ Results also contain a buffer that automatically stores unconsumed records when A :class:`neo4j.Result` is attached to an active connection, through a :class:`neo4j.Session`, until all its content has been buffered or consumed. -.. autoclass:: neo4j.Result +.. autoclass:: neo4j.Result() .. describe:: iter(result) @@ -624,10 +634,13 @@ A :class:`neo4j.Result` is attached to an active connection, through a :class:`n **This is experimental.** +See https://neo4j.com/docs/driver-manual/current/cypher-workflow/#driver-type-mapping for more about type mapping. + + Graph ===== -.. autoclass:: neo4j.graph.Graph +.. autoclass:: neo4j.graph.Graph() A local, self-contained graph object that acts as a container for :class:`.Node` and :class:`neo4j.Relationship` instances. This is typically obtained via the :meth:`neo4j.Result.graph` method. @@ -645,7 +658,7 @@ Graph Record ****** -.. autoclass:: neo4j.Record +.. autoclass:: neo4j.Record() A :class:`neo4j.Record` is an immutable ordered collection of key-value pairs. It is generally closer to a :py:class:`namedtuple` than to an @@ -710,20 +723,20 @@ Record ResultSummary ************* -.. autoclass:: neo4j.ResultSummary +.. autoclass:: neo4j.ResultSummary() :members: SummaryCounters =============== -.. autoclass:: neo4j.SummaryCounters +.. autoclass:: neo4j.SummaryCounters() :members: ServerInfo ========== -.. autoclass:: neo4j.ServerInfo +.. autoclass:: neo4j.ServerInfo() :members: @@ -794,7 +807,7 @@ Path :class:`neo4j.graph.Path` Node ==== -.. autoclass:: neo4j.graph.Node +.. autoclass:: neo4j.graph.Node() .. describe:: node == other @@ -843,7 +856,7 @@ Node Relationship ============ -.. autoclass:: neo4j.graph.Relationship +.. autoclass:: neo4j.graph.Relationship() .. describe:: relationship == other @@ -904,7 +917,7 @@ Relationship Path ==== -.. autoclass:: neo4j.graph.Path +.. autoclass:: neo4j.graph.Path() .. describe:: path == other diff --git a/docs/source/breaking_changes.rst b/docs/source/breaking_changes.rst index 785277afb..41a021123 100644 --- a/docs/source/breaking_changes.rst +++ b/docs/source/breaking_changes.rst @@ -50,7 +50,7 @@ Introduced :class:`neo4j.Bookmark` Exceptions Changes ================== -The exceptions in :code:`neo4j.exceptions` have been updated and there are internal exceptions starting with the naming :code:`Bolt` that should be propagated into the exceptions API. +The exceptions in :code:`neo4j.exceptions` has been updated and there are internal exceptions starting with the naming :code:`Bolt` that should be propagated into the exceptions API. See :ref:`errors-ref` for more about errors. @@ -83,7 +83,24 @@ Argument Renaming Changes API Changes ========================= -* :code:`Result.summary()` have been replaced with :code:`Result.consume()`, this behaviour is to consume all remaining records in the buffer and returns the ResultSummary. +* :code:`Result.summary()` has been replaced with :code:`Result.consume()`, this behaviour is to consume all remaining records in the buffer and returns the ResultSummary. + +* :code:`Transaction.sync()` has been removed. Use :code:`Result.consume()` if the behaviour is to exhaust the result object. + +* :code:`Transaction.success` has been removed. + +* :code:`Transaction.close()` behaviour changed. Will now only perform rollback if no commit have been performed. + +* :code:`Session.sync()` has been removed. Use :code:`Result.consume()` if the behaviour is to exhaust the result object. + +* :code:`Session.detach()` has been removed. Use :code:`Result.consume()` if the behaviour is to exhaust the result object. + +* :code:`Session.next_bookmarks()` has been removed. + +* :code:`Session.has_transaction()` has been removed. + +* :code:`Session.closed()` has been removed. + * :code:`Session.write_transaction` and :code:`Session.read_transaction` will start the retry timer after the first failed attempt. Dependency Changes diff --git a/neo4j/work/simple.py b/neo4j/work/simple.py index f7c0505ab..1a7c33baf 100644 --- a/neo4j/work/simple.py +++ b/neo4j/work/simple.py @@ -186,10 +186,13 @@ def run(self, query, parameters=None, **kwparameters): For more usage details, see :meth:`.Transaction.run`. - :param query: Cypher query + :param query: cypher query + :type query: str, neo4j.Query :param parameters: dictionary of parameters + :type parameters: dict :param kwparameters: additional keyword parameters - :returns: :class:`neo4j.Result` object + :returns: a new :class:`neo4j.Result` object + :type: :class:`neo4j.Result` """ if not query: raise ValueError("Cannot run an empty query") @@ -383,11 +386,11 @@ class Query: """ Create a new query. :param text: The query text. - :type str: + :type text: str :param metadata: metadata attached to the query. - :type dict: + :type metadata: dict :param timeout: seconds. - :type int: + :type timeout: int """ def __init__(self, text, metadata=None, timeout=None): self.text = text diff --git a/neo4j/work/transaction.py b/neo4j/work/transaction.py index 794d0ce73..87cfd0051 100644 --- a/neo4j/work/transaction.py +++ b/neo4j/work/transaction.py @@ -92,11 +92,14 @@ def run(self, query, parameters=None, **kwparameters): :class:`str`, :class:`list` and :class:`dict`. Note however that :class:`list` properties must be homogenous. - :param query: template Cypher query + :param query: cypher query + :type query: str :param parameters: dictionary of parameters + :type parameters: dict :param kwparameters: additional keyword parameters - :returns: :class:`neo4j.Result` object - :raise TransactionError: if the transaction is closed + :returns: a new :class:`neo4j.Result` object + :rtype: :class:`neo4j.Result` + :raise TransactionError: if the transaction is already closed """ from neo4j.work.simple import Query if isinstance(query, Query): @@ -117,11 +120,12 @@ def run(self, query, parameters=None, **kwparameters): return result def commit(self): - """ Mark this transaction as successful and close in order to - trigger a COMMIT. This is functionally equivalent to:: + """Mark this transaction as successful and close in order to trigger a COMMIT. - :raise TransactionError: if already closed + :raise TransactionError: if the transaction is already closed """ + if self._closed: + raise TransactionError("Transaction closed") metadata = {} self._consume_results() # DISCARD pending records then do a commit. try: @@ -139,11 +143,12 @@ def commit(self): return self._bookmark def rollback(self): - """ Mark this transaction as unsuccessful and close in order to - trigger a ROLLBACK. This is functionally equivalent to:: + """Mark this transaction as unsuccessful and close in order to trigger a ROLLBACK. - :raise TransactionError: if already closed + :raise TransactionError: if the transaction is already closed """ + if self._closed: + raise TransactionError("Transaction closed") metadata = {} if not self._connection._is_reset: self._consume_results() # DISCARD pending records then do a rollback. @@ -154,16 +159,18 @@ def rollback(self): self._on_closed() def close(self): - """ Close this transaction, triggering either a ROLLBACK if not committed. + """Close this transaction, triggering a ROLLBACK if not closed. - :raise TransactionError: if already closed + :raise TransactionError: if the transaction could not perform a ROLLBACK. """ if self._closed: return self.rollback() def closed(self): - """ Indicator to show whether the transaction has been closed. - :returns: :const:`True` if closed, :const:`False` otherwise. + """Indicator to show whether the transaction has been closed. + + :return: :const:`True` if closed, :const:`False` otherwise. + :rtype: bool """ return self._closed