Merge pull request #1598 from clinton-hall/flake8/docstrings

Flake8/docstrings

core/github_api.py

@@ -4,9 +4,7 @@ import requests
 
 
 class GitHub(object):
-    """
-    Simple api wrapper for the Github API v3.
-    """
+    """Simple api wrapper for the Github API v3."""
 
     def __init__(self, github_repo_user, github_repo, branch='master'):
 
@@ -15,16 +13,14 @@ class GitHub(object):
         self.branch = branch
 
     def _access_api(self, path, params=None):
-        """
-        Access the API at the path given and with the optional params given.
-        """
+        """Access API at given an API path and optional parameters."""
         url = 'https://api.github.com/{path}'.format(path='/'.join(path))
         data = requests.get(url, params=params, verify=False)
         return data.json() if data.ok else []
 
     def commits(self):
         """
-        Uses the API to get a list of the 100 most recent commits from the specified user/repo/branch, starting from HEAD.
+        Get the 100 most recent commits from the specified user/repo/branch, starting from HEAD.
 
         user: The github username of the person whose repo you're querying
         repo: The repo name to query
@@ -39,7 +35,7 @@ class GitHub(object):
 
     def compare(self, base, head, per_page=1):
         """
-        Uses the API to get a list of compares between base and head.
+        Get compares between base and head.
 
         user: The github username of the person whose repo you're querying
         repo: The repo name to query

core/logger.py

@@ -111,10 +111,7 @@ class NTMRotatingLogHandler(object):
             self.close_log(old_handler)
 
     def _config_handler(self):
-        """
-        Configure a file handler to log at file_name and return it.
-        """
-
+        """Configure a file handler to log at file_name and return it."""
         file_handler = logging.FileHandler(self.log_file_path, encoding='utf-8')
 
         file_handler.setLevel(DB)
@@ -130,21 +127,21 @@ class NTMRotatingLogHandler(object):
 
     def _log_file_name(self, i):
         """
-        Returns a numbered log file name depending on i. If i==0 it just uses logName, if not it appends
-        it to the extension (blah.log.3 for i == 3)
+        Return a numbered log file name depending on i.
+
+        If i==0 it just uses logName, if not it appends it to the extension
+        e.g. (blah.log.3 for i == 3)
 
         i: Log number to ues
         """
-
         return self.log_file_path + ('.{0}'.format(i) if i else '')
 
     def _num_logs(self):
         """
-        Scans the log folder and figures out how many log files there are already on disk
+        Scan the log folder and figure out how many log files there are already on disk.
 
         Returns: The number of the last used file (eg. mylog.log.3 would return 3). If there are no logs it returns -1
         """
-
         cur_log = 0
         while os.path.isfile(self._log_file_name(cur_log)):
             cur_log += 1

core/main_db.py

@@ -14,6 +14,8 @@ from core import logger
 
 def db_filename(filename='nzbtomedia.db', suffix=None):
     """
+    Return the correct location of the database file.
+
     @param filename: The sqlite database filename to use. If not specified,
                      will be made to be nzbtomedia.db
     @param suffix: The suffix to append to the filename. A '.' will be added

core/utils/files.py

@@ -88,7 +88,7 @@ def is_min_size(input_name, min_size):
 
 
 def is_archive_file(filename):
-    """Check if the filename is allowed for the Archive"""
+    """Check if the filename is allowed for the Archive."""
     for regext in core.COMPRESSED_CONTAINER:
         if regext.search(filename):
             return regext.split(filename)[0]

core/utils/naming.py

@@ -3,6 +3,8 @@ import re
 
 def sanitize_name(name):
     """
+    Remove bad chars from the filename.
+
     >>> sanitize_name('a/b/c')
     'a-b-c'
     >>> sanitize_name('abc')
@@ -12,8 +14,6 @@ def sanitize_name(name):
     >>> sanitize_name('.a.b..')
     'a.b'
     """
-
-    # remove bad chars from the filename
     name = re.sub(r'[\\/*]', '-', name)
     name = re.sub(r'[:\'<>|?]', '', name)
 
@@ -28,13 +28,12 @@ def sanitize_name(name):
 
 
 def clean_file_name(filename):
-    """Cleans up nzb name by removing any . and _
-    characters, along with any trailing hyphens.
+    """
+    Clean up nzb name by removing any . and _ characters and trailing hyphens.
 
     Is basically equivalent to replacing all _ and . with a
     space, but handles decimal numbers in string, for example:
     """
-
     filename = re.sub(r'(\D)\.(?!\s)(\D)', r'\1 \2', filename)
     filename = re.sub(r'(\d)\.(\d{4})', r'\1 \2', filename)  # if it ends in a year then don't keep the dot
     filename = re.sub(r'(\D)\.(?!\s)', r'\1 ', filename)

core/utils/paths.py

@@ -74,7 +74,7 @@ def get_dir_size(input_path):
 
 
 def remove_empty_folders(path, remove_root=True):
-    """Function to remove empty folders"""
+    """Remove empty folders."""
     if not os.path.isdir(path):
         return
 

