Flake8 docstrings

.circleci/config.yml

@@ -24,21 +24,6 @@ jobs:
           name: isort
           when: always
           command: isort -c .
-
-  static-code-analysis-flake8:
-    docker:
-      - image: circleci/python:2.7
-        auth:
-          username: $DOCKER_USER
-          password: $DOCKER_PASS
-    working_directory: ~/code
-    steps:
-      - checkout
-
-      - run:
-          name: Prepare Environment
-          command: |
-            sudo -E pip install --no-deps -r requirements/lint.txt
 
       - run:
           name: flake8
@@ -131,7 +116,6 @@ workflows:
   workflow:
     jobs:
       - static-code-analysis
-      - static-code-analysis-flake8
       - build:
           name: build_py2.7
           python_version: "2.7"

.flake8

@@ -17,5 +17,25 @@ ignore=
     E231,
     E203,
     W503,
-    W504
+    W504,
+    # Missing docstrings
+    D1,
+    # One-line docstring should fit on one line with quotes.
+    # We ignore this because it's OK to buy yourself a few extra characters
+    # for the summary line even if the summary line is *the only* line.
+    D200,
+    # 1 blank line required between summary line and description. We ignore
+    # this because we have quite a few docstrings where the summary is
+    # multi-line.
+    D205,
+    # Multi-line docstring summary should start at the first line.
+    # We ignore this because we agreed in #20553 that we we want to put the
+    # summary line below """ for multi-line docstrings.
+    D212,
+    # First line should end with a period. We ignore this because we have
+    # multi-line summaries.
+    D400,
+    # First line should end with a period, question mark, or exclamation point.
+    # We ignore this because we have multi-line summaries.
+    D415
 exclude=migrations/versions

bin/contact-search-service.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-""" Start the contact search indexing service. """
+"""Start the contact search indexing service."""
 from gevent import monkey
 
 monkey.patch_all()
@@ -32,7 +32,7 @@
 )
 @click.option("-c", "--config", default=None, help="Path to JSON configuration file.")
 def main(prod, config):
-    """ Launch the contact search index service. """
+    """Launch the contact search index service."""
     level = os.environ.get("LOGLEVEL", inbox_config.get("LOGLEVEL"))
     configure_logging(log_level=level)
 

bin/detect-missing-sync-host.py

@@ -13,11 +13,10 @@
 @click.command()
 def main():
     """
-    Detects accounts with sync_state and sync_host inconsistent with
+    Detect accounts with sync_state and sync_host inconsistent with
     sync_should_run bit. (At one point, this could happen if, say, an account
     was _started_ on a new host without being first stopped on its previous
     host.)
-
     """
     maybe_enable_rollbar()
 

bin/inbox-api.py

@@ -67,7 +67,7 @@
 @click.option("-c", "--config", default=None, help="Path to JSON configuration file.")
 @click.option("-p", "--port", default=5555, help="Port to run flask app on.")
 def main(prod, start_syncback, enable_tracer, config, port, enable_profiler):
-    """ Launch the Nylas API service. """
+    """Launch the Nylas API service."""
     level = os.environ.get("LOGLEVEL", inbox_config.get("LOGLEVEL"))
     configure_logging(log_level=level)
 

bin/inbox-auth.py

@@ -48,7 +48,7 @@
     help="Manually specify the provider instead of trying to detect it",
 )
 def main(email_address, reauth, target, provider):
-    """ Auth an email account. """
+    """Auth an email account."""
     preflight()
 
     maybe_enable_rollbar()

bin/inbox-console.py

@@ -33,7 +33,7 @@
 )
 @click.option("-c", "--client", is_flag=True, help="Start a repl with an APIClient")
 def console(email_address, client):
-    """ REPL for Nylas. """
+    """Enter REPL for Nylas."""
     maybe_enable_rollbar()
 
     if client:

bin/inbox-start.py

@@ -99,7 +99,7 @@
     "can be used to avoid memory leaks.",
 )
 def main(prod, enable_tracer, enable_profiler, config, process_num, exit_after):
-    """ Launch the Nylas sync service. """
+    """Launch the Nylas sync service."""
     level = os.environ.get("LOGLEVEL", inbox_config.get("LOGLEVEL"))
     configure_logging(log_level=level)
     reconfigure_logging()

bin/syncback-service.py

@@ -63,7 +63,7 @@
     help="Enables the CPU profiler web API",
 )
 def main(prod, config, process_num, syncback_id, enable_tracer, enable_profiler):
