updated api documentation with better information about the auth token (#457)

* updated api documentation with better information about the auth token

* better description of the auth token

* fixed creation example

* added with block context example for driver creation

Author: martin-neotech

docs/source/api.rst

@@ -17,13 +17,38 @@ The :class:`neo4j.Driver` construction is via a `classmethod` on the :class:`neo
    :members: driver
 
 
+Example, driver creation:
+
 .. code-block:: python
 
-   from neo4j import GraphDatabase
+    from neo4j import GraphDatabase
+
+    uri = neo4j://example.com:7687
+    driver = GraphDatabase.driver(uri, auth=("neo4j", "password"), max_connection_lifetime=1000)
+
+    driver.close()  # close the driver object
+
+
+For basic auth, this can be a simple tuple, for example:
 
-   driver = GraphDatabase.driver(uri=neo4j://example.com:7687, auth=("neo4j", "password"), max_connection_lifetime=1000)
+.. code-block:: python
+
+   auth = ("neo4j", "password")
+
+This will implicitly create a :class:`neo4j.Auth` with a ``scheme="basic"``
+
+
+Example, with block context:
+
+.. code-block:: python
+
+    from neo4j import GraphDatabase
+
+    uri = neo4j://example.com:7687
+
+    with GraphDatabase.driver(uri, auth=("neo4j", "password")) as driver:
+        # use the driver
 
-   driver.close()
 
 
 .. _uri-ref:
@@ -78,18 +103,32 @@ Each supported scheme maps to a particular :class:`neo4j.Driver` subclass that i
 Auth
 ====
 
-An authentication token for the server.
+To authenticate with Neo4j the authentication details are supplied at driver creation.
 
-For basic auth, this can be a simple tuple, for example:
+The auth token is an object of the class :class:`neo4j.Auth` containing the details.
+
+.. autoclass:: neo4j.Auth
+
+
+
+Example:
 
 .. code-block:: python
 
-   auth = ("neo4j", "password")
+    import neo4j
+
+    auth = neo4j.Auth(scheme="basic", principal="neo4j", credentials="password")
 
-Alternatively, one of the auth token functions can be used.
+
+Auth Token Helper Functions
+---------------------------
+
+Alternatively, one of the auth token helper functions can be used.
 
 .. autofunction:: neo4j.basic_auth
 
+.. autofunction:: neo4j.kerberos_auth
+
 .. autofunction:: neo4j.custom_auth
 
 

neo4j/api.py

@@ -60,6 +60,17 @@
 # TODO: This class is not tested
 class Auth:
     """ Container for auth details.
+
+    :param scheme: specifies the type of authentication, examples: "basic", "kerberos"
+    :type scheme: str
+    :param principal: specifies who is being authenticated
+    :type principal: str
+    :param credentials: authenticates the principal
+    :type credentials: str
+    :param realm: specifies the authentication provider
+    :type realm: str
+    :param parameters: extra key word parameters passed along to the authentication provider
+    :type parameters: str
     """
 
     #: By default we should not send any realm
@@ -82,32 +93,42 @@ def __init__(self, scheme, principal, credentials, realm=None, **parameters):
 def basic_auth(user, password, realm=None):
     """ Generate a basic auth token for a given user and password.
 
-    :param user: user name
-    :param password: current password
+    This will set the scheme to "basic" for the auth token.
+
+    :param user: user name, this will set the principal
+    :param password: current password, this will set the credentials
     :param realm: specifies the authentication provider
+
     :return: auth token for use with :meth:`GraphDatabase.driver`
+    :rtype: :class:`neo4j.Auth`
     """
     return Auth("basic", user, password, realm)
 
 
 def kerberos_auth(base64_encoded_ticket):
     """ Generate a kerberos auth token with the base64 encoded ticket
 
-    :param base64_encoded_ticket: a base64 encoded service ticket
-    :return: an authentication token that can be used to connect to Neo4j
+    This will set the scheme to "kerberos" for the auth token.
+
+    :param base64_encoded_ticket: a base64 encoded service ticket, this will set the credentials
+
+    :return: auth token for use with :meth:`GraphDatabase.driver`
+    :rtype: :class:`neo4j.Auth`
     """
     return Auth("kerberos", "", base64_encoded_ticket)
 
 
 def custom_auth(principal, credentials, realm, scheme, **parameters):
-    """ Generate a basic auth token for a given user and password.
+    """ Generate a custom auth token.
 
     :param principal: specifies who is being authenticated
     :param credentials: authenticates the principal
     :param realm: specifies the authentication provider
     :param scheme: specifies the type of authentication
-    :param parameters: parameters passed along to the authentication provider
+    :param parameters: extra key word parameters passed along to the authentication provider
+
     :return: auth token for use with :meth:`GraphDatabase.driver`
+    :rtype: :class:`neo4j.Auth`
     """
     return Auth(scheme, principal, credentials, realm, **parameters)