core/version_check.py

@@ -19,9 +19,7 @@ from core import github_api as github, logger
 
 
 class CheckVersion(object):
-    """
-    Version check class meant to run as a thread object with the SB scheduler.
-    """
+    """Version checker that runs in a thread with the SB scheduler."""
 
     def __init__(self):
         self.install_type = self.find_install_type()
@@ -40,14 +38,13 @@ class CheckVersion(object):
 
     def find_install_type(self):
         """
-        Determines how this copy of SB was installed.
+        Determine how this copy of SB was installed.
 
         returns: type of installation. Possible values are:
             'win': any compiled windows build
             'git': running from source using git
             'source': running from source without git
         """
-
         # check if we're a windows build
         if os.path.isdir(os.path.join(core.APP_ROOT, u'.git')):
             install_type = 'git'
@@ -58,13 +55,12 @@ class CheckVersion(object):
 
     def check_for_new_version(self, force=False):
         """
-        Checks the internet for a newer version.
+        Check the internet for a newer version.
 
         returns: bool, True for new version or False for no new version.
 
         force: if true the VERSION_NOTIFY setting will be ignored and a check will be forced
         """
-
         if not core.VERSION_NOTIFY and not force:
             logger.log(u'Version checking is disabled, not checking for the newest version')
             return False
@@ -211,13 +207,12 @@ class GitUpdateManager(UpdateManager):
 
     def _find_installed_version(self):
         """
-        Attempts to find the currently installed version of Sick Beard.
+        Attempt to find the currently installed version of Sick Beard.
 
         Uses git show to get commit version.
 
         Returns: True for success or False for failure
         """
-
         output, err, exit_status = self._run_git(self._git_path, 'rev-parse HEAD')  # @UnusedVariable
 
         if exit_status == 0 and output:
@@ -244,10 +239,12 @@ class GitUpdateManager(UpdateManager):
 
     def _check_github_for_update(self):
         """
-        Uses git commands to check if there is a newer version that the provided
-        commit hash. If there is a newer version it sets _num_commits_behind.
-        """
+        Check Github for a new version.
 
+        Uses git commands to check if there is a newer version than
+        the provided commit hash. If there is a newer version it
+        sets _num_commits_behind.
+        """
         self._newest_commit_hash = None
         self._num_commits_behind = 0
         self._num_commits_ahead = 0
@@ -324,10 +321,11 @@ class GitUpdateManager(UpdateManager):
 
     def update(self):
         """
-        Calls git pull origin <branch> in order to update Sick Beard. Returns a bool depending
-        on the call's success.
-        """
+        Check git for a new version.
 
+        Calls git pull origin <branch> in order to update Sick Beard.
+        Returns a bool depending on the call's success.
+        """
         output, err, exit_status = self._run_git(self._git_path, 'pull origin {branch}'.format(branch=self.branch))  # @UnusedVariable
 
         if exit_status == 0:
@@ -382,12 +380,14 @@ class SourceUpdateManager(UpdateManager):
 
     def _check_github_for_update(self):
         """
-        Uses pygithub to ask github if there is a newer version that the provided
-        commit hash. If there is a newer version it sets Sick Beard's version text.
+        Check Github for a new version.
+
+        Uses pygithub to ask github if there is a newer version than
+        the provided commit hash. If there is a newer version it sets
+        Sick Beard's version text.
 
         commit_hash: hash that we're checking against
         """
-
         self._num_commits_behind = 0
         self._newest_commit_hash = None
 
@@ -435,9 +435,7 @@ class SourceUpdateManager(UpdateManager):
             return
 
     def update(self):
-        """
-        Downloads the latest source tarball from github and installs it over the existing version.
-        """
+        """Download and install latest source tarball from github."""
         tar_download_url = 'https://github.com/{org}/{repo}/tarball/{branch}'.format(
             org=self.github_repo_user, repo=self.github_repo, branch=self.branch)
         version_path = os.path.join(core.APP_ROOT, u'version.txt')

tox.ini

@@ -38,6 +38,22 @@ ignore =
 ;    E501 line too long
     E501
 
+;   -- flake8-docstrings --
+;    D100 Missing docstring in public module
+;    D101 Missing docstring in public class
+;    D102 Missing docstring in public method
+;    D103 Missing docstring in public function
+;    D104 Missing docstring in public package
+;    D105 Missing docstring in magic method
+;    D107 Missing docstring in __init__
+;    D200 One-line docstring should fit on one line with quotes
+;    D202 No blank lines allowed after function docstring
+;    D205 1 blank line required between summary line and description
+;    D400 First line should end with a period
+;    D401 First line should be in imperative mood
+;    D402 First line should not be the function's "signature"
+    D100, D101, D102, D103, D104, D105, D107
+
 per-file-ignores =
 ;    F401 imported but unused
 ;    E402 module level import not at top of file
@@ -51,6 +67,7 @@ deps =
     flake8
     flake8-commas
     flake8-comprehensions
+    flake8-docstrings
     flake8-quotes
 skip_install = true
 commands =