Fixed #22394 -- Refactored built-in datetime lookups to transforms.

1 files changed, 55 insertions, 8 deletions

diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 733025a5f1..6fb3dc6aae 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -2431,36 +2431,45 @@ numbers and even characters.
 year
 ~~~~
 
-For date and datetime fields, an exact year match. Takes an integer year.
+For date and datetime fields, an exact year match. Allows chaining additional
+field lookups. Takes an integer year.
 
 Example::
 
     Entry.objects.filter(pub_date__year=2005)
+    Entry.objects.filter(pub_date__year__gte=2005)
 
 SQL equivalent::
 
     SELECT ... WHERE pub_date BETWEEN '2005-01-01' AND '2005-12-31';
+    SELECT ... WHERE pub_date >= '2005-01-01';
 
 (The exact SQL syntax varies for each database engine.)
 
 When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
 current time zone before filtering.
 
+.. versionchanged:: 1.9
+
+    Allowed chaining additional field lookups.
+
 .. fieldlookup:: month
 
 month
 ~~~~~
 
-For date and datetime fields, an exact month match. Takes an integer 1
-(January) through 12 (December).
+For date and datetime fields, an exact month match. Allows chaining additional
+field lookups. Takes an integer 1 (January) through 12 (December).
 
 Example::
 
     Entry.objects.filter(pub_date__month=12)
+    Entry.objects.filter(pub_date__month__gte=6)
 
 SQL equivalent::
 
     SELECT ... WHERE EXTRACT('month' FROM pub_date) = '12';
+    SELECT ... WHERE EXTRACT('month' FROM pub_date) >= '6';
 
 (The exact SQL syntax varies for each database engine.)
 
@@ -2468,20 +2477,27 @@ 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>`.
 
+.. versionchanged:: 1.9
+
+    Allowed chaining additional field lookups.
+
 .. fieldlookup:: day
 
 day
 ~~~
 
-For date and datetime fields, an exact day match. Takes an integer day.
+For date and datetime fields, an exact day match. Allows chaining additional
+field lookups. Takes an integer day.
 
 Example::
 
     Entry.objects.filter(pub_date__day=3)
+    Entry.objects.filter(pub_date__day__gte=3)
 
 SQL equivalent::
 
     SELECT ... WHERE EXTRACT('day' FROM pub_date) = '3';
+    SELECT ... WHERE EXTRACT('day' FROM pub_date) >= '3';
 
 (The exact SQL syntax varies for each database engine.)
 
@@ -2492,12 +2508,17 @@ 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>`.
 
+.. versionchanged:: 1.9
+
+    Allowed chaining additional field lookups.
+
 .. fieldlookup:: week_day
 
 week_day
 ~~~~~~~~
 
-For date and datetime fields, a 'day of the week' match.
+For date and datetime fields, a 'day of the week' match. Allows chaining
+additional field lookups.
 
 Takes an integer value representing the day of week from 1 (Sunday) to 7
 (Saturday).
@@ -2505,6 +2526,7 @@ Takes an integer value representing the day of week from 1 (Sunday) to 7
 Example::
 
     Entry.objects.filter(pub_date__week_day=2)
+    Entry.objects.filter(pub_date__week_day__gte=2)
 
 (No equivalent SQL code fragment is included for this lookup because
 implementation of the relevant query varies among different database engines.)
@@ -2517,66 +2539,91 @@ 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>`.
 
+.. versionchanged:: 1.9
+
+    Allowed chaining additional field lookups.
+
 .. fieldlookup:: hour
 
 hour
 ~~~~
 
-For datetime fields, an exact hour match. Takes an integer between 0 and 23.
+For datetime fields, an exact hour match. Allows chaining additional field
+lookups. Takes an integer between 0 and 23.
 
 Example::
 
     Event.objects.filter(timestamp__hour=23)
+    Event.objects.filter(timestamp__hour__gte=12)
 
 SQL equivalent::
 
     SELECT ... WHERE EXTRACT('hour' FROM timestamp) = '23';
+    SELECT ... WHERE EXTRACT('hour' FROM timestamp) >= '12';
 
 (The exact SQL syntax varies for each database engine.)
 
 When :setting:`USE_TZ` is ``True``, values are converted to the current time
 zone before filtering.
 
+.. versionchanged:: 1.9
+
+    Allowed chaining additional field lookups.
+
 .. fieldlookup:: minute
 
 minute
 ~~~~~~
 
-For datetime fields, an exact minute match. Takes an integer between 0 and 59.
+For datetime fields, an exact minute match. Allows chaining additional field
+lookups. Takes an integer between 0 and 59.
 
 Example::
 
     Event.objects.filter(timestamp__minute=29)
+    Event.objects.filter(timestamp__minute__gte=29)
 
 SQL equivalent::
 
     SELECT ... WHERE EXTRACT('minute' FROM timestamp) = '29';
+    SELECT ... WHERE EXTRACT('minute' FROM timestamp) >= '29';
 
 (The exact SQL syntax varies for each database engine.)
 
 When :setting:`USE_TZ` is ``True``, values are converted to the current time
 zone before filtering.
 
+.. versionchanged:: 1.9
+
+    Allowed chaining additional field lookups.
+
 .. fieldlookup:: second
 
 second
 ~~~~~~
 
-For datetime fields, an exact second match. Takes an integer between 0 and 59.
+For datetime fields, an exact second match. Allows chaining additional field
+lookups. Takes an integer between 0 and 59.
 
 Example::
 
     Event.objects.filter(timestamp__second=31)
+    Event.objects.filter(timestamp__second__gte=31)
 
 SQL equivalent::
 
     SELECT ... WHERE EXTRACT('second' FROM timestamp) = '31';
+    SELECT ... WHERE EXTRACT('second' FROM timestamp) >= '31';
 
 (The exact SQL syntax varies for each database engine.)
 
 When :setting:`USE_TZ` is ``True``, values are converted to the current time
 zone before filtering.
 
+.. versionchanged:: 1.9
+
+    Allowed chaining additional field lookups.
+
 .. fieldlookup:: isnull
 
 isnull