1 """

     2 7. The lookup API

     3 

     4 This demonstrates features of the database API.

     5 """

     6 

     7 from django.db import models

     8 

     9 class Article(models.Model):

    10     headline = models.CharField(maxlength=100)

    11     pub_date = models.DateTimeField()

    12     class Meta:

    13         ordering = ('-pub_date', 'headline')

    14 

    15     def __str__(self):

    16         return self.headline

    17 

    18 __test__ = {'API_TESTS':r"""

    19 # Create a couple of Articles.

    20 >>> from datetime import datetime

    21 >>> a1 = Article(headline='Article 1', pub_date=datetime(2005, 7, 26))

    22 >>> a1.save()

    23 >>> a2 = Article(headline='Article 2', pub_date=datetime(2005, 7, 27))

    24 >>> a2.save()

    25 >>> a3 = Article(headline='Article 3', pub_date=datetime(2005, 7, 27))

    26 >>> a3.save()

    27 >>> a4 = Article(headline='Article 4', pub_date=datetime(2005, 7, 28))

    28 >>> a4.save()

    29 >>> a5 = Article(headline='Article 5', pub_date=datetime(2005, 8, 1, 9, 0))

    30 >>> a5.save()

    31 >>> a6 = Article(headline='Article 6', pub_date=datetime(2005, 8, 1, 8, 0))

    32 >>> a6.save()

    33 >>> a7 = Article(headline='Article 7', pub_date=datetime(2005, 7, 27))

    34 >>> a7.save()

    35 

    36 # Each QuerySet gets iterator(), which is a generator that "lazily" returns

    37 # results using database-level iteration.

    38 >>> for a in Article.objects.iterator():

    39 ...     print a.headline

    40 Article 5

    41 Article 6

    42 Article 4

    43 Article 2

    44 Article 3

    45 Article 7

    46 Article 1

    47 

    48 # iterator() can be used on any QuerySet.

    49 >>> for a in Article.objects.filter(headline__endswith='4').iterator():

    50 ...     print a.headline

    51 Article 4

    52 

    53 # count() returns the number of objects matching search criteria.

    54 >>> Article.objects.count()

    55 7L

    56 >>> Article.objects.filter(pub_date__exact=datetime(2005, 7, 27)).count()

    57 3L

    58 >>> Article.objects.filter(headline__startswith='Blah blah').count()

    59 0L

    60 

    61 # count() should respect sliced query sets.

    62 >>> articles = Article.objects.all()

    63 >>> articles.count()

    64 7L

    65 >>> articles[:4].count()

    66 4

    67 >>> articles[1:100].count()

    68 6L

    69 >>> articles[10:100].count()

    70 0

    71 

    72 # Date and date/time lookups can also be done with strings.

    73 >>> Article.objects.filter(pub_date__exact='2005-07-27 00:00:00').count()

    74 3L

    75 

    76 # in_bulk() takes a list of IDs and returns a dictionary mapping IDs

    77 # to objects.

    78 >>> Article.objects.in_bulk([1, 2])

    79 {1: <Article: Article 1>, 2: <Article: Article 2>}

    80 >>> Article.objects.in_bulk([3])

    81 {3: <Article: Article 3>}

    82 >>> Article.objects.in_bulk([1000])

    83 {}

    84 >>> Article.objects.in_bulk([])

    85 {}

    86 >>> Article.objects.in_bulk('foo')

    87 Traceback (most recent call last):

    88     ...

    89 AssertionError: in_bulk() must be provided with a list of IDs.

    90 >>> Article.objects.in_bulk()

    91 Traceback (most recent call last):

    92     ...

    93 TypeError: in_bulk() takes exactly 2 arguments (1 given)

    94 >>> Article.objects.in_bulk(headline__startswith='Blah')

    95 Traceback (most recent call last):

    96     ...

    97 TypeError: in_bulk() got an unexpected keyword argument 'headline__startswith'

    98 

    99 # values() returns a list of dictionaries instead of object instances -- and

   100 # you can specify which fields you want to retrieve.

   101 >>> Article.objects.values('headline')

   102 [{'headline': 'Article 5'}, {'headline': 'Article 6'}, {'headline': 'Article 4'}, {'headline': 'Article 2'}, {'headline': 'Article 3'}, {'headline': 'Article 7'}, {'headline': 'Article 1'}]

   103 >>> Article.objects.filter(pub_date__exact=datetime(2005, 7, 27)).values('id')

   104 [{'id': 2}, {'id': 3}, {'id': 7}]

   105 >>> list(Article.objects.values('id', 'headline')) == [{'id': 5, 'headline': 'Article 5'}, {'id': 6, 'headline': 'Article 6'}, {'id': 4, 'headline': 'Article 4'}, {'id': 2, 'headline': 'Article 2'}, {'id': 3, 'headline': 'Article 3'}, {'id': 7, 'headline': 'Article 7'}, {'id': 1, 'headline': 'Article 1'}]

   106 True

   107 

   108 >>> for d in Article.objects.values('id', 'headline'):

   109 ...     i = d.items()

   110 ...     i.sort()

   111 ...     i

   112 [('headline', 'Article 5'), ('id', 5)]

   113 [('headline', 'Article 6'), ('id', 6)]

   114 [('headline', 'Article 4'), ('id', 4)]

   115 [('headline', 'Article 2'), ('id', 2)]

   116 [('headline', 'Article 3'), ('id', 3)]

   117 [('headline', 'Article 7'), ('id', 7)]

   118 [('headline', 'Article 1'), ('id', 1)]

   119 

   120 # You can use values() with iterator() for memory savings, because iterator()

   121 # uses database-level iteration.

   122 >>> for d in Article.objects.values('id', 'headline').iterator():

   123 ...     i = d.items()

   124 ...     i.sort()

   125 ...     i

   126 [('headline', 'Article 5'), ('id', 5)]

   127 [('headline', 'Article 6'), ('id', 6)]

   128 [('headline', 'Article 4'), ('id', 4)]

   129 [('headline', 'Article 2'), ('id', 2)]

   130 [('headline', 'Article 3'), ('id', 3)]

   131 [('headline', 'Article 7'), ('id', 7)]

   132 [('headline', 'Article 1'), ('id', 1)]

   133 

   134 # if you don't specify which fields, all are returned

   135 >>> list(Article.objects.filter(id=5).values()) == [{'id': 5, 'headline': 'Article 5', 'pub_date': datetime(2005, 8, 1, 9, 0)}]

   136 True

   137 

   138 # Every DateField and DateTimeField creates get_next_by_FOO() and

   139 # get_previous_by_FOO() methods.

   140 # In the case of identical date values, these methods will use the ID as a

   141 # fallback check. This guarantees that no records are skipped or duplicated.

   142 >>> a1.get_next_by_pub_date()

   143 <Article: Article 2>

   144 >>> a2.get_next_by_pub_date()

   145 <Article: Article 3>

   146 >>> a2.get_next_by_pub_date(headline__endswith='6')

   147 <Article: Article 6>

   148 >>> a3.get_next_by_pub_date()

   149 <Article: Article 7>

   150 >>> a4.get_next_by_pub_date()

   151 <Article: Article 6>

   152 >>> a5.get_next_by_pub_date()

   153 Traceback (most recent call last):

   154     ...

   155 DoesNotExist: Article matching query does not exist.

   156 >>> a6.get_next_by_pub_date()

   157 <Article: Article 5>

   158 >>> a7.get_next_by_pub_date()

   159 <Article: Article 4>

   160 

   161 >>> a7.get_previous_by_pub_date()

   162 <Article: Article 3>

   163 >>> a6.get_previous_by_pub_date()

   164 <Article: Article 4>

   165 >>> a5.get_previous_by_pub_date()

   166 <Article: Article 6>

   167 >>> a4.get_previous_by_pub_date()

   168 <Article: Article 7>

   169 >>> a3.get_previous_by_pub_date()

   170 <Article: Article 2>

   171 >>> a2.get_previous_by_pub_date()

   172 <Article: Article 1>

   173 

   174 # Underscores and percent signs have special meaning in the underlying

   175 # SQL code, but Django handles the quoting of them automatically.

   176 >>> a8 = Article(headline='Article_ with underscore', pub_date=datetime(2005, 11, 20))

   177 >>> a8.save()

   178 >>> Article.objects.filter(headline__startswith='Article')

   179 [<Article: Article_ with underscore>, <Article: Article 5>, <Article: Article 6>, <Article: Article 4>, <Article: Article 2>, <Article: Article 3>, <Article: Article 7>, <Article: Article 1>]

   180 >>> Article.objects.filter(headline__startswith='Article_')

   181 [<Article: Article_ with underscore>]

   182 

   183 >>> a9 = Article(headline='Article% with percent sign', pub_date=datetime(2005, 11, 21))

   184 >>> a9.save()

   185 >>> Article.objects.filter(headline__startswith='Article')

   186 [<Article: Article% with percent sign>, <Article: Article_ with underscore>, <Article: Article 5>, <Article: Article 6>, <Article: Article 4>, <Article: Article 2>, <Article: Article 3>, <Article: Article 7>, <Article: Article 1>]

   187 >>> Article.objects.filter(headline__startswith='Article%')

   188 [<Article: Article% with percent sign>]

   189 

   190 # exclude() is the opposite of filter() when doing lookups:

   191 >>> Article.objects.filter(headline__contains='Article').exclude(headline__contains='with')

   192 [<Article: Article 5>, <Article: Article 6>, <Article: Article 4>, <Article: Article 2>, <Article: Article 3>, <Article: Article 7>, <Article: Article 1>]

   193 >>> Article.objects.exclude(headline__startswith="Article_")

   194 [<Article: Article% with percent sign>, <Article: Article 5>, <Article: Article 6>, <Article: Article 4>, <Article: Article 2>, <Article: Article 3>, <Article: Article 7>, <Article: Article 1>]

   195 >>> Article.objects.exclude(headline="Article 7")

   196 [<Article: Article% with percent sign>, <Article: Article_ with underscore>, <Article: Article 5>, <Article: Article 6>, <Article: Article 4>, <Article: Article 2>, <Article: Article 3>, <Article: Article 1>]

   197 

   198 # Backslashes also have special meaning in the underlying SQL code, but Django

   199 # automatically quotes them appropriately.

   200 >>> a10 = Article(headline='Article with \\ backslash', pub_date=datetime(2005, 11, 22))

   201 >>> a10.save()

   202 >>> Article.objects.filter(headline__contains='\\')

   203 [<Article: Article with \ backslash>]

   204 

   205 # none() returns an EmptyQuerySet that behaves like any other QuerySet object

   206 >>> Article.objects.none()

   207 []

   208 >>> Article.objects.none().filter(headline__startswith='Article')

   209 []

   210 >>> Article.objects.none().count()

   211 0

   212 >>> [article for article in Article.objects.none().iterator()]

   213 []

   214 

   215 # using __in with an empty list should return an empty query set

   216 >>> Article.objects.filter(id__in=[])

   217 []

   218 

   219 >>> Article.objects.exclude(id__in=[])

   220 [<Article: Article with \ backslash>, <Article: Article% with percent sign>, <Article: Article_ with underscore>, <Article: Article 5>, <Article: Article 6>, <Article: Article 4>, <Article: Article 2>, <Article: Article 3>, <Article: Article 7>, <Article: Article 1>]

   221 

   222 # Programming errors are pointed out with nice error messages

   223 >>> Article.objects.filter(pub_date_year='2005').count()

   224 Traceback (most recent call last):

   225     ...

   226 TypeError: Cannot resolve keyword 'pub_date_year' into field

   227 

   228 >>> Article.objects.filter(headline__starts='Article')

   229 Traceback (most recent call last):

   230     ...

   231 TypeError: Cannot resolve keyword 'headline__starts' into field

   232 

   233 """}