Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #15309 -- reST/Sphinx cleanup on the ContentTypes Framework docs.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15544 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit e9d99c43711087c8840b725726efc7237e125477 1 parent 0577edf
authored February 16, 2011

Showing 1 changed file with 108 additions and 89 deletions. Show diff stats Hide diff stats

  1. 197  docs/ref/contrib/contenttypes.txt
197  docs/ref/contrib/contenttypes.txt
@@ -5,8 +5,8 @@ The contenttypes framework
5 5
 .. module:: django.contrib.contenttypes
6 6
    :synopsis: Provides generic interface to installed models.
7 7
 
8  
-Django includes a :mod:`contenttypes` application that can track all of
9  
-the models installed in your Django-powered project, providing a
  8
+Django includes a :mod:`~django.contrib.contenttypes` application that can
  9
+track all of the models installed in your Django-powered project, providing a
10 10
 high-level, generic interface for working with your models.
11 11
 
12 12
 Overview
@@ -54,34 +54,37 @@ installed; several of Django's other bundled applications require it:
54 54
     * Django's comments system (:mod:`django.contrib.comments`) uses it to
55 55
       "attach" comments to any installed model.
56 56
 
  57
+.. currentmodule:: django.contrib.contenttypes.models
  58
+
57 59
 The ``ContentType`` model
58 60
 =========================
59 61
 
60  
-.. class:: models.ContentType
  62
+.. class:: ContentType
61 63
 
62 64
     Each instance of :class:`~django.contrib.contenttypes.models.ContentType`
63  
-    has three fields which, taken together, uniquely describe an installed model:
  65
+    has three fields which, taken together, uniquely describe an installed
  66
+    model:
64 67
 
65  
-    .. attribute:: models.ContentType.app_label
  68
+    .. attribute:: app_label
66 69
 
67 70
         The name of the application the model is part of. This is taken from
68  
-        the :attr:`app_label` attribute of the model, and includes only the *last*
69  
-        part of the application's Python import path;
70  
-        "django.contrib.contenttypes", for example, becomes an :attr:`app_label`
71  
-        of "contenttypes".
  71
+        the :attr:`app_label` attribute of the model, and includes only the
  72
+        *last* part of the application's Python import path;
  73
+        "django.contrib.contenttypes", for example, becomes an
  74
+        :attr:`app_label` of "contenttypes".
72 75
 
73  
-    .. attribute:: models.ContentType.model
  76
+    .. attribute:: model
74 77
 
75 78
         The name of the model class.
76 79
 
77  
-    .. attribute:: models.ContentType.name
  80
+    .. attribute:: name
78 81
 
79 82
         The human-readable name of the model. This is taken from the
80  
-        :attr:`verbose_name <django.db.models.fields.Field.verbose_name>`
  83
+        :attr:`verbose_name <django.db.models.Field.verbose_name>`
81 84
         attribute of the model.
82 85
 
83 86
 Let's look at an example to see how this works. If you already have
84  
-the contenttypes application installed, and then add
  87
+the :mod:`~django.contrib.contenttypes` application installed, and then add
85 88
 :mod:`the sites application <django.contrib.sites>` to your
86 89
 :setting:`INSTALLED_APPS` setting and run ``manage.py syncdb`` to install it,
87 90
 the model :class:`django.contrib.sites.models.Site` will be installed into
@@ -89,33 +92,34 @@ your database. Along with it a new instance of
89 92
 :class:`~django.contrib.contenttypes.models.ContentType` will be
90 93
 created with the following values:
91 94
 
