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

django/apps/config.py

@@ -8,15 +8,13 @@ MODELS_MODULE_NAME = 'models'
 
 
 class AppConfig:
-    """
-    Class representing a Django application and its configuration.
-    """
+    """Class representing a Django application and its configuration."""
 
     def __init__(self, app_name, app_module):
-        # Full Python path to the application eg. 'django.contrib.admin'.
+        # Full Python path to the application e.g. 'django.contrib.admin'.
         self.name = app_name
 
-        # Root module for the application eg. <module 'django.contrib.admin'
+        # Root module for the application e.g. <module 'django.contrib.admin'
         # from 'django/contrib/admin/__init__.py'>.
         self.module = app_module
 
@@ -27,21 +25,21 @@ class AppConfig:
         # The following attributes could be defined at the class level in a
         # subclass, hence the test-and-set pattern.
 
-        # Last component of the Python path to the application eg. 'admin'.
+        # Last component of the Python path to the application e.g. 'admin'.
         # This value must be unique across a Django project.
         if not hasattr(self, 'label'):
             self.label = app_name.rpartition(".")[2]
 
-        # Human-readable name for the application eg. "Admin".
+        # Human-readable name for the application e.g. "Admin".
         if not hasattr(self, 'verbose_name'):
             self.verbose_name = self.label.title()
 
-        # Filesystem path to the application directory eg.
+        # Filesystem path to the application directory e.g.
         # '/path/to/django/contrib/admin'.
         if not hasattr(self, 'path'):
             self.path = self._path_from_module(app_module)
 
-        # Module containing models eg. <module 'django.contrib.admin.models'
+        # Module containing models e.g. <module 'django.contrib.admin.models'
         # from 'django/contrib/admin/models.py'>. Set by import_models().
         # None if the application doesn't have a models module.
         self.models_module = None
@@ -155,9 +153,9 @@ class AppConfig:
 
     def get_model(self, model_name, require_ready=True):
         """
-        Returns the model with the given case-insensitive model_name.
+        Return the model with the given case-insensitive model_name.
 
-        Raises LookupError if no model exists with this name.
+        Raise LookupError if no model exists with this name.
         """
         if require_ready:
             self.apps.check_models_ready()
@@ -171,7 +169,7 @@ class AppConfig:
 
     def get_models(self, include_auto_created=False, include_swapped=False):
         """
-        Returns an iterable of models.
+        Return an iterable of models.
 
         By default, the following models aren't included:
 

django/apps/registry.py

@@ -14,7 +14,7 @@ class Apps:
     """
     A registry that stores the configuration of installed applications.
 
-    It also keeps track of models eg. to provide reverse-relations.
+    It also keeps track of models, e.g. to provide reverse relations.
     """
 
     def __init__(self, installed_apps=()):
@@ -58,11 +58,11 @@ class Apps:
 
     def populate(self, installed_apps=None):
         """
-        Loads application configurations and models.
+        Load application configurations and models.
 
-        This method imports each application module and then each model module.
+        Import each application module and then each model module.
 
-        It is thread safe and idempotent, but not reentrant.
+        It is thread-safe and idempotent, but not reentrant.
         """
         if self.ready:
             return
@@ -122,31 +122,25 @@ class Apps:
             self.ready = True
 
     def check_apps_ready(self):
-        """
-        Raises an exception if all apps haven't been imported yet.
-        """
+        """Raise an exception if all apps haven't been imported yet."""
         if not self.apps_ready:
             raise AppRegistryNotReady("Apps aren't loaded yet.")
 
     def check_models_ready(self):
-        """
-        Raises an exception if all models haven't been imported yet.
-        """
+        """Raise an exception if all models haven't been imported yet."""
         if not self.models_ready:
             raise AppRegistryNotReady("Models aren't loaded yet.")
 
     def get_app_configs(self):
