Adding docstrings to new code in pylint fix.

Author: dhermes

gcloud/storage/_helpers.py

@@ -5,16 +5,37 @@
 
 
 class _MetadataMixin(object):
-    """Needs class docstring."""
+    """Abstract mixin for cloud storage classes with associated metadata.
+
+    Expected to be subclasses by :class:`gcloud.storage.bucket.Bucket`
+    and :class:`gcloud.storage.key.Key` and both of those classes
+    will implemented the abstract parts:
+      - LOAD_FULL_FIELDS
+      - ACL_CLASS
+      - ACL_KEYWORD
+      - connection
+      - path
+    """
 
     LOAD_FULL_FIELDS = None
-    """Class data attribute docstring."""
+    """Tuple of fields which pertain to metadata.
+
+    Expected to be set by subclasses. Fields in this tuple will cause
+    `get_metadata()` to do a full reload of all metadata before
+    returning.
+    """
 
     ACL_CLASS = type(None)
-    """Class data attribute docstring."""
+    """Class which holds ACL data for a given type.
+
+    Expected to be set by subclasses.
+    """
 
     ACL_KEYWORD = None
-    """Class data attribute docstring."""
+    """Keyword for ACL_CLASS constructor to pass an object in.
+
+    Expected to be set by subclasses.
+    """
 
     def __init__(self):
         # These should be set by the superclass.
@@ -23,12 +44,12 @@ def __init__(self):
 
     @property
     def connection(self):
-        """Needs property docstring."""
+        """Abstract getter for the connection to use."""
         raise NotImplementedError
 
     @property
     def path(self):
-        """Needs property docstring."""
+        """Abstract getter for the object path."""
         raise NotImplementedError
 
     def has_metadata(self, field=None):

gcloud/storage/bucket.py

@@ -21,13 +21,13 @@ class Bucket(_MetadataMixin):
     """
 
     LOAD_FULL_FIELDS = ('acl', 'defaultObjectAcl')
-    """Class data attribute docstring."""
+    """Tuple of metadata fields pertaining to bucket ACLs."""
 
     ACL_CLASS = BucketACL
-    """Class data attribute docstring."""
+    """Class which holds ACL data for buckets."""
 
     ACL_KEYWORD = 'bucket'
-    """Class data attribute docstring."""
+    """Keyword for BucketACL constructor to pass a bucket in."""
 
     def __init__(self, connection=None, name=None, metadata=None):
         super(Bucket, self).__init__()
@@ -66,7 +66,11 @@ def __contains__(self, key):
 
     @property
     def connection(self):
-        """Needs property docstring."""
+        """Getter property for the connection to use with this Bucket.
+
+        :rtype: :class:`gcloud.storage.connection.Connection`
+        :returns: The connection to use.
+        """
         return self._connection
 
     @property

gcloud/storage/key.py

@@ -14,13 +14,13 @@ class Key(_MetadataMixin):
     """A wrapper around Cloud Storage's concept of an ``Object``."""
 
     LOAD_FULL_FIELDS = ('acl',)
-    """Class data attribute docstring."""
+    """Tuple of metadata fields pertaining to key ACLs."""
 
     ACL_CLASS = ObjectACL
-    """Class data attribute docstring."""
+    """Class which holds ACL data for keys."""
 
     ACL_KEYWORD = 'key'
-    """Class data attribute docstring."""
+    """Keyword for ObjectACL constructor to pass a key in."""
 
     CHUNK_SIZE = 1024 * 1024  # 1 MB.
     """The size of a chunk of data whenever iterating (1 MB).

run_pylint.py

@@ -1,60 +1,81 @@
-"""Needs module docstring."""
+"""Custom script to run PyLint on gcloud codebase.
 
+This runs pylint as a script via subprocess in two different
+subprocesses. The first lints the production/library code
+using the default rc file (PRODUCTION_RC). The second lints the
+demo/test code using an rc file (TEST_RC) which allows more style
+violations (hence it has a reduced number of style checks).
+"""
 
 import subprocess
 import sys
 
 
-IGNORED = [
+IGNORED_FILES = [
     'gcloud/datastore/datastore_v1_pb2.py',
     'docs/conf.py',
     'setup.py',
 ]
+PRODUCTION_RC = 'pylintrc_default'
+TEST_RC = 'pylintrc_reduced'
 
 
 def valid_filename(filename):
-    """Needs method docstring."""
+    """Checks if a file is a Python file and is not ignored."""
     return (filename.endswith('.py') and
-            filename not in IGNORED)
+            filename not in IGNORED_FILES)
+
+
+def is_production_filename(filename):
+    """Checks if the file contains production code.
+
+    :rtype: `bool`
+    :returns: Boolean indicating production status.
+    """
+    return not ('demo' in filename or 'test' in filename)
 
 
 def get_python_files():
-    """Needs method docstring."""
+    """Gets a list of all Python files in the repository.
+
+    NOTE: This requires `git` to be installed and requires that this
+          is run within the `git` repository.
+
+    :rtype: `tuple`
+    :returns: A tuple containing two lists. The first list contains
+              all production files and the next all test/demo files.
+    """
     all_files = subprocess.check_output(['git', 'ls-files'])
 
     library_files = []
     non_library_files = []
     for filename in all_files.split('\n'):
         if valid_filename(filename):
-            if 'demo' in filename or 'test' in filename:
-                non_library_files.append(filename)
-            else:
+            if is_production_filename(filename):
                 library_files.append(filename)
+            else:
+                non_library_files.append(filename)
 
     return library_files, non_library_files
 
 
-def main():
-    """Needs method docstring."""
-    library_files, non_library_files = get_python_files()
-    # Use default RC file with the code from the library.
-    pylint_library_code = (['pylint', '--rcfile=pylintrc_default'] +
-                           library_files)
-    status_code = subprocess.call(pylint_library_code)
+def lint_fileset(filenames, rcfile, description):
+    """Lints a group of files using a given rcfile."""
+    rc_flag = '--rcfile=%s' % (rcfile,)
+    pylint_shell_command = ['pylint', rc_flag] + filenames
+    status_code = subprocess.call(pylint_shell_command)
     if status_code != 0:
-        error_message = ('Pylint failed on library code with '
-                         'status %d.' % (status_code,))
+        error_message = ('Pylint failed on %s with '
+                         'status %d.' % (description, status_code))
         print >> sys.stderr, error_message
         sys.exit(status_code)
 
-    pylint_non_library_code = (['pylint', '--rcfile=pylintrc_reduced']
-                               + non_library_files)
-    status_code = subprocess.call(pylint_non_library_code)
-    if status_code != 0:
-        error_message = ('Pylint failed on test and demo code with '
-                         'status %d.' % (status_code,))
-        print >> sys.stderr, error_message
-        sys.exit(status_code)
+
+def main():
+    """Script entry point. Lints both sets of files."""
+    library_files, non_library_files = get_python_files()
+    lint_fileset(library_files, PRODUCTION_RC, 'library code')
+    lint_fileset(non_library_files, TEST_RC, 'test and demo code')
 
 
 if __name__ == '__main__':