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

5 files changed, 143 insertions, 186 deletions

diff --git a/django/db/models/sql/compiler.py b/django/db/models/sql/compiler.py
index 76a595d2b1..3215aaaa9c 100644
--- a/django/db/models/sql/compiler.py
+++ b/django/db/models/sql/compiler.py
@@ -38,7 +38,7 @@ class SQLCompiler:
 
     def pre_sql_setup(self):
         """
-        Does any necessary class setup immediately prior to producing SQL. This
+        Do any necessary class setup immediately prior to producing SQL. This
         is for things that can't necessarily be done in __init__ because we
         might not have all the pieces in place at that time.
         """
@@ -51,7 +51,7 @@ class SQLCompiler:
 
     def get_group_by(self, select, order_by):
         """
-        Returns a list of 2-tuples of form (sql, params).
+        Return a list of 2-tuples of form (sql, params).
 
         The logic of what exactly the GROUP BY clause contains is hard
         to describe in other words than "if it passes the test suite,
@@ -163,7 +163,7 @@ class SQLCompiler:
 
     def get_select(self):
         """
-        Returns three values:
+        Return three values:
         - a list of 3-tuples of (expression, (sql, params), alias)
         - a klass_info structure,
         - a dictionary of annotations
@@ -232,7 +232,7 @@ class SQLCompiler:
 
     def get_order_by(self):
         """
-        Returns a list of 2-tuples of form (expr, (sql, params, is_ref)) for the
+        Return a list of 2-tuples of form (expr, (sql, params, is_ref)) for the
         ORDER BY clause.
 
         The order_by clause can alter the select clause (for example it
@@ -400,7 +400,7 @@ class SQLCompiler:
 
     def as_sql(self, with_limits=True, with_col_aliases=False):
         """
-        Creates the SQL for this query. Returns the SQL string and list of
+        Create the SQL for this query. Return the SQL string and list of
         parameters.
 
         If 'with_limits' is False, any limit/offset information is not included
@@ -513,14 +513,14 @@ class SQLCompiler:
 
     def get_default_columns(self, start_alias=None, opts=None, from_parent=None):
         """
-        Computes the default columns for selecting every field in the base
+        Compute the default columns for selecting every field in the base
         model. Will sometimes be called to pull in related models (e.g. via
         select_related), in which case "opts" and "start_alias" will be given
         to provide a starting point for the traversal.
 
-        Returns a list of strings, quoted appropriately for use in SQL
+        Return a list of strings, quoted appropriately for use in SQL
         directly, as well as a set of aliases used in the select statement (if
-        'as_pairs' is True, returns a list of (alias, col_name) pairs instead
+        'as_pairs' is True, return a list of (alias, col_name) pairs instead
         of strings as the first component and None as the second component).
         """
         result = []
@@ -558,10 +558,10 @@ class SQLCompiler:
 
     def get_distinct(self):
         """
-        Returns a quoted list of fields to use in DISTINCT ON part of the query.
+        Return a quoted list of fields to use in DISTINCT ON part of the query.
 
-        Note that this method can alter the tables in the query, and thus it
-        must be called before get_from_clause().
+        This method can alter the tables in the query, and thus it must be
+        called before get_from_clause().
         """
         qn = self.quote_name_unless_alias
         qn2 = self.connection.ops.quote_name
@@ -582,7 +582,7 @@ class SQLCompiler:
     def find_ordering_name(self, name, opts, alias=None, default_order='ASC',
                            already_seen=None):
         """
-        Returns the table alias (the name might be ambiguous, the alias will
+        Return the table alias (the name might be ambiguous, the alias will
         not be) and column name for ordering by the given 'name' parameter.
         The 'name' is of the form 'field1__field2__...__fieldN'.
         """
@@ -613,11 +613,11 @@ class SQLCompiler:
 
     def _setup_joins(self, pieces, opts, alias):
         """
-        A helper method for get_order_by and get_distinct.
+        Helper method for get_order_by() and get_distinct().
 
-        Note that get_ordering and get_distinct must produce same target
-        columns on same input, as the prefixes of get_ordering and get_distinct
-        must match. Executing SQL where this is not true is an error.
+        get_ordering() and get_distinct() must produce same target columns on
+        same input, as the prefixes of get_ordering() and get_distinct() must
+        match. Executing SQL where this is not true is an error.
         """
         if not alias:
             alias = self.query.get_initial_alias()
@@ -628,14 +628,14 @@ class SQLCompiler:
 
     def get_from_clause(self):
         """
-        Returns a list of strings that are joined together to go after the
+        Return a list of strings that are joined together to go after the
         "FROM" part of the query, as well as a list any extra parameters that
-        need to be included. Sub-classes, can override this to create a
+        need to be included. Subclasses, can override this to create a
         from-clause via a "select".
 
         This should only be called after any SQL construction methods that
-        might change the tables we need. This means the select columns,
-        ordering and distinct must be done first.
+        might change the tables that are needed. This means the select columns,
+        ordering, and distinct must be done first.
         """
         result = []
         params = []