-    """ Launch the actions syncback service. """
+    """Launch the actions syncback service."""
     setproctitle("syncback-{}".format(process_num))
 
     maybe_enable_rollbar()

bin/syncback-stats.py

@@ -17,9 +17,9 @@
 
 @click.command()
 def main():
-    """ Generate per-shard and per-namespace breakdowns of syncback queue
+    """
+    Generate per-shard and per-namespace breakdowns of syncback queue
     lengths.
-
     """
     maybe_enable_rollbar()
 

inbox/actions/backends/generic.py

@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
-""" Operations for syncing back local datastore changes to
-    generic IMAP providers.
+"""
+Operations for syncing back local datastore changes to
+generic IMAP providers.
 """
 from collections import defaultdict
 from imaplib import IMAP4

inbox/actions/backends/gmail.py

@@ -1,4 +1,4 @@
-""" Operations for syncing back local datastore changes to Gmail. """
+"""Operations for syncing back local datastore changes to Gmail."""
 
 from imaplib import IMAP4
 

inbox/actions/base.py

@@ -1,4 +1,5 @@
-""" Code for propagating Nylas datastore changes to account backends.
+"""
+Code for propagating Nylas datastore changes to account backends.
 
 Syncback actions don't update anything in the local datastore; the Nylas
 datastore is updated asynchronously (see namespace.py) and bookkeeping about
@@ -21,7 +22,6 @@
 
 ACTIONS MUST BE IDEMPOTENT! We are going to have task workers guarantee
 at-least-once semantics.
-
 """
 from inbox.actions.backends.generic import (
     remote_create_folder,
@@ -105,7 +105,7 @@ def delete_label(crispin_client, account_id, category_id):
 
 
 def save_draft(crispin_client, account_id, message_id, args):
-    """ Sync a new draft back to the remote backend. """
+    """Sync a new draft back to the remote backend."""
     with session_scope(account_id) as db_session:
         message = db_session.query(Message).get(message_id)
         version = args.get("version")
@@ -131,7 +131,7 @@ def save_draft(crispin_client, account_id, message_id, args):
 
 
 def update_draft(crispin_client, account_id, message_id, args):
-    """ Sync an updated draft back to the remote backend. """
+    """Sync an updated draft back to the remote backend."""
     with session_scope(account_id) as db_session:
         message = db_session.query(Message).get(message_id)
         version = args.get("version")

inbox/api/err.py

@@ -18,11 +18,11 @@ def get_request_uid(headers):
 
 
 def log_exception(exc_info, **kwargs):
-    """ Add exception info to the log context for the request.
+    """
+    Add exception info to the log context for the request.
 
     We do not log in a separate log statement in order to make debugging
     easier. As a bonus, this reduces log volume somewhat.
-
     """
     rollbar.report_exc_info(exc_info)
 
@@ -52,8 +52,10 @@ class APIException(Exception):
 
 
 class InputError(APIException):
-    """Raised on invalid user input (missing required parameter, value too
-    long, etc.)"""
+    """
+    Raised on invalid user input (missing required parameter, value too
+    long, etc.)
+    """
 
     status_code = 400
 
@@ -81,7 +83,7 @@ def __init__(self, message):
 
 
 class AccountInvalidError(APIException):
