diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt index 8b5342c54b1..d6c48f966ce 100644 --- a/docs/ref/models/database-functions.txt +++ b/docs/ref/models/database-functions.txt @@ -286,9 +286,9 @@ Date Functions We'll be using the following model in examples of each function:: class Experiment(models.Model): - start_time = models.DateTimeField() + start_datetime = models.DateTimeField() start_date = models.DateField(null=True, blank=True) - end_time = models.DateTimeField(null=True, blank=True) + end_datetime = models.DateTimeField(null=True, blank=True) end_date = models.DateField(null=True, blank=True) ``Extract`` @@ -349,16 +349,16 @@ Usage example:: >>> start = datetime(2015, 6, 15) >>> end = datetime(2015, 7, 2) >>> Experiment.objects.create( - ... start_time=start, start_date=start.date(), - ... end_time=end, end_date=end.date()) + ... start_datetime=start, start_date=start.date(), + ... end_datetime=end, end_date=end.date()) >>> # Add the experiment start year as a field in the QuerySet. >>> experiment = Experiment.objects.annotate( - ... start_year=Extract('start_time', 'year')).get() + ... start_year=Extract('start_datetime', 'year')).get() >>> experiment.start_year 2015 >>> # How many experiments completed in the same year in which they started? >>> Experiment.objects.filter( - ... start_time__year=Extract('end_time', 'year')).count() + ... start_datetime__year=Extract('end_datetime', 'year')).count() 1 ``DateField`` extracts @@ -395,8 +395,8 @@ that deal with date-parts can be used with ``DateField``:: >>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=timezone.utc) >>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=timezone.utc) >>> Experiment.objects.create( - ... start_time=start_2015, start_date=start_2015.date(), - ... end_time=end_2015, end_date=end_2015.date()) + ... start_datetime=start_2015, start_date=start_2015.date(), + ... end_datetime=end_2015, end_date=end_2015.date()) >>> Experiment.objects.annotate( ... year=ExtractYear('start_date'), ... month=ExtractMonth('start_date'), @@ -440,19 +440,19 @@ Each class is also a ``Transform`` registered on ``DateTimeField`` as >>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=timezone.utc) >>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=timezone.utc) >>> Experiment.objects.create( - ... start_time=start_2015, start_date=start_2015.date(), - ... end_time=end_2015, end_date=end_2015.date()) + ... start_datetime=start_2015, start_date=start_2015.date(), + ... end_datetime=end_2015, end_date=end_2015.date()) >>> Experiment.objects.annotate( - ... year=ExtractYear('start_time'), - ... month=ExtractMonth('start_time'), - ... day=ExtractDay('start_time'), - ... weekday=ExtractWeekDay('start_time'), - ... hour=ExtractHour('start_time'), - ... minute=ExtractMinute('start_time'), - ... second=ExtractSecond('start_time'), + ... year=ExtractYear('start_datetime'), + ... month=ExtractMonth('start_datetime'), + ... day=ExtractDay('start_datetime'), + ... weekday=ExtractWeekDay('start_datetime'), + ... hour=ExtractHour('start_datetime'), + ... minute=ExtractMinute('start_datetime'), + ... second=ExtractSecond('start_datetime'), ... ).values( ... 'year', 'month', 'day', 'weekday', 'hour', 'minute', 'second', - ... ).get(end_time__year=ExtractYear('start_time')) + ... ).get(end_datetime__year=ExtractYear('start_datetime')) {'year': 2015, 'month': 6, 'day': 15, 'weekday': 2, 'hour': 23, 'minute': 30, 'second': 1} When :setting:`USE_TZ` is ``True`` then datetimes are stored in the database @@ -465,11 +465,11 @@ values that are returned:: >>> tzinfo = pytz.timezone('Australia/Melbourne') # UTC+10:00 >>> with timezone.override(tzinfo): ... Experiment.objects.annotate( - ... day=ExtractDay('start_time'), - ... weekday=ExtractWeekDay('start_time'), - ... hour=ExtractHour('start_time'), + ... day=ExtractDay('start_datetime'), + ... weekday=ExtractWeekDay('start_datetime'), + ... hour=ExtractHour('start_datetime'), ... ).values('day', 'weekday', 'hour').get( - ... end_time__year=ExtractYear('start_time'), + ... end_datetime__year=ExtractYear('start_datetime'), ... ) {'day': 16, 'weekday': 3, 'hour': 9} @@ -479,11 +479,11 @@ way, and takes priority over an active timezone:: >>> import pytz >>> tzinfo = pytz.timezone('Australia/Melbourne') >>> Experiment.objects.annotate( - ... day=ExtractDay('start_time', tzinfo=melb), - ... weekday=ExtractWeekDay('start_time', tzinfo=melb), - ... hour=ExtractHour('start_time', tzinfo=melb), + ... day=ExtractDay('start_datetime', tzinfo=melb), + ... weekday=ExtractWeekDay('start_datetime', tzinfo=melb), + ... hour=ExtractHour('start_datetime', tzinfo=melb), ... ).values('day', 'weekday', 'hour').get( - ... end_time__year=ExtractYear('start_time'), + ... end_datetime__year=ExtractYear('start_datetime'), ... ) {'day': 16, 'weekday': 3, 'hour': 9} @@ -546,11 +546,11 @@ Usage example:: >>> from datetime import datetime >>> from django.db.models import Count, DateTimeField >>> from django.db.models.functions import Trunc - >>> Experiment.objects.create(start_time=datetime(2015, 6, 15, 14, 30, 50, 321)) - >>> Experiment.objects.create(start_time=datetime(2015, 6, 15, 14, 40, 2, 123)) - >>> Experiment.objects.create(start_time=datetime(2015, 12, 25, 10, 5, 27, 999)) + >>> Experiment.objects.create(start_datetime=datetime(2015, 6, 15, 14, 30, 50, 321)) + >>> Experiment.objects.create(start_datetime=datetime(2015, 6, 15, 14, 40, 2, 123)) + >>> Experiment.objects.create(start_datetime=datetime(2015, 12, 25, 10, 5, 27, 999)) >>> experiments_per_day = Experiment.objects.annotate( - ... start_day=Trunc('start_time', 'day', output_field=DateTimeField()) + ... start_day=Trunc('start_datetime', 'day', output_field=DateTimeField()) ... ).values('start_day').annotate(experiments=Count('id')) >>> for exp in experiments_per_day: ... print(exp['start_day'], exp['experiments']) @@ -558,10 +558,10 @@ Usage example:: 2015-06-15 00:00:00 2 2015-12-25 00:00:00 1 >>> experiments = Experiment.objects.annotate( - ... start_day=Trunc('start_time', 'day', output_field=DateTimeField()) + ... start_day=Trunc('start_datetime', 'day', output_field=DateTimeField()) ... ).filter(start_day=datetime(2015, 6, 15)) >>> for exp in experiments: - ... print(exp.start_time) + ... print(exp.start_datetime) ... 2015-06-15 14:30:50.000321 2015-06-15 14:40:02.000123 @@ -592,9 +592,9 @@ that deal with date-parts can be used with ``DateField``:: >>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc) >>> start2 = datetime(2015, 6, 15, 14, 40, 2, 123, tzinfo=timezone.utc) >>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=timezone.utc) - >>> Experiment.objects.create(start_time=start1, start_date=start1.date()) - >>> Experiment.objects.create(start_time=start2, start_date=start2.date()) - >>> Experiment.objects.create(start_time=start3, start_date=start3.date()) + >>> Experiment.objects.create(start_datetime=start1, start_date=start1.date()) + >>> Experiment.objects.create(start_datetime=start2, start_date=start2.date()) + >>> Experiment.objects.create(start_datetime=start3, start_date=start3.date()) >>> experiments_per_year = Experiment.objects.annotate( ... year=TruncYear('start_date')).values('year').annotate( ... experiments=Count('id')) @@ -607,7 +607,7 @@ that deal with date-parts can be used with ``DateField``:: >>> import pytz >>> melb = pytz.timezone('Australia/Melbourne') >>> experiments_per_month = Experiment.objects.annotate( - ... month=TruncMonth('start_time', tzinfo=melb)).values('month').annotate( + ... month=TruncMonth('start_datetime', tzinfo=melb)).values('month').annotate( ... experiments=Count('id')) >>> for exp in experiments_per_month: ... print(exp['month'], exp['experiments']) @@ -659,14 +659,14 @@ Usage example:: >>> from django.utils import timezone >>> import pytz >>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc) - >>> Experiment.objects.create(start_time=start1, start_date=start1.date()) + >>> Experiment.objects.create(start_datetime=start1, start_date=start1.date()) >>> melb = pytz.timezone('Australia/Melbourne') >>> Experiment.objects.annotate( - ... date=TruncDate('start_time'), - ... day=TruncDay('start_time', tzinfo=melb), - ... hour=TruncHour('start_time', tzinfo=melb), - ... minute=TruncMinute('start_time'), - ... second=TruncSecond('start_time'), + ... date=TruncDate('start_datetime'), + ... day=TruncDay('start_datetime', tzinfo=melb), + ... hour=TruncHour('start_datetime', tzinfo=melb), + ... minute=TruncMinute('start_datetime'), + ... second=TruncSecond('start_datetime'), ... ).values('date', 'day', 'hour', 'minute', 'second').get() {'date': datetime.date(2014, 6, 15), 'day': datetime.datetime(2014, 6, 16, 0, 0, tzinfo=),