@@ -792,8 +792,8 @@ class SQLCompiler:
 
     def deferred_to_columns(self):
         """
-        Converts the self.deferred_loading data structure to mapping of table
-        names to sets of column names which are to be loaded. Returns the
+        Convert the self.deferred_loading data structure to mapping of table
+        names to sets of column names which are to be loaded. Return the
         dictionary.
         """
         columns = {}
@@ -820,9 +820,7 @@ class SQLCompiler:
         return tuple(row)
 
     def results_iter(self, results=None):
-        """
-        Returns an iterator over the results from executing this query.
-        """
+        """Return an iterator over the results from executing this query."""
         if results is None:
             results = self.execute_sql(MULTI)
         fields = [s[0] for s in self.select[0:self.col_count]]
@@ -845,7 +843,7 @@ class SQLCompiler:
 
     def execute_sql(self, result_type=MULTI, chunked_fetch=False):
         """
-        Run the query against the database and returns the result(s). The
+        Run the query against the database and return the result(s). The
         return value is a single data item if result_type is SINGLE, or an
         iterator over the results if the result_type is MULTI.
 
@@ -933,10 +931,10 @@ class SQLInsertCompiler(SQLCompiler):
     def field_as_sql(self, field, val):
         """
         Take a field and a value intended to be saved on that field, and
-        return placeholder SQL and accompanying params. Checks for raw values,
-        expressions and fields with get_placeholder() defined in that order.
+        return placeholder SQL and accompanying params. Check for raw values,
+        expressions, and fields with get_placeholder() defined in that order.
 
-        When field is None, the value is considered raw and is used as the
+        When field is None, consider the value raw and use it as the
         placeholder, with no corresponding parameters returned.
         """
         if field is None:
@@ -994,9 +992,9 @@ class SQLInsertCompiler(SQLCompiler):
 
     def assemble_as_sql(self, fields, value_rows):
         """
-        Take a sequence of N fields and a sequence of M rows of values,
-        generate placeholder SQL and parameters for each field and value, and
-        return a pair containing:
+        Take a sequence of N fields and a sequence of M rows of values, and
+        generate placeholder SQL and parameters for each field and value.
+        Return a pair containing:
          * a sequence of M rows of N SQL placeholder strings, and
          * a sequence of M rows of corresponding parameter values.
 
@@ -1105,7 +1103,7 @@ class SQLInsertCompiler(SQLCompiler):
 class SQLDeleteCompiler(SQLCompiler):
     def as_sql(self):
         """
-        Creates the SQL for this query. Returns the SQL string and list of
+        Create the SQL for this query. Return the SQL string and list of
         parameters.
         """
         assert len([t for t in self.query.tables if self.query.alias_refcount[t] > 0]) == 1, \
@@ -1121,7 +1119,7 @@ class SQLDeleteCompiler(SQLCompiler):
 class SQLUpdateCompiler(SQLCompiler):
     def as_sql(self):
         """
-        Creates the SQL for this query. Returns the SQL string and list of
+        Create the SQL for this query. Return the SQL string and list of
         parameters.
         """
         self.pre_sql_setup()
@@ -1176,7 +1174,7 @@ class SQLUpdateCompiler(SQLCompiler):
 
     def execute_sql(self, result_type):
         """
-        Execute the specified update. Returns the number of rows affected by
+        Execute the specified update. Return the number of rows affected by
         the primary update query. The "primary update query" is the first
         non-empty query that is executed. Row counts for any subsequent,
         related queries are not available.
@@ -1197,13 +1195,12 @@ class SQLUpdateCompiler(SQLCompiler):
 
     def pre_sql_setup(self):
         """
-        If the update depends on results from other tables, we need to do some
-        munging of the "where" conditions to match the format required for
-        (portable) SQL updates. That is done here.
+        If the update depends on results from other tables, munge the "where"
+        conditions to match the format required for (portable) SQL updates.
 
-        Further, if we are going to be running multiple updates, we pull out
-        the id values to update at this point so that they don't change as a
-        result of the progressive updates.
+        If multiple updates are required, pull out the id values to update at
+        this point so that they don't change as a result of the progressive
+        updates.
         """
         refcounts_before = self.query.alias_refcount.copy()
         # Ensure base table is in the query
@@ -1242,7 +1239,7 @@ class SQLUpdateCompiler(SQLCompiler):
 class SQLAggregateCompiler(SQLCompiler):
     def as_sql(self):
         """
