promote Cluster to top-level namespace

and add Cluster to docs

Author: minrk

docs/source/api/ipyparallel.rst

@@ -11,6 +11,8 @@ API Reference
 Classes
 -------
 
+.. autoclass:: Cluster
+
 .. autoclass:: Client
 
 .. autoclass:: DirectView

docs/source/conf.py

@@ -60,13 +60,13 @@
 # You can specify multiple suffix as a list of string:
 source_suffix = ['.rst', '.md']
 
-from traitlets.config import HasTraits
+from traitlets.config import LoggingConfigurable
 
 # exclude members inherited from HasTraits by default
 autodoc_default_options = {
     'members': None,
     "inherited-members": None,
-    "exclude-members": ','.join(dir(HasTraits)),
+    "exclude-members": ','.join(dir(LoggingConfigurable)),
 }
 
 # Add dev disclaimer.

examples/Cluster API.ipynb

@@ -48,7 +48,7 @@
     }
    ],
    "source": [
-    "from ipyparallel.cluster import Cluster\n",
+    "from ipyparallel import Cluster\n",
     "\n",
     "cluster = Cluster()\n",
     "cluster"

ipyparallel/__init__.py

@@ -14,6 +14,7 @@
 from .client.client import Client
 from .client.remotefunction import *
 from .client.view import *
+from .cluster import Cluster
 from .controller.dependency import *
 from .error import *
 from .serialize import *

ipyparallel/cluster/cluster.py

@@ -42,6 +42,9 @@ class Cluster(AsyncFirst, LoggingConfigurable):
     i.e. one controller and a groups of engines
 
     Can start/stop/monitor/poll cluster resources
+
+    All async methods can be called synchronously with a `_sync` suffix,
+    e.g. `cluster.start_cluster_sync()`
     """
 
     # general configuration
@@ -424,7 +427,7 @@ async def stop_cluster(self):
         await self.stop_engines()
         await self.stop_controller()
 
-    def connect_client(self):
+    def connect_client(self, **client_kwargs):
         """Return a client connected to the cluster"""
         # TODO: get connect info directly from controller
         # this assumes local files exist
@@ -434,6 +437,7 @@ def connect_client(self):
             cluster=self,
             profile_dir=self.profile_dir,
             cluster_id=self.cluster_id,
+            **client_kwargs,
         )
 
     # context managers (both async and sync)