Update docstrings to work with pep257 tool

I don't have a preference either way, but it is nice
having clean tooling output.

Author: jamesls

awsshell/app.py

@@ -40,6 +40,7 @@ class InputInterrupt(Exception):
 
     Raising `InputInterrupt` is useful to force a cli rebuild, which is
     sometimes necessary in order for config changes to take effect.
+
     """
     pass
 
@@ -91,7 +92,7 @@ def __init__(self, output=sys.stdout, err=sys.stderr):
         self._err = err
 
     def handle_cmd(self, command, application):
-        """Handles running a given dot command from a user.
+        """Handle running a given dot command from a user.
 
         :type command: str
         :param command: The full dot command string, e.g. ``.edit``,
@@ -115,7 +116,7 @@ def _unknown_cmd(self, cmd_parts, application):
 
 
 class AWSShell(object):
-    """Encapsulates the ui, completer, command history, docs, and config.
+    """Encapsulate the ui, completer, command history, docs, and config.
 
     Runs the input event loop and delegates the command execution to either
     the `awscli` or the underlying shell.
@@ -147,6 +148,7 @@ class AWSShell(object):
 
     :type theme: str
     :param theme: The pygments theme.
+
     """
 
     def __init__(self, completer, model_completer, docs):
@@ -172,7 +174,7 @@ def __init__(self, completer, model_completer, docs):
         self.load_config()
 
     def load_config(self):
-        """Loads the config from the config file or template."""
+        """Load the config from the config file or template."""
         config = Config()
         self.config_obj = config.load('awsshellrc')
         self.config_section = self.config_obj['aws-shell']
@@ -186,7 +188,7 @@ def load_config(self):
         self.theme = self.config_section['theme']
 
     def save_config(self):
-        """Saves the config to the config file."""
+        """Save the config to the config file."""
         self.config_section['match_fuzzy'] = self.model_completer.match_fuzzy
         self.config_section['enable_vi_bindings'] = self.enable_vi_bindings
         self.config_section['show_completion_columns'] = \
@@ -235,13 +237,14 @@ def run(self):
                     p.communicate()
 
     def stop_input_and_refresh_cli(self):
-        """Stops input by raising an `InputInterrupt`, forces a cli refresh.
+        """Stop input by raising an `InputInterrupt`, forces a cli refresh.
 
         The cli refresh is necessary because changing options such as key
         bindings, single vs multi column menu completions, and the help pane
         all require a rebuild.
 
         :raises: :class:`InputInterrupt <exceptions.InputInterrupt>`.
+
         """
         self.refresh_cli = True
         self.cli.request_redraw()
@@ -267,7 +270,7 @@ def create_buffer(self, completer, history):
             accept_action=AcceptAction.RETURN_DOCUMENT)
 
     def create_key_manager(self):
-        """Creates the :class:`KeyManager`.
+        """Create the :class:`KeyManager`.
 
         The inputs to KeyManager are expected to be callable, so we can't
         use the standard @property and @attrib.setter for these attributes.
@@ -277,13 +280,14 @@ def create_key_manager(self):
         :return: A KeyManager with callables to set the toolbar options.  Also
             includes the method stop_input_and_refresh_cli to ensure certain
             options take effect within the current session.
-        """
 
+        """
         def set_match_fuzzy(match_fuzzy):
             """Setter for fuzzy matching mode.
 
             :type match_fuzzy: bool
             :param match_fuzzy: The match fuzzy flag.
+
             """
             self.model_completer.match_fuzzy = match_fuzzy
 
@@ -295,6 +299,7 @@ def set_enable_vi_bindings(enable_vi_bindings):
 
             :type enable_vi_bindings: bool
             :param enable_vi_bindings: The enable Vi bindings flag.
+
             """
             self.enable_vi_bindings = enable_vi_bindings
 
@@ -304,6 +309,7 @@ def set_show_completion_columns(show_completion_columns):
             :type show_completion_columns: bool
             :param show_completion_columns: The show completions in
                 multiple columns flag.
+
             """
             self.show_completion_columns = show_completion_columns
 
@@ -312,6 +318,7 @@ def set_show_help(show_help):
 
             :type show_help: bool
             :param show_help: The show help flag.
+
             """
             self.show_help = show_help
 