92  
-    * :attr:`app_label` will be set to ``'sites'`` (the last part of the Python
  95
+    * :attr:`~django.contrib.contenttypes.models.ContentType.app_label`
  96
+      will be set to ``'sites'`` (the last part of the Python
93 97
       path "django.contrib.sites").
94 98
 
95  
-    * :attr:`model` will be set to ``'site'``.
  99
+    * :attr:`~django.contrib.contenttypes.models.ContentType.model`
  100
+      will be set to ``'site'``.
96 101
 
97  
-    * :attr:`name` will be set to ``'site'``.
  102
+    * :attr:`~django.contrib.contenttypes.models.ContentType.name`
  103
+      will be set to ``'site'``.
98 104
 
99 105
 .. _the verbose_name attribute: ../model-api/#verbose_name
100 106
 
101 107
 Methods on ``ContentType`` instances
102 108
 ====================================
103 109
 
104  
-.. class:: models.ContentType
105  
-
106  
-    Each :class:`~django.contrib.contenttypes.models.ContentType` instance has
107  
-    methods that allow you to get from a
108  
-    :class:`~django.contrib.contenttypes.models.ContentType` instance to the model
109  
-    it represents, or to retrieve objects from that model:
  110
+Each :class:`~django.contrib.contenttypes.models.ContentType` instance has
  111
+methods that allow you to get from a
  112
+:class:`~django.contrib.contenttypes.models.ContentType` instance to the
  113
+model it represents, or to retrieve objects from that model:
110 114
 
111  
-.. method:: models.ContentType.get_object_for_this_type(**kwargs)
  115
+.. method:: ContentType.get_object_for_this_type(**kwargs)
112 116
 
113 117
     Takes a set of valid :ref:`lookup arguments <field-lookups-intro>` for the
114 118
     model the :class:`~django.contrib.contenttypes.models.ContentType`
115  
-    represents, and does :lookup:`a get() lookup <get>` on that model,
116  
-    returning the corresponding object.
  119
+    represents, and does :meth:`a get() lookup <django.db.models.QuerySet.get>`
  120
+    on that model, returning the corresponding object.
117 121
 
118  
-.. method:: models.ContentType.model_class()
  122
+.. method:: ContentType.model_class()
119 123
 
120 124
     Returns the model class represented by this
121 125
     :class:`~django.contrib.contenttypes.models.ContentType` instance.
@@ -129,7 +133,8 @@ For example, we could look up the
129 133
     >>> user_type
130 134
     <ContentType: user>
131 135
 
132  
-And then use it to query for a particular ``User``, or to get access
  136
+And then use it to query for a particular
  137
+:class:`~django.contrib.auth.models.User`, or to get access
133 138
 to the ``User`` model class::
134 139
 
135 140
     >>> user_type.model_class()
@@ -139,15 +144,15 @@ to the ``User`` model class::
139 144
 
140 145
 Together,
141 146
 :meth:`~django.contrib.contenttypes.models.ContentType.get_object_for_this_type`
142  
-and :meth:`~django.contrib.contenttypes.models.ContentType.model_class`
143  
-enable two extremely important use cases:
  147
+and :meth:`~django.contrib.contenttypes.models.ContentType.model_class` enable
  148
+two extremely important use cases:
144 149
 
145 150
     1. Using these methods, you can write high-level generic code that
146  
-       performs queries on any installed model -- instead of importing and using
147  
-       a single specific model class, you can pass an ``app_label`` and
148  
-       ``model`` into a :class:`~django.contrib.contenttypes.models.ContentType`
149  
-       lookup at runtime, and then work with the model class or retrieve objects
150  
-       from it.
  151
+       performs queries on any installed model -- instead of importing and
  152
+       using a single specific model class, you can pass an ``app_label`` and
  153
+       ``model`` into a
  154
+       :class:`~django.contrib.contenttypes.models.ContentType` lookup at
  155
+       runtime, and then work with the model class or retrieve objects from it.
151 156
 
152 157
     2. You can relate another model to
153 158
        :class:`~django.contrib.contenttypes.models.ContentType` as a way of
@@ -156,7 +161,7 @@ enable two extremely important use cases:
156 161
 
157 162
 Several of Django's bundled applications make use of the latter technique.
158 163
 For example,
159  
-:class:`the permissions system <django.contrib.auth.models.Permission` in
  164
+:class:`the permissions system <django.contrib.auth.models.Permission>` in
160 165
 Django's authentication framework uses a
161 166
 :class:`~django.contrib.auth.models.Permission` model with a foreign
162 167
 key to :class:`~django.contrib.contenttypes.models.ContentType`; this lets
@@ -166,36 +171,40 @@ key to :class:`~django.contrib.contenttypes.models.ContentType`; this lets
166 171
 The ``ContentTypeManager``
167 172
 --------------------------
168 173
 
169  
-.. class:: models.ContentTypeManager
  174
+.. class:: ContentTypeManager
170 175
 
171 176
     :class:`~django.contrib.contenttypes.models.ContentType` also has a custom
172 177
     manager, :class:`~django.contrib.contenttypes.models.ContentTypeManager`,
173 178
     which adds the following methods:
174 179
 
175  
-    .. method:: models.ContentTypeManager.clear_cache()
  180
+    .. method:: clear_cache()
176 181
 
177 182
         Clears an internal cache used by
178 183
         :class:`~django.contrib.contenttypes.models.ContentType` to keep track
179 184
         of which models for which it has created
180  
-        :class:`django.contrib.contenttypes.models.ContentType` instances. You
  185
+        :class:`~django.contrib.contenttypes.models.ContentType` instances. You
181 186
         probably won't ever need to call this method yourself; Django will call
182 187
         it automatically when it's needed.
183 188
 
184  
-    .. method:: models.ContentTypeManager.get_for_model(model)
  189
+    .. method:: get_for_model(model)
185 190
 
186 191
         Takes either a model class or an instance of a model, and returns the
187 192
         :class:`~django.contrib.contenttypes.models.ContentType` instance
188 193
         representing that model.
189 194
 
190  
-The :meth:`~models.ContentTypeManager.get_for_model()` method is especially useful when you know you
191  
-need to work with a :class:`ContentType <django.contrib.contenttypes.models.ContentType>` but don't want to go to the
192  
-trouble of obtaining the model's metadata to perform a manual lookup::
  195
+The :meth:`~ContentTypeManager.get_for_model()` method is especially
  196
+useful when you know you need to work with a
  197
+:class:`ContentType <django.contrib.contenttypes.models.ContentType>` but don't
  198
+want to go to the trouble of obtaining the model's metadata to perform a manual
  199
+lookup::
193 200
 
194 201
     >>> from django.contrib.auth.models import User
195 202
     >>> user_type = ContentType.objects.get_for_model(User)
196 203
     >>> user_type
197 204
     <ContentType: user>
198 205
 
  206
+.. module:: django.contrib.contenttypes.generic
  207
+
199 208
 .. _generic-relations:
200 209
 
201 210
 Generic relations
@@ -224,40 +233,42 @@ A simple example is a tagging system, which might look like this::
224 233
         def __unicode__(self):
225 234
             return self.tag
226 235
 
227  
-A normal :class:`~django.db.models.fields.related.ForeignKey` can only "point
  236
+A normal :class:`~django.db.models.ForeignKey` can only "point
228 237
 to" one other model, which means that if the ``TaggedItem`` model used a
229  
-:class:`~django.db.models.fields.related.ForeignKey` it would have to
  238
+:class:`~django.db.models.ForeignKey` it would have to
230 239
 choose one and only one model to store tags for. The contenttypes
231  
-application provides a special field type --
232  
-:class:`django.contrib.contenttypes.generic.GenericForeignKey` -- which
  240
+application provides a special field type which
233 241
 works around this and allows the relationship to be with any
234  
-model. There are three parts to setting up a
235  
-:class:`~django.contrib.contenttypes.generic.GenericForeignKey`:
236  
-
237  
-    1. Give your model a :class:`~django.db.models.fields.related.ForeignKey`
238  
-       to :class:`~django.contrib.contenttypes.models.ContentType`.
239  
-
240  
-    2. Give your model a field that can store a primary-key value from the
241  
-       models you'll be relating to. (For most models, this means an
242  
-       :class:`~django.db.models.fields.IntegerField` or
243  
-       :class:`~django.db.models.fields.PositiveIntegerField`.)
244  
-
245  
-       This field must be of the same type as the primary key of the models
246  
-       that will be involved in the generic relation. For example, if you use
247  
-       :class:`~django.db.models.fields.IntegerField`, you won't be able to
248  
-       form a generic relation with a model that uses a
249  
-       :class:`~django.db.models.fields.CharField` as a primary key.
250  
-
251  
-    3. Give your model a
252  
-       :class:`~django.contrib.contenttypes.generic.GenericForeignKey`, and
253  
-       pass it the names of the two fields described above. If these fields
254  
-       are named "content_type" and "object_id", you can omit this -- those
255  
-       are the default field names
256  
-       :class:`~django.contrib.contenttypes.generic.GenericForeignKey` will
257  
-       look for.
  242