-        """
-        Imports applications and returns an iterable of app configs.
-        """
+        """Import applications and return an iterable of app configs."""
         self.check_apps_ready()
         return self.app_configs.values()
 
     def get_app_config(self, app_label):
         """
-        Imports applications and returns an app config for the given label.
+        Import applications and returns an app config for the given label.
 
-        Raises LookupError if no application exists with this label.
+        Raise LookupError if no application exists with this label.
         """
         self.check_apps_ready()
         try:
@@ -163,7 +157,7 @@ class Apps:
     @functools.lru_cache(maxsize=None)
     def get_models(self, include_auto_created=False, include_swapped=False):
         """
-        Returns a list of all installed models.
+        Return a list of all installed models.
 
         By default, the following models aren't included:
 
@@ -182,15 +176,14 @@ class Apps:
 
     def get_model(self, app_label, model_name=None, require_ready=True):
         """
-        Returns the model matching the given app_label and model_name.
+        Return the model matching the given app_label and model_name.
 
-        As a shortcut, this function also accepts a single argument in the
-        form <app_label>.<model_name>.
+        As a shortcut, app_label may be in the form <app_label>.<model_name>.
 
         model_name is case-insensitive.
 
-        Raises LookupError if no application exists with this label, or no
-        model exists with this name in the application. Raises ValueError if
+        Raise LookupError if no application exists with this label, or no
+        model exists with this name in the application. Raise ValueError if
         called with a single argument that doesn't contain exactly one dot.
         """
         if require_ready:
@@ -232,9 +225,9 @@ class Apps:
 
     def is_installed(self, app_name):
         """
-        Checks whether an application with this name exists in the registry.
+        Check whether an application with this name exists in the registry.
 
-        app_name is the full name of the app eg. 'django.contrib.admin'.
+        app_name is the full name of the app e.g. 'django.contrib.admin'.
         """
         self.check_apps_ready()
         return any(ac.name == app_name for ac in self.app_configs.values())
@@ -245,8 +238,8 @@ class Apps:
 
         object_name is the dotted Python path to the object.
 
-        Returns the app config for the inner application in case of nesting.
-        Returns None if the object isn't in any registered app config.
+        Return the app config for the inner application in case of nesting.
+        Return None if the object isn't in any registered app config.
         """
         self.check_apps_ready()
         candidates = []
@@ -296,7 +289,7 @@ class Apps:
 
     def set_available_apps(self, available):
         """
-        Restricts the set of installed apps used by get_app_config[s].
+        Restrict the set of installed apps used by get_app_config[s].
 
         available must be an iterable of application names.
 
@@ -304,7 +297,7 @@ class Apps:
 
         Primarily used for performance optimization in TransactionTestCase.
 
-        This method is safe is the sense that it doesn't trigger any imports.
+        This method is safe in the sense that it doesn't trigger any imports.
         """
         available = set(available)
         installed = set(app_config.name for app_config in self.get_app_configs())
@@ -322,15 +315,13 @@ class Apps:
         self.clear_cache()
 
     def unset_available_apps(self):
-        """
-        Cancels a previous call to set_available_apps().
-        """
+        """Cancel a previous call to set_available_apps()."""
         self.app_configs = self.stored_app_configs.pop()
         self.clear_cache()
 
     def set_installed_apps(self, installed):
         """
-        Enables a different set of installed apps for get_app_config[s].
+        Enable a different set of installed apps for get_app_config[s].
 
         installed must be an iterable in the same format as INSTALLED_APPS.
 
@@ -342,7 +333,7 @@ class Apps:
         This method may trigger new imports, which may add new models to the
         registry of all imported models. They will stay in the registry even
         after unset_installed_apps(). Since it isn't possible to replay
-        imports safely (eg. that could lead to registering listeners twice),
+        imports safely (e.g. that could lead to registering listeners twice),
         models are registered when they're imported and never removed.
         """
         if not self.ready:
@@ -354,16 +345,14 @@ class Apps:
         self.populate(installed)
 
     def unset_installed_apps(self):
