Merge pull request #142 from mpacer/client_fix

Fixes client endpoints and adds docstrings

Author: willingc

bookstore/client/nb_client.py

@@ -1,22 +1,4 @@
-"""Client to test bookstore endpoints from within a notebook.
-
-
-TODO: (Clarify) We want to test our bookstore endpoints, but it's no fun having
-to do this in an insecure fashion. Better would be to have some security in
-place.
-
-Example
--------
-
-[{'base_url': '/',
-  'hostname': 'localhost',
-  'notebook_dir': '/Users/mpacer/jupyter/eg_notebooks',
-  'password': False,
-  'pid': 96033,
-  'port': 8888,
-  'secure': False,
-  'token': '',
-  'url': 'http://localhost:8888/'}]
+"""Client for accessing notebook server endpoints from within a notebook.
 """
 import json
 import os
@@ -42,6 +24,21 @@ class LiveNotebookRecord(NamedTuple):
 
     This is a record of an object returned by
     `notebook.notebookapp.list_running_servers()`.
+
+    Example
+    -------
+    :: 
+
+        [{'base_url': '/',
+        'hostname': 'localhost',
+        'notebook_dir': '/Users/mpacer/jupyter/eg_notebooks',
+        'password': False,
+        'pid': 96033,
+        'port': 8888,
+        'secure': False,
+        'token': '',
+        'url': 'http://localhost:8888/'}]
+
     """
 
     base_url: str
@@ -56,11 +53,27 @@ class LiveNotebookRecord(NamedTuple):
 
 
 class KernelInfo:
-    #     id: str # 'f92b7c8b-0858-4d10-903c-b0631540fb36',
-    #     name: str # 'dev',
-    #     last_activity: str #'2019-03-14T23:38:08.137987Z',
-    #     execution_state: str #'idle',
-    #     connections: int # 0
+    """Representation of kernel info returned by the notebook's /api/kernel endpoint.
+
+    Attributes
+    ----------
+    id: str
+    name: str
+    last_activity: str
+    execution_state: str 
+    connections: int
+
+    Example
+    -------
+    ::
+
+        {id: 'f92b7c8b-0858-4d10-903c-b0631540fb36',
+        name: 'dev',
+        last_activity: '2019-03-14T23:38:08.137987Z',
+        execution_state: 'idle',
+        connections: 0}
+    """
+
     def __init__(self, *args, id, name, last_activity, execution_state, connections):
         self.model = {
             "id": id,
@@ -92,13 +105,35 @@ def __eq__(self, other):
             return False
 
 
-class NotebookSession:  # (NamedTuple):
-    #     id: str #'68d9c58f-c57d-4133-8b41-5ec2731b268d',
-    #     path: str #'Untitled38.ipynb',
-    #     name: str #'',
-    #     type: str #'notebook',
-    #     kernel: KernelInfo
-    #     notebook: dict # deprecated API {'path': 'Untitled38.ipynb', 'name': ''}
+class NotebookSession:
+    """Representation of session info returned by the notebook's /api/sessions/ endpoint.
+    
+    Attributes
+    ----------
+    id: str
+    path: str 
+    name: str 
+    type: str 
+    kernel: KernelInfo
+    notebook: dict 
+    model: dict
+        Record of the raw response (without converting the KernelInfo).
+
+    Example
+    -------
+    ::
+    
+        {id: '68d9c58f-c57d-4133-8b41-5ec2731b268d',
+         path: 'Untitled38.ipynb',
+         name: '',
+         type: 'notebook',
+         kernel: KernelInfo(id='f92b7c8b-0858-4d10-903c-b0631540fb36', 
+                            name='dev', 
+                            last_activity='2019-03-14T23:38:08.137987Z', 
+                            execution_state='idle', 
+                            connections=0),
+        notebook: {'path': 'Untitled38.ipynb', 'name': ''}}
+    """
 
     def __init__(self, *args, path, name, type, kernel, notebook={}, **kwargs):
         self.model = {
@@ -133,7 +168,28 @@ def __eq__(self, other):
 
 
 class NotebookClient:
-    """Client used to interact with bookstore from within a running notebook UI"""
+    """EXPERIMENTAL SUPPORT: Client used to interact with a notebook server from within a notebook.
+
+    Parameters
+    ----------
+    nb_config: dict
+        Dictionary of info compatible with creating a LiveNotebookRecord.
+
+    Attributes
+    ----------
+    nb_config: dict
+       Dictionary of info compatible with creating a LiveNotebookRecord. 
+    nb_record: LiveNotebookRecord
+        LiveNotebookRecord of info for this notebook
+    url: str
+        url from nb_record minus final /
+    token: str
+        token used for authenticating requests serverside
+    xsrf_token: str
+        xsrf_token used in cookie for authenticating requests
+    req_session: requests.Session
+        Session to be reused across methods
+    """
 
     def __init__(self, nb_config):
         self.nb_config = nb_config
@@ -154,23 +210,20 @@ def setup_auth(self):
         self.xsrf_token = first.cookies.get("_xsrf", "")
 
     def setup_request_sessions(self):
-        """ Sets up a requests.Session object for sharing headers across API requests.
-        """
+        """ Sets up a requests.Session object for sharing headers across API requests. """
         self.req_session = requests.Session()
         self.req_session.headers.update(self.headers)
 
     @property
     def sessions(self):
-        """Current notebook sessions. Reissues request on each call.
-        """
+        """Current notebook sessions. Reissues request on each call. """
         return {
             session['kernel']['id']: NotebookSession(**session) for session in self.get_sessions()
         }
 
     @property
     def headers(self):
-        """Default headers to be shared across requests.
-        """
+        """Default headers to be shared across requests. """
         headers = {
             'Authorization': f'token {self.token}',
             'X-XSRFToken': self.xsrf_token,
@@ -180,41 +233,48 @@ def headers(self):
 
     @property
     def sessions_endpoint(self):
+        """Current server's kernels API endpoint."""
         api_endpoint = "/api/sessions/"
         return f"{self.url}{api_endpoint}"
 
     def get_sessions(self):
+        """Requests info about current sessions from notebook server."""
         target_url = f"{self.sessions_endpoint}"
         resp = self.req_session.get(target_url)
         return resp.json()
 
     @property
     def kernels_endpoint(self):
+        """Current server's kernels API endpoint."""
         api_endpoint = "/api/kernels/"
         return f"{self.url}{api_endpoint}"
 
     def get_kernels(self):
+        """Requests info about current kernels from notebook server."""
         target_url = f"{self.kernels_endpoint}"
         resp = self.req_session.get(target_url)
         return resp.json()
 
     @property
     def kernels(self):
+        """Current notebook kernels. Reissues request on each call."""
         return self.get_kernels()
 
     @property
     def contents_endpoint(self):
+        """Current server's contents API endpoint."""
         api_endpoint = "/api/contents/"
         return f"{self.url}{api_endpoint}"
 
     def get_contents(self, path):
+        """Requests info about current contents from notebook server."""
         target_url = f"{self.contents_endpoint}{path}"
         resp = self.req_session.get(target_url)
         return resp.json()
 
 
 class NotebookClientCollection:
-    """Representation of a collection of notebook clients"""
+    """EXPERIMENTAL SUPPORT: Representation of a collection of notebook clients"""
 
     # TODO: refactor from lambda to a def
     nb_client_gen = lambda: (NotebookClient(x) for x in list_running_servers())
@@ -234,7 +294,7 @@ def current_server(cls):
 
 
 class CurrentNotebookClient(NotebookClient):
-    """Represents the currently active notebook client"""
+    """EXPERIMENTAL SUPPORT: Represents the currently active notebook client."""
 
     def __init__(self):
         self.nb_client = NotebookClientCollection.current_server()
@@ -243,8 +303,10 @@ def __init__(self):
 
     @property
     def connection_file(self):
+        """Connection file for connecting to current notebook's kernel."""
         return get_ipython().parent.parent.connection_file
 
     @property
     def kernel_id(self):
+        """Kernel id for identifying which notebook is currently being used by this session."""
         return extract_kernel_id(self.connection_file)

bookstore/client/store_client.py

@@ -1,11 +1,23 @@
-"""Client to interact with the notebook store"""
+"""Client to interact with a notebook's bookstore functionality."""
 import requests
 
 from .nb_client import CurrentNotebookClient
 
 
 class BookstoreClient(CurrentNotebookClient):
-    """Represents a bookstore client that corresponds to the active nb client"""
+    """EXPERIMENTAL SUPPORT: A client that allows access to a Bookstore from within a notebook.
+    
+    Parameters
+    ----------
+    s3_bucket: str
+        (optional) Provide a default bucket for this bookstore client to clone from.
+    
+
+    Attributes
+    ----------
+    default_bucket : str
+        The default bucket to be used for cloning.
+    """
 
     def __init__(self, s3_bucket=None):
         if s3_bucket:
@@ -14,11 +26,20 @@ def __init__(self, s3_bucket=None):
 
     @property
     def publish_endpoint(self):
-        api_endpoint = "/api/bookstore/published/"
+        """Helper to refer to construct the publish endpoint for this notebook server."""
+        api_endpoint = "/api/bookstore/publish/"
         return f"{self.url}{api_endpoint}"
 
     def publish(self, path=None):
-        """Publish notebook to bookstore"""
+        """Publish notebook to bookstore
+        
+        Parameters
+        ----------
+        path : str
+            (optional) Path that you wish to publish; defaults to current notebook.
+        s3_object_key: str
+            The the path we wish to clone to.
+        """
         if path is None:
             path = self.session.path
         nb_json = self.get_contents(path)['content']
@@ -31,10 +52,22 @@ def publish(self, path=None):
 
     @property
     def clone_endpoint(self):
-        api_endpoint = "/api/bookstore/cloned/"
+        """Helper to refer to construct the clone endpoint for this notebook server."""
+        api_endpoint = "/api/bookstore/clone/"
         return f"{self.url}{api_endpoint}"
 
     def clone(self, s3_bucket="", s3_key="", target_path=""):
+        """Clone files via bookstore.
+        
+        Parameters
+        ----------
+        s3_bucket : str
+            (optional) S3 bucket you wish to clone from; defaults to client's bucket.
+        s3_object_key: str
+            The object key describing the object you wish to clone from S3.
+        target_path: str
+            (optional) The location you wish to clone the object to; defaults to s3_object_key.
+        """
         s3_bucket = s3_bucket or self.default_bucket
         json_body = {"s3_bucket": s3_bucket, "s3_key": s3_key, "target_path": target_path}
         # TODO: Add a check for success