From ad4a8acdb55a80a6a6dec60724b22abed0025399 Mon Sep 17 00:00:00 2001
From: François Freitag <mail@franek.fr>
Date: Wed, 21 Jun 2017 13:28:16 -0700
Subject: Fixed #11557 -- Added support for a list of fields in
 Meta.get_latest_by and QuerySet.earliest()/latest().

---
 docs/ref/models/options.txt   | 14 +++++++++++---
 docs/ref/models/querysets.txt | 27 ++++++++++++++++++++-------
 2 files changed, 31 insertions(+), 10 deletions(-)

(limited to 'docs/ref')

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.
-- 
cgit v1.3