-        """
-        Cancels a previous call to set_installed_apps().
-        """
+        """Cancel a previous call to set_installed_apps()."""
         self.app_configs = self.stored_app_configs.pop()
         self.apps_ready = self.models_ready = self.ready = True
         self.clear_cache()
 
     def clear_cache(self):
         """
-        Clears all internal caches, for methods that alter the app registry.
+        Clear all internal caches, for methods that alter the app registry.
 
         This is mostly used in tests.
         """
@@ -419,7 +408,7 @@ class Apps:
     def do_pending_operations(self, model):
         """
         Take a newly-prepared model and pass it to each function waiting for
-        it. This is called at the very end of `Apps.register_model()`.
+        it. This is called at the very end of Apps.register_model().
         """
         key = model._meta.app_label, model._meta.model_name
         for function in self._pending_operations.pop(key, []):

django/conf/__init__.py

 """
 Settings and configuration for Django.
 
-Values will be read from the module specified by the DJANGO_SETTINGS_MODULE environment
-variable, and then from django.conf.global_settings; see the global settings file for
-a list of all possible variables.
+Read values from the module specified by the DJANGO_SETTINGS_MODULE environment
+variable, and then from django.conf.global_settings; see the global_settings.py
+for a list of all possible variables.
 """
 
 import importlib
@@ -28,8 +28,8 @@ class LazySettings(LazyObject):
     def _setup(self, name=None):
         """
         Load the settings module pointed to by the environment variable. This
-        is used the first time we need any settings at all, if the user has not
-        previously configured the settings manually.
+        is used the first time settings are needed, if the user hasn't
+        configured settings manually.
         """
         settings_module = os.environ.get(ENVIRONMENT_VARIABLE)
         if not settings_module:
@@ -51,9 +51,7 @@ class LazySettings(LazyObject):
         }
 
     def __getattr__(self, name):
-        """
-        Return the value of a setting and cache it in self.__dict__.
-        """
+        """Return the value of a setting and cache it in self.__dict__."""
         if self._wrapped is empty:
             self._setup(name)
         val = getattr(self._wrapped, name)
@@ -72,9 +70,7 @@ class LazySettings(LazyObject):
         super().__setattr__(name, value)
 
     def __delattr__(self, name):
-        """
-        Delete a setting and clear it from cache if needed.
-        """
+        """Delete a setting and clear it from cache if needed."""
         super().__delattr__(name)
         self.__dict__.pop(name, None)
 
@@ -93,9 +89,7 @@ class LazySettings(LazyObject):
 
     @property
     def configured(self):
-        """
-        Returns True if the settings have already been configured.
-        """
+        """Return True if the settings have already been configured."""
         return self._wrapped is not empty
 
 
@@ -156,9 +150,7 @@ class Settings:
 
 
 class UserSettingsHolder:
-    """
-    Holder for user configured settings.
-    """
+    """Holder for user configured settings."""
     # SETTINGS_MODULE doesn't make much sense in the manually configured
     # (standalone) case.
     SETTINGS_MODULE = None

django/conf/urls/i18n.py

@@ -8,9 +8,8 @@ from django.views.i18n import set_language
 
 def i18n_patterns(*urls, prefix_default_language=True):
     """
-    Adds the language code prefix to every URL pattern within this
-    function. This may only be used in the root URLconf, not in an included
-    URLconf.
+    Add the language code prefix to every URL pattern within this function.
+    This may only be used in the root URLconf, not in an included URLconf.
     """
     if not settings.USE_I18N:
         return list(urls)

django/conf/urls/static.py

@@ -8,7 +8,7 @@ from django.views.static import serve
 
 def static(prefix, view=serve, **kwargs):
     """
-    Helper function to return a URL pattern for serving files in debug mode.
+    Return a URL pattern for serving files in debug mode.
 
     from django.conf import settings
     from django.conf.urls.static import static

django/contrib/sessions/backends/signed_cookies.py

@@ -7,9 +7,9 @@ class SessionStore(SessionBase):
 
     def load(self):
         """
