API docs: driver page

Author: technige

docs/source/driver.rst

@@ -6,13 +6,20 @@ A `Driver` object holds the detail of a Neo4j database including server URIs, cr
 It also manages a pool of connections which are used to power :class:`.Session` instances.
 
 The scheme of the URI passed to the `Driver` constructor determines the type of `Driver` object constructed.
-Two types are currently available: the :class:`.DirectDriver` and the :class:`.RoutingDriver`.
-These are described in more detail below.
+For example, the ``bolt`` scheme generates a :class:`.DirectDriver` instance::
+
+    from neo4j.v1 import GraphDatabase
+    uri = "bolt://localhost:7687"
+    driver = GraphDatabase.driver(uri, auth=("neo4j", "password"))
 
 
 .. autoclass:: neo4j.v1.GraphDatabase
    :members:
 
+.. autoclass:: neo4j.v1.Driver
+   :members:
+   :inherited-members:
+
 .. autoclass:: neo4j.v1.DirectDriver
    :members:
    :inherited-members:
@@ -29,21 +36,21 @@ These are described in more detail below.
 .. autofunction:: neo4j.v1.custom_auth
 
 
-Encryption Settings
--------------------
-.. py:attribute:: neo4j.v1.ENCRYPTION_OFF
-.. py:attribute:: neo4j.v1.ENCRYPTION_ON
-.. py:attribute:: neo4j.v1.ENCRYPTION_DEFAULT
+Trust Options
+-------------
+.. py:attribute:: neo4j.v1.TRUST_ALL_CERTIFICATES
 
+   Trust any server certificate (default). This ensures that communication
+   is encrypted but does not verify the server certificate against a
+   certificate authority. This option is primarily intended for use with
+   the default auto-generated server certificate.
 
-Trust Settings
---------------
-.. py:attribute:: neo4j.v1.TRUST_ALL_CERTIFICATES
-.. py:attribute:: neo4j.v1.TRUST_CUSTOM_CA_SIGNED_CERTIFICATES
 .. py:attribute:: neo4j.v1.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES
-.. py:attribute:: neo4j.v1.TRUST_DEFAULT
 
-Deprecated
-~~~~~~~~~~
-.. py:attribute:: neo4j.v1.TRUST_ON_FIRST_USE
-.. py:attribute:: neo4j.v1.TRUST_SIGNED_CERTIFICATES
+   Trust server certificates that can be verified against the system
+   certificate authority. This option is primarily intended for use with
+   full certificates.
+
+.. NOTE:: The option :attr:`.TRUST_CUSTOM_CA_SIGNED_CERTIFICATES` is not yet available for Python
+
+.. NOTE:: The options :attr:`.TRUST_ON_FIRST_USE` and :attr:`.TRUST_SIGNED_CERTIFICATES` are deprecated.

docs/source/index.rst

@@ -2,19 +2,18 @@
 Neo4j Bolt Driver for Python
 ****************************
 
-The Official Neo4j Driver for Python supports Neo4j 3.0 and above and Python versions 2.7, 3.4 and 3.5.
+The Official Neo4j Driver for Python supports Neo4j 3.0 and above and Python versions 2.7, 3.4, 3.5 and 3.6.
 
 
 Quick Example
 =============
 
 .. code-block:: python
 
-    from neo4j.v1 import GraphDatabase, basic_auth
+    from neo4j.v1 import GraphDatabase
 
     uri = "bolt://localhost:7687"
-    auth_token = basic_auth("neo4j", "password")
-    driver = GraphDatabase.driver(uri, auth=auth_token)
+    driver = GraphDatabase.driver(uri, auth=("neo4j", "password"))
 
     def print_friends_of(name):
         with driver.session() as session:

neo4j/v1/api.py

@@ -39,9 +39,9 @@ def hydrate(self, values):
 
 
 class GraphDatabase(object):
