4.0 examples update (#385)

* hello world up to date

* custom resolver example updated

* fixed the url in the example

* updated the all import

* added a todo

* added example for connection timeout

* renamed example file name

* added unencrypted example

* aligned naming for configuration max_retry_time to be max_transaction_retry_time

* fiexed typo

* database-selection

* transaction-function example updated

* result-consume example updated

* result_retain updated

* updated examples

* fixed test to run against Neo4j 3.5

* fixed test against Neo4j 3.4

* fixed import for examples

* added what examples have imports in the comment

* updated comment

Author: martin-neotech

docs/source/index.rst

@@ -163,7 +163,10 @@ Dependency Changes
 The dependency :code:`neobolt` have been removed.
 
 
+Configuration Name Changes
+==========================
 
+* :code:`max_retry_time` is now :code:`max_transaction_retry_time`
 
 
 *****************

docs/source/usage_patterns.rst

@@ -53,7 +53,7 @@ Driver Initialization Work Pattern
         "max_connection_lifetime": 1000,
         "max_connection_pool_size": 100,
         "keep_alive": False,
-        "max_retry_time": 10,
+        "max_transaction_retry_time": 10,
         "resolver": None,
     }
 
@@ -99,7 +99,7 @@ Session Initialization Work Pattern
         "bookmarks": ["bookmark-1",],
         "access_mode": ACCESS_WRITE,
         "connection_acquisition_timeout": 60.0,
-        "max_retry_time": 30.0,
+        "max_transaction_retry_time": 30.0,
         "initial_retry_delay": 1.0,
         "retry_delay_multiplier": 2.0,
         "retry_delay_jitter_factor": 0.2,

neo4j/__init__.py

@@ -27,6 +27,31 @@
     "Neo4jDriver",
     "Auth",
     "AuthToken",
+    "basic_auth",
+    "kerberos_auth",
+    "custom_auth",
+    "Bookmark",
+    "ServerInfo",
+    "Version",
+    "READ_ACCESS",
+    "WRITE_ACCESS",
+    "DEFAULT_DATABASE",
+    "TRUST_ALL_CERTIFICATES",
+    "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES",
+    "Address",
+    "IPv4Address",
+    "IPv6Address",
+    "Config",
+    "PoolConfig",
+    "WorkspaceConfig",
+    "SessionConfig",
+    "Record",
+    "Transaction",
+    "Result",
+    "ResultSummary",
+    "Query",
+    "Session",
+    "unit_of_work",
 ]
 
 from logging import getLogger

neo4j/api.py

@@ -56,6 +56,7 @@
 DEFAULT_DATABASE = None  # Must be a non string hashable value
 
 
+# TODO: This class is not tested
 class Auth:
     """ Container for auth details.
     """

neo4j/conf.py

@@ -275,9 +275,9 @@ class WorkspaceConfig(Config):
     # Since the process of acquiring a connection may involve creating a new connection, ensure that the value
     # of this configuration is higher than the configured Connection Timeout.
 
-    #: Max Retry Time
-    max_retry_time = 30.0  # seconds
-    # The maximum amount of time that a managed transaction will retry for before failing.
+    #: Max Transaction Retry Time
+    max_transaction_retry_time = 30.0  # seconds
+    # The maximum amount of time that a managed transaction will retry before failing.
 
     #: Initial Retry Delay
     initial_retry_delay = 1.0  # seconds

neo4j/work/simple.py

@@ -416,7 +416,7 @@ def _run_transaction(self, access_mode, unit_of_work, *args, **kwargs):
             else:
                 return result
             t1 = perf_counter()
