Refs #27656 -- Updated django.core docstring verbs according to PEP 257.

38 files changed, 200 insertions, 271 deletions

diff --git a/django/core/cache/__init__.py b/django/core/cache/__init__.py
index d51c1cb38e..7aaa057229 100644
--- a/django/core/cache/__init__.py
+++ b/django/core/cache/__init__.py
@@ -59,7 +59,7 @@ class CacheHandler:
     """
     A Cache Handler to manage access to Cache instances.
 
-    Ensures only one instance of each alias exists per thread.
+    Ensure only one instance of each alias exists per thread.
     """
     def __init__(self):
         self._caches = local()
diff --git a/django/core/cache/backends/base.py b/django/core/cache/backends/base.py
index 2d5b0634a1..b5661891d6 100644
--- a/django/core/cache/backends/base.py
+++ b/django/core/cache/backends/base.py
@@ -26,7 +26,7 @@ def default_key_func(key, key_prefix, version):
     """
     Default function to generate keys.
 
-    Constructs the key used by all other methods. By default it prepends
+    Construct the key used by all other methods. By default, prepend
     the `key_prefix'. KEY_FUNCTION can be used to specify an alternate
     function with custom key making behavior.
     """
@@ -37,7 +37,7 @@ def get_key_func(key_func):
     """
     Function to decide which key function to use.
 
-    Defaults to ``default_key_func``.
+    Default to ``default_key_func``.
     """
     if key_func is not None:
         if callable(key_func):
@@ -76,7 +76,7 @@ class BaseCache:
 
     def get_backend_timeout(self, timeout=DEFAULT_TIMEOUT):
         """
-        Returns the timeout value usable by this backend based upon the provided
+        Return the timeout value usable by this backend based upon the provided
         timeout.
         """
         if timeout == DEFAULT_TIMEOUT:
@@ -87,12 +87,12 @@ class BaseCache:
         return None if timeout is None else time.time() + timeout
 
     def make_key(self, key, version=None):
