4.1 api docs update introduction example (#443)

* updated docs

* added application example and aura link

Author: martin-neotech

docs/source/breaking_changes.rst

@@ -4,11 +4,18 @@
 Breaking Changes
 ****************
 
+This describes the breaking changes between Python Driver 1.7 and Python Driver 4.0
+
 Version Scheme Changes
 ======================
 
 The version number has jumped from **Python Driver 1.7** to **Python Driver 4.0** to align with the Neo4j Database version scheme.
 
+Python Versions
+===============
+
+Python 2.7 is no longer supported.
+
 
 Namespace Changes
 =================
@@ -79,13 +86,16 @@ Argument Renaming Changes
 * :code:`StatementResultSummary.statement_type` is now :code:`ResultSummary.query_type`
 * :code:`StatementResultSummary.protocol_version` is now :code:`ResultSummary.server.protocol_version`
 
-
 API Changes
 =========================
 
 * :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:`Result.data()` has been removed. Use :code:`Record.data()` for each Record when iterating the Result object.
+* :code:`Result.data(*items)` has been changed to :code:`Result.data(*keys)` for alignment with :code:`Record.data(*keys)`.
+
+* :code:`Result.value(item=0, default=None)` has been changed to :code:`Result.value(key=0, default=None)` for alignment with :code:`Record.value(key=0, default=None)`.
+
+* :code:`Result.values(*items)` has been changed to :code:`Result.values(*keys)` for alignment with :code:`Record.values(*keys)`.
 
 * :code:`Transaction.sync()` has been removed. Use :code:`Result.consume()` if the behaviour is to exhaust the result object.
 

docs/source/index.rst

@@ -18,9 +18,8 @@ Python versions supported:
 * Python 3.5
 
 .. note::
-    Python 2.7 support has been dropped.
 
-    The previous driver `Python Driver 1.7`_ supports older versions of python, **Neo4j 4.1** will work in fallback mode with that driver.
+    The `Python Driver 1.7`_ supports older versions of python, **Neo4j 4.1** will work in fallback mode with that driver.
 
 
 ******
@@ -42,10 +41,57 @@ Topics
    breaking_changes.rst
 
 
+************
+Installation
+************
+
+To install the latest stable release, use:
+
+.. code:: bash
+
+    python -m pip install neo4j
+
+
+To install the latest pre-release, use:
+
+.. code:: bash
+
+    python -m pip install --pre neo4j
+
+
+.. note::
+
+   It is always recommended to install python packages for user space in a virtual environment.
+
+
+Virtual Environment
+===================
+
+To create a virtual environment named sandbox, use:
+
+.. code:: bash
+
+    python -m venv sandbox
+
+To activate the virtual environment named sandbox, use:
+
+.. code:: bash
+
+    source sandbox/bin/activate
+
+To deactivate the current active virtual environment, use:
+
+.. code:: bash
+
+    deactivate
+
+
 *************
 Quick Example
 *************
 
+Creating nodes.
+
 .. code-block:: python
 
     from neo4j import GraphDatabase
@@ -66,6 +112,9 @@ Quick Example
 
     driver.close()
 
+
+Finding nodes.
+
 .. code-block:: python
 
     from neo4j import GraphDatabase
@@ -90,49 +139,88 @@ Quick Example
     driver.close()
 
 
-************
-Installation
-************
-
-To install the latest stable release, use:
-
-.. code:: bash
-
-    python -m pip install neo4j
-
-
-To install the latest pre-release, use:
-
-.. code:: bash
-
-    python -m pip install --pre neo4j
-
-
-.. note::
-
-   It is always recommended to install python packages for user space in a virtual environment.
+*******************
+Example Application
+*******************
 
+.. code-block:: python
 
-Virtual Environment
-===================
-
-To create a virtual environment named sandbox, use:
-
-.. code:: bash
-
-    python -m venv sandbox
-
-To activate the virtual environment named sandbox, use:
-
-.. code:: bash
-
-    source sandbox/bin/activate
-
-To deactivate the current active virtual environment, use:
-
-.. code:: bash
-
-    deactivate
+    import logging
+    from neo4j import GraphDatabase
+    from neo4j.exceptions import ServiceUnavailable
+
+    class App:
+
+        def __init__(self, uri, user, password):
+            # Aura queries use an encrypted connection
+            self.driver = GraphDatabase.driver(uri, auth=(user, password), encrypted=True)
+
+        def close(self):
+            # Don't forget to close the driver connection when you are finished with it
+            self.driver.close()
+
+        def create_friendship(self, person1_name, person2_name):
+            with self.driver.session() as session:
+                # Write transactions allow the driver to handle retries and transient errors
+                result = session.write_transaction(
+                    self._create_and_return_friendship, person1_name, person2_name)
+                for record in result:
+                    print("Created friendship between: {p1}, {p2}".format(
+                        p1=record['p1'], p2=record['p2']))
+
+        @staticmethod
+        def _create_and_return_friendship(tx, person1_name, person2_name):
+
+            # To learn more about the Cypher syntax,
+            # see https://neo4j.com/docs/cypher-manual/current/
+
+            # The Reference Card is also a good resource for keywords,
+            # see https://neo4j.com/docs/cypher-refcard/current/
+
+            query = """
+            CREATE (p1:Person { name: $person1_name })
+            CREATE (p2:Person { name: $person2_name })
+            CREATE (p1)-[:KNOWS]->(p2)
+            RETURN p1, p2
+            """
+            result = tx.run(query, person1_name=person1_name, person2_name=person2_name)
+            try:
+                return [{"p1": record["p1"]["name"], "p2": record["p2"]["name"]}
+                        for record in result]
+            # Capture any errors along with the query and data for traceability
+            except ServiceUnavailable as exception:
+                logging.error("{query} raised an error: \n {exception}".format(
+                    query=query, exception=exception))
+                raise
+
+        def find_person(self, person_name):
+            with self.driver.session() as session:
+                result = session.read_transaction(self._find_and_return_person, person_name)
+                for record in result:
+                    print("Found person: {record}".format(record=record))
+
+        @staticmethod
+        def _find_and_return_person(tx, person_name):
+            query = """
+            MATCH (p:Person)
+            WHERE p.name = $person_name
+            RETURN p.name AS name
+            """
+            result = tx.run(query, person_name=person_name)
+            return [record["name"] for record in result]
+
+    if __name__ == "__main__":
+        # See https://neo4j.com/developer/aura-connect-driver/ for Aura specific connection URL.
+        scheme = "neo4j"
+        host_name = "example.com"
+        port = 7687
+        url = "{scheme}://{host_name}:{port}".format(scheme=scheme, host_name=host_name, port=port)
+        user = "<Username for Neo4j database>"
+        password = "<Password for Neo4j database>"
+        app = App(url, user, password)
+        app.create_friendship("Alice", "David")
+        app.find_person("Alice")
+        app.close()
 
 
 *****************
@@ -145,6 +233,7 @@ Other Information
 * `Example Project`_
 * `Driver Wiki`_ (includes change logs)
 * `Migration Guide - Upgrade Neo4j drivers`_
+* `Neo4j Aura`_
 
 .. _`Python Driver 1.7`: https://neo4j.com/docs/api/python-driver/1.7/
 .. _`Neo4j Documentation`: https://neo4j.com/docs/
@@ -153,3 +242,4 @@ Other Information
 .. _`Example Project`: https://github.com/neo4j-examples/movies-python-bolt
 .. _`Driver Wiki`: https://github.com/neo4j/neo4j-python-driver/wiki
 .. _`Migration Guide - Upgrade Neo4j drivers`: https://neo4j.com/docs/migration-guide/4.0/upgrade-driver/
+.. _`Neo4j Aura`: https://neo4j.com/neo4j-aura/