Merge branch '1.1' of https://github.com/neo4j/neo4j-python-driver into 1.1

Author: Zhen Li

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "neokit"]
-    path = neokit
-    url = https://github.com/nigelsmall/neokit.git
+	path = neokit
+	url = https://github.com/neo-technology/neokit.git

CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to the Neo4j Ecosystem
+
+At [Neo Technology](http://neo4j.com/), we develop our software in the open at GitHub.
+This provides transparency for you, our users, and allows you to fork the software to make your own additions and enhancements.
+We also provide areas specifically for community contributions, in particular the [neo4j-contrib](https://github.com/neo4j-contrib) space.
+
+There's an active [mailing list](https://groups.google.com/forum/#!forum/neo4j) and [Slack channel](http://neo4j.com/slack) where we work directly with the community.
+If you're not already a member, sign up!
+
+We love our community and wouldn't be where we are without you.
+
+
+## Need to raise an issue?
+
+Where you raise an issue depends largely on the nature of the problem.
+
+Firstly, if you are an Enterprise customer, you might want to head over to our [Customer Support Portal](http://support.neo4j.com/).
+
+There are plenty of public channels available too, though.
+If you simply want to get started or have a question on how to use a particular feature, drop a line to the [mailing list](https://groups.google.com/forum/#!forum/neo4j), ask a question in [Slack](http://neo4j.com/slack), or [tweet](https://twitter.com/neo4j) us.
+If you think you might have hit a bug in our software (it happens occasionally!) or you have specific feature request then use the issue feature on the relevant GitHub repository.
+Check first though as someone else may have already raised something similar.
+
+[StackOverflow](http://stackoverflow.com/questions/tagged/neo4j) also hosts a ton of questions and might already have a discussion around your problem.
+Make sure you have a look there too.
+
+Include as much information as you can in any request you make:
+
+- Which versions of our products are you using?
+- Which language (and which version of that language) are you developing with?
+- What operating system are you on?
+- Are you working with a cluster or on a single machine?
+- What code are you running?
+- What errors are you seeing?
+- What solutions have you tried already?
+
+
+## Want to contribute?
+
+If you want to contribute a pull request, we have a little bit of process you'll need to follow:
+
+- Do all your work in a personal fork of the original repository
+- [Rebase](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request), don't merge (we prefer to keep our history clean)
+- Create a branch (with a useful name) for your contribution
+- Make sure you're familiar with the appropriate coding style (this varies by language so ask if you're in doubt)
+- Include unit tests if appropriate (obviously not necessary for documentation changes)
+- Take a moment to read and sign our [CLA](http://neo4j.com/developer/cla)
+
+We can't guarantee that we'll accept pull requests and may ask you to make some changes before they go in.
+Occasionally, we might also have logistical, commercial, or legal reasons why we can't accept your work but we'll try to find an alternative way for you to contribute in that case.
+Remember that many community members have become regular contributors and some are now even Neo employees!
+
+
+## Got an idea for a new project?
+
+If you have an idea for a new tool or library, start by talking to other people in the community.
+Chances are that someone has a similar idea or may have already started working on it.
+The best software comes from getting like minds together to solve a problem.
+And we'll do our best to help you promote and co-ordinate your Neo ecosystem projects.
+
+
+## Further reading
+
+If you want to find out more about how you can contribute, head over to our website for [more information](http://neo4j.com/developer/contributing-code/).
+

docs_requirements.txt renamed to docs/requirements.txt

@@ -32,7 +32,7 @@
 # (* "good reason" is defined as knowing what you are doing)
 
 
-auth_token = basic_auth("neo4j", "password")
+auth_token = basic_auth("neo4j", "neo4j")
 
 
 class FreshDatabaseTestCase(ServerTestCase):
@@ -48,7 +48,7 @@ class MinimalWorkingExampleTestCase(FreshDatabaseTestCase):
 
     def test_minimal_working_example(self):
         # tag::minimal-example[]
-        driver = GraphDatabase.driver("bolt://localhost", auth=basic_auth("neo4j", "password"))
+        driver = GraphDatabase.driver("bolt://localhost", auth=basic_auth("neo4j", "neo4j"))
         session = driver.session()
 
         session.run("CREATE (a:Person {name:'Arthur', title:'King'})")
@@ -65,33 +65,33 @@ class ExamplesTestCase(FreshDatabaseTestCase):
 
     def test_construct_driver(self):
         # tag::construct-driver[]
-        driver = GraphDatabase.driver("bolt://localhost", auth=basic_auth("neo4j", "password"))
+        driver = GraphDatabase.driver("bolt://localhost", auth=basic_auth("neo4j", "neo4j"))
         # end::construct-driver[]
         return driver
 
     def test_configuration(self):
         # tag::configuration[]
-        driver = GraphDatabase.driver("bolt://localhost", auth=basic_auth("neo4j", "password"), max_pool_size=10)
+        driver = GraphDatabase.driver("bolt://localhost", auth=basic_auth("neo4j", "neo4j"), max_pool_size=10)
         # end::configuration[]
         return driver
 
     @skipUnless(SSL_AVAILABLE, "Bolt over TLS is not supported by this version of Python")
     def test_tls_require_encryption(self):
         # tag::tls-require-encryption[]
-        driver = GraphDatabase.driver("bolt://localhost", auth=basic_auth("neo4j", "password"), encrypted=True)
+        driver = GraphDatabase.driver("bolt://localhost", auth=basic_auth("neo4j", "neo4j"), encrypted=True)
         # end::tls-require-encryption[]
 
     @skipUnless(SSL_AVAILABLE, "Bolt over TLS is not supported by this version of Python")
     def test_tls_trust_on_first_use(self):
         # tag::tls-trust-on-first-use[]
-        driver = GraphDatabase.driver("bolt://localhost", auth=basic_auth("neo4j", "password"), encrypted=True, trust=TRUST_ON_FIRST_USE)
+        driver = GraphDatabase.driver("bolt://localhost", auth=basic_auth("neo4j", "neo4j"), encrypted=True, trust=TRUST_ON_FIRST_USE)
         # end::tls-trust-on-first-use[]
         assert driver
 
     @skip("testing verified certificates not yet supported ")
     def test_tls_signed(self):
         # tag::tls-signed[]
-        driver = GraphDatabase.driver("bolt://localhost", auth=basic_auth("neo4j", "password"), encrypted=True, trust=TRUST_SIGNED_CERTIFICATES)
+        driver = GraphDatabase.driver("bolt://localhost", auth=basic_auth("neo4j", "neo4j"), encrypted=True, trust=TRUST_SIGNED_CERTIFICATES)
         # end::tls-signed[]
         assert driver
 

examples/test_examples.py

@@ -20,3 +20,12 @@
 
 
 from .meta import version as __version__
+
+# Export current (v1) API. This should be updated to export the latest
+# version of the API when a new one is added. This gives the option to
+# `import neo4j.vX` for a specific version or `import neo4j` for the
+# latest.
+from .v1.constants import *
+from .v1.exceptions import *
+from .v1.session import *
+from .v1.types import *

makedocs.sh

@@ -19,14 +19,8 @@
 # limitations under the License.
 
 
-from __future__ import unicode_literals
-
 import logging
-from argparse import ArgumentParser
-from json import loads as json_loads
-from sys import stdout, stderr
-
-from .v1.session import GraphDatabase, CypherError
+from sys import stdout
 
 
 class ColourFormatter(logging.Formatter):
@@ -50,7 +44,7 @@ def format(self, record):
 
 
 class Watcher(object):
-    """ Log watcher for debug output.
+    """ Log watcher for monitoring driver and protocol activity.
     """
 
     handlers = {}
@@ -74,3 +68,16 @@ def stop(self):
             self.logger.removeHandler(self.handlers[self.logger_name])
         except KeyError:
             pass
+
+
+def watch(logger_name, level=logging.INFO, out=stdout):
+    """ Quick wrapper for using the Watcher.
+
+    :param logger_name: name of logger to watch
+    :param level: minimum log level to show (default INFO)
+    :param out: where to send output (default stdout)
+    :return: Watcher instance
+    """
+    watcher = Watcher(logger_name)
+    watcher.watch(level, out)
+    return watcher

neo4j/.DS_Store

@@ -18,7 +18,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .connection import ProtocolError
 from .constants import *
+from .exceptions import *
 from .session import *
 from .types import *

neo4j/__init__.py

@@ -19,6 +19,13 @@
 # limitations under the License.
 
 
+"""
+This module contains the low-level functionality required for speaking
+Bolt. It is not intended to be used directly by driver users. Instead,
+the `session` module provides the main user-facing abstractions.
+"""
+
+
 from __future__ import division
 
 from base64 import b64encode
@@ -31,18 +38,16 @@
 from socket import create_connection, SHUT_RDWR, error as SocketError
 from struct import pack as struct_pack, unpack as struct_unpack, unpack_from as struct_unpack_from
 
-import errno
-
-from .constants import DEFAULT_PORT, DEFAULT_USER_AGENT, KNOWN_HOSTS, MAGIC_PREAMBLE, \
-    TRUST_DEFAULT, TRUST_ON_FIRST_USE
+from .constants import DEFAULT_USER_AGENT, KNOWN_HOSTS, MAGIC_PREAMBLE, TRUST_DEFAULT, TRUST_ON_FIRST_USE
 from .compat import hex2
 from .exceptions import ProtocolError
 from .packstream import Packer, Unpacker
 from .ssl_compat import SSL_AVAILABLE, HAS_SNI, SSLError
 
 
 # Signature bytes for each message type
-INIT = b"\x01"             # 0000 0001 // INIT <user_agent>
+INIT = b"\x01"             # 0000 0001 // INIT <user_agent> <auth>
+ACK_FAILURE = b"\x0E"      # 0000 1110 // ACK_FAILURE
 RESET = b"\x0F"            # 0000 1111 // RESET
 RUN = b"\x10"              # 0001 0000 // RUN <statement> <parameters>
 DISCARD_ALL = b"\x2F"      # 0010 1111 // DISCARD *
@@ -57,6 +62,7 @@
 
 message_names = {
     INIT: "INIT",
+    ACK_FAILURE: "ACK_FAILURE",
     RESET: "RESET",
     RUN: "RUN",
     DISCARD_ALL: "DISCARD_ALL",
@@ -224,7 +230,7 @@ def __init__(self, sock, **config):
         self.der_encoded_server_certificate = config.get("der_encoded_server_certificate")
 
         def on_failure(metadata):
-            raise ProtocolError(metadata.get("message", "Inititalisation failed"))
+            raise ProtocolError(metadata.get("message", "INIT failed"))
 
         response = Response(self)
         response.on_failure = on_failure
@@ -237,6 +243,13 @@ def on_failure(metadata):
     def __del__(self):
         self.close()
 
+    @property
+    def healthy(self):
+        """ Return ``True`` if this connection is healthy, ``False`` if
+        unhealthy and ``None`` if closed.
+        """
+        return None if self.closed else not self.defunct
+
     def append(self, signature, fields=(), response=None):
         """ Add a message to the outgoing queue.
 
@@ -253,6 +266,23 @@ def append(self, signature, fields=(), response=None):
         self.channel.flush(end_of_message=True)
         self.responses.append(response)
 
+    def acknowledge_failure(self):
+        """ Add an ACK_FAILURE message to the outgoing queue, send
+        it and consume all remaining messages.
+        """
+        response = Response(self)
+
+        def on_failure(metadata):
+            raise ProtocolError("ACK_FAILURE failed")
+
+        response.on_failure = on_failure
+
+        self.append(ACK_FAILURE, response=response)
+        self.send()
+        fetch = self.fetch
+        while not response.complete:
+            fetch()
+
     def reset(self):
         """ Add a RESET message to the outgoing queue, send
         it and consume all remaining messages.
@@ -304,7 +334,7 @@ def fetch(self):
                 response.complete = True
                 self.responses.popleft()
             if signature == FAILURE:
-                self.reset()
+                self.acknowledge_failure()
             handler_name = "on_%s" % message_names[signature].lower()
             try:
                 handler = getattr(response, handler_name)
@@ -314,6 +344,12 @@ def fetch(self):
                 handler(*fields)
         raw.close()
 
+    def fetch_all(self):
+        while self.responses:
+            response = self.responses[0]
+            while not response.complete:
+                self.fetch()
+
     def close(self):
         """ Close the connection.
         """
@@ -370,26 +406,26 @@ def match_or_trust(self, host, der_encoded_certificate):
         return True
 
 
-def connect(host, port=None, ssl_context=None, **config):
+def connect(host_port, ssl_context=None, **config):
     """ Connect and perform a handshake and return a valid Connection object, assuming
     a protocol version can be agreed.
     """
 
     # Establish a connection to the host and port specified
     # Catches refused connections see:
     # https://docs.python.org/2/library/errno.html
-    port = port or DEFAULT_PORT
-    if __debug__: log_info("~~ [CONNECT] %s %d", host, port)
+    if __debug__: log_info("~~ [CONNECT] %s", host_port)
     try:
-        s = create_connection((host, port))
+        s = create_connection(host_port)
     except SocketError as error:
         if error.errno == 111 or error.errno == 61:
-            raise ProtocolError("Unable to connect to %s on port %d - is the server running?" % (host, port))
+            raise ProtocolError("Unable to connect to %s on port %d - is the server running?" % host_port)
         else:
             raise
 
     # Secure the connection if an SSL context has been provided
     if ssl_context and SSL_AVAILABLE:
+        host, port = host_port
         if __debug__: log_info("~~ [SECURE] %s", host)
         try:
             s = ssl_context.wrap_socket(s, server_hostname=host if HAS_SNI else None)