tests/testapp/models/basic.py

   1 """
   2 1. Bare-bones model
   3
   4 This is a basic model with only two non-primary-key fields.
   5 """
   6
   7 from django.core import meta
   8
   9 class Article(meta.Model):
  10     headline = meta.CharField(maxlength=100, default='Default headline')
  11     pub_date = meta.DateTimeField()
  12
  13 API_TESTS = """
  14 # No articles are in the system yet.
  15 >>> articles.get_list()
  16 []
  17
  18 # Create an Article.
  19 >>> from datetime import datetime
  20 >>> a = articles.Article(id=None, headline='Area man programs in Python',
  21 ...     pub_date=datetime(2005, 7, 28))
  22
  23 # Save it into the database. You have to call save() explicitly.
  24 >>> a.save()
  25
  26 # Now it has an ID. Note it's a long integer, as designated by the trailing "L".
  27 >>> a.id
  28 1L
  29
  30 # Access database columns via Python attributes.
  31 >>> a.headline
  32 'Area man programs in Python'
  33 >>> a.pub_date
  34 datetime.datetime(2005, 7, 28, 0, 0)
  35
  36 # Change values by changing the attributes, then calling save().
  37 >>> a.headline = 'Area woman programs in Python'
  38 >>> a.save()
  39
  40 # get_list() displays all the articles in the database. Note that the article
  41 # is represented by "<Article object>", because we haven't given the Article
  42 # model a __repr__() method.
  43 >>> articles.get_list()
  44 [<Article object>]
  45
  46 # Django provides a rich database lookup API that's entirely driven by
  47 # keyword arguments.
  48 >>> articles.get_object(id__exact=1)
  49 <Article object>
  50 >>> articles.get_object(headline__startswith='Area woman')
  51 <Article object>
  52 >>> articles.get_object(pub_date__year=2005)
  53 <Article object>
  54 >>> articles.get_object(pub_date__year=2005, pub_date__month=7)
  55 <Article object>
  56 >>> articles.get_object(pub_date__year=2005, pub_date__month=7, pub_date__day=28)
  57 <Article object>
  58
  59 >>> articles.get_list(pub_date__year=2005)
  60 [<Article object>]
  61 >>> articles.get_list(pub_date__year=2004)
  62 []
  63 >>> articles.get_list(pub_date__year=2005, pub_date__month=7)
  64 [<Article object>]
  65
  66 # Django raises an ArticleDoesNotExist exception for get_object()
  67 >>> articles.get_object(id__exact=2)
  68 Traceback (most recent call last):
  69     ...
  70 ArticleDoesNotExist: Article does not exist for {'id__exact': 2}
  71
  72 >>> articles.get_object(pub_date__year=2005, pub_date__month=8)
  73 Traceback (most recent call last):
  74     ...
  75 ArticleDoesNotExist: Article does not exist for ...
  76
  77 # Lookup by a primary key is the most common case, so Django provides a
  78 # shortcut for primary-key exact lookups.
  79 # The following is identical to articles.get_object(id__exact=1).
  80 >>> articles.get_object(pk=1)
  81 <Article object>
  82
  83 # Model instances of the same type and same ID are considered equal.
  84 >>> a = articles.get_object(pk=1)
  85 >>> b = articles.get_object(pk=1)
  86 >>> a == b
  87 True
  88
  89 # You can initialize a model instance using positional arguments, which should
  90 # match the field order as defined in the model...
  91 >>> a2 = articles.Article(None, 'Second article', datetime(2005, 7, 29))
  92 >>> a2.save()
  93 >>> a2.id
  94 2L
  95 >>> a2.headline
  96 'Second article'
  97 >>> a2.pub_date
  98 datetime.datetime(2005, 7, 29, 0, 0)
  99
 100 # ...or, you can use keyword arguments.
 101 >>> a3 = articles.Article(id=None, headline='Third article',
 102 ...    pub_date=datetime(2005, 7, 30))
 103 >>> a3.save()
 104 >>> a3.id
 105 3L
 106 >>> a3.headline
 107 'Third article'
 108 >>> a3.pub_date
 109 datetime.datetime(2005, 7, 30, 0, 0)
 110
 111 # You can also mix and match position and keyword arguments, but be sure not to
 112 # duplicate field information.
 113 >>> a4 = articles.Article(None, 'Fourth article', pub_date=datetime(2005, 7, 31))
 114 >>> a4.save()
 115 >>> a4.headline
 116 'Fourth article'
 117
 118 # Don't use invalid keyword arguments.
 119 >>> a5 = articles.Article(id=None, headline='Invalid', pub_date=datetime(2005, 7, 31), foo='bar')
 120 Traceback (most recent call last):
 121     ...
 122 TypeError: 'foo' is an invalid keyword argument for this function
 123
 124 # You can leave off the ID.
 125 >>> a5 = articles.Article(headline='Article 6', pub_date=datetime(2005, 7, 31))
 126 >>> a5.save()
 127 >>> a5.id
 128 5L
 129 >>> a5.headline
 130 'Article 6'
 131
 132 # If you leave off a field with "default" set, Django will use the default.
 133 >>> a6 = articles.Article(pub_date=datetime(2005, 7, 31))
 134 >>> a6.save()
 135 >>> a6.headline
 136 'Default headline'
 137
 138 # For DateTimeFields, Django saves as much precision (in seconds) as you
 139 # give it.
 140 >>> a7 = articles.Article(headline='Article 7', pub_date=datetime(2005, 7, 31, 12, 30))
 141 >>> a7.save()
 142 >>> articles.get_object(id__exact=7).pub_date
 143 datetime.datetime(2005, 7, 31, 12, 30)
 144
 145 >>> a8 = articles.Article(headline='Article 8', pub_date=datetime(2005, 7, 31, 12, 30, 45))
 146 >>> a8.save()
 147 >>> articles.get_object(id__exact=8).pub_date
 148 datetime.datetime(2005, 7, 31, 12, 30, 45)
 149 >>> a8.id
 150 8L
 151
 152 # Saving an object again shouldn't create a new object -- it just saves the old one.
 153 >>> a8.save()
 154 >>> a8.id
 155 8L
 156 >>> a8.headline = 'Updated article 8'
 157 >>> a8.save()
 158 >>> a8.id
 159 8L
 160
 161 >>> a7 == a8
 162 False
 163 >>> a8 == articles.get_object(id__exact=8)
 164 True
 165 >>> a7 != a8
 166 True
 167 >>> articles.get_object(id__exact=8) != articles.get_object(id__exact=7)
 168 True
 169 >>> articles.get_object(id__exact=8) == articles.get_object(id__exact=7)
 170 False
 171 """
 172
 173 from django.conf import settings
 174
 175 building_docs = getattr(settings, 'BUILDING_DOCS', False)
 176
 177 if building_docs or settings.DATABASE_ENGINE == 'postgresql':
 178     API_TESTS += """
 179 # In PostgreSQL, microsecond-level precision is available.
 180 >>> a9 = articles.Article(headline='Article 9', pub_date=datetime(2005, 7, 31, 12, 30, 45, 180))
 181 >>> a9.save()
 182 >>> articles.get_object(id__exact=9).pub_date
 183 datetime.datetime(2005, 7, 31, 12, 30, 45, 180)
 184 """
 185
 186 if building_docs or settings.DATABASE_ENGINE == 'mysql':
 187     API_TESTS += """
 188 # In MySQL, microsecond-level precision isn't available. You'll lose
 189 # microsecond-level precision once the data is saved.
 190 >>> a9 = articles.Article(headline='Article 9', pub_date=datetime(2005, 7, 31, 12, 30, 45, 180))
 191 >>> a9.save()
 192 >>> articles.get_object(id__exact=9).pub_date
 193 datetime.datetime(2005, 7, 31, 12, 30, 45)
 194 """
 195
 196 API_TESTS += """
 197
 198 # You can manually specify the primary key when creating a new objet
 199 >>> a101 = articles.Article(id=101, headline='Article 101', pub_date=datetime(2005, 7, 31, 12, 30, 45))
 200 >>> a101.save()
 201 >>> a101 = articles.get_object(pk=101)
 202 >>> a101.headline
 203 'Article 101'
 204 """