-        Creates the SQL for this query. Returns the SQL string and list of
+        Create the SQL for this query. Return the SQL string and list of
         parameters.
         """
         sql, params = [], []
@@ -1261,7 +1258,7 @@ class SQLAggregateCompiler(SQLCompiler):
 
 def cursor_iter(cursor, sentinel, col_count):
     """
-    Yields blocks of rows from a cursor and ensures the cursor is closed when
+    Yield blocks of rows from a cursor and ensure the cursor is closed when
     done.
     """
     try:
diff --git a/django/db/models/sql/datastructures.py b/django/db/models/sql/datastructures.py
index 81b6cabdc6..788c2dd669 100644
--- a/django/db/models/sql/datastructures.py
+++ b/django/db/models/sql/datastructures.py
@@ -59,7 +59,7 @@ class Join:
 
     def as_sql(self, compiler, connection):
         """
-        Generates the full
+        Generate the full
            LEFT OUTER JOIN sometable ON sometable.somecol = othertable.othercol, params
         clause for this join.
         """
diff --git a/django/db/models/sql/query.py b/django/db/models/sql/query.py
index 9040c5a5a4..7af04e7d77 100644
--- a/django/db/models/sql/query.py
+++ b/django/db/models/sql/query.py
@@ -44,9 +44,7 @@ def get_field_names_from_opts(opts):
 
 
 class RawQuery:
-    """
-    A single raw SQL query
-    """
+    """A single raw SQL query."""
 
     def __init__(self, sql, using, params=None, context=None):
         self.params = params or ()
@@ -112,9 +110,7 @@ class RawQuery:
 
 
 class Query:
-    """
-    A single SQL query.
-    """
+    """A single SQL query."""
 
     alias_prefix = 'T'
     subq_aliases = frozenset([alias_prefix])
@@ -221,7 +217,7 @@ class Query:
 
     def __str__(self):
         """
-        Returns the query as a string of SQL with the parameter values
+        Return the query as a string of SQL with the parameter values
         substituted in (use sql_with_params() to see the unsubstituted string).
 
         Parameter values won't necessarily be quoted correctly, since that is
@@ -232,7 +228,7 @@ class Query:
 
     def sql_with_params(self):
         """
-        Returns the query as an SQL string and the parameters that will be
+        Return the query as an SQL string and the parameters that will be
         substituted into the query.
         """
         return self.get_compiler(DEFAULT_DB_ALIAS).as_sql()
@@ -254,7 +250,7 @@ class Query:
 
     def get_meta(self):
         """
-        Returns the Options instance (the model._meta) from which to start
+        Return the Options instance (the model._meta) from which to start
         processing. Normally, this is self.model._meta, but it can be changed
         by subclasses.
         """
@@ -262,7 +258,7 @@ class Query:
 
     def clone(self, klass=None, memo=None, **kwargs):
         """
-        Creates a copy of the current instance. The 'kwargs' parameter can be
+        Create a copy of the current instance. The 'kwargs' parameter can be
         used by clients to update attributes after copying has taken place.
         """
         obj = Empty()
@@ -395,7 +391,7 @@ class Query:
 
     def get_aggregation(self, using, added_aggregate_names):
         """
-        Returns the dictionary with the values of the existing aggregations.
+        Return the dictionary with the values of the existing aggregations.
         """
         if not self.annotation_select:
             return {}
@@ -488,7 +484,7 @@ class Query:
 
     def get_count(self, using):
         """
-        Performs a COUNT() query using the current filter constraints.
+        Perform a COUNT() query using the current filter constraints.
         """
         obj = self.clone()
         obj.add_annotation(Count('*'), alias='__count', is_summary=True)
@@ -613,7 +609,7 @@ class Query:
 
     def deferred_to_data(self, target, callback):
         """
-        Converts the self.deferred_loading data structure to an alternate data
+        Convert the self.deferred_loading data structure to an alternate data
         structure, describing the field that *will* be loaded. This is used to
         compute the columns to select from the database and also by the
         QuerySet class to work out which fields are being initialized on each
@@ -699,7 +695,7 @@ class Query:
 
     def table_alias(self, table_name, create=False):
         """
-        Returns a table alias for the given table_name and whether this is a
+        Return a table alias for the given table_name and whether this is a
         new alias or not.
 
         If 'create' is true, a new alias is always created. Otherwise, the
@@ -724,17 +720,17 @@ class Query:
         return alias, True
 
     def ref_alias(self, alias):
-        """ Increases the reference count for this alias. """
+        """Increases the reference count for this alias."""
         self.alias_refcount[alias] += 1
 
     def unref_alias(self, alias, amount=1):