-    """ Raised when an account's credentials are not valid. """
+    """Raised when an account's credentials are not valid."""
 
     status_code = 403
     message = (
@@ -92,7 +94,7 @@ class AccountInvalidError(APIException):
 
 
 class AccountStoppedError(APIException):
-    """ Raised when an account has been stopped. """
+    """Raised when an account has been stopped."""
 
     status_code = 403
     message = (
@@ -103,14 +105,14 @@ class AccountStoppedError(APIException):
 
 
 class AccountDoesNotExistError(APIException):
-    """ Raised when an account does not exist (for example, if it was deleted). """
+    """Raised when an account does not exist (for example, if it was deleted)."""
 
     status_code = 404
     message = "The account does not exist."
 
 
 def err(http_code, message, **kwargs):
-    """ Handle unexpected errors, including sending the traceback to Rollbar. """
+    """Handle unexpected errors, including sending the traceback to Rollbar."""
     log_exception(sys.exc_info(), user_error_message=message, **kwargs)
     resp = {"type": "api_error", "message": message}
     resp.update(kwargs)

inbox/api/kellogs.py

@@ -96,7 +96,7 @@ def _convert_timezone_to_iana_tz(original_tz):
 
 def _encode(obj, namespace_public_id=None, expand=False, is_n1=False):
     """
-    Returns a dictionary representation of a Nylas model object obj, or
+    Return a dictionary representation of a Nylas model object obj, or
     None if there is no such representation defined. If the optional
     namespace_public_id parameter is passed, it will used instead of fetching
     the namespace public id for each object. This improves performance when
@@ -111,16 +111,18 @@ def _encode(obj, namespace_public_id=None, expand=False, is_n1=False):
     Returns
     -------
     dictionary or None
-
     """
 
     def _get_namespace_public_id(obj):
         return namespace_public_id or obj.namespace.public_id
 
     def _format_participant_data(participant):
-        """Event.participants is a JSON blob which may contain internal data.
-        This function returns a dict with only the data we want to make
-        public."""
+        """
+        Return a dict with only the data we want to make public.
+
+        Event.participants is a JSON blob which may contain internal data.
+        This function
+        """
         dct = {}
         for attribute in ["name", "status", "email", "comment"]:
             dct[attribute] = participant.get(attribute)
@@ -417,7 +419,7 @@ def _get_lowercase_class_name(obj):
 
 class APIEncoder(object):
     """
-    Provides methods for serializing Nylas objects. If the optional
+    Provide methods for serializing Nylas objects. If the optional
     namespace_public_id parameter is passed, it will be bound and used instead
     of fetching the namespace public id for each object. This improves
     performance when serializing large numbers of objects, but also means that
@@ -428,7 +430,6 @@ class APIEncoder(object):
     ----------
     namespace_public_id: string, optional
         public id of the namespace to which the object to serialize belongs.
-
     """
 
     def __init__(self, namespace_public_id=None, expand=False, is_n1=False):
@@ -451,7 +452,7 @@ def default(self, obj):
 
     def cereal(self, obj, pretty=False):
         """
-        Returns the JSON string representation of obj.
+        Return the JSON string representation of obj.
 
         Parameters
         ----------
@@ -477,7 +478,7 @@ def cereal(self, obj, pretty=False):
 
     def jsonify(self, obj):
         """
-        Returns a Flask Response object encapsulating the JSON
+        Return a Flask Response object encapsulating the JSON
         representation of obj.
 
         Parameters

inbox/api/ns_api.py

@@ -498,7 +498,7 @@ def thread_api_update(public_id):
 #
 @app.route("/threads/<public_id>", methods=["DELETE"])
 def thread_api_delete(public_id):
-    """ Moves the thread to the trash """
+    """Move the thread to the trash"""
     raise NotImplementedError
 
 
@@ -1838,7 +1838,7 @@ def draft_send_api():
 
 @app.route("/send-multiple", methods=["POST"])
 def multi_send_create():
-    """Initiates a multi-send session by creating a new multi-send draft."""
+    """Initiate a multi-send session by creating a new multi-send draft."""
     account = g.namespace.account
 
     if account.discriminator == "easaccount":
@@ -1860,11 +1860,13 @@ def multi_send_create():
 
 @app.route("/send-multiple/<draft_id>", methods=["POST"])
 def multi_send(draft_id):
-    """Performs a single send operation in an individualized multi-send
+    """
+    Perform a single send operation in an individualized multi-send
     session. Sends a copy of the draft at draft_id to the specified address
     with the specified body, and ensures that a corresponding sent message is
     either not created in the user's Sent folder or is immediately
-    deleted from it."""
+    deleted from it.
+    """
     request_started = time.time()
     account = g.namespace.account
 
@@ -1906,9 +1908,10 @@ def multi_send(draft_id):
 
 @app.route("/send-multiple/<draft_id>", methods=["DELETE"])
 def multi_send_finish(draft_id):
-    """Closes out a multi-send session by marking the sending draft as sent
-    and moving it to the user's Sent folder."""
-
+    """
+    Close out a multi-send session by marking the sending draft as sent
+    and moving it to the user's Sent folder.
+    """
     account = g.namespace.account
 
     if account.discriminator == "easaccount":

inbox/api/sending.py

@@ -35,7 +35,7 @@ def send_draft(account, draft, db_session):
 
 def send_draft_copy(account, draft, custom_body, recipient):
     """
-    Sends a copy of this draft to the recipient, using the specified body
+    Send a copy of this draft to the recipient, using the specified body
     rather that the one on the draft object, and not marking the draft as
     sent. Used within multi-send to send messages to individual recipients
     with customized bodies.