+model:
  243
+
  244
+.. class:: GenericForeignKey
  245
+
  246
+    There are three parts to setting up a
  247
+    :class:`~django.contrib.contenttypes.generic.GenericForeignKey`:
  248
+
  249
+        1. Give your model a :class:`~django.db.models.ForeignKey`
  250
+           to :class:`~django.contrib.contenttypes.models.ContentType`.
  251
+
  252
+        2. Give your model a field that can store primary key values from the
  253
+           models you'll be relating to. For most models, this means a
  254
+           :class:`~django.db.models.PositiveIntegerField`.
  255
+           
  256
+           This field must be of the same type as the primary key of the models
  257
+           that will be involved in the generic relation. For example, if you use
  258
+           :class:`~django.db.models.fields.IntegerField`, you won't be able to
  259
+           form a generic relation with a model that uses a
  260
+           :class:`~django.db.models.fields.CharField` as a primary key.
  261
+
  262
+        3. Give your model a
  263
+           :class:`~django.contrib.contenttypes.generic.GenericForeignKey`, and
  264
+           pass it the names of the two fields described above. If these fields
  265
+           are named "content_type" and "object_id", you can omit this -- those
  266
+           are the default field names
  267
+           :class:`~django.contrib.contenttypes.generic.GenericForeignKey` will
  268
