From e69348b4e7f07ef927edaecc7126901fc91c79d0 Mon Sep 17 00:00:00 2001 From: Aymeric Augustin Date: Sat, 8 Sep 2012 11:00:04 -0400 Subject: [PATCH] Avoided mixing dates and datetimes in the examples. Refs #16023. --- docs/faq/models.txt | 2 +- docs/intro/overview.txt | 8 ++++---- docs/ref/contrib/comments/moderation.txt | 8 ++++---- docs/ref/models/fields.txt | 4 ++-- docs/ref/models/instances.txt | 2 +- docs/ref/models/querysets.txt | 13 ++++++++++++- docs/topics/db/examples/many_to_one.txt | 8 ++++---- docs/topics/db/queries.txt | 12 ++++++------ 8 files changed, 34 insertions(+), 23 deletions(-) diff --git a/docs/faq/models.txt b/docs/faq/models.txt index 4a83aa9f2cc..69965b66e18 100644 --- a/docs/faq/models.txt +++ b/docs/faq/models.txt @@ -11,7 +11,7 @@ Then, just do this:: >>> from django.db import connection >>> connection.queries - [{'sql': 'SELECT polls_polls.id,polls_polls.question,polls_polls.pub_date FROM polls_polls', + [{'sql': 'SELECT polls_polls.id, polls_polls.question, polls_polls.pub_date FROM polls_polls', 'time': '0.002'}] ``connection.queries`` is only available if :setting:`DEBUG` is ``True``. diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt index 49233fb8a76..4d5a86f82b9 100644 --- a/docs/intro/overview.txt +++ b/docs/intro/overview.txt @@ -31,7 +31,7 @@ the file ``mysite/news/models.py``:: return self.full_name class Article(models.Model): - pub_date = models.DateTimeField() + pub_date = models.DateField() headline = models.CharField(max_length=200) content = models.TextField() reporter = models.ForeignKey(Reporter) @@ -96,8 +96,8 @@ access your data. The API is created on the fly, no code generation necessary:: DoesNotExist: Reporter matching query does not exist. Lookup parameters were {'id': 2} # Create an article. - >>> from datetime import datetime - >>> a = Article(pub_date=datetime.now(), headline='Django is cool', + >>> from datetime import date + >>> a = Article(pub_date=date.today(), headline='Django is cool', ... content='Yeah.', reporter=r) >>> a.save() @@ -140,7 +140,7 @@ as registering your model in the admin site:: from django.db import models class Article(models.Model): - pub_date = models.DateTimeField() + pub_date = models.DateField() headline = models.CharField(max_length=200) content = models.TextField() reporter = models.ForeignKey(Reporter) diff --git a/docs/ref/contrib/comments/moderation.txt b/docs/ref/contrib/comments/moderation.txt index 4f4b326cb2a..f03c7fda0d5 100644 --- a/docs/ref/contrib/comments/moderation.txt +++ b/docs/ref/contrib/comments/moderation.txt @@ -32,11 +32,11 @@ A simple example is the best illustration of this. Suppose we have the following model, which would represent entries in a Weblog:: from django.db import models - + class Entry(models.Model): title = models.CharField(maxlength=250) body = models.TextField() - pub_date = models.DateTimeField() + pub_date = models.DateField() enable_comments = models.BooleanField() Now, suppose that we want the following steps to be applied whenever a @@ -55,11 +55,11 @@ Accomplishing this is fairly straightforward and requires very little code:: from django.contrib.comments.moderation import CommentModerator, moderator - + class EntryModerator(CommentModerator): email_notification = True enable_field = 'enable_comments' - + moderator.register(Entry, EntryModerator) The :class:`CommentModerator` class pre-defines a number of useful moderation diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 275c696230f..190c0037ca7 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -983,10 +983,10 @@ define the details of how the relation works. this with functions from the Python ``datetime`` module to limit choices of objects by date. For example:: - limit_choices_to = {'pub_date__lte': datetime.now} + limit_choices_to = {'pub_date__lte': datetime.date.today} only allows the choice of related objects with a ``pub_date`` before the - current date/time to be chosen. + current date to be chosen. Instead of a dictionary this can also be a :class:`~django.db.models.Q` object for more :ref:`complex queries `. However, diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 472ac964578..2fdc87df8c7 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -135,7 +135,7 @@ access to more than a single field:: raise ValidationError('Draft entries may not have a publication date.') # Set the pub_date for published items if it hasn't been set already. if self.status == 'published' and self.pub_date is None: - self.pub_date = datetime.datetime.now() + self.pub_date = datetime.date.today() Any :exc:`~django.core.exceptions.ValidationError` exceptions raised by ``Model.clean()`` will be stored in a special key error dictionary key, diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 4f5f8858b53..96fa5c9f26c 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -1945,6 +1945,17 @@ SQL equivalent:: You can use ``range`` anywhere you can use ``BETWEEN`` in SQL — for dates, numbers and even characters. +.. warning:: + + Filtering a ``DateTimeField`` with dates won't include items on the last + day, because the bounds are interpreted as "0am on the given date". If + ``pub_date`` was a ``DateTimeField``, the above expression would be turned + into this SQL:: + + SELECT ... WHERE pub_date BETWEEN '2005-01-01 00:00:00' and '2005-03-31 00:00:00'; + + Generally speaking, you can't mix dates and datetimes. + .. fieldlookup:: year year @@ -1958,7 +1969,7 @@ Example:: SQL equivalent:: - SELECT ... WHERE pub_date BETWEEN '2005-01-01' AND '2005-12-31 23:59:59.999999'; + SELECT ... WHERE pub_date BETWEEN '2005-01-01' AND '2005-12-31'; (The exact SQL syntax varies for each database engine.) diff --git a/docs/topics/db/examples/many_to_one.txt b/docs/topics/db/examples/many_to_one.txt index 0a9978b8d1f..c869362d16e 100644 --- a/docs/topics/db/examples/many_to_one.txt +++ b/docs/topics/db/examples/many_to_one.txt @@ -42,8 +42,8 @@ Create a few Reporters:: Create an Article:: - >>> from datetime import datetime - >>> a = Article(id=None, headline="This is a test", pub_date=datetime(2005, 7, 27), reporter=r) + >>> from datetime import date + >>> a = Article(id=None, headline="This is a test", pub_date=date(2005, 7, 27), reporter=r) >>> a.save() >>> a.reporter.id @@ -65,7 +65,7 @@ database, which always returns unicode strings):: Create an Article via the Reporter object:: - >>> new_article = r.article_set.create(headline="John's second story", pub_date=datetime(2005, 7, 29)) + >>> new_article = r.article_set.create(headline="John's second story", pub_date=date(2005, 7, 29)) >>> new_article >>> new_article.reporter @@ -75,7 +75,7 @@ Create an Article via the Reporter object:: Create a new article, and add it to the article set:: - >>> new_article2 = Article(headline="Paul's story", pub_date=datetime(2006, 1, 17)) + >>> new_article2 = Article(headline="Paul's story", pub_date=date(2006, 1, 17)) >>> r.article_set.add(new_article2) >>> new_article2.reporter diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index 12e9b447b3c..5385b2a72d2 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -35,8 +35,8 @@ models, which comprise a Weblog application: blog = models.ForeignKey(Blog) headline = models.CharField(max_length=255) body_text = models.TextField() - pub_date = models.DateTimeField() - mod_date = models.DateTimeField() + pub_date = models.DateField() + mod_date = models.DateField() authors = models.ManyToManyField(Author) n_comments = models.IntegerField() n_pingbacks = models.IntegerField() @@ -233,7 +233,7 @@ refinements together. For example:: >>> Entry.objects.filter( ... headline__startswith='What' ... ).exclude( - ... pub_date__gte=datetime.now() + ... pub_date__gte=datetime.date.today() ... ).filter( ... pub_date__gte=datetime(2005, 1, 30) ... ) @@ -258,8 +258,8 @@ stored, used and reused. Example:: >> q1 = Entry.objects.filter(headline__startswith="What") - >> q2 = q1.exclude(pub_date__gte=datetime.now()) - >> q3 = q1.filter(pub_date__gte=datetime.now()) + >> q2 = q1.exclude(pub_date__gte=datetime.date.today()) + >> q3 = q1.filter(pub_date__gte=datetime.date.today()) These three ``QuerySets`` are separate. The first is a base :class:`~django.db.models.query.QuerySet` containing all entries that contain a @@ -282,7 +282,7 @@ actually run the query until the :class:`~django.db.models.query.QuerySet` is *evaluated*. Take a look at this example:: >>> q = Entry.objects.filter(headline__startswith="What") - >>> q = q.filter(pub_date__lte=datetime.now()) + >>> q = q.filter(pub_date__lte=datetime.date.today()) >>> q = q.exclude(body_text__icontains="food") >>> print(q)