-        """ Decreases the reference count for this alias. """
+        """Decreases the reference count for this alias."""
         self.alias_refcount[alias] -= amount
 
     def promote_joins(self, aliases):
         """
-        Promotes recursively the join type of given aliases and its children to
-        an outer join. If 'unconditional' is False, the join is only promoted if
+        Promote recursively the join type of given aliases and its children to
+        an outer join. If 'unconditional' is False, only promote the join if
         it is nullable or the parent join is an outer join.
 
         The children promotion is done to avoid join chains that contain a LOUTER
@@ -786,8 +782,8 @@ class Query:
 
     def reset_refcounts(self, to_counts):
         """
-        This method will reset reference counts for aliases so that they match
-        the value passed in :param to_counts:.
+        Reset reference counts for aliases so that they match the value passed
+        in `to_counts`.
         """
         for alias, cur_refcount in self.alias_refcount.copy().items():
             unref_amount = cur_refcount - to_counts.get(alias, 0)
@@ -795,7 +791,7 @@ class Query:
 
     def change_aliases(self, change_map):
         """
-        Changes the aliases in change_map (which maps old-alias -> new-alias),
+        Change the aliases in change_map (which maps old-alias -> new-alias),
         relabelling any references to them in select columns and the where
         clause.
         """
@@ -831,14 +827,14 @@ class Query:
 
     def bump_prefix(self, outer_query):
         """
-        Changes the alias prefix to the next letter in the alphabet in a way
+        Change the alias prefix to the next letter in the alphabet in a way
         that the outer query's aliases and this query's aliases will not
         conflict. Even tables that previously had no alias will get an alias
         after this call.
         """
         def prefix_gen():
             """
-            Generates a sequence of characters in alphabetical order:
+            Generate a sequence of characters in alphabetical order:
                 -> 'A', 'B', 'C', ...
 
             When the alphabet is finished, the sequence will continue with the
@@ -878,7 +874,7 @@ class Query:
 
     def get_initial_alias(self):
         """
-        Returns the first alias for this query, after increasing its reference
+        Return the first alias for this query, after increasing its reference
         count.
         """
         if self.tables:
@@ -890,15 +886,15 @@ class Query:
 
     def count_active_tables(self):
         """
-        Returns the number of tables in this query with a non-zero reference
-        count. Note that after execution, the reference counts are zeroed, so
-        tables added in compiler will not be seen by this method.
+        Return the number of tables in this query with a non-zero reference
+        count. After execution, the reference counts are zeroed, so tables
+        added in compiler will not be seen by this method.
         """
         return len([1 for count in self.alias_refcount.values() if count])
 
     def join(self, join, reuse=None):
         """
-        Returns an alias for the join in 'connection', either reusing an
+        Return an alias for the join in 'connection', either reusing an
         existing alias for that join or creating a new one. 'connection' is a
         tuple (lhs, table, join_cols) where 'lhs' is either an existing
         table alias or a table name. 'join_cols' is a tuple of tuples containing
@@ -940,7 +936,7 @@ class Query:
 
     def join_parent_model(self, opts, model, alias, seen):
         """
-        Makes sure the given 'model' is joined in the query. If 'model' isn't
+        Make sure the given 'model' is joined in the query. If 'model' isn't
         a parent of 'opts' or if it is None this method is a no-op.
 
         The 'alias' is the root alias for starting the join, 'seen' is a dict
@@ -973,9 +969,7 @@ class Query:
         return alias or seen[None]
 
     def add_annotation(self, annotation, alias, is_summary=False):
-        """
-        Adds a single annotation expression to the Query
-        """
+        """Add a single annotation expression to the Query."""
         annotation = annotation.resolve_expression(self, allow_joins=True, reuse=None,
                                                    summarize=is_summary)
         self.append_annotation_mask([alias])
@@ -1031,7 +1025,7 @@ class Query:
 
     def solve_lookup_type(self, lookup):
         """
-        Solve the lookup type from the lookup (eg: 'foobar__id__icontains')
+        Solve the lookup type from the lookup (e.g.: 'foobar__id__icontains').
         """
         lookup_splitted = lookup.split(LOOKUP_SEP)
         if self._annotations:
@@ -1051,8 +1045,8 @@ class Query:
 
     def check_query_object_type(self, value, opts, field):
         """
-        Checks whether the object passed while querying is of the correct type.
-        If not, it raises a ValueError specifying the wrong object.
+        Check whether the object passed while querying is of the correct type.
+        If not, raise a ValueError specifying the wrong object.
         """
         if hasattr(value, '_meta'):
             if not check_rel_lookup_compatibility(value._meta.model, opts, field):
@@ -1061,9 +1055,7 @@ class Query:
                     (value, opts.object_name))
 
     def check_related_objects(self, field, value, opts):