+           look for.
258 269
 
259 270
 This will enable an API similar to the one used for a normal
260  
-:class:`~django.db.models.fields.related.ForeignKey`;
  271
+:class:`~django.db.models.ForeignKey`;
261 272
 each ``TaggedItem`` will have a ``content_object`` field that returns the
262 273
 object it's related to, and you can also assign to that field or use it when
263 274
 creating a ``TaggedItem``::
@@ -271,8 +282,9 @@ creating a ``TaggedItem``::
271 282
 
272 283
 Due to the way :class:`~django.contrib.contenttypes.generic.GenericForeignKey`
273 284
 is implemented, you cannot use such fields directly with filters (``filter()``
274  
-and ``exclude()``, for example) via the database API. They aren't normal field
275  
-objects. These examples will *not* work::
  285
+and ``exclude()``, for example) via the database API. Because a 
  286
+:class:`~django.contrib.contenttypes.generic.GenericForeignKey` isn't a 
  287
+normal field objects, these examples will *not* work::
276 288
 
277 289
     # This will fail
278 290
     >>> TaggedItem.objects.filter(content_object=guido)
@@ -282,6 +294,8 @@ objects. These examples will *not* work::
282 294
 Reverse generic relations
283 295
 -------------------------
284 296
 
  297
+.. class:: GenericRelation
  298
+
285 299
 If you know which models you'll be using most often, you can also add
286 300
 a "reverse" generic relationship to enable an additional API. For example::
287 301
 
@@ -301,17 +315,20 @@ be used to retrieve their associated ``TaggedItems``::
301 315
     >>> b.tags.all()
302 316
     [<TaggedItem: django>, <TaggedItem: python>]
303 317
 
304  
-Just as :class:`django.contrib.contenttypes.generic.GenericForeignKey`
  318
+Just as :class:`~django.contrib.contenttypes.generic.GenericForeignKey`
305 319
 accepts the names of the content-type and object-ID fields as
306  
-arguments, so too does ``GenericRelation``; if the model which has the
307  
-generic foreign key is using non-default names for those fields, you
308  
-must pass the names of the fields when setting up a
309  
-``GenericRelation`` to it. For example, if the ``TaggedItem`` model
  320
+arguments, so too does
  321
+:class:`~django.contrib.contenttypes.generic.GenericRelation`;
  322
+if the model which has the generic foreign key is using non-default names
  323