-        We load the data from the key itself instead of fetching from
-        some external data store. Opposite of _get_session_key(),
-        raises BadSignature if signature fails.
+        Load the data from the key itself instead of fetching from some
+        external data store. Opposite of _get_session_key(), raise BadSignature
+        if signature fails.
         """
         try:
             return signing.loads(

django/middleware/cache.py

@@ -72,7 +72,7 @@ class UpdateCacheMiddleware(MiddlewareMixin):
         return hasattr(request, '_cache_update_cache') and request._cache_update_cache
 
     def process_response(self, request, response):
-        """Sets the cache, if needed."""
+        """Set the cache, if needed."""
         if not self._should_update_cache(request, response):
             # We don't need to update the cache, just return.
             return response
@@ -122,7 +122,7 @@ class FetchFromCacheMiddleware(MiddlewareMixin):
 
     def process_request(self, request):
         """
-        Checks whether the page is already cached and returns the cached
+        Check whether the page is already cached and return the cached
         version if available.
         """
         if request.method not in ('GET', 'HEAD'):

django/middleware/clickjacking.py

@@ -11,21 +11,15 @@ from django.utils.deprecation import MiddlewareMixin
 
 class XFrameOptionsMiddleware(MiddlewareMixin):
     """
-    Middleware that sets the X-Frame-Options HTTP header in HTTP responses.
+    Set the X-Frame-Options HTTP header in HTTP responses.
 
-    Does not set the header if it's already set or if the response contains
+    Do not set the header if it's already set or if the response contains
     a xframe_options_exempt value set to True.
 
-    By default, sets the X-Frame-Options header to 'SAMEORIGIN', meaning the
+    By default, set the X-Frame-Options header to 'SAMEORIGIN', meaning the
     response can only be loaded on a frame within the same site. To prevent the
     response from being loaded in a frame in any site, set X_FRAME_OPTIONS in
     your project's Django settings to 'DENY'.
-
-    Note: older browsers will quietly ignore this header, thus other
-    clickjacking protection techniques should be used if protection in those
-    browsers is required.
-
-    https://en.wikipedia.org/wiki/Clickjacking#Server_and_client
     """
     def process_response(self, request, response):
         # Don't set it if it's already in the response
@@ -42,10 +36,8 @@ class XFrameOptionsMiddleware(MiddlewareMixin):
 
     def get_xframe_options_value(self, request, response):
         """
-        Gets the value to set for the X_FRAME_OPTIONS header.
-
-        By default this uses the value from the X_FRAME_OPTIONS Django
-        settings. If not found in settings, defaults to 'SAMEORIGIN'.
+        Get the value to set for the X_FRAME_OPTIONS header. Use the value from
+        the X_FRAME_OPTIONS setting, or 'SAMEORIGIN' if not set.
 
         This method can be overridden if needed, allowing it to vary based on
         the request or response.

django/middleware/common.py

@@ -17,17 +17,16 @@ class CommonMiddleware(MiddlewareMixin):
     """
     "Common" middleware for taking care of some basic operations:
 
-        - Forbids access to User-Agents in settings.DISALLOWED_USER_AGENTS
+        - Forbid access to User-Agents in settings.DISALLOWED_USER_AGENTS
 
         - URL rewriting: Based on the APPEND_SLASH and PREPEND_WWW settings,
-          this middleware appends missing slashes and/or prepends missing
-          "www."s.
+          append missing slashes and/or prepends missing "www."s.
 
             - If APPEND_SLASH is set and the initial URL doesn't end with a
-              slash, and it is not found in urlpatterns, a new URL is formed by
+              slash, and it is not found in urlpatterns, form a new URL by
               appending a slash at the end. If this new URL is found in
-              urlpatterns, then an HTTP-redirect is returned to this new URL;
-              otherwise the initial URL is processed as usual.
+              urlpatterns, return an HTTP redirect to this new URL; otherwise
+              process the initial URL as usual.
 
           This behavior can be customized by subclassing CommonMiddleware and
           overriding the response_redirect_class attribute.
@@ -140,9 +139,7 @@ class CommonMiddleware(MiddlewareMixin):
         return response
 
     def needs_etag(self, response):
-        """
-        Return True if an ETag header should be added to response.
-        """
+        """Return True if an ETag header should be added to response."""
         cache_control_headers = cc_delim_re.split(response.get('Cache-Control', ''))
         return all(header.lower() != 'no-store' for header in cache_control_headers)
 
@@ -150,9 +147,7 @@ class CommonMiddleware(MiddlewareMixin):
 class BrokenLinkEmailsMiddleware(MiddlewareMixin):
 
     def process_response(self, request, response):
-        """
-        Send broken link emails for relevant 404 NOT FOUND responses.
-        """
+        """Send broken link emails for relevant 404 NOT FOUND responses."""
         if response.status_code == 404 and not settings.DEBUG:
             domain = request.get_host()
             path = request.get_full_path()
@@ -173,7 +168,8 @@ class BrokenLinkEmailsMiddleware(MiddlewareMixin):
 
     def is_internal_request(self, domain, referer):
         """
