Fixed #11557 -- Added support for a list of fields in Meta.get_latest_by and QuerySet.earliest()/latest().

4 files changed, 43 insertions, 10 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index c41245ac65..c49b124f9c 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -26,6 +26,9 @@ details on these changes.
 * Support for the ``context`` argument of ``Field.from_db_value()`` and
   ``Expression.convert_value()`` will be removed.
 
+* The ``field_name`` keyword argument of ``QuerySet.earliest()` and
+  ``latest()`` will be removed.
+
 .. _deprecation-removed-in-2.1:
 
 2.1
diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt
index 33ff581d39..188552dbb2 100644
--- a/docs/ref/models/options.txt
+++ b/docs/ref/models/options.txt
@@ -131,18 +131,26 @@ Django quotes column and table names behind the scenes.
 
 .. attribute:: Options.get_latest_by
 
-    The name of an orderable field in the model, typically a :class:`DateField`,
-    :class:`DateTimeField`, or :class:`IntegerField`. This specifies the default
-    field to use in your model :class:`Manager`’s
+    The name of a field or a list of field names in the model, typically
+    :class:`DateField`, :class:`DateTimeField`, or :class:`IntegerField`. This
+    specifies the default field(s) to use in your model :class:`Manager`’s
     :meth:`~django.db.models.query.QuerySet.latest` and
     :meth:`~django.db.models.query.QuerySet.earliest` methods.
 
     Example::
 
+        # Latest by ascending order_date.
         get_latest_by = "order_date"
 
+        # Latest by priority descending, order_date ascending.
+        get_latest_by = ['-priority', 'order_date']
+
     See the :meth:`~django.db.models.query.QuerySet.latest` docs for more.
 
+    .. versionchanged:: 2.0
+
+        Support for a list of fields was added.
+
 ``managed``
 -----------
 
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 9c329d48ee..5973f2b5a3 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -2099,20 +2099,29 @@ psycopg mailing list <https://www.postgresql.org/message-id/4D2F2C71.8080805%40d
 ``latest()``
 ~~~~~~~~~~~~
 
-.. method:: latest(field_name=None)
+.. method:: latest(*fields)
 
-Returns the latest object in the table, by date, using the ``field_name``
-provided as the date field.
+Returns the latest object in the table based on the given field(s).
 
 This example returns the latest ``Entry`` in the table, according to the
 ``pub_date`` field::
 
     Entry.objects.latest('pub_date')
 
+You can also choose the latest based on several fields. For example, to select
+the ``Entry`` with the earliest ``expire_date`` when two entries have the same
+``pub_date``::
+
+    Entry.objects.latest('pub_date', '-expire_date')
+
+The negative sign in ``'-expire_date'`` means to sort ``expire_date`` in
+*descending* order. Since ``latest()`` gets the last result, the ``Entry`` with
+the earliest ``expire_date`` is selected.
+
 If your model's :ref:`Meta <meta-options>` specifies
-:attr:`~django.db.models.Options.get_latest_by`, you can leave off the
-``field_name`` argument to ``earliest()`` or ``latest()``. Django will use the
-field specified in :attr:`~django.db.models.Options.get_latest_by` by default.
+:attr:`~django.db.models.Options.get_latest_by`, you can omit any arguments to
+``earliest()`` or ``latest()``. The fields specified in
+:attr:`~django.db.models.Options.get_latest_by` will be used by default.
 
 Like :meth:`get()`, ``earliest()`` and ``latest()`` raise
 :exc:`~django.db.models.Model.DoesNotExist` if there is no object with the
@@ -2121,6 +2130,10 @@ given parameters.
 Note that ``earliest()`` and ``latest()`` exist purely for convenience and
 readability.
 
+.. versionchanged:: 2.0
+
+    Support for several arguments was added.
+
 .. admonition:: ``earliest()`` and ``latest()`` may return instances with null dates.
 
     Since ordering is delegated to the database, results on fields that allow
@@ -2135,7 +2148,7 @@ readability.
 ``earliest()``
 ~~~~~~~~~~~~~~
 
-.. method:: earliest(field_name=None)
+.. method:: earliest(*fields)
 
 Works otherwise like :meth:`~django.db.models.query.QuerySet.latest` except
 the direction is changed.
diff --git a/docs/releases/2.0.txt b/docs/releases/2.0.txt
index a8530d11c2..dd8183d798 100644
--- a/docs/releases/2.0.txt
+++ b/docs/releases/2.0.txt
@@ -250,6 +250,10 @@ Models
   from the database. For databases that don't support server-side cursors, it
   controls the number of results Django fetches from the database adapter.
 
+* :meth:`.QuerySet.earliest`, :meth:`.QuerySet.latest`, and
+  :attr:`Meta.get_latest_by <django.db.models.Options.get_latest_by>`  now
+  allow ordering by several fields.
+
 * Added the :class:`~django.db.models.functions.datetime.ExtractQuarter`
   function to extract the quarter from :class:`~django.db.models.DateField` and
   :class:`~django.db.models.DateTimeField`, and exposed it through the
@@ -642,6 +646,11 @@ Miscellaneous
 * ``HttpRequest.xreadlines()`` is deprecated in favor of iterating over the
   request.
 
+* The ``field_name`` keyword argument to :meth:`.QuerySet.earliest` and
+  :meth:`.QuerySet.latest` is deprecated in favor of passing the field
+  names as arguments. Write ``.earliest('pub_date')`` instead of
+  ``.earliest(field_name='pub_date')``.
+
 .. _removed-features-2.0:
 
 Features removed in 2.0