awsshell/config.py

@@ -22,7 +22,7 @@ class Config(object):
     """Reads and writes the config template and user config file."""
 
     def load(self, config_template, config_file=None):
-        """Reads the config file if it exists, else reads the default config.
+        """Read the config file if it exists, else read the default config.
 
         Creates the user config file if it doesn't exist using the template.
 
@@ -45,7 +45,7 @@ def load(self, config_template, config_file=None):
         return self._load_template_or_config(template_path, config_path)
 
     def _load_template_or_config(self, template_path, config_path):
-        """Loads the config file if it exists, else reads the default config.
+        """Load the config file if it exists, else read the default config.
 
         :type template_path: str
         :param template_path: The template config file path.
@@ -65,7 +65,7 @@ def _load_template_or_config(self, template_path, config_path):
 
     def _copy_template_to_config(self, template_path,
                                  config_path, overwrite=False):
-        """Writes the default config from a template.
+        """Write the default config from a template.
 
         :type template_path: str
         :param template_path: The template config file path.

awsshell/docs.py

@@ -13,8 +13,7 @@ def load_doc_db(filename):
 
 
 class DocRetriever(object):
-    """Retrieves documentation for the AWS CLI.
-    """
+    """Retrieve documentation for the AWS CLI."""
     def __init__(self, doc_index):
         # Internally, most of the speedup comes from
         # the fact that this data is pre-rendered and

awsshell/keys.py

@@ -44,7 +44,7 @@ def _create_key_manager(self, get_match_fuzzy, set_match_fuzzy,
                             set_show_completion_columns,
                             get_show_help, set_show_help,
                             stop_input_and_refresh_cli):
-        """Creates and initializes the keybinding manager.
+        """Create and initialize the keybinding manager.
 
         :type get_fuzzy_match: callable
         :param get_fuzzy_match: Gets the fuzzy matching config.
