From 1446902be48ebf19bfe484371897a2815dd21fca Mon Sep 17 00:00:00 2001
From: Mads Jensen <mje@inducks.org>
Date: Fri, 11 Nov 2016 14:01:40 +0100
Subject: Fixed #25240 -- Added ExtractWeek and exposed it through the __week
 lookup.

Thanks to Mariusz Felisiak and Tim Graham for review.
---
 docs/ref/models/database-functions.txt | 15 +++++++++++++++
 docs/ref/models/querysets.txt          | 22 ++++++++++++++++++++++
 docs/releases/1.11.txt                 |  5 +++++
 3 files changed, 42 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt
index 0d9c80fa25..ad653a710b 100644
--- a/docs/ref/models/database-functions.txt
+++ b/docs/ref/models/database-functions.txt
@@ -313,6 +313,7 @@ Given the datetime ``2015-06-15 23:30:01.000321+00:00``, the built-in
 * "year": 2015
 * "month": 6
 * "day": 15
+* "week": 25
 * "week_day": 2
 * "hour": 23
 * "minute": 30
@@ -340,6 +341,14 @@ returned when this timezone is active will be the same as above except for:
         >>> (dt.isoweekday() % 7) + 1
         2
 
+.. admonition:: ``week`` values
+
+    The ``week`` ``lookup_type`` is calculated based on `ISO-8601
+    <https://en.wikipedia.org/wiki/ISO-8601>`_, i.e.,
+    a week starts on a Monday. The first week is the one with the majority
+    of the days, i.e., a week that starts on or before Thursday. The value
+    returned is in the range 1 to 52 or 53.
+
 Each ``lookup_name`` above has a corresponding ``Extract`` subclass (listed
 below) that should typically be used instead of the more verbose equivalent,
 e.g. use ``ExtractYear(...)`` rather than ``Extract(..., lookup_name='year')``.
@@ -382,6 +391,12 @@ Usage example::
 
     .. attribute:: lookup_name = 'week_day'
 
+.. class:: ExtractWeek(expression, tzinfo=None, **extra)
+
+    .. versionadded:: 1.11
+
+    .. attribute:: lookup_name = 'week'
+
 These are logically equivalent to ``Extract('date_field', lookup_name)``. Each
 class is also a ``Transform`` registered on ``DateField`` and ``DateTimeField``
 as ``__(lookup_name)``, e.g. ``__year``.
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 7bcf2fc6ed..0d89f221b9 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -2703,6 +2703,28 @@ When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
 current time zone before filtering. This requires :ref:`time zone definitions
 in the database <database-time-zone-definitions>`.
 
+.. fieldlookup:: week
+
+``week``
+~~~~~~~~
+
+.. versionadded:: 1.11
+
+For date and datetime fields, return the week number (1-52 or 53) according
+to `ISO-8601 <https://en.wikipedia.org/wiki/ISO-8601>`_, i.e., weeks start
+on a Monday and the first week starts on or before Thursday.
+
+Example::
+
+    Entry.objects.filter(pub_date__week=52)
+    Entry.objects.filter(pub_date__week__gte=32, pub_date__week__lte=38)
+
+(No equivalent SQL code fragment is included for this lookup because
+implementation of the relevant query varies among different database engines.)
+
+When :setting:`USE_TZ` is ``True``, fields are converted to the current time
+zone before filtering.
+
 .. fieldlookup:: week_day
 
 ``week_day``
diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt
index 77a1c3ea12..d26a6a0a51 100644
--- a/docs/releases/1.11.txt
+++ b/docs/releases/1.11.txt
@@ -306,6 +306,11 @@ Models
 * Added support for time truncation to
   :class:`~django.db.models.functions.datetime.Trunc` functions.
 
+* Added the :class:`~django.db.models.functions.datetime.ExtractWeek` function
+  to extract the week from :class:`~django.db.models.DateField` and
+  :class:`~django.db.models.DateTimeField` and exposed it through the
+  :lookup:`week` lookup.
+
 * Added the :class:`~django.db.models.functions.datetime.TruncTime` function
   to truncate :class:`~django.db.models.DateTimeField` to its time component
   and exposed it through the :lookup:`time` lookup.
-- 
cgit v1.3