Merge pull request #19 from adambullmer/tests

Added style tests to the project.

Author: adambullmer

.gitignore

@@ -1 +1,2 @@
-*.sublime-package
+.tox
+*.sublime-package

DocblockrPython.py

@@ -1,3 +1,11 @@
+"""DocBlockr for Python.
+
+Author: Adam Bullmer <[email protected]>
+Website: https://github.com/adambullmer/sublime-docblockr-python
+
+Credit to `spadgos` and the team at DocBlockr for providing some source code
+to support this project
+"""
 import sublime
 
 from .formatters.registry import populate_registry
@@ -12,4 +20,4 @@ def plugin_loaded():
     global plugin_is_loaded
     plugin_is_loaded = True
 
-    window = sublime.active_window()
+    sublime.active_window()

MANIFEST.in

@@ -0,0 +1 @@
+include requirements.txt

commands.py

@@ -1,5 +1,4 @@
-"""
-DocBlockr Python v1.3.0
+"""DocBlockr for Python.
 
 Author: Adam Bullmer <[email protected]>
 Website: https://github.com/adambullmer/sublime-docblockr-python
@@ -8,9 +7,10 @@
 to support this project
 """
 import logging
+import re
+
 import sublime
 import sublime_plugin
-import re
 
 from .formatters.utils import get_formatter, get_setting
 from .parsers.parser import get_parser
@@ -19,7 +19,7 @@
 
 
 def write(view, string):
-    """Writes a string to the view as a snippet.
+    """Write a string to the view as a snippet.
 
     Arguments:
         view   {sublime.View} -- view to have content written to
@@ -30,7 +30,7 @@ def write(view, string):
 
 
 def escape(string):
-    """Escapes the special characters.
+    r"""Escape the special characters.
 
     Escapes characters that are also in snippet tab fields so that inserting into the view
     doesn't accidentally create another tabbable field
@@ -65,6 +65,7 @@ class DocblockrPythonCommand(sublime_plugin.TextCommand):
         line            {String}
         contents        {String}
     """
+
     position = 0
     trailing_rgn = ''
     trailing_string = ''
@@ -77,7 +78,7 @@ class DocblockrPythonCommand(sublime_plugin.TextCommand):
     project_settings = None
 
     def run(self, edit):
-        """Sublime Command Entrypoint
+        """Sublime Command Entrypoint.
 
         Entrypoint for the Sublime Text Command. Outputs the result of the parsing to
         the view.
@@ -130,6 +131,17 @@ def initialize(self, view):
         log.debug('contents -- {}'.format(self.contents))
 
     def create_snippet(self, parsed_attributes):
+        """Format a Sublime Text snippet syntax string.
+
+        Iterates through the list of field groups, and then through each item
+        in the group to create the snippets using the user specified formatter.
+
+        Arguments:
+            parsed_attributes {dict} -- key value of attributes groups
+
+        Returns:
+            str -- sublime text formatted snippet string
+        """
         project_formatter = self.project_settings.get('formatter', None)
         formatter = get_formatter(project_formatter or get_setting('formatter'))()
 

formatters/PEP0257.py

@@ -1,16 +1,22 @@
+"""Default Formatter for PEP-257."""
 from .base import Base
 
 
 class Pep0257Formatter(Base):
+    """Documentation Formatter Class."""
+
     name = 'PEP0257'
 
     def decorators(self, attributes):
+        """Create snippet string for a list of decorators."""
         return ''
 
     def extends(self, attributes):
+        """Create snippet string for a list of extended objects."""
         return ''
 
     def arguments(self, attributes):
+        """Create snippet string for a list of arguments."""
         section = '\nArguments:\n'
         template = '\t{name} -- {description}\n'
 
@@ -28,6 +34,7 @@ def arguments(self, attributes):
         return section
 
     def keyword_arguments(self, attributes):
+        """Create snippet string for a list of keyword arguments."""
         section = '\nKeyword arguments:\n'
         template = '\t{name} -- {description} (default: {{{default}}})\n'
 
@@ -44,12 +51,15 @@ def keyword_arguments(self, attributes):
         return section
 
     def returns(self, attribute):
+        """Create snippet string for a list of return values."""
         return ''
 
     def yields(self, attribute):
+        """Create snippet string for a list of yielded results."""
         return ''
 
     def raises(self, attributes):
+        """Create snippet string for a list of raiased exceptions."""
         section = '\n'
         template = 'Raises a {{{attribute}}} ${{{tab_index_1}:[description]}}\n'
 
@@ -62,6 +72,7 @@ def raises(self, attributes):
         return section
 
     def variables(self, attributes):
+        """Create snippet string for a list of variables."""
         section = '\nVariables:\n'
         template = '\t{name} -- {description}\n'
 

formatters/__init__.py

@@ -0,0 +1 @@
+"""Default documentation formatting classes."""

formatters/base.py

@@ -1,7 +1,9 @@
+"""Base formatter class."""
 from abc import abstractmethod, ABCMeta
 
 from .registry import register
 
+
 def counter():
     """Simple Iteratable Counter.
 
@@ -18,12 +20,14 @@ def counter():
 
 
 class FormatterMeta(ABCMeta):
-    """Registers the class in the formatter
+    """Register the class in the formatter.
 
     Extends:
         ABCMeta
     """
+
     def __new__(mcs, classname, bases, attributes):
+        """---."""
         newclass = super(FormatterMeta, mcs).__new__(mcs, classname, bases, attributes)
         register(newclass)
         return newclass