-        """Constructs the key used by all other methods. By default it
-        uses the key_func to generate a key (which, by default,
-        prepends the `key_prefix' and 'version'). A different key
-        function can be provided at the time of cache construction;
-        alternatively, you can subclass the cache backend to provide
-        custom key making behavior.
+        """
+        Construct the key used by all other methods. By default, use the
+        key_func to generate a key (which, by default, prepends the
+        `key_prefix' and 'version'). A different key function can be provided
+        at the time of cache construction; alternatively, you can subclass the
+        cache backend to provide custom key making behavior.
         """
         if version is None:
             version = self.version
@@ -103,10 +103,10 @@ class BaseCache:
     def add(self, key, value, timeout=DEFAULT_TIMEOUT, version=None):
         """
         Set a value in the cache if the key does not already exist. If
-        timeout is given, that timeout will be used for the key; otherwise
-        the default cache timeout will be used.
+        timeout is given, use that timeout for the key; otherwise use the
+        default cache timeout.
 
-        Returns True if the value was stored, False otherwise.
+        Return True if the value was stored, False otherwise.
         """
         raise NotImplementedError('subclasses of BaseCache must provide an add() method')
 
@@ -119,8 +119,8 @@ class BaseCache:
 
     def set(self, key, value, timeout=DEFAULT_TIMEOUT, version=None):
         """
-        Set a value in the cache. If timeout is given, that timeout will be
-        used for the key; otherwise the default cache timeout will be used.
+        Set a value in the cache. If timeout is given, use that timeout for the
+        key; otherwise use the default cache timeout.
         """
         raise NotImplementedError('subclasses of BaseCache must provide a set() method')
 
@@ -135,7 +135,7 @@ class BaseCache:
         Fetch a bunch of keys from the cache. For certain backends (memcached,
         pgsql) this can be *much* faster when fetching multiple values.
 
-        Returns a dict mapping each key in keys to its value. If the given
+        Return a dict mapping each key in keys to its value. If the given
         key is missing, it will be missing from the response dict.
         """
         d = {}
@@ -148,9 +148,9 @@ class BaseCache:
     def get_or_set(self, key, default, timeout=DEFAULT_TIMEOUT, version=None):
         """
         Fetch a given key from the cache. If the key does not exist,
-        the key is added and set to the default value. The default value can
-        also be any callable. If timeout is given, that timeout will be used
-        for the key; otherwise the default cache timeout will be used.
+        add the key and set it to the default value. The default value can
+        also be any callable. If timeout is given, use that timeout for the
+        key; otherwise use the default cache timeout.
 
         Return the value of the key stored or retrieved.
         """
@@ -166,7 +166,7 @@ class BaseCache:
 
     def has_key(self, key, version=None):
         """
-        Returns True if the key is in the cache and has not expired.
+        Return True if the key is in the cache and has not expired.
         """
         return self.get(key, version=version) is not None
 
@@ -191,7 +191,7 @@ class BaseCache:
 
     def __contains__(self, key):
         """
-        Returns True if the key is in the cache and has not expired.
+        Return True if the key is in the cache and has not expired.
         """
         # This is a separate method, rather than just a copy of has_key(),
         # so that it always has the same functionality as has_key(), even
@@ -204,8 +204,8 @@ class BaseCache:
         pairs.  For certain backends (memcached), this is much more efficient
         than calling set() multiple times.
 
-        If timeout is given, that timeout will be used for the key; otherwise
-        the default cache timeout will be used.
+        If timeout is given, use that timeout for the key; otherwise use the
+        default cache timeout.
         """
         for key, value in data.items():
             self.set(key, value, timeout=timeout, version=version)
@@ -243,8 +243,9 @@ class BaseCache:
                 break
 
     def incr_version(self, key, delta=1, version=None):
-        """Adds delta to the cache version for the supplied key. Returns the
-        new version.
+        """
+        Add delta to the cache version for the supplied key. Return the new
+        version.
         """
         if version is None:
             version = self.version
@@ -258,8 +259,9 @@ class BaseCache:
         return version + delta
 
     def decr_version(self, key, delta=1, version=None):
-        """Subtracts delta from the cache version for the supplied key. Returns
-        the new version.
+        """
+        Subtract delta from the cache version for the supplied key. Return the
+        new version.
         """
         return self.incr_version(key, -delta, version)
 
diff --git a/django/core/cache/backends/filebased.py b/django/core/cache/backends/filebased.py
index a381ebc265..56d2cf5b6d 100644
--- a/django/core/cache/backends/filebased.py
+++ b/django/core/cache/backends/filebased.py
@@ -75,7 +75,7 @@ class FileBasedCache(BaseCache):
 
     def _cull(self):
         """
-        Removes random cache entries if max_entries is reached at a ratio
+        Remove random cache entries if max_entries is reached at a ratio
         of num_entries / cull_frequency. A value of 0 for CULL_FREQUENCY means
         that the entire cache will be purged.
         """
@@ -119,8 +119,7 @@ class FileBasedCache(BaseCache):
 
     def _is_expired(self, f):
         """
-        Takes an open cache file and determines if it has expired,
-        deletes the file if it is has passed its expiry time.
+        Take an open cache file `f` and delete it if it's expired.
         """
         exp = pickle.load(f)
         if exp is not None and exp < time.time():
diff --git a/django/core/cache/backends/memcached.py b/django/core/cache/backends/memcached.py
index 8f87f487bf..6e8211bdff 100644
--- a/django/core/cache/backends/memcached.py
+++ b/django/core/cache/backends/memcached.py
@@ -30,7 +30,7 @@ class BaseMemcachedCache(BaseCache):
     @property
     def _cache(self):
         """
-        Implements transparent thread-safe access to a memcached client.
+        Implement transparent thread-safe access to a memcached client.
         """
         if getattr(self, '_client', None) is None:
             self._client = self._lib.Client(self._servers, **self._options)
diff --git a/django/core/files/base.py b/django/core/files/base.py
index 9030ed9155..90b75b18cb 100644
--- a/django/core/files/base.py
+++ b/django/core/files/base.py
@@ -76,7 +76,7 @@ class File(FileProxyMixin):
 
     def multiple_chunks(self, chunk_size=None):
         """
-        Returns ``True`` if you can expect multiple chunks.
+        Return ``True`` if you can expect multiple chunks.
 
         NB: If a particular file representation is in memory, subclasses should
         always return ``False`` -- there's no good reason to read from memory in
@@ -133,7 +133,7 @@ class File(FileProxyMixin):
 
 class ContentFile(File):
     """
-    A File-like object that takes just raw content, rather than an actual file.
+    A File-like object that take just raw content, rather than an actual file.
     """
     def __init__(self, content, name=None):
         stream_class = StringIO if isinstance(content, str) else BytesIO
@@ -154,21 +154,15 @@ class ContentFile(File):
 
 
 def endswith_cr(line):
-    """
-    Return True if line (a text or byte string) ends with '\r'.
-    """
+    """Return True if line (a text or byte string) ends with '\r'."""
     return line.endswith('\r' if isinstance(line, str) else b'\r')
 
 
 def endswith_lf(line):
-    """
-    Return True if line (a text or byte string) ends with '\n'.
-    """
+    """Return True if line (a text or byte string) ends with '\n'."""
     return line.endswith('\n' if isinstance(line, str) else b'\n')
 
 
 def equals_lf(line):
-    """
-    Return True if line (a text or byte string) equals '\n'.
-    """
+    """Return True if line (a text or byte string) equals '\n'."""
     return line == ('\n' if isinstance(line, str) else b'\n')
diff --git a/django/core/files/images.py b/django/core/files/images.py
index 5bd0f638fe..cdb89de2cc 100644
--- a/django/core/files/images.py
+++ b/django/core/files/images.py
@@ -32,7 +32,7 @@ class ImageFile(File):
 
 def get_image_dimensions(file_or_path, close=False):
     """
-    Returns the (width, height) of an image, given an open file or a path.  Set
+    Return the (width, height) of an image, given an open file or a path.  Set
     'close' to True to close the file at the end if it is initially in an open
     state.
     """
diff --git a/django/core/files/move.py b/django/core/files/move.py
index 9e6cfe7684..23491d6573 100644
--- a/django/core/files/move.py
+++ b/django/core/files/move.py
@@ -28,15 +28,14 @@ def _samefile(src, dst):
 
 def file_move_safe(old_file_name, new_file_name, chunk_size=1024 * 64, allow_overwrite=False):
     """
-    Moves a file from one location to another in the safest way possible.
+    Move a file from one location to another in the safest way possible.
 
-    First, tries ``os.rename``, which is simple but will break across filesystems.
-    If that fails, streams manually from one file to another in pure Python.
+    First, try ``os.rename``, which is simple but will break across filesystems.
+    If that fails, stream manually from one file to another in pure Python.
 
-    If the destination file exists and ``allow_overwrite`` is ``False``, this
-    function will throw an ``IOError``.
+    If the destination file exists and ``allow_overwrite`` is ``False``, raise
+    ``IOError``.
     """
-
     # There's no reason to move if we don't have to.
     if _samefile(old_file_name, new_file_name):
         return
diff --git a/django/core/files/storage.py b/django/core/files/storage.py
index df4db9f2e8..1ee9533eb2 100644
--- a/django/core/files/storage.py
+++ b/django/core/files/storage.py
@@ -29,14 +29,12 @@ class Storage:
     # These shouldn't be overridden by subclasses unless absolutely necessary.
 
     def open(self, name, mode='rb'):
-        """
-        Retrieves the specified file from storage.
-        """
+        """Retrieve the specified file from storage."""
         return self._open(name, mode)
 
     def save(self, name, content, max_length=None):
         """
-        Saves new content to the file specified by name. The content should be
+        Save new content to the file specified by name. The content should be
         a proper File object or any python file-like object, ready to be read
         from the beginning.
         """
@@ -54,14 +52,14 @@ class Storage:
 
     def get_valid_name(self, name):
         """
-        Returns a filename, based on the provided filename, that's suitable for
+        Return a filename, based on the provided filename, that's suitable for
         use in the target storage system.
         """
         return get_valid_filename(name)
 
     def get_available_name(self, name, max_length=None):
         """
-        Returns a filename that's free on the target storage system, and
+        Return a filename that's free on the target storage system and
         available for new content to be written to.
         """
         dir_name, file_name = os.path.split(name)
@@ -101,7 +99,7 @@ class Storage:
 
     def path(self, name):
         """
-        Returns a local filesystem path where the file can be retrieved using
+        Return a local filesystem path where the file can be retrieved using
         Python's built-in open() function. Storage systems that can't be
         accessed using open() should *not* implement this method.
         """
@@ -112,33 +110,33 @@ class Storage:
 
     def delete(self, name):
         """
-        Deletes the specified file from the storage system.
+        Delete the specified file from the storage system.
         """
         raise NotImplementedError('subclasses of Storage must provide a delete() method')
 
     def exists(self, name):
         """
-        Returns True if a file referenced by the given name already exists in the
+        Return True if a file referenced by the given name already exists in the
         storage system, or False if the name is available for a new file.
         """
         raise NotImplementedError('subclasses of Storage must provide an exists() method')
 
     def listdir(self, path):
         """
-        Lists the contents of the specified path, returning a 2-tuple of lists;
+        List the contents of the specified path. Return a 2-tuple of lists:
         the first item being directories, the second item being files.
         """
         raise NotImplementedError('subclasses of Storage must provide a listdir() method')
 
     def size(self, name):
         """
-        Returns the total size, in bytes, of the file specified by name.
+        Return the total size, in bytes, of the file specified by name.
         """
         raise NotImplementedError('subclasses of Storage must provide a size() method')
 
     def url(self, name):
         """
-        Returns an absolute URL where the file's contents can be accessed
+        Return an absolute URL where the file's contents can be accessed
         directly by a Web browser.
         """
         raise NotImplementedError('subclasses of Storage must provide a url() method')
diff --git a/django/core/files/uploadedfile.py b/django/core/files/uploadedfile.py
index 9f1efde419..485bfbfd6f 100644
--- a/django/core/files/uploadedfile.py
+++ b/django/core/files/uploadedfile.py
@@ -62,9 +62,7 @@ class TemporaryUploadedFile(UploadedFile):
         super().__init__(file, name, content_type, size, charset, content_type_extra)
 
     def temporary_file_path(self):
-        """
-        Returns the full path of this file.
-        """
+        """Return the full path of this file."""
         return self.file.name
 
     def close(self):
@@ -108,8 +106,7 @@ class SimpleUploadedFile(InMemoryUploadedFile):
     @classmethod
     def from_dict(cls, file_dict):
         """
-        Creates a SimpleUploadedFile object from
-        a dictionary object with the following keys:
+        Create a SimpleUploadedFile object from a dictionary with keys:
            - filename
            - content-type
            - content
diff --git a/django/core/files/uploadhandler.py b/django/core/files/uploadhandler.py
index a6832491c1..5e993d13e2 100644
--- a/django/core/files/uploadhandler.py
+++ b/django/core/files/uploadhandler.py
@@ -158,7 +158,8 @@ class MemoryFileUploadHandler(FileUploadHandler):
 
     def handle_raw_input(self, input_data, META, content_length, boundary, encoding=None):
         """
-        Use the content_length to signal whether or not this handler should be in use.
+        Use the content_length to signal whether or not this handler should be
+        used.
         """
         # Check the content-length header to see if we should
         # If the post is too large, we cannot use the Memory handler.
@@ -174,18 +175,14 @@ class MemoryFileUploadHandler(FileUploadHandler):
             raise StopFutureHandlers()
 
     def receive_data_chunk(self, raw_data, start):
-        """
-        Add the data to the BytesIO file.
-        """
+        """Add the data to the BytesIO file."""
         if self.activated:
             self.file.write(raw_data)
         else:
             return raw_data
 
     def file_complete(self, file_size):
-        """
-        Return a file object if we're activated.
-        """
+        """Return a file object if this handler is activated."""
         if not self.activated:
             return
 
diff --git a/django/core/handlers/wsgi.py b/django/core/handlers/wsgi.py
index a041dd11d4..6c0c5ae57f 100644
--- a/django/core/handlers/wsgi.py
+++ b/django/core/handlers/wsgi.py
@@ -15,10 +15,7 @@ _slashes_re = re.compile(br'/+')
 
 
 class LimitedStream:
-    '''
-    LimitedStream wraps another stream in order to not allow reading from it
-    past specified amount of bytes.
-    '''
+    """Wrap another stream to disallow reading it past a number of bytes."""
     def __init__(self, stream, limit, buf_size=64 * 1024 * 1024):
         self.stream = stream
         self.remaining = limit
@@ -161,9 +158,7 @@ class WSGIHandler(base.BaseHandler):
 
 
 def get_path_info(environ):
-    """
-    Return the HTTP request's PATH_INFO as a string.
-    """
+    """Return the HTTP request's PATH_INFO as a string."""
     path_info = get_bytes_from_wsgi(environ, 'PATH_INFO', '/')
 
     return repercent_broken_unicode(path_info).decode()
@@ -171,8 +166,8 @@ def get_path_info(environ):
 
 def get_script_name(environ):
     """
-    Returns the equivalent of the HTTP request's SCRIPT_NAME environment
-    variable. If Apache mod_rewrite has been used, returns what would have been
+    Return the equivalent of the HTTP request's SCRIPT_NAME environment
+    variable. If Apache mod_rewrite is used, return what would have been
     the script name prior to any rewriting (so it's the script name as seen
     from the client's perspective), unless the FORCE_SCRIPT_NAME setting is
     set (to anything).
diff --git a/django/core/mail/__init__.py b/django/core/mail/__init__.py
index 23beae0cce..05c8c6a1b1 100644
--- a/django/core/mail/__init__.py
+++ b/django/core/mail/__init__.py
@@ -26,7 +26,7 @@ __all__ = [
 def get_connection(backend=None, fail_silently=False, **kwds):
     """Load an email backend and return an instance of it.
 
-    If backend is None (default) settings.EMAIL_BACKEND is used.
+    If backend is None (default), use settings.EMAIL_BACKEND.
 
     Both fail_silently and other keyword arguments are used in the
     constructor of the backend.
@@ -42,8 +42,8 @@ def send_mail(subject, message, from_email, recipient_list,
     Easy wrapper for sending a single message to a recipient list. All members
     of the recipient list will see the other recipients in the 'To' field.
 
-    If auth_user is None, the EMAIL_HOST_USER setting is used.
-    If auth_password is None, the EMAIL_HOST_PASSWORD setting is used.
+    If auth_user is None, use the EMAIL_HOST_USER setting.
+    If auth_password is None, use the EMAIL_HOST_PASSWORD setting.
 
     Note: The API for this method is frozen. New code wanting to extend the
     functionality should use the EmailMessage class directly.
@@ -63,13 +63,13 @@ def send_mail(subject, message, from_email, recipient_list,
 def send_mass_mail(datatuple, fail_silently=False, auth_user=None,
                    auth_password=None, connection=None):
     """
-    Given a datatuple of (subject, message, from_email, recipient_list), sends
-    each message to each recipient list. Returns the number of emails sent.
+    Given a datatuple of (subject, message, from_email, recipient_list), send
+    each message to each recipient list. Return the number of emails sent.
 
-    If from_email is None, the DEFAULT_FROM_EMAIL setting is used.
-    If auth_user and auth_password are set, they're used to log in.
-    If auth_user is None, the EMAIL_HOST_USER setting is used.
-    If auth_password is None, the EMAIL_HOST_PASSWORD setting is used.
+    If from_email is None, use the DEFAULT_FROM_EMAIL setting.
+    If auth_user and auth_password are set, use them to log in.
+    If auth_user is None, use the EMAIL_HOST_USER setting.
+    If auth_password is None, use the EMAIL_HOST_PASSWORD setting.
 
     Note: The API for this method is frozen. New code wanting to extend the
     functionality should use the EmailMessage class directly.
@@ -88,7 +88,7 @@ def send_mass_mail(datatuple, fail_silently=False, auth_user=None,
 
 def mail_admins(subject, message, fail_silently=False, connection=None,
                 html_message=None):
-    """Sends a message to the admins, as defined by the ADMINS setting."""
+    """Send a message to the admins, as defined by the ADMINS setting."""
     if not settings.ADMINS:
         return
     mail = EmailMultiAlternatives(
@@ -103,7 +103,7 @@ def mail_admins(subject, message, fail_silently=False, connection=None,
 
 def mail_managers(subject, message, fail_silently=False, connection=None,
                   html_message=None):
-    """Sends a message to the managers, as defined by the MANAGERS setting."""
+    """Send a message to the managers, as defined by the MANAGERS setting."""
     if not settings.MANAGERS:
         return
     mail = EmailMultiAlternatives(
diff --git a/django/core/mail/backends/base.py b/django/core/mail/backends/base.py
index e0d2e3626b..d687703332 100644
--- a/django/core/mail/backends/base.py
+++ b/django/core/mail/backends/base.py
@@ -7,8 +7,8 @@ class BaseEmailBackend:
 
     Subclasses must at least overwrite send_messages().
 
-   open() and close() can be called indirectly by using a backend object as a
-   context manager:
+    open() and close() can be called indirectly by using a backend object as a
+    context manager:
 
        with backend as connection:
            # do something with connection
@@ -18,7 +18,8 @@ class BaseEmailBackend:
         self.fail_silently = fail_silently
 
     def open(self):
-        """Open a network connection.
+        """
+        Open a network connection.
 
         This method can be overwritten by backend implementations to
         open a network connection.
@@ -52,7 +53,7 @@ class BaseEmailBackend:
 
     def send_messages(self, email_messages):
         """
-        Sends one or more EmailMessage objects and returns the number of email
+        Send one or more EmailMessage objects and return the number of email
         messages sent.
         """
         raise NotImplementedError('subclasses of BaseEmailBackend must override send_messages() method')
diff --git a/django/core/mail/backends/locmem.py b/django/core/mail/backends/locmem.py
index f022236dd7..84732e997b 100644
--- a/django/core/mail/backends/locmem.py
+++ b/django/core/mail/backends/locmem.py
@@ -7,7 +7,8 @@ from django.core.mail.backends.base import BaseEmailBackend
 
 
 class EmailBackend(BaseEmailBackend):
-    """A email backend for use during test sessions.
+    """
+    An email backend for use during test sessions.
 
     The test connection stores email messages in a dummy outbox,
     rather than sending them out on the wire.
diff --git a/django/core/mail/backends/smtp.py b/django/core/mail/backends/smtp.py
index 97b5df97e8..d061fb5750 100644
--- a/django/core/mail/backends/smtp.py
+++ b/django/core/mail/backends/smtp.py
@@ -74,7 +74,7 @@ class EmailBackend(BaseEmailBackend):
                 raise
 
     def close(self):
-        """Closes the connection to the email server."""
+        """Close the connection to the email server."""
         if self.connection is None:
             return
         try:
@@ -94,7 +94,7 @@ class EmailBackend(BaseEmailBackend):
 
     def send_messages(self, email_messages):
         """
-        Sends one or more EmailMessage objects and returns the number of email
+        Send one or more EmailMessage objects and return the number of email
         messages sent.
         """
         if not email_messages:
diff --git a/django/core/mail/message.py b/django/core/mail/message.py
index 790cbdf31a..7ab5414482 100644
--- a/django/core/mail/message.py
+++ b/django/core/mail/message.py
@@ -53,7 +53,7 @@ ADDRESS_HEADERS = {
 
 
 def forbid_multi_line_headers(name, val, encoding):
-    """Forbids multi-line headers, to prevent header injection."""
+    """Forbid multi-line headers to prevent header injection."""
     encoding = encoding or settings.DEFAULT_CHARSET
     val = force_text(val)
     if '\n' in val or '\r' in val:
@@ -73,7 +73,7 @@ def forbid_multi_line_headers(name, val, encoding):
 
 def split_addr(addr, encoding):
     """
-    Split the address into local part and domain, properly encoded.
+    Split the address into local part and domain and encode them.
 
     When non-ascii characters are present in the local part, it must be
     MIME-word encoded. The domain name must be idna-encoded if it contains
@@ -193,9 +193,7 @@ class SafeMIMEMultipart(MIMEMixin, MIMEMultipart):
 
 
 class EmailMessage:
-    """
-    A container for email information.
-    """
+    """A container for email information."""
     content_subtype = 'plain'
     mixed_subtype = 'mixed'
     encoding = None     # None => use settings default
@@ -280,13 +278,13 @@ class EmailMessage:
 
     def recipients(self):
         """
-        Returns a list of all recipients of the email (includes direct
+        Return a list of all recipients of the email (includes direct
         addressees as well as Cc and Bcc entries).
         """
         return [email for email in (self.to + self.cc + self.bcc) if email]
 
     def send(self, fail_silently=False):
-        """Sends the email message."""
+        """Send the email message."""
         if not self.recipients():
             # Don't bother creating the network connection if there's nobody to
             # send to.
@@ -295,16 +293,15 @@ class EmailMessage:
 
     def attach(self, filename=None, content=None, mimetype=None):
         """
-        Attaches a file with the given filename and content. The filename can
+        Attach a file with the given filename and content. The filename can
         be omitted and the mimetype is guessed, if not provided.
 
-        If the first parameter is a MIMEBase subclass it is inserted directly
+        If the first parameter is a MIMEBase subclass, insert it directly
         into the resulting message attachments.
 
         For a text/* mimetype (guessed or specified), when a bytes object is
-        specified as content, it will be decoded as UTF-8. If that fails,
-        the mimetype will be set to DEFAULT_ATTACHMENT_MIME_TYPE and the
-        content is not decoded.
+        specified as content, decode it as UTF-8. If that fails, set the
+        mimetype to DEFAULT_ATTACHMENT_MIME_TYPE and don't decode the content.
         """
         if isinstance(filename, MIMEBase):
             assert content is None
@@ -332,14 +329,14 @@ class EmailMessage:
 
     def attach_file(self, path, mimetype=None):
         """
-        Attaches a file from the filesystem.
+        Attach a file from the filesystem.
 
-        The mimetype will be set to the DEFAULT_ATTACHMENT_MIME_TYPE if it is
-        not specified and cannot be guessed.
+        Set the mimetype to DEFAULT_ATTACHMENT_MIME_TYPE if it isn't specified
+        and cannot be guessed.
 
-        For a text/* mimetype (guessed or specified), the file's content
-        will be decoded as UTF-8. If that fails, the mimetype will be set to
-        DEFAULT_ATTACHMENT_MIME_TYPE and the content is not decoded.
+        For a text/* mimetype (guessed or specified), decode the file's content
+        as UTF-8. If that fails, set the mimetype to
+        DEFAULT_ATTACHMENT_MIME_TYPE and don't decode the content.
         """
         filename = os.path.basename(path)
 
@@ -366,7 +363,7 @@ class EmailMessage:
 
     def _create_mime_attachment(self, content, mimetype):
         """
-        Converts the content, mimetype pair into a MIME attachment object.
+        Convert the content, mimetype pair into a MIME attachment object.
 
         If the mimetype is message/rfc822, content may be an
         email.Message or EmailMessage object, as well as a str.
@@ -396,7 +393,7 @@ class EmailMessage:
 
     def _create_attachment(self, filename, content, mimetype=None):
         """
-        Converts the filename, content, mimetype triple into a MIME attachment
+        Convert the filename, content, mimetype triple into a MIME attachment
         object.
         """
         attachment = self._create_mime_attachment(content, mimetype)
diff --git a/django/core/management/__init__.py b/django/core/management/__init__.py
index d5295680ab..b4782172d2 100644
--- a/django/core/management/__init__.py
+++ b/django/core/management/__init__.py
@@ -19,10 +19,8 @@ from django.utils.encoding import force_text
 
 def find_commands(management_dir):
     """
-    Given a path to a management directory, returns a list of all the command
+    Given a path to a management directory, return a list of all the command
     names that are available.
-
-    Returns an empty list if no commands are defined.
     """
     command_dir = os.path.join(management_dir, 'commands')
     return [name for _, name, is_pkg in pkgutil.iter_modules([command_dir])
@@ -31,9 +29,9 @@ def find_commands(management_dir):
 
 def load_command_class(app_name, name):
     """
-    Given a command name and an application name, returns the Command
-    class instance. All errors raised by the import process
-    (ImportError, AttributeError) are allowed to propagate.
+    Given a command name and an application name, return the Command
+    class instance. Allow all errors raised by the import process
+    (ImportError, AttributeError) to propagate.
     """
     module = import_module('%s.management.commands.%s' % (app_name, name))
     return module.Command()
@@ -42,14 +40,14 @@ def load_command_class(app_name, name):
 @functools.lru_cache(maxsize=None)
 def get_commands():
     """
-    Returns a dictionary mapping command names to their callback applications.
+    Return a dictionary mapping command names to their callback applications.
 
-    This works by looking for a management.commands package in django.core, and
-    in each installed application -- if a commands package exists, all commands
-    in that package are registered.
+    Look for a management.commands package in django.core, and in each
+    installed application -- if a commands package exists, register all
+    commands in that package.
 
     Core commands are always included. If a settings module has been
-    specified, user-defined commands will also be included.
+    specified, also include user-defined commands.
 
     The dictionary is in the format {command_name: app_name}. Key-value
     pairs from this dictionary can then be used in calls to
@@ -76,7 +74,7 @@ def get_commands():
 
 def call_command(command_name, *args, **options):
     """
-    Calls the given command, with the given options and args/kwargs.
+    Call the given command, with the given options and args/kwargs.
 
     This is the primary API you should use for calling specific commands.
 
@@ -130,7 +128,7 @@ def call_command(command_name, *args, **options):
 
 class ManagementUtility:
     """
-    Encapsulates the logic of the django-admin and manage.py utilities.
+    Encapsulate the logic of the django-admin and manage.py utilities.
     """
     def __init__(self, argv=None):
         self.argv = argv or sys.argv[:]
@@ -138,9 +136,7 @@ class ManagementUtility:
         self.settings_exception = None
 
     def main_help_text(self, commands_only=False):
-        """
-        Returns the script's main help text, as a string.
-        """
+        """Return the script's main help text, as a string."""
         if commands_only:
             usage = sorted(get_commands().keys())
         else:
@@ -174,7 +170,7 @@ class ManagementUtility:
 
     def fetch_command(self, subcommand):
         """
-        Tries to fetch the given subcommand, printing a message with the
+        Try to fetch the given subcommand, printing a message with the
         appropriate command called from the command line (usually
         "django-admin" or "manage.py") if it can't be found.
         """
@@ -280,8 +276,8 @@ class ManagementUtility:
 
     def execute(self):
         """
-        Given the command-line arguments, this figures out which subcommand is
-        being run, creates a parser appropriate to that command, and runs it.
+        Given the command-line arguments, figure out which subcommand is being
+        run, create a parser appropriate to that command, and run it.
         """
         try:
             subcommand = self.argv[1]
@@ -354,8 +350,6 @@ class ManagementUtility:
 
 
 def execute_from_command_line(argv=None):
-    """
-    A simple method that runs a ManagementUtility.
-    """
+    """Run a ManagementUtility."""
     utility = ManagementUtility(argv)
     utility.execute()
diff --git a/django/core/management/base.py b/django/core/management/base.py
index b0f454381a..6300b0c0bf 100644
--- a/django/core/management/base.py
+++ b/django/core/management/base.py
@@ -345,10 +345,10 @@ class BaseCommand:
     def check(self, app_configs=None, tags=None, display_num_errors=False,
               include_deployment_checks=False, fail_level=checks.ERROR):
         """
-        Uses the system check framework to validate entire Django project.
-        Raises CommandError for any serious message (error or critical errors).
-        If there are only light messages (like warnings), they are printed to
-        stderr and no exception is raised.
+        Use the system check framework to validate entire Django project.
+        Raise CommandError for any serious message (error or critical errors).
+        If there are only light messages (like warnings), print them to stderr
+        and don't raise an exception.
         """
         all_issues = self._run_checks(
             app_configs=app_configs,
diff --git a/django/core/management/color.py b/django/core/management/color.py
index 4519d29025..e04c94fed1 100644
--- a/django/core/management/color.py
+++ b/django/core/management/color.py
@@ -11,7 +11,7 @@ from django.utils import termcolors
 
 def supports_color():
     """
-    Returns True if the running system's terminal supports color,
+    Return True if the running system's terminal supports color,
     and False otherwise.
     """
     plat = sys.platform
@@ -61,14 +61,14 @@ def make_style(config_string=''):
 @functools.lru_cache(maxsize=None)
 def no_style():
     """
-    Returns a Style object with no color scheme.
+    Return a Style object with no color scheme.
     """
     return make_style('nocolor')
 
 
 def color_style():
     """
-    Returns a Style object from the Django color scheme.
+    Return a Style object from the Django color scheme.
     """
     if not supports_color():
         return no_style()
diff --git a/django/core/management/commands/diffsettings.py b/django/core/management/commands/diffsettings.py
index 3a5ebcf845..c8bb7cb352 100644
--- a/django/core/management/commands/diffsettings.py
+++ b/django/core/management/commands/diffsettings.py
@@ -2,7 +2,7 @@ from django.core.management.base import BaseCommand
 
 
 def module_to_dict(module, omittable=lambda k: k.startswith('_')):
-    """Converts a module namespace to a Python dictionary."""
+    """Convert a module namespace to a Python dictionary."""
     return {k: repr(v) for k, v in module.__dict__.items() if not omittable(k)}
 
 
diff --git a/django/core/management/commands/loaddata.py b/django/core/management/commands/loaddata.py
index 4556d9b9d8..1b685e8767 100644
--- a/django/core/management/commands/loaddata.py
+++ b/django/core/management/commands/loaddata.py
@@ -137,9 +137,7 @@ class Command(BaseCommand):
                 )
 
     def load_label(self, fixture_label):
-        """
-        Loads fixtures files for a given label.
-        """
+        """Load fixtures files for a given label."""
         show_progress = self.verbosity >= 3
         for fixture_file, fixture_dir, fixture_name in self.find_fixtures(fixture_label):
             _, ser_fmt, cmp_fmt = self.parse_name(os.path.basename(fixture_file))
@@ -203,9 +201,7 @@ class Command(BaseCommand):
 
     @functools.lru_cache(maxsize=None)
     def find_fixtures(self, fixture_label):
-        """
-        Finds fixture files for a given label.
-        """
+        """Find fixture files for a given label."""
         fixture_name, ser_fmt, cmp_fmt = self.parse_name(fixture_label)
         databases = [self.using, None]
         cmp_fmts = list(self.compression_formats.keys()) if cmp_fmt is None else [cmp_fmt]
@@ -291,7 +287,7 @@ class Command(BaseCommand):
 
     def parse_name(self, fixture_name):
         """
-        Splits fixture name in name, serialization format, compression format.
+        Split fixture name in name, serialization format, compression format.
         """
         parts = fixture_name.rsplit('.', 2)
 
diff --git a/django/core/management/commands/makemessages.py b/django/core/management/commands/makemessages.py
index fd2cb7eaa6..17b1f05d5a 100644
--- a/django/core/management/commands/makemessages.py
+++ b/django/core/management/commands/makemessages.py
@@ -60,7 +60,7 @@ class TranslatableFile:
 
 class BuildFile:
     """
-    Represents the state of a translatable file during the build process.
+    Represent the state of a translatable file during the build process.
     """
     def __init__(self, command, domain, translatable):
         self.command = command
@@ -170,8 +170,8 @@ def normalize_eols(raw_contents):
 
 def write_pot_file(potfile, msgs):
     """
-    Write the :param potfile: POT file with the :param msgs: contents,
-    previously making sure its format is valid.
+    Write the `potfile` with the `msgs` contents, making sure its format is
+    valid.
     """
     pot_lines = msgs.splitlines()
     if os.path.exists(potfile):
@@ -423,10 +423,9 @@ class Command(BaseCommand):
 
     def find_files(self, root):
         """
-        Helper method to get all files in the given root. Also check that there
-        is a matching locale dir for each file.
+        Get all files in the given root. Also check that there is a matching
+        locale dir for each file.
         """
-
         def is_ignored(path, ignore_patterns):
             """
             Check if the given path should be ignored or not.
@@ -499,7 +498,7 @@ class Command(BaseCommand):
         Extract translatable literals from the specified files, creating or
         updating the POT file for a given locale directory.
 
-        Uses the xgettext GNU gettext utility.
+        Use the xgettext GNU gettext utility.
         """
         build_files = []
         for translatable in files:
@@ -591,10 +590,10 @@ class Command(BaseCommand):
 
     def write_po_file(self, potfile, locale):
         """
-        Creates or updates the PO file for self.domain and :param locale:.
-        Uses contents of the existing :param potfile:.
+        Create or update the PO file for self.domain and `locale`.
+        Use contents of the existing `potfile`.
 
-        Uses msgmerge, and msgattrib GNU gettext utilities.
+        Use msgmerge and msgattrib GNU gettext utilities.
         """
         basedir = os.path.join(os.path.dirname(potfile), locale, 'LC_MESSAGES')
         if not os.path.isdir(basedir):
@@ -633,7 +632,7 @@ class Command(BaseCommand):
 
     def copy_plural_forms(self, msgs, locale):
         """
-        Copies plural forms header contents from a Django catalog of locale to
+        Copy plural forms header contents from a Django catalog of locale to
         the msgs string, inserting it at the right place. msgs should be the
         contents of a newly created .po file.
         """
diff --git a/django/core/management/commands/makemigrations.py b/django/core/management/commands/makemigrations.py
index 8572bbeb95..baa335c984 100644
--- a/django/core/management/commands/makemigrations.py
+++ b/django/core/management/commands/makemigrations.py
@@ -176,7 +176,7 @@ class Command(BaseCommand):
 
     def write_migration_files(self, changes):
         """
-        Takes a changes dict and writes them out as migration files.
+        Take a changes dict and write them out as migration files.
         """
         directory_created = {}
         for app_label, app_migrations in changes.items():
diff --git a/django/core/management/commands/runserver.py b/django/core/management/commands/runserver.py
index cc47b14ca2..0ef6b5c4ac 100644
--- a/django/core/management/commands/runserver.py
+++ b/django/core/management/commands/runserver.py
@@ -62,9 +62,7 @@ class Command(BaseCommand):
         super().execute(*args, **options)
 
     def get_handler(self, *args, **options):
-        """
-        Returns the default WSGI handler for the runner.
-        """
+        """Return the default WSGI handler for the runner."""
         return get_internal_wsgi_application()
 
     def handle(self, *args, **options):
@@ -101,9 +99,7 @@ class Command(BaseCommand):
         self.run(**options)
 
     def run(self, **options):
-        """
-        Runs the server, using the autoreloader if needed
-        """
+        """Run the server, using the autoreloader if needed."""
         use_reloader = options['use_reloader']
 
         if use_reloader:
diff --git a/django/core/management/commands/showmigrations.py b/django/core/management/commands/showmigrations.py
index 1e20ec1745..4130d44389 100644
--- a/django/core/management/commands/showmigrations.py
+++ b/django/core/management/commands/showmigrations.py
@@ -54,7 +54,7 @@ class Command(BaseCommand):
 
     def show_list(self, connection, app_names=None):
         """
-        Shows a list of all migrations on the system, or only those of
+        Show a list of all migrations on the system, or only those of
         some named apps.
         """
         # Load migrations from disk/DB
@@ -90,7 +90,7 @@ class Command(BaseCommand):
 
     def show_plan(self, connection, app_names=None):
         """
-        Shows all known migrations (or only those of the specified app_names)
+        Show all known migrations (or only those of the specified app_names)
         in the order they will be applied.
         """
         # Load migrations from disk/DB
diff --git a/django/core/management/sql.py b/django/core/management/sql.py
index 3783025900..44b57b386a 100644
--- a/django/core/management/sql.py
+++ b/django/core/management/sql.py
@@ -4,10 +4,10 @@ from django.db import models
 
 def sql_flush(style, connection, only_django=False, reset_sequences=True, allow_cascade=False):
     """
-    Returns a list of the SQL statements used to flush the database.
+    Return a list of the SQL statements used to flush the database.
 
-    If only_django is True, then only table names that have associated Django
-    models and are in INSTALLED_APPS will be included.
+    If only_django is True, only include the table names that have associated
+    Django models and are in INSTALLED_APPS .
     """
     if only_django:
         tables = connection.introspection.django_table_names(only_existing=True, include_views=False)
diff --git a/django/core/management/templates.py b/django/core/management/templates.py
index 772f20b93f..3aecd10a42 100644
--- a/django/core/management/templates.py
+++ b/django/core/management/templates.py
@@ -24,7 +24,7 @@ _url_drive_re = re.compile('^([a-z])[:|]', re.I)
 
 class TemplateCommand(BaseCommand):
     """
-    Copies either a Django application layout template or a Django project
+    Copy either a Django application layout template or a Django project
     layout template into the specified directory.
 
     :param style: A color style object (see django.core.management.color).
@@ -185,9 +185,9 @@ class TemplateCommand(BaseCommand):
 
     def handle_template(self, template, subdir):
         """
-        Determines where the app or project templates are.
-        Use django.__path__[0] as the default because we don't
-        know into which directory Django has been installed.
+        Determine where the app or project templates are.
+        Use django.__path__[0] as the default because the Django install
+        directory isn't known.
         """
         if template is None:
             return path.join(django.__path__[0], 'conf', subdir)
@@ -222,7 +222,7 @@ class TemplateCommand(BaseCommand):
 
     def download(self, url):
         """
-        Downloads the given URL and returns the file name.
+        Download the given URL and return the file name.
         """
         def cleanup_url(url):
             tmp = url.rstrip('/')
@@ -286,7 +286,7 @@ class TemplateCommand(BaseCommand):
 
     def extract(self, filename):
         """
-        Extracts the given file to a temporarily and returns
+        Extract the given file to a temporarily and return
         the path of the directory with the extracted content.
         """
         prefix = 'django_%s_template_' % self.app_or_project
@@ -302,9 +302,7 @@ class TemplateCommand(BaseCommand):
                                (filename, tempdir, e))
 
     def is_url(self, template):
-        """
-        Returns True if the name looks like a URL
-        """
+        """Return True if the name looks like a URL."""
         if ':' not in template:
             return False
         scheme = template.split(':', 1)[0].lower()
diff --git a/django/core/management/utils.py b/django/core/management/utils.py
index 5903e53341..a4ac6fad58 100644
--- a/django/core/management/utils.py
+++ b/django/core/management/utils.py
@@ -12,7 +12,7 @@ def popen_wrapper(args, os_err_exc_type=CommandError, stdout_encoding='utf-8'):
     """
     Friendly wrapper around Popen.
 
-    Returns stdout output, stderr output and OS status code.
+    Return stdout output, stderr output, and OS status code.
     """
     try:
         p = Popen(args, shell=False, stdout=PIPE, stderr=PIPE, close_fds=os.name != 'nt')
@@ -28,7 +28,7 @@ def popen_wrapper(args, os_err_exc_type=CommandError, stdout_encoding='utf-8'):
 
 def handle_extensions(extensions):
     """
-    Organizes multiple extensions that are separated with commas or passed by
+    Organize multiple extensions that are separated with commas or passed by
     using --extension/-e multiple times.
 
     For example: running 'django-admin makemessages -e js,txt -e xhtml -a'
diff --git a/django/core/paginator.py b/django/core/paginator.py
index e0e78bf020..85d88eb180 100644
--- a/django/core/paginator.py
+++ b/django/core/paginator.py
@@ -33,9 +33,7 @@ class Paginator:
         self.allow_empty_first_page = allow_empty_first_page
 
     def validate_number(self, number):
-        """
-        Validates the given 1-based page number.
-        """
+        """Validate the given 1-based page number."""
         try:
             number = int(number)
         except (TypeError, ValueError):
@@ -50,9 +48,7 @@ class Paginator:
         return number
 
     def page(self, number):
-        """
-        Returns a Page object for the given 1-based page number.
-        """
+        """Return a Page object for the given 1-based page number."""
         number = self.validate_number(number)
         bottom = (number - 1) * self.per_page
         top = bottom + self.per_page
@@ -62,7 +58,7 @@ class Paginator:
 
     def _get_page(self, *args, **kwargs):
         """
-        Returns an instance of a single page.
+        Return an instance of a single page.
 
         This hook can be used by subclasses to use an alternative to the
         standard :cls:`Page` object.
@@ -71,9 +67,7 @@ class Paginator:
 
     @cached_property
     def count(self):
-        """
-        Returns the total number of objects, across all pages.
-        """
+        """Return the total number of objects, across all pages."""
         try:
             return self.object_list.count()
         except (AttributeError, TypeError):
@@ -84,9 +78,7 @@ class Paginator:
 
     @cached_property
     def num_pages(self):
-        """
-        Returns the total number of pages.
-        """
+        """Return the total number of pages."""
         if self.count == 0 and not self.allow_empty_first_page:
             return 0
         hits = max(1, self.count - self.orphans)
@@ -95,7 +87,7 @@ class Paginator:
     @property
     def page_range(self):
         """
-        Returns a 1-based range of pages for iterating through within
+        Return a 1-based range of pages for iterating through within
         a template for loop.
         """
         return range(1, self.num_pages + 1)
@@ -154,7 +146,7 @@ class Page(collections.Sequence):
 
     def start_index(self):
         """
-        Returns the 1-based index of the first object on this page,
+        Return the 1-based index of the first object on this page,
         relative to total objects in the paginator.
         """
         # Special case, return zero if no items.
@@ -164,7 +156,7 @@ class Page(collections.Sequence):
 
     def end_index(self):
         """
-        Returns the 1-based index of the last object on this page,
+        Return the 1-based index of the last object on this page,
         relative to total objects found (hits).
         """
         # Special case for the last page because there can be orphans.
diff --git a/django/core/serializers/__init__.py b/django/core/serializers/__init__.py
index 3d0ed9a13f..666d1bb297 100644
--- a/django/core/serializers/__init__.py
+++ b/django/core/serializers/__init__.py
@@ -131,7 +131,7 @@ def serialize(format, queryset, **options):
 
 def deserialize(format, stream_or_string, **options):
     """
-    Deserialize a stream or a string. Returns an iterator that yields ``(obj,
+    Deserialize a stream or a string. Return an iterator that yields ``(obj,
     m2m_relation_dict)``, where ``obj`` is an instantiated -- but *unsaved* --
     object, and ``m2m_relation_dict`` is a dictionary of ``{m2m_field_name :
     list_of_related_objects}``.
diff --git a/django/core/serializers/json.py b/django/core/serializers/json.py
index a948d87856..31f065a831 100644
--- a/django/core/serializers/json.py
+++ b/django/core/serializers/json.py
@@ -17,9 +17,7 @@ from django.utils.timezone import is_aware
 
 
 class Serializer(PythonSerializer):
-    """
-    Convert a queryset to JSON.
-    """
+    """Convert a queryset to JSON."""
     internal_use_only = False
 
     def _init_options(self):
@@ -64,9 +62,7 @@ class Serializer(PythonSerializer):
 
 
 def Deserializer(stream_or_string, **options):
-    """
-    Deserialize a stream or string of JSON data.
-    """
+    """Deserialize a stream or string of JSON data."""
     if not isinstance(stream_or_string, (bytes, str)):
         stream_or_string = stream_or_string.read()
     if isinstance(stream_or_string, bytes):
@@ -83,7 +79,8 @@ def Deserializer(stream_or_string, **options):
 
 class DjangoJSONEncoder(json.JSONEncoder):
     """
-    JSONEncoder subclass that knows how to encode date/time, decimal types and UUIDs.
+    JSONEncoder subclass that knows how to encode date/time, decimal types, and
+    UUIDs.
     """
     def default(self, o):
         # See "Date Time String Format" in the ECMA-262 specification.
diff --git a/django/core/serializers/python.py b/django/core/serializers/python.py
index a299ed62c8..80c8bfe1d2 100644
--- a/django/core/serializers/python.py
+++ b/django/core/serializers/python.py
@@ -14,7 +14,7 @@ from django.utils.encoding import force_text, is_protected_type
 
 class Serializer(base.Serializer):
     """
-    Serializes a QuerySet to basic Python objects.
+    Serialize a QuerySet to basic Python objects.
     """
 
     internal_use_only = True
@@ -180,9 +180,7 @@ def Deserializer(object_list, *, using=DEFAULT_DB_ALIAS, ignorenonexistent=False
 
 
 def _get_model(model_identifier):
-    """
-    Helper to look up a model from an "app_label.model_name" string.
-    """
+    """Look up a model from an "app_label.model_name" string."""
     try:
         return apps.get_model(model_identifier)
     except (LookupError, TypeError):
diff --git a/django/core/serializers/pyyaml.py b/django/core/serializers/pyyaml.py
index 991ffa4f1e..b65c9ec3a8 100644
--- a/django/core/serializers/pyyaml.py
+++ b/django/core/serializers/pyyaml.py
@@ -37,9 +37,7 @@ DjangoSafeDumper.add_representer(collections.OrderedDict, DjangoSafeDumper.repre
 
 
 class Serializer(PythonSerializer):
-    """
-    Convert a queryset to YAML.
-    """
+    """Convert a queryset to YAML."""
 
     internal_use_only = False
 
@@ -64,9 +62,7 @@ class Serializer(PythonSerializer):
 
 
 def Deserializer(stream_or_string, **options):
-    """
-    Deserialize a stream or string of YAML data.
-    """
+    """Deserialize a stream or string of YAML data."""
     if isinstance(stream_or_string, bytes):
         stream_or_string = stream_or_string.decode()
     if isinstance(stream_or_string, str):
diff --git a/django/core/serializers/xml_serializer.py b/django/core/serializers/xml_serializer.py
index 7e64952074..cf860d1d24 100644
--- a/django/core/serializers/xml_serializer.py
+++ b/django/core/serializers/xml_serializer.py
@@ -18,9 +18,7 @@ from django.utils.xmlutils import (
 
 
 class Serializer(base.Serializer):
-    """
-    Serializes a QuerySet to XML.
-    """
+    """Serialize a QuerySet to XML."""
 
     def indent(self, level):
         if self.options.get('indent') is not None:
@@ -67,8 +65,8 @@ class Serializer(base.Serializer):
 
     def handle_field(self, obj, field):
         """
-        Called to handle each field on an object (except for ForeignKeys and
-        ManyToManyFields)
+        Handle each field on an object (except for ForeignKeys and
+        ManyToManyFields).
         """
         self.indent(2)
         self.xml.startElement("field", OrderedDict([
@@ -90,7 +88,7 @@ class Serializer(base.Serializer):
 
     def handle_fk_field(self, obj, field):
         """
-        Called to handle a ForeignKey (we need to treat them slightly
+        Handle a ForeignKey (they need to be treated slightly
         differently from regular fields).
         """
         self._start_relational_field(field)
@@ -113,9 +111,9 @@ class Serializer(base.Serializer):
 
     def handle_m2m_field(self, obj, field):
         """
-        Called to handle a ManyToManyField. Related objects are only
-        serialized as references to the object's PK (i.e. the related *data*
-        is not dumped, just the relation).
+        Handle a ManyToManyField. Related objects are only serialized as
+        references to the object's PK (i.e. the related *data* is not dumped,
+        just the relation).
         """
         if field.remote_field.through._meta.auto_created:
             self._start_relational_field(field)
@@ -141,9 +139,7 @@ class Serializer(base.Serializer):
             self.xml.endElement("field")
 
     def _start_relational_field(self, field):
-        """
-        Helper to output the <field> element for relational fields
-        """
+        """Output the <field> element for relational fields."""
         self.indent(2)
         self.xml.startElement("field", OrderedDict([
             ("name", field.name),
@@ -153,9 +149,7 @@ class Serializer(base.Serializer):
 
 
 class Deserializer(base.Deserializer):
-    """
-    Deserialize XML.
-    """
+    """Deserialize XML."""
 
     def __init__(self, stream_or_string, *, using=DEFAULT_DB_ALIAS, ignorenonexistent=False, **options):
         super().__init__(stream_or_string, **options)
@@ -175,9 +169,7 @@ class Deserializer(base.Deserializer):
         raise StopIteration
 
     def _handle_object(self, node):
-        """
-        Convert an <object> node to a DeserializedObject.
-        """
+        """Convert an <object> node to a DeserializedObject."""
         # Look up the model using the model loading mechanism. If this fails,
         # bail.
         Model = self._get_model_from_node(node, "model")
@@ -278,8 +270,8 @@ class Deserializer(base.Deserializer):
 
     def _get_model_from_node(self, node, attr):
         """
-        Helper to look up a model from a <object model=...> or a <field
-        rel=... to=...> node.
+        Look up a model from a <object model=...> or a <field rel=... to=...>
+        node.
         """
         model_identifier = node.getAttribute(attr)
         if not model_identifier:
@@ -295,9 +287,7 @@ class Deserializer(base.Deserializer):
 
 
 def getInnerText(node):
-    """
-    Get all the inner text of a DOM node (recursively).
-    """
+    """Get all the inner text of a DOM node (recursively)."""
     # inspired by http://mail.python.org/pipermail/xml-sig/2005-March/011022.html
     inner_text = []
     for child in node.childNodes:
@@ -317,7 +307,7 @@ class DefusedExpatParser(_ExpatParser):
     """
     An expat parser hardened against XML bomb attacks.
 
-    Forbids DTDs, external entity references
+    Forbid DTDs, external entity references
     """
     def __init__(self, *args, **kwargs):
         _ExpatParser.__init__(self, *args, **kwargs)
diff --git a/django/core/servers/basehttp.py b/django/core/servers/basehttp.py
index 111b5818cd..8ef39e98fc 100644
--- a/django/core/servers/basehttp.py
+++ b/django/core/servers/basehttp.py
@@ -24,7 +24,7 @@ logger = logging.getLogger('django.server')
 
 def get_internal_wsgi_application():
     """
-    Loads and returns the WSGI application as configured by the user in
+    Load and return the WSGI application as configured by the user in
     ``settings.WSGI_APPLICATION``. With the default ``startproject`` layout,
     this will be the ``application`` object in ``projectname/wsgi.py``.
 
@@ -32,7 +32,7 @@ def get_internal_wsgi_application():
     for Django's internal server (runserver); external WSGI servers should just
     be configured to point to the correct application object directly.
 
-    If settings.WSGI_APPLICATION is not set (is ``None``), we just return
+    If settings.WSGI_APPLICATION is not set (is ``None``), return
     whatever ``django.core.wsgi.get_wsgi_application`` returns.
     """
     from django.conf import settings
diff --git a/django/core/signing.py b/django/core/signing.py
index 2ab3ae89cf..f9ee60dae8 100644
--- a/django/core/signing.py
+++ b/django/core/signing.py
@@ -50,16 +50,12 @@ _SEP_UNSAFE = re.compile(r'^[A-z0-9-_=]*$')
 
 
 class BadSignature(Exception):
-    """
-    Signature does not match
-    """
+    """Signature does not match."""
     pass
 
 
 class SignatureExpired(BadSignature):
-    """
-    Signature timestamp is older than required max_age
-    """
+    """Signature timestamp is older than required max_age."""
     pass
 
 
@@ -96,11 +92,11 @@ class JSONSerializer:
 
 def dumps(obj, key=None, salt='django.core.signing', serializer=JSONSerializer, compress=False):
     """
-    Returns URL-safe, sha1 signed base64 compressed JSON string. If key is
-    None, settings.SECRET_KEY is used instead.
+    Return URL-safe, sha1 signed base64 compressed JSON string. If key is
+    None, use settings.SECRET_KEY instead.
 
-    If compress is True (not the default) checks if compressing using zlib can
-    save some space. Prepends a '.' to signify compression. This is included
+    If compress is True (not the default), check if compressing using zlib can
+    save some space. Prepend a '.' to signify compression. This is included
     in the signature, to protect against zip bombs.
 
     Salt can be used to namespace the hash, so that a signed string is
@@ -129,7 +125,7 @@ def dumps(obj, key=None, salt='django.core.signing', serializer=JSONSerializer,
 
 def loads(s, key=None, salt='django.core.signing', serializer=JSONSerializer, max_age=None):
     """
-    Reverse of dumps(), raises BadSignature if signature fails.
+    Reverse of dumps(), raise BadSignature if signature fails.
 
     The serializer is expected to accept a bytestring.
     """
diff --git a/django/core/validators.py b/django/core/validators.py
index 44db6c00f0..f55918c8ba 100644
--- a/django/core/validators.py
+++ b/django/core/validators.py
@@ -52,8 +52,8 @@ class RegexValidator:
 
     def __call__(self, value):
         """
-        Validates that the input matches the regular expression
-        if inverse_match is False, otherwise raises ValidationError.
+        Validate that the input matches the regular expression
+        if inverse_match is False, otherwise raise ValidationError.
         """
         if not (self.inverse_match is not bool(self.regex.search(
                 force_text(value)))):
@@ -280,10 +280,8 @@ ip_address_validator_map = {
 
 def ip_address_validators(protocol, unpack_ipv4):
     """
-    Depending on the given parameters returns the appropriate validators for
+    Depending on the given parameters, return the appropriate validators for
     the GenericIPAddressField.
-
-    This code is here, because it is exactly the same for the model and the form field.
     """
     if protocol != 'both' and unpack_ipv4:
         raise ValueError(
diff --git a/django/core/wsgi.py b/django/core/wsgi.py
index e0ded3db54..35e0fa8e80 100644
--- a/django/core/wsgi.py
+++ b/django/core/wsgi.py
@@ -4,11 +4,10 @@ from django.core.handlers.wsgi import WSGIHandler
 
 def get_wsgi_application():
     """
-    The public interface to Django's WSGI support. Should return a WSGI
-    callable.
+    The public interface to Django's WSGI support. Return a WSGI callable.
 
-    Allows us to avoid making django.core.handlers.WSGIHandler public API, in
-    case the internal WSGI implementation changes or moves in the future.
+    Avoids making django.core.handlers.WSGIHandler a public API, in case the
+    internal WSGI implementation changes or moves in the future.
     """
     django.setup(set_prefix=False)
     return WSGIHandler()