From 99b6aa4bd0b8f0babe07b78740f94e007204d9b5 Mon Sep 17 00:00:00 2001 From: Peter Parente Date: Sun, 3 Jul 2016 16:24:28 -0400 Subject: [PATCH] Docstring cleanup (c) Copyright IBM Corp. 2016 --- notebook/bundler/handlers.py | 126 +++++++++++++++++++++++++---------- 1 file changed, 90 insertions(+), 36 deletions(-) diff --git a/notebook/bundler/handlers.py b/notebook/bundler/handlers.py index c8bdd0fc6..2a68dd6ad 100644 --- a/notebook/bundler/handlers.py +++ b/notebook/bundler/handlers.py @@ -1,3 +1,5 @@ +"""Tornado handler for bundling notebooks.""" + # Copyright (c) Jupyter Development Team. # Distributed under the terms of the Modified BSD License. import os @@ -13,33 +15,45 @@ from ipython_genutils.importstring import import_item from tornado import web, gen class BundlerTools(object): - '''Set of common tools to aid bundler implementations.''' + """Set of common tools to aid bundler implementations.""" def get_file_references(self, abs_nb_path, version): - ''' - Gets a list of files referenced either in Markdown fenced code blocks + """Gets a list of files referenced either in Markdown fenced code blocks or in HTML comments from the notebook. Expands patterns expressed in gitignore syntax (https://git-scm.com/docs/gitignore). Returns the fully expanded list of filenames relative to the notebook dirname. - NOTE: Temporarily changes the current working directory when called. - - :param abs_nb_path: Absolute path of the notebook on disk - :param version: Version of the notebook document format to use - :returns: List of filename strings relative to the notebook path - ''' + Parameters + ---------- + abs_nb_path: str + Absolute path of the notebook on disk + version: int + Version of the notebook document format to use + + Returns + ------- + list + Filename strings relative to the notebook path + """ ref_patterns = self.get_reference_patterns(abs_nb_path, version) expanded = self.expand_references(os.path.dirname(abs_nb_path), ref_patterns) return expanded def get_reference_patterns(self, abs_nb_path, version): - ''' - Gets a list of reference patterns either in Markdown fenced code blocks + """Gets a list of reference patterns either in Markdown fenced code blocks or in HTML comments from the notebook. - :param abs_nb_path: Absolute path of the notebook on disk - :param version: Version of the notebook document format to use - :returns: List of pattern strings from the notebook - ''' + Parameters + ---------- + abs_nb_path: str + Absolute path of the notebook on disk + version: int + Version of the notebook document format to use + + Returns + ------- + list + Pattern strings from the notebook + """ notebook = nbformat.read(abs_nb_path, version) referenced_list = [] for cell in notebook.cells: @@ -67,8 +81,15 @@ class BundlerTools(object): !foo/bar --> - :param cell: Notebook cell object - :returns: List of strings + Parameters + ---------- + cell: dict + Notebook cell object + + Returns + ------- + list + Reference patterns found in the cell ''' referenced = [] # invisible after execution: unrendered HTML comment @@ -98,16 +119,25 @@ class BundlerTools(object): return [ref for ref in referenced if ref.strip()] def expand_references(self, root_path, references): - ''' - Expands a set of reference patterns by evaluating them against the + """Expands a set of reference patterns by evaluating them against the given root directory. Expansions are performed against patterns expressed in the same manner as in gitignore (https://git-scm.com/docs/gitignore). + + NOTE: Temporarily changes the current working directory when called. - :param root_path: Assumed root directory for the patterns - :param references: List of reference patterns - :returns: List of filename strings relative to the root path - ''' + Parameters + ---------- + root_path: str + Assumed root directory for the patterns + references: list + Reference patterns from get_reference_patterns + + Returns + ------- + list + Filename strings relative to the root path + """ globbed = [] negations = [] must_walk = [] @@ -164,16 +194,20 @@ class BundlerTools(object): return set(globbed) def copy_filelist(self, src, dst, src_relative_filenames): - ''' - Copies the given list of files, relative to src, into dst, creating + """Copies the given list of files, relative to src, into dst, creating directories along the way as needed and ignore existence errors. Skips any files that do not exist. Does not create empty directories from src in dst. - :param src: Root of the source directory - :param dst: Root of the destination directory - :param src_relative_filenames: List of filename relative to src - ''' + Parameters + ---------- + src: str + Root of the source directory + dst: str + Root of the destination directory + src_relative_filenames: list + Filenames relative to src + """ for filename in src_relative_filenames: # Only consider the file if it exists in src if os.path.isfile(os.path.join(src, filename)): @@ -192,16 +226,29 @@ class BundlerTools(object): class BundlerHandler(IPythonHandler): def initialize(self): - # Create common tools for bundler plugin to use + """Create common tools for bundler implementations to use.""" self.tools = BundlerTools() def get_bundler(self, bundler_id): - ''' - :param bundler_id: Unique ID within the notebook/jupyter_cms_bundlers - config section. - :returns: Dict of bundler metadata with keys label, group, module_name - :raises KeyError: If the bundler is not registered - ''' + """ + Get bundler metadata from config given a bundler ID. + + Parameters + ---------- + bundler_id: str + Unique bundler ID within the notebook/bundlerextensions config section + + Returns + ------- + dict + Bundler metadata with label, group, and module_name attributes + + + Raises + ------ + KeyError + If the bundler ID is unknown + """ cm = ConfigManager() return cm.get('notebook').get('bundlers', {})[bundler_id] @@ -209,6 +256,13 @@ class BundlerHandler(IPythonHandler): @gen.coroutine def get(self, path): """Bundle the given notebook. + + Parameters + ---------- + path: str + Path to the notebook (path parameter) + bundler: str + Bundler ID to use (query parameter) """ bundler_id = self.get_query_argument('bundler') model = self.contents_manager.get(path=url2path(path))