-    """ The :class:`.GraphDatabase` class provides access to all graph
-    database functionality. This is primarily used to construct a driver
-    instance, using the :meth:`.driver` method.
+    """ The `GraphDatabase` class provides access to all graph
+    database functionality. This class is primarily used to construct a
+    :class:`.Driver` instance, using the :meth:`.driver` method.
     """
 
     uri_schemes = {}
@@ -50,31 +50,33 @@ class GraphDatabase(object):
 
     @classmethod
     def driver(cls, uri, **config):
-        """ Acquire a :class:`.Driver` instance for the given URL and
-        configuration:
+        """ Acquire a :class:`.Driver` instance for the given URI and
+        configuration. The URI scheme determines the Driver implementation
+        that will be returned. Options are:
 
-            >>> from neo4j.v1 import GraphDatabase
-            >>> driver = GraphDatabase.driver("bolt://localhost:7687")
+            ``bolt``
+              Returns a :class:`.DirectDriver`.
 
-        :param uri: URI for a graph database
+            ``bolt+routing``
+              Returns a :class:`.RoutingDriver`.
+
+        :param uri: URI for a graph database service
         :param config: configuration and authentication details (valid keys are listed below)
 
             `auth`
               An authentication token for the server, for example
-              ``basic_auth("neo4j", "password")``.
+              ``("neo4j", "password")``.
 
             `der_encoded_server_certificate`
               The server certificate in DER format, if required.
 
             `encrypted`
-              Encryption level: one of :attr:`.ENCRYPTION_ON`, :attr:`.ENCRYPTION_OFF`
-              or :attr:`.ENCRYPTION_NON_LOCAL`. The default setting varies
-              depending on whether SSL is available or not. If it is,
-              :attr:`.ENCRYPTION_NON_LOCAL` is the default.
+              A boolean flag to determine whether encryption should be used.
+              Defaults to :const:`True`.
 
             `trust`
-              Trust level: one of :attr:`.TRUST_ON_FIRST_USE` (default) or
-              :attr:`.TRUST_SIGNED_CERTIFICATES`.
+              Trust level: one of :attr:`.TRUST_ALL_CERTIFICATES` (default) or
+              :attr:`.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES`.
 
             `user_agent`
               A custom user agent string, if required.
@@ -90,12 +92,12 @@ def driver(cls, uri, **config):
 
 
 class Driver(object):
-    """ A :class:`.Driver` is an accessor for a specific graph database
-    resource. It is thread-safe, acts as a template for sessions and hosts
-    a connection pool.
+    """ The base class for all `Driver` implementations. A Driver is an accessor for
+    a specific graph database. It is typically thread-safe, acts as a template for
+    :class:`.Session` creation and hosts a connection pool.
 
     All configuration and authentication settings are held immutably by the
-    `Driver`. Should different settings be required, a new `Driver` instance
+    Driver. Should different settings be required, a new Driver instance
     should be created via the :meth:`.GraphDatabase.driver` method.
     """
 
@@ -118,10 +120,16 @@ def session(self, access_mode=None):
         pool. Session creation is a lightweight operation and sessions are
         not thread safe, therefore a session should generally be short-lived
         within a single thread.
+
+        :param access_mode:
+        :return: new :class:`.Session` object
         """
         pass
 
     def close(self):
+        """ Shut down, closing any open connections that were spawned by
+        this Driver.
+        """
         if self.pool:
             self.pool.close()
             self.pool = None

neo4j/v1/bolt.py

@@ -33,8 +33,9 @@
 
 
 class DirectDriver(Driver):
-    """ A :class:`.DirectDriver` is created from a `bolt` URI and addresses
-    a single database instance.
+    """ A :class:`.DirectDriver` is created from a ``bolt`` URI and addresses
+    a single database instance. This provides basic connectivity to any
+    database service topology.
     """
 
     def __init__(self, uri, **config):
@@ -58,7 +59,9 @@ def session(self, access_mode=None):
 
 
 class RoutingDriver(Driver):
-    """ A :class:`.RoutingDriver` is created from a `bolt+routing` URI.
+    """ A :class:`.RoutingDriver` is created from a ``bolt+routing`` URI. The
+    routing behaviour works in tandem with Neo4j's causal clustering feature
+    by directing read and write behaviour to appropriate cluster members.
     """
 
     def __init__(self, uri, **config):