-            if t1 - t0 > self._config.max_retry_time:
+            if t1 - t0 > self._config.max_transaction_retry_time:
                 break
             delay = next(retry_delay)
             log.warning("Transaction failed and will be retried in {}s "

tests/integration/examples/__init__.py

@@ -19,6 +19,36 @@
 # limitations under the License.
 
 
+# List of example tags used in the drivers manual version 4.0
+
+
+# hello-world, hello-world-import                               - Example 1.6. Hello World
+# driver-lifecycle, driver-lifecycle-import                     - Example 2.1. The driver lifecycle
+# custom-resolver, custom-resolver-import                       - Example 2.2. Custom Address Resolver
+# basic-auth, basic-auth-import                                 - Example 2.5. Basic authentication
+# kerberos-auth, kerberos-auth-import                           - Example 2.6. Kerberos authentication
+# custom-auth, custom-auth-import                               - Example 2.7. Custom authentication
+# config-connection-pool, config-connection-pool-import         - Example 2.8. Configure connection pool
+# config-connection-timeout, config-connection-timeout-import   - Example 2.9. Configure connection timeout
+# config-unencrypted, config-unencrypted-import                 - Example 2.10. Unencrypted configuration
+# config-max-retry-time, config-max-retry-time-import           - Example 2.11. Configure maximum transaction retry time
+# config-trust, config-trust-import                             - Example 2.12. Configure trusted certificates
+# pass-bookmarks, pass-bookmarks-import                         - Example 3.1. Pass bookmarks
+# read-write-transaction                                        - Example 3.2. Read-write transaction
+# database-selection, database-selection-import                 - Example 3.3. Database selection on session creation
+# Hard coded (session)                                          - Example 4.1. Session construction and closure
+# transaction-function, transaction-function-import             - Example 4.2. Transaction function
+# autocommit-transaction, autocommit-transaction-import         - Example 4.3. Simple auto-commit transactions
+# result-consume                                                - Example 4.4. Consuming results
+# result-retain                                                 - Example 4.5. Retain results for further processing
+#                                                               - Example 4.6. Asynchronous transaction functions
+#                                                               - Example 4.7. Asynchronous auto-commit transactions
+#                                                               - Example 4.8. Asynchronous consuming results
+#                                                               - Example 4.9. Reactive transaction functions
+#                                                               - Example 4.10.Reactive auto-commit transactions
+#                                                               - Example 4.11.Reactive consuming results
+
+
 class DriverSetupExample:
 
     driver = None

tests/integration/examples/test_autocommit_transaction_example.py

@@ -20,7 +20,7 @@
 
 
 # tag::autocommit-transaction-import[]
-from neo4j.work.simple import Query
+from neo4j import Query
 # end::autocommit-transaction-import[]
 
 

tests/integration/examples/test_auth_example.py renamed to tests/integration/examples/test_basic_auth_example.py

@@ -30,7 +30,7 @@
 from tests.integration.examples import DriverSetupExample
 
 
-# python -m pytest tests/integration/examples/test_auth_example.py -s -v
+# python -m pytest tests/integration/examples/test_basic_auth_example.py -s -v
 
 class BasicAuthExample(DriverSetupExample):
 

tests/integration/examples/test_config_connection_timeout_example.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python
+# -*- encoding: utf-8 -*-
+
+# Copyright (c) 2002-2020 "Neo4j,"
+# Neo4j Sweden AB [http://neo4j.com]
+#
+# This file is part of Neo4j.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import pytest
+
+from neo4j.exceptions import ServiceUnavailable
+from neo4j._exceptions import BoltHandshakeError
+
+# tag::config-connection-timeout-import[]
+from neo4j import GraphDatabase
+# end::config-connection-timeout-import[]
+
+from tests.integration.examples import DriverSetupExample
+
+
+# python -m pytest tests/integration/examples/test_config_connection_timeout_example.py -s -v
+
+class ConfigConnectionTimeoutExample(DriverSetupExample):
+
+    # tag::config-connection-timeout[]
+    def __init__(self, uri, auth):
+        self.driver = GraphDatabase.driver(uri, auth=auth, connection_timeout=15)
+    # end::config-connection-timeout[]
+
+
+def test(uri, auth):
+    try:
+        ConfigConnectionTimeoutExample.test(uri, auth)
+    except ServiceUnavailable as error:
+        if isinstance(error.__cause__, BoltHandshakeError):
+            pytest.skip(error.args[0])

tests/integration/examples/test_config_max_retry_time_example.py

@@ -36,7 +36,7 @@ class ConfigMaxRetryTimeExample(DriverSetupExample):
 
     # tag::config-max-retry-time[]
     def __init__(self, uri, auth):
-        self.driver = GraphDatabase.driver(uri, auth=auth, max_retry_time=15)
+        self.driver = GraphDatabase.driver(uri, auth=auth, max_transaction_retry_time=15)
     # end::config-max-retry-time[]
 
 

tests/integration/examples/test_config_unencrypted_example.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python
+# -*- encoding: utf-8 -*-
+
+# Copyright (c) 2002-2020 "Neo4j,"
+# Neo4j Sweden AB [http://neo4j.com]
+#
+# This file is part of Neo4j.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import pytest
+
+# tag::config-unencrypted-import[]
+from neo4j import GraphDatabase
+# end::config-unencrypted-import[]
+
+from neo4j.exceptions import ServiceUnavailable
+from neo4j._exceptions import BoltHandshakeError
+
+from tests.integration.examples import DriverSetupExample
+
+
+# python -m pytest tests/integration/examples/test_config_unencrypted_example.py -s -v
+
+class ConfigUnencryptedExample(DriverSetupExample):
+
+    # tag::config-unencrypted[]
+    def __init__(self, uri, auth):
+        self.driver = GraphDatabase.driver(uri, auth=auth, encrypted=False)
+    # end::config-unencrypted[]
+
+
+def test_example(uri, auth):
+    try:
+        ConfigUnencryptedExample.test(uri, auth)
+    except ServiceUnavailable as error:
+        if isinstance(error.__cause__, BoltHandshakeError):
+            pytest.skip(error.args[0])

tests/integration/examples/test_custom_auth_example.py

@@ -22,7 +22,10 @@
 import pytest
 
 # tag::custom-auth-import[]
-from neo4j import GraphDatabase, custom_auth
+from neo4j import (
+    GraphDatabase,
+    custom_auth,
+)
 # end::custom-auth-import[]
 
 from neo4j.exceptions import ServiceUnavailable

tests/integration/examples/test_custom_resolver_example.py

@@ -22,38 +22,47 @@
 import pytest
 
 # tag::custom-resolver-import[]
-from neo4j import GraphDatabase
+from neo4j import (
+    GraphDatabase,
+    WRITE_ACCESS,
+)
 # end::custom-resolver-import[]
 
 from neo4j.exceptions import ServiceUnavailable
 from neo4j._exceptions import BoltHandshakeError
-from tests.integration.examples import DriverSetupExample
 
 
 # python -m pytest tests/integration/examples/test_custom_resolver_example.py -s -v
 
+# tag::custom-resolver[]
+def create_driver(uri, user, password):
 
-class CustomResolverExample(DriverSetupExample):
+    def resolver(address):
+        host, port = address
+        if host == "x.example.com":
+            yield "a.example.com", port
+            yield "b.example.com", port
+            yield "c.example.com", port
+        else:
+            yield host, port
 
-    # tag::custom-resolver[]
-    def __init__(self, uri, auth):
+    return GraphDatabase.driver(uri, auth=(user, password), resolver=resolver)
 
-        def resolve(address):
-            host, port = address
-            if host == "x.example.com":
-                yield "a.example.com", port
-                yield "b.example.com", port
-                yield "c.example.com", port
-            else:
-                yield host, port
 
-        self.driver = GraphDatabase.driver(uri, auth=auth, resolver=resolve)
-    # end::custom-resolver[]
+def add_person(name):
+    driver = create_driver("neo4j://x.example.com", user="neo4j", password="password")
+    session = driver.session(default_access_mode=WRITE_ACCESS)
+    session.run("CREATE (a:Person {name: $name})", {"name", name})
+    session.close()
+    driver.close()
+# end::custom-resolver[]
 
 
 def test_example(uri, auth):
     try:
-        CustomResolverExample.test(uri, auth)
+        add_person("testing_resolver")
     except ServiceUnavailable as error:
         if isinstance(error.__cause__, BoltHandshakeError):
             pytest.skip(error.args[0])
+    except ValueError as error:
+        assert error.args[0] == "Cannot resolve address a.example.com:7687"