Fixed #25916 -- Added lastmod support to sitemap index view.

Co-authored-by: Matthew Downey <matthew.downey@webit.com.au>

3 files changed, 51 insertions, 4 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 202acdf608..13c800e0ee 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -65,6 +65,8 @@ details on these changes.
 See the :ref:`Django 4.1 release notes <deprecated-features-4.1>` for more
 details on these changes.
 
+* The ``SitemapIndexItem.__str__()`` method will be removed.
+
 .. _deprecation-removed-in-4.1:
 
 4.1
diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt
index ec0358391c..e6c96be21d 100644
--- a/docs/ref/contrib/sitemaps.txt
+++ b/docs/ref/contrib/sitemaps.txt
@@ -294,6 +294,23 @@ Note:
         fallback entry with a value of :setting:`LANGUAGE_CODE`. The default is
         ``False``.
 
+    .. method:: Sitemap.get_latest_lastmod()
+
+        .. versionadded:: 4.1
+
+        **Optional.** A method that returns the latest value returned by
+        :attr:`~Sitemap.lastmod`. This function is used to add the ``lastmod``
+        attribute to :ref:`Sitemap index context
+        variables<sitemap-index-context-variables>`.
+
+        By default :meth:`~Sitemap.get_latest_lastmod` returns:
+
+        * If :attr:`~Sitemap.lastmod` is an attribute:
+          :attr:`~Sitemap.lastmod`.
+        * If :attr:`~Sitemap.lastmod` is a method:
+          The latest ``lastmod`` returned by calling the method with all
+          items returned by :meth:`Sitemap.items`.
+
 Shortcuts
 =========
 
@@ -306,7 +323,8 @@ The sitemap framework provides a convenience class for a common case:
     a ``queryset`` entry. This queryset will be used to generate the items
     of the sitemap. It may also have a ``date_field`` entry that
     specifies a date field for objects retrieved from the ``queryset``.
-    This will be used for the :attr:`~Sitemap.lastmod` attribute in the
+    This will be used for the :attr:`~Sitemap.lastmod` attribute and
+    :meth:`~Sitemap.get_latest_lastmod` methods in the in the
     generated sitemap.
 
     The :attr:`~Sitemap.priority`, :attr:`~Sitemap.changefreq`,
@@ -413,6 +431,10 @@ both :file:`sitemap-flatpages.xml` and :file:`sitemap-blog.xml`. The
 :class:`~django.contrib.sitemaps.Sitemap` classes and the ``sitemaps``
 dict don't change at all.
 
+If all sitemaps have a ``lastmod`` returned by
+:meth:`Sitemap.get_latest_lastmod` the sitemap index will have a
+``Last-Modified`` header equal to the latest ``lastmod``.
+
 You should create an index file if one of your sitemaps has more than 50,000
 URLs. In this case, Django will automatically paginate the sitemap, and the
 index will reflect that.
@@ -433,6 +455,9 @@ with a caching decorator -- you must name your sitemap view and pass
              {'sitemaps': sitemaps}, name='sitemaps'),
     ]
 
+.. versionchanged:: 4.1
+
+    Use of the ``Last-Modified`` header was added.
 
 Template customization
 ======================
@@ -468,10 +493,23 @@ When customizing the templates for the
 :func:`~django.contrib.sitemaps.views.sitemap` views, you can rely on the
 following context variables.
 
+.. _sitemap-index-context-variables:
+
 Index
 -----
 
-The variable ``sitemaps`` is a list of absolute URLs to each of the sitemaps.
+The variable ``sitemaps`` is a list of objects containing the ``location`` and
+``lastmod`` attribute for each of the sitemaps. Each URL exposes the following
+attributes:
+
+- ``location``: The location (url & page) of the sitemap.
+- ``lastmod``: Populated by the :meth:`~Sitemap.get_latest_lastmod`
+  method for each sitemap.
+
+.. versionchanged:: 4.1
+
+    The context was changed to a list of objects with ``location`` and optional
+    ``lastmod`` attributes.
 
 Sitemap
 -------
diff --git a/docs/releases/4.1.txt b/docs/releases/4.1.txt
index af4b6d83a3..0c133f24f1 100644
--- a/docs/releases/4.1.txt
+++ b/docs/releases/4.1.txt
@@ -88,7 +88,11 @@ Minor features
 :mod:`django.contrib.sitemaps`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* ...
+* The default sitemap index template ``<sitemapindex>`` now includes the
+  ``<lastmod>`` timestamp where available, through the new
+  :meth:`~django.contrib.sitemaps.Sitemap.get_latest_lastmod` method. Custom
+  sitemap index templates should be updated for the adjusted :ref:`context
+  variables <sitemap-index-context-variables>`.
 
 :mod:`django.contrib.sites`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -253,7 +257,10 @@ Features deprecated in 4.1
 Miscellaneous
 -------------
 
-* ...
+* The context for sitemap index templates of a flat list of URLs is deprecated.
+  Custom sitemap index templates should be updated for the adjusted
+  :ref:`context variables <sitemap-index-context-variables>`, expecting a list
+  of objects with ``location`` and optional ``lastmod`` attributes.
 
 Features removed in 4.1
 =======================