-        """
-        Checks the type of object passed to query relations.
-        """
+        """Check the type of object passed to query relations."""
         if field.is_relation:
             # Check that the field and the queryset use the same model in a
             # query like .filter(author=Author.objects.all()). For example, the
@@ -1087,7 +1079,7 @@ class Query:
 
     def build_lookup(self, lookups, lhs, rhs):
         """
-        Tries to extract transforms and lookup from given lhs.
+        Try to extract transforms and lookup from given lhs.
 
         The lhs value is something that works like SQLExpression.
         The rhs value is what the lookup is going to compare against.
@@ -1114,7 +1106,7 @@ class Query:
 
     def try_transform(self, lhs, name, rest_of_lookups):
         """
-        Helper method for build_lookup. Tries to fetch and initialize
+        Helper method for build_lookup(). Try to fetch and initialize
         a transform for name parameter from lhs.
         """
         transform_class = lhs.get_transform(name)
@@ -1129,7 +1121,7 @@ class Query:
     def build_filter(self, filter_expr, branch_negated=False, current_negated=False,
                      can_reuse=None, connector=AND, allow_joins=True, split_subq=True):
         """
-        Builds a WhereNode for a single filter clause, but doesn't add it
+        Build a WhereNode for a single filter clause but don't add it
         to this Query. Query.add_q() will then add this filter to the where
         Node.
 
@@ -1140,7 +1132,7 @@ class Query:
         negated or not and this will be used to determine if IS NULL filtering
         is needed.
 
-        The difference between current_netageted and branch_negated is that
+        The difference between current_negated and branch_negated is that
         branch_negated is set on first negation, but current_negated is
         flipped for each negation.
 
@@ -1263,9 +1255,7 @@ class Query:
 
     def _add_q(self, q_object, used_aliases, branch_negated=False,
                current_negated=False, allow_joins=True, split_subq=True):
-        """
-        Adds a Q-object to the current filter.
-        """
+        """Add a Q-object to the current filter."""
         connector = q_object.connector
         current_negated = current_negated ^ q_object.negated
         branch_negated = branch_negated or q_object.negated
@@ -1292,20 +1282,18 @@ class Query:
 
     def names_to_path(self, names, opts, allow_many=True, fail_on_missing=False):
         """
-        Walks the list of names and turns them into PathInfo tuples. Note that
-        a single name in 'names' can generate multiple PathInfos (m2m for
-        example).
+        Walk the list of names and turns them into PathInfo tuples. A single
+        name in 'names' can generate multiple PathInfos (m2m, for example).
 
         'names' is the path of names to travel, 'opts' is the model Options we
         start the name resolving from, 'allow_many' is as for setup_joins().
         If fail_on_missing is set to True, then a name that can't be resolved
         will generate a FieldError.
 
-        Returns a list of PathInfo tuples. In addition returns the final field
-        (the last used join field), and target (which is a field guaranteed to
-        contain the same value as the final field). Finally, the method returns
-        those names that weren't found (which are likely transforms and the
-        final lookup).
+        Return a list of PathInfo tuples. In addition return the final field
+        (the last used join field) and target (which is a field guaranteed to
+        contain the same value as the final field). Finally, return those names
+        that weren't found (which are likely transforms and the final lookup).
         """
         path, names_with_path = [], []
         for pos, name in enumerate(names):
@@ -1397,7 +1385,7 @@ class Query:
         If 'allow_many' is False, then any reverse foreign key seen will
         generate a MultiJoin exception.
 
