Commit 90468079 authored by Simon Charette's avatar Simon Charette
Browse files

Refs #25774 -- Adjusted datetime database function docs field names.

parent c4a876a0

docs/ref/models/database-functions.txt

+42 −42
Original line number Diff line number Diff line
@@ -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=<DstTzInfo 'Australia/Melbourne' AEST+10:00:00 STD>),