+for those fields, you must pass the names of the fields when setting up a
  324
+:class:`.GenericRelation` to it. For example, if the ``TaggedItem`` model
310 325
 referred to above used fields named ``content_type_fk`` and
311 326
 ``object_primary_key`` to create its generic foreign key, then a
312  
-``GenericRelation`` back to it would need to be defined like so::
  327
+:class:`.GenericRelation` back to it would need to be defined like so::
313 328
 
314  
-    tags = generic.GenericRelation(TaggedItem, content_type_field='content_type_fk', object_id_field='object_primary_key')
  329
+    tags = generic.GenericRelation(TaggedItem,
  330
+                                   content_type_field='content_type_fk',
  331
+                                   object_id_field='object_primary_key')
315 332
 
316 333
 Of course, if you don't add the reverse relationship, you can do the
317 334
 same types of lookups manually::
@@ -332,7 +349,7 @@ the :class:`~django.contrib.contenttypes.generic.GenericRelation` to
332 349
 match the ``ct_field`` and ``fk_field``, respectively, in the
333 350
 :class:`~django.contrib.contenttypes.generic.GenericForeignKey`::
334 351
 
335  
-	comments = generic.GenericRelation(Comment, object_id_field="object_pk")
  352
+    comments = generic.GenericRelation(Comment, object_id_field="object_pk")
336 353
 
337 354
 Note also, that if you delete an object that has a
338 355
 :class:`~django.contrib.contenttypes.generic.GenericRelation`, any objects
@@ -362,37 +379,39 @@ might be tempted to try something like::
362 379
     Bookmark.objects.aggregate(Count('tags'))
363 380
 
364 381
 This will not work correctly, however. The generic relation adds extra filters
365  
-to the queryset to ensure the correct content type, but the ``aggregate`` method
366  
-doesn't take them into account. For now, if you need aggregates on generic
367  
-relations, you'll need to calculate them without using the aggregation API.
  382
+to the queryset to ensure the correct content type, but the
  383
+:meth:`~django.db.models.QuerySet.aggregate` method doesn't take them into
  384
+account. For now, if you need aggregates on generic relations, you'll need
  385
+to calculate them without using the aggregation API.
368 386
 
369 387
 Generic relations in forms and admin
370 388
 ------------------------------------
371 389
 
372  
-:mod:`django.contrib.contenttypes.generic` provides
  390
+The :mod:`django.contrib.contenttypes.generic` module provides
373 391
 :class:`~django.contrib.contenttypes.generic.GenericInlineFormSet`,
374 392
 :class:`~django.contrib.contenttypes.generic.GenericTabularInline`
375 393
 and :class:`~django.contrib.contenttypes.generic.GenericStackedInline`
376  
-(the last two subclasses of :class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin`).
  394
+(the last two are subclasses of
  395
+:class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin`).
377 396
 This enables the use of generic relations in forms and the admin. See the
378 397
 :doc:`model formset </topics/forms/modelforms>` and
379 398
 :ref:`admin <using-generic-relations-as-an-inline>` documentation for more
380 399
 information.
381 400
 
382  
-.. class:: generic.GenericInlineModelAdmin
  401
+.. class:: GenericInlineModelAdmin
383 402
 
384 403
     The :class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin`
385 404
     class inherits all properties from an
386 405
     :class:`~django.contrib.admin.InlineModelAdmin` class. However,
387 406
     it adds a couple of its own for working with the generic relation:
388 407
 
389  
-    .. attribute:: generic.GenericInlineModelAdmin.ct_field
  408
+    .. attribute:: ct_field
390 409
 
391 410
         The name of the
392 411
         :class:`~django.contrib.contenttypes.models.ContentType` foreign key
393 412
         field on the model. Defaults to ``content_type``.
394 413
 
395  
-    .. attribute:: generic.GenericInlineModelAdmin.ct_fk_field
  414
+    .. attribute:: ct_fk_field
396 415
 
397 416
         The name of the integer field that represents the ID of the related
398 417
         object. Defaults to ``object_id``.

0 notes on commit e9d99c4

Please sign in to comment.
Something went wrong with that request. Please try again.