-        Returns the final field involved in the joins, the target field (used
+        Return the final field involved in the joins, the target field (used
         for any 'where' constraint), the final 'opts' value, the joins and the
         field path travelled to generate the joins.
 
@@ -1433,13 +1421,12 @@ class Query:
         is the full list of join aliases. The 'path' contain the PathInfos
         used to create the joins.
 
-        Returns the final target field and table alias and the new active
+        Return the final target field and table alias and the new active
         joins.
 
-        We will always trim any direct join if we have the target column
-        available already in the previous table. Reverse joins can't be
-        trimmed as we don't know if there is anything on the other side of
-        the join.
+        Always trim any direct join if the target column is already in the
+        previous table. Can't trim reverse joins as it's unknown if there's
+        anything on the other side of the join.
         """
         joins = joins[:]
         for pos, info in enumerate(reversed(path)):
@@ -1555,13 +1542,12 @@ class Query:
 
     def set_limits(self, low=None, high=None):
         """
-        Adjusts the limits on the rows retrieved. We use low/high to set these,
+        Adjust the limits on the rows retrieved. Use low/high to set these,
         as it makes it more Pythonic to read and write. When the SQL query is
-        created, they are converted to the appropriate offset and limit values.
+        created, convert them to the appropriate offset and limit values.
 
-        Any limits passed in here are applied relative to the existing
-        constraints. So low is added to the current low value and both will be
-        clamped to any existing high value.
+        Apply any limits passed in here to the existing constraints. Add low
+        to the current low value and clamp both to any existing high value.
         """
         if high is not None:
             if self.high_mark is not None:
@@ -1578,23 +1564,19 @@ class Query:
             self.set_empty()
 
     def clear_limits(self):
-        """
-        Clears any existing limits.
-        """
+        """Clear any existing limits."""
         self.low_mark, self.high_mark = 0, None
 
     def can_filter(self):
         """
-        Returns True if adding filters to this instance is still possible.
+        Return True if adding filters to this instance is still possible.
 
         Typically, this means no limits or offsets have been put on the results.
         """
         return not self.low_mark and self.high_mark is None
 
     def clear_select_clause(self):
-        """
-        Removes all fields from SELECT clause.
-        """
+        """Remove all fields from SELECT clause."""
         self.select = []
         self.default_cols = False
         self.select_related = False
@@ -1603,7 +1585,7 @@ class Query:
 
     def clear_select_fields(self):
         """
-        Clears the list of fields to select (but not extra_select columns).
+        Clear the list of fields to select (but not extra_select columns).
         Some queryset types completely replace any existing list of select
         columns.
         """
@@ -1620,15 +1602,15 @@ class Query:
 
     def add_distinct_fields(self, *field_names):
         """
-        Adds and resolves the given fields to the query's "distinct on" clause.
+        Add and resolve the given fields to the query's "distinct on" clause.
         """
         self.distinct_fields = field_names
         self.distinct = True
 
     def add_fields(self, field_names, allow_m2m=True):
         """
-        Adds the given (model) fields to the select set. The field names are
-        added in the order specified.
+        Add the given (model) fields to the select set. Add the field names in
+        the order specified.
         """
         alias = self.get_initial_alias()
         opts = self.get_meta()
@@ -1656,12 +1638,12 @@ class Query:
 
     def add_ordering(self, *ordering):
         """
-        Adds items from the 'ordering' sequence to the query's "order by"
+        Add items from the 'ordering' sequence to the query's "order by"
         clause. These items are either field names (not column names) --
         possibly with a direction prefix ('-' or '?') -- or OrderBy
         expressions.
 
-        If 'ordering' is empty, all ordering is cleared from the query.
+        If 'ordering' is empty, clear all ordering from the query.
         """
         errors = []
         for item in ordering:
@@ -1681,7 +1663,7 @@ class Query:
 
     def clear_ordering(self, force_empty):
         """
-        Removes any ordering settings. If 'force_empty' is True, there will be
+        Remove any ordering settings. If 'force_empty' is True, there will be
         no ordering in the resulting query (not even the model's default).
         """
         self.order_by = []
@@ -1691,7 +1673,7 @@ class Query:
 
     def set_group_by(self):
         """
-        Expands the GROUP BY clause required by the query.
+        Expand the GROUP BY clause required by the query.
 
         This will usually be the set of all non-aggregate fields in the
         return data. If the database backend supports grouping by the
@@ -1710,7 +1692,7 @@ class Query:
 
     def add_select_related(self, fields):
         """
-        Sets up the select_related data structure so that we only select
+        Set up the select_related data structure so that we only select
         certain related models (as opposed to all models, when
         self.select_related=True).
         """
@@ -1726,7 +1708,7 @@ class Query:
 
     def add_extra(self, select, select_params, where, params, tables, order_by):
         """
-        Adds data to the various extra_* attributes for user-created additions
+        Add data to the various extra_* attributes for user-created additions
         to the query.
         """
         if select:
@@ -1758,16 +1740,14 @@ class Query:
             self.extra_order_by = order_by
 
     def clear_deferred_loading(self):
-        """
-        Remove any fields from the deferred loading set.
-        """
+        """Remove any fields from the deferred loading set."""
         self.deferred_loading = (set(), True)
 
     def add_deferred_loading(self, field_names):
         """
         Add the given list of model field names to the set of fields to
         exclude from loading from the database when automatic column selection
-        is done. The new field names are added to any existing field names that
+        is done. Add the new field names to any existing field names that
         are deferred (or removed from any existing field names that are marked
         as the only ones for immediate loading).
         """
@@ -1788,8 +1768,8 @@ class Query:
         Add the given list of model field names to the set of fields to
         retrieve when the SQL is executed ("immediate loading" fields). The
         field names replace any existing immediate loading field names. If
-        there are field names already specified for deferred loading, those
-        names are removed from the new field_names before storing the new names
+        there are field names already specified for deferred loading, remove
+        those names from the new field_names before storing the new names
         for immediate loading. (That is, immediate loading overrides any
         existing immediate values, but respects existing deferrals.)
         """
@@ -1809,12 +1789,12 @@ class Query:
 
     def get_loaded_field_names(self):
         """
-        If any fields are marked to be deferred, returns a dictionary mapping
+        If any fields are marked to be deferred, return a dictionary mapping
         models to a set of names in those fields that will be loaded. If a
         model is not in the returned dictionary, none of its fields are
         deferred.
 
-        If no fields are marked for deferral, returns an empty dictionary.
+        If no fields are marked for deferral, return an empty dictionary.
         """
         # We cache this because we call this function multiple times
         # (compiler.fill_related_selections, query.iterator)
@@ -1827,13 +1807,11 @@ class Query:
             return collection
 
     def get_loaded_field_names_cb(self, target, model, fields):
-        """
-        Callback used by get_deferred_field_names().
-        """
+        """Callback used by get_deferred_field_names()."""
         target[model] = {f.attname for f in fields}
 
     def set_annotation_mask(self, names):
-        "Set the mask of annotations that will actually be returned by the SELECT"
+        """Set the mask of annotations that will be returned by the SELECT."""
         if names is None:
             self.annotation_select_mask = None
         else:
@@ -1846,9 +1824,8 @@ class Query:
 
     def set_extra_mask(self, names):
         """
-        Set the mask of extra select items that will be returned by SELECT,
-        we don't actually remove them from the Query since they might be used
-        later
+        Set the mask of extra select items that will be returned by SELECT.
+        Don't remove them from the Query since they might be used later.
         """
         if names is None:
             self.extra_select_mask = None
@@ -1893,10 +1870,9 @@ class Query:
 
     @property
     def annotation_select(self):
-        """The OrderedDict of aggregate columns that are not masked, and should
-        be used in the SELECT clause.
-
-        This result is cached for optimization purposes.
+        """
+        Return the OrderedDict of aggregate columns that are not masked and
+        should be used in the SELECT clause. Cache this result for performance.
         """
         if self._annotation_select_cache is not None:
             return self._annotation_select_cache
@@ -1928,16 +1904,16 @@ class Query:
 
     def trim_start(self, names_with_path):
         """
-        Trims joins from the start of the join path. The candidates for trim
+        Trim joins from the start of the join path. The candidates for trim
         are the PathInfos in names_with_path structure that are m2m joins.
 
-        Also sets the select column so the start matches the join.
+        Also set the select column so the start matches the join.
 
         This method is meant to be used for generating the subquery joins &
         cols in split_exclude().
 
-        Returns a lookup usable for doing outerq.filter(lookup=self). Returns
-        also if the joins in the prefix contain a LEFT OUTER join.
+        Return a lookup usable for doing outerq.filter(lookup=self) and a
+        boolean indicating if the joins in the prefix contain a LEFT OUTER join.
         _"""
         all_paths = []
         for _, paths in names_with_path:
@@ -1995,7 +1971,7 @@ class Query:
 
     def is_nullable(self, field):
         """
-        A helper to check if the given field should be treated as nullable.
+        Check if the given field should be treated as nullable.
 
         Some backends treat '' as null and Django treats such fields as
         nullable for those backends. In such situations field.null can be
@@ -2025,7 +2001,7 @@ class Query:
 
 def get_order_dir(field, default='ASC'):
     """
-    Returns the field name and direction for an order specification. For
+    Return the field name and direction for an order specification. For
     example, '-foo' is returned as ('foo', 'DESC').
 
     The 'default' param is used to indicate which way no prefix (or a '+'
@@ -2039,8 +2015,8 @@ def get_order_dir(field, default='ASC'):
 
 def add_to_dict(data, key, value):
     """
-    A helper function to add "value" to the set of values for "key", whether or
-    not "key" already exists.
+    Add "value" to the set of values for "key", whether or not "key" already
+    exists.
     """
     if key in data:
         data[key].add(value)
@@ -2050,8 +2026,8 @@ def add_to_dict(data, key, value):
 
 def is_reverse_o2o(field):
     """
-    A little helper to check if the given field is reverse-o2o. The field is
-    expected to be some sort of relation field or related object.
+    Check if the given field is reverse-o2o. The field is expected to be some
+    sort of relation field or related object.
     """
     return field.is_relation and field.one_to_one and not field.concrete
 
diff --git a/django/db/models/sql/subqueries.py b/django/db/models/sql/subqueries.py
index 03a5155b9b..65e944baa9 100644
--- a/django/db/models/sql/subqueries.py
+++ b/django/db/models/sql/subqueries.py
@@ -14,10 +14,7 @@ __all__ = ['DeleteQuery', 'UpdateQuery', 'InsertQuery', 'AggregateQuery']
 
 
 class DeleteQuery(Query):
-    """
-    Delete queries are done through this class, since they are more constrained
-    than general queries.
-    """
+    """A DELETE SQL query."""
 
     compiler = 'SQLDeleteCompiler'
 
@@ -81,9 +78,7 @@ class DeleteQuery(Query):
 
 
 class UpdateQuery(Query):
-    """
-    Represents an "update" SQL query.
-    """
+    """An UPDATE SQL query."""
 
     compiler = 'SQLUpdateCompiler'
 
@@ -93,7 +88,7 @@ class UpdateQuery(Query):
 
     def _setup_query(self):
         """
-        Runs on initialization and after cloning. Any attributes that would
+        Run on initialization and after cloning. Any attributes that would
         normally be set in __init__ should go in here, instead, so that they
         are also set up after a clone() call.
         """
@@ -148,15 +143,15 @@ class UpdateQuery(Query):
 
     def add_related_update(self, model, field, value):
         """
-        Adds (name, value) to an update query for an ancestor model.
+        Add (name, value) to an update query for an ancestor model.
 
-        Updates are coalesced so that we only run one update query per ancestor.
+        Update are coalesced so that only one update query per ancestor is run.
         """
         self.related_updates.setdefault(model, []).append((field, None, value))
 
     def get_related_updates(self):
         """
-        Returns a list of query objects: one for each update required to an
+        Return a list of query objects: one for each update required to an
         ancestor model. Each query will have the same filtering conditions as
         the current query but will only update a single table.
         """
@@ -181,15 +176,6 @@ class InsertQuery(Query):
         self.objs = []
 
     def insert_values(self, fields, objs, raw=False):
-        """
-        Set up the insert query from the 'insert_values' dictionary. The
-        dictionary gives the model field names and their target values.
-
-        If 'raw_values' is True, the values in the 'insert_values' dictionary
-        are inserted directly into the query, rather than passed as SQL
-        parameters. This provides a way to insert NULL and DEFAULT keywords
-        into the query, for example.
-        """
         self.fields = fields
         self.objs = objs
         self.raw = raw
@@ -197,8 +183,8 @@ class InsertQuery(Query):
 
 class AggregateQuery(Query):
     """
-    An AggregateQuery takes another query as a parameter to the FROM
-    clause and only selects the elements in the provided list.
+    Take another query as a parameter to the FROM clause and only select the
+    elements in the provided list.
     """
 
     compiler = 'SQLAggregateCompiler'
diff --git a/django/db/models/sql/where.py b/django/db/models/sql/where.py
index 7ce7617bfa..ed24b08bd0 100644
--- a/django/db/models/sql/where.py
+++ b/django/db/models/sql/where.py
@@ -13,7 +13,7 @@ OR = 'OR'
 
 class WhereNode(tree.Node):
     """
-    Used to represent the SQL where-clause.
+    An SQL WHERE clause.
 
     The class is tied to the Query class that created it (in order to create
     the correct SQL).
@@ -29,7 +29,7 @@ class WhereNode(tree.Node):
 
     def split_having(self, negated=False):
         """
-        Returns two possibly None nodes: one for those parts of self that
+        Return two possibly None nodes: one for those parts of self that
         should be included in the WHERE clause and one for those parts of
         self that must be included in the HAVING clause.
         """
@@ -62,9 +62,9 @@ class WhereNode(tree.Node):
 
     def as_sql(self, compiler, connection):
         """
-        Returns the SQL version of the where clause and the value to be
-        substituted in. Returns '', [] if this node matches everything,
-        None, [] if this node is empty, and raises EmptyResultSet if this
+        Return the SQL version of the where clause and the value to be
+        substituted in. Return '', [] if this node matches everything,
+        None, [] if this node is empty, and raise EmptyResultSet if this
         node can't match anything.
         """
         result = []
@@ -127,7 +127,7 @@ class WhereNode(tree.Node):
 
     def relabel_aliases(self, change_map):
         """
-        Relabels the alias values of any children. 'change_map' is a dictionary
+        Relabel the alias values of any children. 'change_map' is a dictionary
         mapping old (current) alias values to the new values.
         """
         for pos, child in enumerate(self.children):
@@ -139,7 +139,7 @@ class WhereNode(tree.Node):
 
     def clone(self):
         """
-        Creates a clone of the tree. Must only be called on root nodes (nodes
+        Create a clone of the tree. Must only be called on root nodes (nodes
         with empty subtree_parents). Childs must be either (Contraint, lookup,
         value) tuples, or objects supporting .clone().
         """
@@ -173,9 +173,7 @@ class WhereNode(tree.Node):
 
 
 class NothingNode:
-    """
-    A node that matches nothing.
-    """
+    """A node that matches nothing."""
     contains_aggregate = False
 
     def as_sql(self, compiler=None, connection=None):