-        Returns True if the referring URL is the same domain as the current request.
+        Return True if the referring URL is the same domain as the current
+        request.
         """
         # Different subdomains are treated as different domains.
         return bool(re.match("^https?://%s/" % re.escape(domain), referer))

django/middleware/csrf.py

@@ -33,9 +33,7 @@ CSRF_SESSION_KEY = '_csrftoken'
 
 
 def _get_failure_view():
-    """
-    Returns the view to be used for CSRF rejections
-    """
+    """Return the view to be used for CSRF rejections."""
     return get_callable(settings.CSRF_FAILURE_VIEW)
 
 
@@ -75,7 +73,7 @@ def _get_new_csrf_token():
 
 def get_token(request):
     """
-    Returns the CSRF token required for a POST form. The token is an
+    Return the CSRF token required for a POST form. The token is an
     alphanumeric value. A new token is created if one is not already set.
 
     A side effect of calling this function is to make the csrf_protect
@@ -94,7 +92,7 @@ def get_token(request):
 
 def rotate_token(request):
     """
-    Changes the CSRF token in use for a request - should be done on login
+    Change the CSRF token in use for a request - should be done on login
     for security purposes.
     """
     request.META.update({
@@ -132,12 +130,11 @@ def _compare_salted_tokens(request_csrf_token, csrf_token):
 
 class CsrfViewMiddleware(MiddlewareMixin):
     """
-    Middleware that requires a present and correct csrfmiddlewaretoken
-    for POST requests that have a CSRF cookie, and sets an outgoing
-    CSRF cookie.
+    Require a present and correct csrfmiddlewaretoken for POST requests that
+    have a CSRF cookie, and set an outgoing CSRF cookie.
 
-    This middleware should be used in conjunction with the csrf_token template
-    tag.
+    This middleware should be used in conjunction with the {% csrf_token %}
+    template tag.
     """
     # The _accept and _reject methods currently only exist for the sake of the
     # requires_csrf_token decorator.

django/middleware/gzip.py

@@ -9,8 +9,8 @@ re_accepts_gzip = re.compile(r'\bgzip\b')
 
 class GZipMiddleware(MiddlewareMixin):
     """
-    This middleware compresses content if the browser allows gzip compression.
-    It sets the Vary header accordingly, so that caches will base their storage
+    Compress content if the browser allows gzip compression.
+    Set the Vary header accordingly, so that caches will base their storage
     on the Accept-Encoding header.
     """
     def process_response(self, request, response):

django/middleware/http.py

@@ -7,10 +7,9 @@ from django.utils.http import parse_http_date_safe
 
 class ConditionalGetMiddleware(MiddlewareMixin):
     """
-    Handles conditional GET operations. If the response has an ETag or
-    Last-Modified header, and the request has If-None-Match or
-    If-Modified-Since, the response is replaced by an HttpNotModified. An ETag
-    header is added if needed.
+    Handle conditional GET operations. If the response has an ETag or
+    Last-Modified header and the request has If-None-Match or If-Modified-Since,
+    replace the response with HttpNotModified. Add an ETag header if needed.
     """
     def process_response(self, request, response):
         # It's too late to prevent an unsafe request with a 412 response, and
@@ -38,8 +37,6 @@ class ConditionalGetMiddleware(MiddlewareMixin):
         return response
 
     def needs_etag(self, response):
-        """
-        Return True if an ETag header should be added to response.
-        """
+        """Return True if an ETag header should be added to response."""
         cache_control_headers = cc_delim_re.split(response.get('Cache-Control', ''))
         return all(header.lower() != 'no-store' for header in cache_control_headers)

django/middleware/locale.py

-"This is the locale selecting middleware that will look at accept headers"
-
 from django.conf import settings
 from django.conf.urls.i18n import is_language_prefix_patterns_used
 from django.http import HttpResponseRedirect
@@ -11,11 +9,9 @@ from django.utils.deprecation import MiddlewareMixin
 
 class LocaleMiddleware(MiddlewareMixin):
     """
-    This is a very simple middleware that parses a request
-    and decides what translation object to install in the current
-    thread context. This allows pages to be dynamically
-    translated to the language the user desires (if the language
-    is available, of course).
+    Parse a request and decide what translation object to install in the
+    current thread context. This allows pages to be dynamically translated to
+    the language the user desires (if the language is available, of course).
     """
     response_redirect_class = HttpResponseRedirect
 

django/shortcuts.py

@@ -17,7 +17,7 @@ from django.utils.functional import Promise
 
 def render_to_response(template_name, context=None, content_type=None, status=None, using=None):
     """
-    Returns a HttpResponse whose content is filled with the result of calling
+    Return a HttpResponse whose content is filled with the result of calling
     django.template.loader.render_to_string() with the passed arguments.
     """
     warnings.warn(
@@ -31,7 +31,7 @@ def render_to_response(template_name, context=None, content_type=None, status=No
 
 def render(request, template_name, context=None, content_type=None, status=None, using=None):
     """
-    Returns a HttpResponse whose content is filled with the result of calling
+    Return a HttpResponse whose content is filled with the result of calling
     django.template.loader.render_to_string() with the passed arguments.
     """
     content = loader.render_to_string(template_name, context, request, using=using)
@@ -40,7 +40,7 @@ def render(request, template_name, context=None, content_type=None, status=None,
 
 def redirect(to, *args, permanent=False, **kwargs):
     """
-    Returns an HttpResponseRedirect to the appropriate URL for the arguments
+    Return an HttpResponseRedirect to the appropriate URL for the arguments
     passed.
 
     The arguments could be:
@@ -74,7 +74,7 @@ def _get_queryset(klass):
 
 def get_object_or_404(klass, *args, **kwargs):
     """
-    Uses get() to return an object, or raises a Http404 exception if the object
+    Use get() to return an object, or raise a Http404 exception if the object
     does not exist.
 
     klass may be a Model, Manager, or QuerySet object. All other passed
@@ -98,7 +98,7 @@ def get_object_or_404(klass, *args, **kwargs):
 
 def get_list_or_404(klass, *args, **kwargs):
     """
-    Uses filter() to return a list of objects, or raise a Http404 exception if
+    Use filter() to return a list of objects, or raise a Http404 exception if
     the list is empty.
 
     klass may be a Model, Manager, or QuerySet object. All other passed

django/test/__init__.py

-"""
-Django Unit Test and Doctest framework.
-"""
+"""Django Unit Test framework."""
 
 from django.test.client import Client, RequestFactory
 from django.test.testcases import (

django/test/html.py

-"""
-Comparing two html documents.
-"""
+"""Compare two HTML documents."""
 
 import re
 
@@ -214,7 +212,7 @@ class Parser(HTMLParser):
 
 def parse_html(html):
     """
-    Takes a string that contains *valid* HTML and turns it into a Python object
+    Take a string that contains *valid* HTML and turn it into a Python object
     structure that can be easily compared against other HTML on semantic
     equivalence. Syntactical differences like which quotation is used on
     arguments will be ignored.

django/test/runner.py

@@ -253,9 +253,7 @@ class RemoteTestRunner:
 
 
 def default_test_processes():
-    """
-    Default number of test processes when using the --parallel option.
-    """
+    """Default number of test processes when using the --parallel option."""
     # The current implementation of the parallel test runner requires
     # multiprocessing to start subprocesses with fork().
     if multiprocessing.get_start_method() != 'fork':
@@ -389,9 +387,7 @@ class ParallelTestSuite(unittest.TestSuite):
 
 
 class DiscoverRunner:
-    """
-    A Django test runner that uses unittest2 test discovery.
-    """
+    """A Django test runner that uses unittest2 test discovery."""
 
     test_suite = unittest.TestSuite
     parallel_test_suite = ParallelTestSuite
@@ -566,9 +562,7 @@ class DiscoverRunner:
         return runner.run(suite)
 
     def teardown_databases(self, old_config, **kwargs):
-        """
-        Destroys all the non-mirror databases.
-        """
+        """Destroy all the non-mirror databases."""
         _teardown_databases(
             old_config,
             verbosity=self.verbosity,
@@ -593,7 +587,7 @@ class DiscoverRunner:
         A list of 'extra' tests may also be provided; these tests
         will be added to the test suite.
 
-        Returns the number of tests that failed.
+        Return the number of tests that failed.
         """
         self.setup_test_environment()
         suite = self.build_suite(test_labels, extra_tests)
@@ -623,15 +617,15 @@ def is_discoverable(label):
 
 def reorder_suite(suite, classes, reverse=False):
     """
-    Reorders a test suite by test type.
+    Reorder a test suite by test type.
 
     `classes` is a sequence of types
 
     All tests of type classes[0] are placed first, then tests of type
     classes[1], etc. Tests with no match in classes are placed last.
 
-    If `reverse` is True, tests within classes are sorted in opposite order,
-    but test classes are not reversed.
+    If `reverse` is True, sort tests within classes in opposite order but
+    don't reverse test classes.
     """
     class_count = len(classes)
     suite_class = type(suite)
@@ -645,7 +639,7 @@ def reorder_suite(suite, classes, reverse=False):
 
 def partition_suite_by_type(suite, classes, bins, reverse=False):
     """
-    Partitions a test suite by test type. Also prevents duplicated tests.
+    Partition a test suite by test type. Also prevent duplicated tests.
 
     classes is a sequence of types
     bins is a sequence of TestSuites, one more than classes
@@ -670,9 +664,7 @@ def partition_suite_by_type(suite, classes, bins, reverse=False):
 
 
 def partition_suite_by_case(suite):
-    """
-    Partitions a test suite by test case, preserving the order of tests.
-    """
+    """Partition a test suite by test case, preserving the order of tests."""
     groups = []
     suite_class = type(suite)
     for test_type, test_group in itertools.groupby(suite, type):

django/test/selenium.py

@@ -73,7 +73,7 @@ class SeleniumTestCase(LiveServerTestCase, metaclass=SeleniumTestCaseBase):
 
     @contextmanager
     def disable_implicit_wait(self):
-        """Context manager that disables the default implicit wait."""
+        """Disable the default implicit wait."""
         self.selenium.implicitly_wait(0)
         try:
             yield

django/test/utils.py

@@ -55,7 +55,8 @@ class Approximate:
 
 
 class ContextList(list):
-    """A wrapper that provides direct key access to context items contained
+    """
+    A wrapper that provides direct key access to context items contained
     in a list of context objects.
     """
     def __getitem__(self, key):
@@ -93,8 +94,8 @@ class ContextList(list):
 
 def instrumented_test_render(self, context):
     """
-    An instrumented Template render method, providing a signal
-    that can be intercepted by the test system Client
+    An instrumented Template render method, providing a signal that can be
+    intercepted by the test Client.
     """
     template_rendered.send(sender=self, template=self, context=context)
     return self.nodelist.render(context)
@@ -157,9 +158,7 @@ def teardown_test_environment():
 
 
 def setup_databases(verbosity, interactive, keepdb=False, debug_sql=False, parallel=0, **kwargs):
-    """
-    Create the test databases.
-    """
+    """Create the test databases."""
     test_databases, mirrored_aliases = get_unique_databases_and_mirrors()
 
     old_names = []
@@ -290,9 +289,7 @@ def get_unique_databases_and_mirrors():
 
 
 def teardown_databases(old_config, verbosity, parallel=0, keepdb=False):
-    """
-    Destroy all the non-mirror databases.
-    """
+    """Destroy all the non-mirror databases."""
     for connection, old_name, destroy in old_config:
         if destroy:
             if parallel > 1:
@@ -387,10 +384,10 @@ class TestContextDecorator:
 
 class override_settings(TestContextDecorator):
     """
-    Acts as either a decorator or a context manager. If it's a decorator it
-    takes a function and returns a wrapped function. If it's a contextmanager
-    it's used with the ``with`` statement. In either event entering/exiting
-    are called before and after, respectively, the function/block is executed.
+    Act as either a decorator or a context manager. If it's a decorator, take a
+    function and return a wrapped function. If it's a contextmanager, use it
+    with the ``with`` statement. In either event, entering/exiting are called
+    before and after, respectively, the function/block is executed.
     """
     def __init__(self, **kwargs):
         self.options = kwargs
@@ -444,7 +441,7 @@ class override_settings(TestContextDecorator):
 
 class modify_settings(override_settings):
     """
-    Like override_settings, but makes it possible to append, prepend or remove
+    Like override_settings, but makes it possible to append, prepend, or remove
     items instead of redefining the entire list.
     """
     def __init__(self, *args, **kwargs):
@@ -492,7 +489,7 @@ class modify_settings(override_settings):
 
 class override_system_checks(TestContextDecorator):
     """
-    Acts as a decorator. Overrides list of registered system checks.
+    Act as a decorator. Override list of registered system checks.
     Useful when you override `INSTALLED_APPS`, e.g. if you exclude `auth` app,
     you also need to exclude its system checks.
     """
@@ -516,10 +513,10 @@ class override_system_checks(TestContextDecorator):
 
 
 def compare_xml(want, got):
-    """Tries to do a 'xml-comparison' of want and got.  Plain string
-    comparison doesn't always work because, for example, attribute
-    ordering should not be important. Comment nodes are not considered in the
-    comparison. Leading and trailing whitespace is ignored on both chunks.
+    """
+    Try to do a 'xml-comparison' of want and got. Plain string comparison
+    doesn't always work because, for example, attribute ordering should not be
+    important. Ignore comment nodes and leading and trailing whitespace.
 
     Based on https://github.com/lxml/lxml/blob/master/src/lxml/doctestcompare.py
     """
@@ -794,9 +791,7 @@ def require_jinja2(test_func):
 
 
 class override_script_prefix(TestContextDecorator):
-    """
-    Decorator or context manager to temporary override the script prefix.
-    """
+    """Decorator or context manager to temporary override the script prefix."""
     def __init__(self, prefix):
         self.prefix = prefix
         super().__init__()
@@ -840,7 +835,6 @@ class isolate_apps(TestContextDecorator):
     `kwarg_name`: keyword argument passing the isolated registry if used as a
                   function decorator.
     """
-
     def __init__(self, *installed_apps, **kwargs):
         self.installed_apps = installed_apps
         super().__init__(**kwargs)
@@ -856,9 +850,7 @@ class isolate_apps(TestContextDecorator):
 
 
 def tag(*tags):
-    """
-    Decorator to add tags to a test class or method.
-    """
+    """Decorator to add tags to a test class or method."""
     def decorator(obj):
         setattr(obj, 'tags', set(tags))
         return obj