@@ -81,6 +81,7 @@ def _create_key_manager(self, get_match_fuzzy, set_match_fuzzy,
 
         :rtype: :class:`prompt_toolkit.KeyBindingManager`
         :return: A custom `KeyBindingManager`.
+
         """
         assert callable(get_match_fuzzy)
         assert callable(set_match_fuzzy)
@@ -101,51 +102,56 @@ def _create_key_manager(self, get_match_fuzzy, set_match_fuzzy,
 
         @self.manager.registry.add_binding(Keys.F2)
         def handle_f2(_):
-            """Enables/disables fuzzy matching.
+            """Toggle fuzzy matching.
 
             :type _: :class:`prompt_toolkit.Event`
             :param _: (Unused)
+
             """
             set_match_fuzzy(not get_match_fuzzy())
 
         @self.manager.registry.add_binding(Keys.F3)
         def handle_f3(_):
-            """Enables/disables Vi mode keybindings matching.
+            """Toggle Vi mode keybindings matching.
 
             Disabling Vi keybindings will enable Emacs keybindings.
 
             :type _: :class:`prompt_toolkit.Event`
             :param _: (Unused)
+
             """
             set_enable_vi_bindings(not get_enable_vi_bindings())
             stop_input_and_refresh_cli()
 
         @self.manager.registry.add_binding(Keys.F4)
         def handle_f4(_):
-            """Enables/disables multiple column completions.
+            """Toggle multiple column completions.
 
             :type _: :class:`prompt_toolkit.Event`
             :param _: (Unused)
+
             """
             set_show_completion_columns(not get_show_completion_columns())
             stop_input_and_refresh_cli()
 
         @self.manager.registry.add_binding(Keys.F5)
         def handle_f5(_):
-            """Shows/hides the help container.
+            """Toggle the help container.
 
             :type _: :class:`prompt_toolkit.Event`
             :param _: (Unused)
+
             """
             set_show_help(not get_show_help())
             stop_input_and_refresh_cli()
 
         @self.manager.registry.add_binding(Keys.F10)
         def handle_f10(event):
-            """Quits when the `F10` key is pressed.
+            """Quit when the `F10` key is pressed.
 
             :type event: :class:`prompt_toolkit.Event`
             :param event: Contains info about the event, namely the cli
                 which is used for exiting the app.
+
             """
             event.cli.set_exit()

awsshell/makeindex.py

@@ -122,7 +122,7 @@ def render_docs_for_cmd(help_command):
 
 
 def convert_rst_to_basic_text(contents):
-    """Converts restructured text to basic text output.
+    """Convert restructured text to basic text output.
 
     This function removes most of the decorations added
     in restructured text.

awsshell/resource/index.py

@@ -92,7 +92,7 @@ def __init__(self, resource_index):
         self._index = resource_index
 
     def describe_autocomplete(self, service, operation, param):
-        """
+        """Describe operation and args needed for server side completion.
 
         :type service: str
         :param service: The AWS service name.

awsshell/style.py

@@ -18,7 +18,7 @@
 
 
 class StyleFactory(object):
-    """Provides styles for the autocomplete menu and the toolbar.
+    """Provide styles for the autocomplete menu and the toolbar.
 
     :type style: :class:`pygments.style.StyleMeta`
     :param style: Contains pygments style info.
@@ -28,7 +28,7 @@ def __init__(self, style_name):
         self.style = self.style_factory(style_name)
 
     def style_factory(self, style_name):
-        """Retrieves the specified pygments style.
+        """Retrieve the specified pygments style.
 
         If the specified style is not found, the vim style is returned.
 

awsshell/substring.py

@@ -13,7 +13,7 @@
 
 
 def substring_search(word, collection):
-    """Finds all matches in the `collection` for the specified `word`.
+    """Find all matches in the `collection` for the specified `word`.
 
     If `word` is empty, returns all items in `collection`.
 

awsshell/toolbar.py

@@ -14,10 +14,11 @@
 
 
 class Toolbar(object):
-    """Shows information about the aws-shell in a tool bar.
+    """Show information about the aws-shell in a tool bar.
 
     :type handler: callable
     :param handler: Wraps the callable `get_toolbar_items`.
+
     """
 
     def __init__(self, get_match_fuzzy, get_enable_vi_bindings,
@@ -28,7 +29,7 @@ def __init__(self, get_match_fuzzy, get_enable_vi_bindings,
 
     def _create_toolbar_handler(self, get_match_fuzzy, get_enable_vi_bindings,
                                 get_show_completion_columns, get_show_help):
-        """Creates the toolbar handler.
+        """Create the toolbar handler.
 
         :type get_fuzzy_match: callable
         :param fuzzy_match: Gets the fuzzy matching config.
@@ -46,14 +47,15 @@ def _create_toolbar_handler(self, get_match_fuzzy, get_enable_vi_bindings,
 
         :rtype: callable
         :returns: get_toolbar_items.
+
         """
         assert callable(get_match_fuzzy)
         assert callable(get_enable_vi_bindings)
         assert callable(get_show_completion_columns)
         assert callable(get_show_help)
 
         def get_toolbar_items(_):
-            """Returns the toolbar items.
+            """Return the toolbar items.
 
             :type _: :class:`prompt_toolkit.Cli`
             :param _: (Unused)

awsshell/ui.py

@@ -34,6 +34,7 @@ def create_default_layout(app, message='',
                           extra_input_processors=None, multiline=False):
     """
     Generate default layout.
+
     Returns a ``Layout`` instance.
 
     :param message: Text to be used as prompt.
@@ -193,10 +194,12 @@ def separator():
 
 
 def _split_multiline_prompt(get_prompt_tokens):
-    """
+    """Split prompt tokens into two multiline prompt token functions.
+
     Take a `get_prompt_tokens` function. and return two new functions instead.
     One that returns the tokens to be shown on the lines above the input, and
     another one with the tokens to be shown at the first line of the input.
+
     """
     def before(cli):
         result = []

awsshell/utils.py

@@ -71,7 +71,7 @@ class FSLayer(object):
 
     """
     def file_contents(self, filename, binary=False):
-        """Returns the file for a given filename.
+        """Return the file for a given filename.
 
         If you want binary content use ``mode='rb'``.
 
@@ -87,7 +87,7 @@ def file_contents(self, filename, binary=False):
             raise FileReadError(str(e))
 
     def file_exists(self, filename):
-        """Checks if a file exists.
+        """Check if a file exists.
 
         This method returns true if: