Ticket #14820: 14820-textfield-generic-relations-r15449.diff

docs/ref/contrib/contenttypes.txt

@@ -60 +60 @@
 .. class:: models.ContentType
 
     Each instance of :class:`~django.contrib.contenttypes.models.ContentType`
-    has three fields which, taken together, uniquely describe an installed model:
+    has three fields which, taken together, uniquely describe an installed
+    model:
 
     .. attribute:: models.ContentType.app_label
 
         The name of the application the model is part of. This is taken from
-        the :attr:`app_label` attribute of the model, and includes only the *last*
-        part of the application's Python import path;
-        "django.contrib.contenttypes", for example, becomes an :attr:`app_label`
-        of "contenttypes".
+        the :attr:`app_label` attribute of the model, and includes only the
+        *last* part of the application's Python import path;
+        "django.contrib.contenttypes", for example, becomes an
+        :attr:`app_label` of "contenttypes".
 
     .. attribute:: models.ContentType.model
 
@@ -105 +106 @@
 
     Each :class:`~django.contrib.contenttypes.models.ContentType` instance has
     methods that allow you to get from a
-    :class:`~django.contrib.contenttypes.models.ContentType` instance to the model
-    it represents, or to retrieve objects from that model:
+    :class:`~django.contrib.contenttypes.models.ContentType` instance to the
+    model it represents, or to retrieve objects from that model:
 
 .. method:: models.ContentType.get_object_for_this_type(**kwargs)
 
@@ -139 +140 @@
 
 Together,
 :meth:`~django.contrib.contenttypes.models.ContentType.get_object_for_this_type`
-and :meth:`~django.contrib.contenttypes.models.ContentType.model_class`
-enable two extremely important use cases:
+and :meth:`~django.contrib.contenttypes.models.ContentType.model_class` enable
+two extremely important use cases:
 
     1. Using these methods, you can write high-level generic code that
-       performs queries on any installed model -- instead of importing and using
-       a single specific model class, you can pass an ``app_label`` and
-       ``model`` into a :class:`~django.contrib.contenttypes.models.ContentType`
-       lookup at runtime, and then work with the model class or retrieve objects
-       from it.
+       performs queries on any installed model -- instead of importing and
+       using a single specific model class, you can pass an ``app_label`` and
+       ``model`` into a
+       :class:`~django.contrib.contenttypes.models.ContentType` lookup at
+       runtime, and then work with the model class or retrieve objects from it.
 
     2. You can relate another model to
        :class:`~django.contrib.contenttypes.models.ContentType` as a way of
@@ -187 +188 @@
         :class:`~django.contrib.contenttypes.models.ContentType` instance
         representing that model.
 
-The :meth:`~models.ContentTypeManager.get_for_model()` method is especially useful when you know you
-need to work with a :class:`ContentType <django.contrib.contenttypes.models.ContentType>` but don't want to go to the
-trouble of obtaining the model's metadata to perform a manual lookup::
+The :meth:`~models.ContentTypeManager.get_for_model()` method is especially
+useful when you know you need to work with a
+:class:`ContentType <django.contrib.contenttypes.models.ContentType>` but don't
+want to go to the trouble of obtaining the model's metadata to perform a manual
+lookup::
 
     >>> from django.contrib.auth.models import User
     >>> user_type = ContentType.objects.get_for_model(User)
@@ -237 +240 @@
     1. Give your model a :class:`~django.db.models.fields.related.ForeignKey`
        to :class:`~django.contrib.contenttypes.models.ContentType`.
 
-    2. Give your model a field that can store a primary-key value from the
-       models you'll be relating to. (For most models, this means an
-       :class:`~django.db.models.fields.IntegerField` or
-       :class:`~django.db.models.fields.PositiveIntegerField`.)
+    2. Give your model a field that can store primary key values from the
+       models you'll be relating to. For most models, this means an
+       :class:`~django.db.models.fields.PositiveIntegerField`. The usual
+       name for this field is "object_id".
 
-       This field must be of the same type as the primary key of the models
-       that will be involved in the generic relation. For example, if you use
-       :class:`~django.db.models.fields.IntegerField`, you won't be able to
-       form a generic relation with a model that uses a
-       :class:`~django.db.models.fields.CharField` as a primary key.
+       .. versionchanged:: 1.3
 
+       .. admonition:: Related model primary key field type compatibility
+
+           The "object_id" field doesn't have to be the same type as the
+           primary key fields on related models, but their primary key values
+           must be coercible to the same type as the "object_id" field by its
+           :meth:`get_db_prep_value` method.
+
+           For example, if you want to allow generic relations to your model
+           from other models with either
+           :class:`~django.db.models.fields.IntegerField` or
+           :class:`~django.db.models.fields.CharField` primary key fields, you
+           can use :class:`~django.db.models.fields.CharField` for the
+           "object_id" field in your model, because integers can be coerced to
+           strings by the
+           :meth:`~django.db.models.fields.CharField.get_db_prep_value` method.
+
+           For maximum flexibility when you don't know which models will be
+           related back to yours with generic relations, you can use
+           :class:`~django.db.models.fields.TextField` which doesn't have a
+           maximum length defined and should work in generic relations with
+           any models whose primary keys can be coerced to string.
+
+           However, keep in mind that text database columns can use more
+           memory, be less performant or have indexing woes, depending on the
+           database and its configuration. If you are certain that all related
+           models will use the one type of primary key field, it's better to
+           use the same type in your model, too.
+
     3. Give your model a
        :class:`~django.contrib.contenttypes.generic.GenericForeignKey`, and
        pass it the names of the two fields described above. If these fields
@@ -311 +338 @@
 ``object_primary_key`` to create its generic foreign key, then a
 ``GenericRelation`` back to it would need to be defined like so::
 
-    tags = generic.GenericRelation(TaggedItem, content_type_field='content_type_fk', object_id_field='object_primary_key')
+    tags = generic.GenericRelation(TaggedItem,
+                                   content_type_field='content_type_fk',
+                                   object_id_field='object_primary_key')
 
 Of course, if you don't add the reverse relationship, you can do the
 same types of lookups manually::
@@ -362 +391 @@
     Bookmark.objects.aggregate(Count('tags'))
 
 This will not work correctly, however. The generic relation adds extra filters
-to the queryset to ensure the correct content type, but the ``aggregate`` method
-doesn't take them into account. For now, if you need aggregates on generic
-relations, you'll need to calculate them without using the aggregation API.
+to the queryset to ensure the correct content type, but the ``aggregate``
+method doesn't take them into account. For now, if you need aggregates on
+generic relations, you'll need to calculate them without using the aggregation
+API.
 
 Generic relations in forms and admin
 ------------------------------------