@@ -51,10 +55,12 @@ class Base(metaclass=FormatterMeta):
         tab_index {generator} -- Provides a simple count generator for convenience
                                  in making tabbable fields
     """
+
     name = None
     tab_index = counter()
 
     def __dict__(self):
+        """---."""
         return {
             'summary': self.summary,
             'description': self.description,
@@ -69,11 +75,12 @@ def __dict__(self):
         }
 
     def __iter__(self):
+        """---."""
         for attr, value in self.__dict__().items():
             yield attr, value
 
     def _generate_field(self, name, value=None):
-        """Makes Sublime Text snippet fields.
+        """Make a Sublime Text snippet field.
 
         If a value is passed and it is not None, it will be returned. Otherwise,
         this will generate a snippet field in the next tabbable index.
@@ -96,65 +103,85 @@ def _generate_field(self, name, value=None):
         )
 
     def summary(self):
+        """Create snippet string for the summary line."""
         return '{}'.format(self._generate_field('summary'))
 
     def description(self):
+        """Create snippet string for the description body."""
         return '\n\n{}\n'.format(self._generate_field('description'))
 
     @abstractmethod
     def decorators(self, attributes):
+        """Create snippet string for a list of decorators."""
         return ''
 
     @abstractmethod
     def extends(self, attributes):
+        """Create snippet string for a list of extended objects."""
         return ''
 
     @abstractmethod
     def arguments(self, attributes):
+        """Create snippet string for a list of arguments."""
         return ''
 
     @abstractmethod
     def keyword_arguments(self, attributes):
+        """Create snippet string for a list of keyword arguments."""
         return ''
 
     @abstractmethod
     def returns(self, attribute):
+        """Create snippet string for a list of return values."""
         return ''
 
     @abstractmethod
     def yields(self, attribute):
+        """Create snippet string for a list of yielded results."""
         return ''
 
     @abstractmethod
     def raises(self, attributes):
+        """Create snippet string for a list of raiased exceptions."""
         return ''
 
     @abstractmethod
     def variables(self, attributes):
+        """Create snippet string for a list of variables."""
         return ''
 
 
 class BaseFormatter(Base):
+    """Documentation Formatter Class."""
+
     def decorators(self, attributes):
+        """Create snippet string for a list of decorators."""
         return '{}\n'.format(self._generate_field('decorators'))
 
     def extends(self, attributes):
+        """Create snippet string for a list of extended objects."""
         return '{}\n'.format(self._generate_field('extends'))
 
     def arguments(self, attributes):
+        """Create snippet string for a list of arguments."""
         return '{}\n'.format(self._generate_field('arguments'))
 
     def keyword_arguments(self, attributes):
+        """Create snippet string for a list of keyword arguments."""
         return '{}\n'.format(self._generate_field('keyword arguments'))
 
     def returns(self, attribute):
+        """Create snippet string for a list of return values."""
         return '{}\n'.format(self._generate_field('returns'))
 
     def yields(self, attribute):
+        """Create snippet string for a list of yielded results."""
         return '{}\n'.format(self._generate_field('yields'))
 
     def raises(self, attributes):
+        """Create snippet string for a list of raiased exceptions."""
         return '{}\n'.format(self._generate_field('raises'))
 
     def variables(self, attributes):
+        """Create snippet string for a list of variables."""
         return '{}\n'.format(self._generate_field('variables'))

formatters/docblock.py

@@ -1,10 +1,14 @@
+"""Default Formatter for DocBlock."""
 from .base import Base
 
 
 class DocblockFormatter(Base):
+    """Documentation Formatter Class."""
+
     name = 'docblock'
 
     def decorators(self, attributes):
+        """Create snippet string for a list of decorators."""
         section = '\nDecorators:\n'
         template = '\t{}\n'
 
@@ -14,6 +18,7 @@ def decorators(self, attributes):
         return section
 
     def extends(self, attributes):
+        """Create snippet string for a list of extended objects."""
         section = '\nExtends:\n'
         template = '\t{}\n'
 
@@ -23,6 +28,7 @@ def extends(self, attributes):
         return section
 
     def arguments(self, attributes):
+        """Create snippet string for a list of arguments."""
         section = '\nArguments:\n'
         template = '\t{name} {{{type}}} -- {description}\n'
 
@@ -41,6 +47,7 @@ def arguments(self, attributes):
         return section
 
     def keyword_arguments(self, attributes):
+        """Create snippet string for a list of keyword arguments."""
         section = '\nKeyword Arguments:\n'
         template = '\t{name} {{{type}}} -- {description} (default: {{{default}}})\n'
 
@@ -58,6 +65,7 @@ def keyword_arguments(self, attributes):
         return section
 
     def returns(self, attribute):
+        """Create snippet string for a list of return values."""
         section = '\nReturns:\n'
         template = '\t{type} -- {description}\n'
 
@@ -69,6 +77,7 @@ def returns(self, attribute):
         return section
 
     def yields(self, attribute):
+        """Create snippet string for a list of yielded results."""
         section = '\nYields:\n'
         template = '\t{type} -- {description}\n'
 
@@ -80,6 +89,7 @@ def yields(self, attribute):
         return section
 
     def raises(self, attributes):
+        """Create snippet string for a list of raiased exceptions."""
         section = '\nRaises:\n'
         template = '\t{name} -- {description}\n'
 
@@ -92,6 +102,7 @@ def raises(self, attributes):
         return section
 
     def variables(self, attributes):
+        """Create snippet string for a list of variables."""
         section = '\nVariables:\n'
         template = '\t{name} {{{type}}} -- {description}\n'