trust method docstrings

IPython/html/services/notebooks/nbmanager.py

@@ -1,260 +1,283 b''
 """A base class notebook manager.
 
 Authors:
 
 * Brian Granger
 * Zach Sailer
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from fnmatch import fnmatch
 import itertools
 import os
 
 from IPython.config.configurable import LoggingConfigurable
 from IPython.nbformat import current, sign
 from IPython.utils.traitlets import Instance, Unicode, List
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class NotebookManager(LoggingConfigurable):
 
     filename_ext = Unicode(u'.ipynb')
     
     notary = Instance(sign.NotebookNotary)
     def _notary_default(self):
         return sign.NotebookNotary(parent=self)
     
     hide_globs = List(Unicode, [u'__pycache__'], config=True, help="""
         Glob patterns to hide in file and directory listings.
     """)
 
     # NotebookManager API part 1: methods that must be
     # implemented in subclasses.
 
     def path_exists(self, path):
         """Does the API-style path (directory) actually exist?
         
         Override this method in subclasses.
         
         Parameters
         ----------
         path : string
-            The 
+            The path to check
         
         Returns
         -------
         exists : bool
             Whether the path does indeed exist.
         """
         raise NotImplementedError
 
     def is_hidden(self, path):
         """Does the API style path correspond to a hidden directory or file?
         
         Parameters
         ----------
         path : string
             The path to check. This is an API path (`/` separated,
             relative to base notebook-dir).
         
         Returns
         -------
         exists : bool
             Whether the path is hidden.
         
         """
         raise NotImplementedError
 
     def notebook_exists(self, name, path=''):
         """Returns a True if the notebook exists. Else, returns False.
 
         Parameters
         ----------
         name : string
             The name of the notebook you are checking.
         path : string
             The relative path to the notebook (with '/' as separator)
 
         Returns
         -------
         bool
         """
         raise NotImplementedError('must be implemented in a subclass')
 
     # TODO: Remove this after we create the contents web service and directories are
     # no longer listed by the notebook web service.
     def list_dirs(self, path):
         """List the directory models for a given API style path."""
         raise NotImplementedError('must be implemented in a subclass')
 
     # TODO: Remove this after we create the contents web service and directories are
     # no longer listed by the notebook web service.
     def get_dir_model(self, name, path=''):
         """Get the directory model given a directory name and its API style path.
         
         The keys in the model should be:
         * name
         * path
         * last_modified
         * created
         * type='directory'
         """
         raise NotImplementedError('must be implemented in a subclass')
 
     def list_notebooks(self, path=''):
         """Return a list of notebook dicts without content.
 
         This returns a list of dicts, each of the form::
 
             dict(notebook_id=notebook,name=name)
 
         This list of dicts should be sorted by name::
 
             data = sorted(data, key=lambda item: item['name'])
         """
         raise NotImplementedError('must be implemented in a subclass')
 
     def get_notebook(self, name, path='', content=True):
         """Get the notebook model with or without content."""
         raise NotImplementedError('must be implemented in a subclass')
 
     def save_notebook(self, model, name, path=''):
         """Save the notebook and return the model with no content."""
         raise NotImplementedError('must be implemented in a subclass')
 
     def update_notebook(self, model, name, path=''):
         """Update the notebook and return the model with no content."""
         raise NotImplementedError('must be implemented in a subclass')
 
     def delete_notebook(self, name, path=''):
         """Delete notebook by name and path."""
         raise NotImplementedError('must be implemented in a subclass')
 
     def create_checkpoint(self, name, path=''):
         """Create a checkpoint of the current state of a notebook
         
         Returns a checkpoint_id for the new checkpoint.
         """
         raise NotImplementedError("must be implemented in a subclass")
     
     def list_checkpoints(self, name, path=''):
         """Return a list of checkpoints for a given notebook"""
         return []
     
     def restore_checkpoint(self, checkpoint_id, name, path=''):
         """Restore a notebook from one of its checkpoints"""
         raise NotImplementedError("must be implemented in a subclass")
 
     def delete_checkpoint(self, checkpoint_id, name, path=''):
         """delete a checkpoint for a notebook"""
         raise NotImplementedError("must be implemented in a subclass")
     
     def info_string(self):
         return "Serving notebooks"
 
     # NotebookManager API part 2: methods that have useable default
     # implementations, but can be overridden in subclasses.
 
     def increment_filename(self, basename, path=''):
         """Increment a notebook filename without the .ipynb to make it unique.
         
         Parameters
         ----------
         basename : unicode
             The name of a notebook without the ``.ipynb`` file extension.
         path : unicode
             The URL path of the notebooks directory
 
         Returns
         -------
         name : unicode
             A notebook name (with the .ipynb extension) that starts
             with basename and does not refer to any existing notebook.
         """
         path = path.strip('/')
         for i in itertools.count():
             name = u'{basename}{i}{ext}'.format(basename=basename, i=i,
                                                 ext=self.filename_ext)
             if not self.notebook_exists(name, path):
                 break
         return name
 
     def create_notebook(self, model=None, path=''):
         """Create a new notebook and return its model with no content."""
         path = path.strip('/')
         if model is None:
             model = {}
         if 'content' not in model:
             metadata = current.new_metadata(name=u'')
             model['content'] = current.new_notebook(metadata=metadata)
         if 'name' not in model:
             model['name'] = self.increment_filename('Untitled', path)
             
         model['path'] = path
         model = self.save_notebook(model, model['name'], model['path'])
         return model
 
     def copy_notebook(self, from_name, to_name=None, path=''):
         """Copy an existing notebook and return its new model.
         
         If to_name not specified, increment `from_name-Copy#.ipynb`.
         """
         path = path.strip('/')
         model = self.get_notebook(from_name, path)
         if not to_name:
             base = os.path.splitext(from_name)[0] + '-Copy'
             to_name = self.increment_filename(base, path)
         model['name'] = to_name
         model = self.save_notebook(model, to_name, path)
         return model
     
     def log_info(self):
         self.log.info(self.info_string())
 
     def trust_notebook(self, name, path=''):
-        """Check for trusted cells, and sign the notebook.
+        """Explicitly trust a notebook
         
-        Called as a part of saving notebooks.
+        Parameters
+        ----------
+        name : string
+            The filename of the notebook
+        path : string
+            The notebook's directory
         """
         model = self.get_notebook(name, path)
         nb = model['content']
         self.log.warn("Trusting notebook %s/%s", path, name)
         self.notary.mark_cells(nb, True)
         self.save_notebook(model, name, path)
     
     def check_and_sign(self, nb, name, path=''):
         """Check for trusted cells, and sign the notebook.
         
         Called as a part of saving notebooks.
+        
+        Parameters
+        ----------
+        nb : dict
+            The notebook structure
+        name : string
+            The filename of the notebook
+        path : string
+            The notebook's directory
         """
         if self.notary.check_cells(nb):
             self.notary.sign(nb)
         else:
             self.log.warn("Saving untrusted notebook %s/%s", path, name)
     
     def mark_trusted_cells(self, nb, name, path=''):
         """Mark cells as trusted if the notebook signature matches.
         
         Called as a part of loading notebooks.
+        
+        Parameters
+        ----------
+        nb : dict
+            The notebook structure
+        name : string
+            The filename of the notebook
+        path : string
+            The notebook's directory
         """
         trusted = self.notary.check_signature(nb)
         if not trusted:
             self.log.warn("Notebook %s/%s is not trusted", path, name)
         self.notary.mark_cells(nb, trusted)
 
     def should_list(self, name):
         """Should this file/directory name be displayed in a listing?"""
         return not any(fnmatch(name, glob) for glob in self.hide_globs)