update api documentation (#409)

Author: martin-neotech

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,18 +534,21 @@ 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
 
     .. 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
 

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

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

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