schema-evolution: update from HEAD (v5821)

git-svn-id: http://code.djangoproject.com/svn/django/branches/schema-evolution@5822 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 71 insertions, 59 deletions

diff --git a/docs/model-api.txt b/docs/model-api.txt
index 6a706c57cb..3b634de1d8 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -22,7 +22,7 @@ A companion to this document is the `official repository of model examples`_.
 ``tests/modeltests`` directory.)
 
 .. _Database API reference: ../db-api/
-.. _official repository of model examples: http://www.djangoproject.com/documentation/models/
+.. _official repository of model examples: ../models/
 
 Quick example
 =============
@@ -33,8 +33,8 @@ This example model defines a ``Person``, which has a ``first_name`` and
     from django.db import models
 
     class Person(models.Model):
-        first_name = models.CharField(maxlength=30)
-        last_name = models.CharField(maxlength=30)
+        first_name = models.CharField(max_length=30)
+        last_name = models.CharField(max_length=30)
 
 ``first_name`` and ``last_name`` are *fields* of the model. Each field is
 specified as a class attribute, and each attribute maps to a database column.
@@ -69,13 +69,13 @@ attributes.
 Example::
 
     class Musician(models.Model):
-        first_name = models.CharField(maxlength=50)
-        last_name = models.CharField(maxlength=50)
-        instrument = models.CharField(maxlength=100)
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
+        instrument = models.CharField(max_length=100)
 
     class Album(models.Model):
         artist = models.ForeignKey(Musician)
-        name = models.CharField(maxlength=100)
+        name = models.CharField(max_length=100)
         release_date = models.DateField()
         num_stars = models.IntegerField()
 
@@ -142,14 +142,18 @@ For large amounts of text, use ``TextField``.
 
 The admin represents this as an ``<input type="text">`` (a single-line input).
 
-``CharField`` has an extra required argument, ``maxlength``, the maximum length
-(in characters) of the field. The maxlength is enforced at the database level
+``CharField`` has an extra required argument, ``max_length``, the maximum length
+(in characters) of the field. The max_length is enforced at the database level
 and in Django's validation.
 
-``CommaSeparatedIntegerField``
+Django veterans: Note that the argument is now called ``max_length`` to
+provide consistency throughout Django. There is full legacy support for
+the old ``maxlength`` argument, but ``max_length`` is prefered.
+	
+ ``CommaSeparatedIntegerField``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A field of integers separated by commas. As in ``CharField``, the ``maxlength``
+A field of integers separated by commas. As in ``CharField``, the ``max_length``
 argument is required.
 
 ``DateField``
@@ -217,7 +221,7 @@ The admin represents this as an ``<input type="text">`` (a single-line input).
 ~~~~~~~~~~~~~~
 
 A ``CharField`` that checks that the value is a valid e-mail address.
-This doesn't accept ``maxlength``; its ``maxlength`` is automatically set to
+This doesn't accept ``max_length``; its ``max_length`` is automatically set to
 75.
 
 ``FileField``
@@ -400,7 +404,7 @@ Like a ``PositiveIntegerField``, but only allows values under a certain
 containing only letters, numbers, underscores or hyphens. They're generally
 used in URLs.
 
-Like a CharField, you can specify ``maxlength``. If ``maxlength`` is
+Like a CharField, you can specify ``max_length``. If ``max_length`` is
 not specified, Django will use a default length of 50.
 
 Implies ``db_index=True``.
@@ -447,9 +451,9 @@ and doesn't give a 404 response).
 
 The admin represents this as an ``<input type="text">`` (a single-line input).
 
-``URLField`` takes an optional argument, ``maxlength``, the maximum length (in
-characters) of the field. The maxlength is enforced at the database level and
-in Django's validation. If you don't specify ``maxlength``, a default of 200
+``URLField`` takes an optional argument, ``max_length``, the maximum length (in
+characters) of the field. The maximum length is enforced at the database level and
+in Django's validation. If you don't specify ``max_length``, a default of 200
 is used.
 
 ``USStateField``
@@ -536,7 +540,7 @@ The choices list can be defined either as part of your model class::
             ('M', 'Male'),
             ('F', 'Female'),
         )
-        gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)
+        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
 
 or outside your model class altogether::
 
@@ -545,7 +549,7 @@ or outside your model class altogether::
         ('F', 'Female'),
     )
     class Foo(models.Model):
-        gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)
+        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
 
 For each model field that has ``choices`` set, Django will add a method to
 retrieve the human-readable name for the field's current value. See
@@ -620,6 +624,12 @@ Extra "help" text to be displayed under the field on the object's admin
 form. It's useful for documentation even if your object doesn't have an
 admin form.
 
+Note that this value is *not* HTML-escaped when it's displayed in the admin
+interface. This lets you include HTML in ``help_text`` if you so desire. For
+example::
+
+	help_text="Please use the following format: <em>YYYY-MM-DD</em>."
+
 ``primary_key``
 ~~~~~~~~~~~~~~~
 
@@ -698,11 +708,11 @@ it using the field's attribute name, converting underscores to spaces.
 
 In this example, the verbose name is ``"Person's first name"``::
 
-    first_name = models.CharField("Person's first name", maxlength=30)
+    first_name = models.CharField("Person's first name", max_length=30)
 
 In this example, the verbose name is ``"first name"``::
 
-    first_name = models.CharField(maxlength=30)
+    first_name = models.CharField(max_length=30)
 
 ``ForeignKey``, ``ManyToManyField`` and ``OneToOneField`` require the first
 argument to be a model class, so use the ``verbose_name`` keyword argument::
@@ -775,7 +785,7 @@ You can, of course, call the field whatever you want. For example::
 
 See the `Many-to-one relationship model example`_ for a full example.
 
-.. _Many-to-one relationship model example: http://www.djangoproject.com/documentation/models/many_to_one/
+.. _Many-to-one relationship model example: ../models/many_to_one/
 
 ``ForeignKey`` fields take a number of extra arguments for defining how the
 relationship should work. All are optional:
@@ -902,7 +912,7 @@ set up above, the ``Pizza`` admin form would let users select the toppings.
 
 See the `Many-to-many relationship model example`_ for a full example.
 
-.. _Many-to-many relationship model example: http://www.djangoproject.com/documentation/models/many_to_many/
+.. _Many-to-many relationship model example: ../models/many_to_many/
 
 ``ManyToManyField`` objects take a number of extra arguments for defining how
 the relationship should work. All are optional:
@@ -979,7 +989,7 @@ as a read-only field when you edit an object in the admin interface:
 
 See the `One-to-one relationship model example`_ for a full example.
 
-.. _One-to-one relationship model example: http://www.djangoproject.com/documentation/models/one_to_one/
+.. _One-to-one relationship model example: ../models/one_to_one/
 
 Custom field types
 ------------------
@@ -1027,8 +1037,8 @@ Once you have ``MytypeField``, you can use it in any model, just like any other
 ``Field`` type::
 
     class Person(models.Model):
-        name = models.CharField(maxlength=80)
-        gender = models.CharField(maxlength=1)
+        name = models.CharField(max_length=80)
+        gender = models.CharField(max_length=1)
         something_else = MytypeField()
 
 If you aim to build a database-agnostic application, you should account for
@@ -1074,12 +1084,12 @@ time -- i.e., when the class is instantiated. To do that, just implement
 
     # This is a much more flexible example.
     class BetterCharField(models.Field):
-        def __init__(self, maxlength, *args, **kwargs):
-            self.maxlength = maxlength
+        def __init__(self, max_length, *args, **kwargs):
+            self.max_length = max_length
             super(BetterCharField, self).__init__(*args, **kwargs)
 
         def db_type(self):
-            return 'char(%s)' % self.maxlength
+            return 'char(%s)' % self.max_length
 
     # In the model:
     class MyModel(models.Model):
@@ -1096,7 +1106,7 @@ Meta options
 Give your model metadata by using an inner ``class Meta``, like so::
 
     class Foo(models.Model):
-        bar = models.CharField(maxlength=30)
+        bar = models.CharField(max_length=30)
 
         class Meta:
             # ...
@@ -1186,7 +1196,7 @@ See `Specifying ordering`_ for more examples.
 Note that, regardless of how many fields are in ``ordering``, the admin
 site uses only the first field.
 
-.. _Specifying ordering: http://www.djangoproject.com/documentation/models/ordering/
+.. _Specifying ordering: ../models/ordering/
 
 ``permissions``
 ---------------
@@ -1270,8 +1280,8 @@ If you want your model to be visible to Django's admin site, give your model an
 inner ``"class Admin"``, like so::
 
     class Person(models.Model):
-        first_name = models.CharField(maxlength=30)
-        last_name = models.CharField(maxlength=30)
+        first_name = models.CharField(max_length=30)
+        last_name = models.CharField(max_length=30)
 
         class Admin:
             # Admin options go here
@@ -1430,7 +1440,7 @@ A few special cases to note about ``list_display``:
       Here's a full example model::
 
           class Person(models.Model):
-              name = models.CharField(maxlength=50)
+              name = models.CharField(max_length=50)
               birthday = models.DateField()
 
               class Admin:
@@ -1447,9 +1457,9 @@ A few special cases to note about ``list_display``:
       Here's a full example model::
 
           class Person(models.Model):
-              first_name = models.CharField(maxlength=50)
-              last_name = models.CharField(maxlength=50)
-              color_code = models.CharField(maxlength=6)
+              first_name = models.CharField(max_length=50)
+              last_name = models.CharField(max_length=50)
+              color_code = models.CharField(max_length=6)
 
               class Admin:
                   list_display = ('first_name', 'last_name', 'colored_name')
@@ -1465,7 +1475,7 @@ A few special cases to note about ``list_display``:
       Here's a full example model::
 
           class Person(models.Model):
-              first_name = models.CharField(maxlength=50)
+              first_name = models.CharField(max_length=50)
               birthday = models.DateField()
 
               class Admin:
@@ -1493,8 +1503,8 @@ A few special cases to note about ``list_display``:
       For example::
 
         class Person(models.Model):
-            first_name = models.CharField(maxlength=50)
-            color_code = models.CharField(maxlength=6)
+            first_name = models.CharField(max_length=50)
+            color_code = models.CharField(max_length=6)
 
             class Admin:
                 list_display = ('first_name', 'colored_first_name')
@@ -1744,13 +1754,13 @@ returns a list of all ``OpinionPoll`` objects, each with an extra
             return result_list
 
     class OpinionPoll(models.Model):
-        question = models.CharField(maxlength=200)
+        question = models.CharField(max_length=200)
         poll_date = models.DateField()
         objects = PollManager()
 
     class Response(models.Model):
         poll = models.ForeignKey(Poll)
-        person_name = models.CharField(maxlength=50)
+        person_name = models.CharField(max_length=50)
         response = models.TextField()
 
 With this example, you'd use ``OpinionPoll.objects.with_counts()`` to return
@@ -1766,8 +1776,8 @@ A ``Manager``'s base ``QuerySet`` returns all objects in the system. For
 example, using this model::
 
     class Book(models.Model):
-        title = models.CharField(maxlength=100)
-        author = models.CharField(maxlength=50)
+        title = models.CharField(max_length=100)
+        author = models.CharField(max_length=50)
 
 ...the statement ``Book.objects.all()`` will return all books in the database.
 
@@ -1785,8 +1795,8 @@ all objects, and one that returns only the books by Roald Dahl::
 
     # Then hook it into the Book model explicitly.
     class Book(models.Model):
-        title = models.CharField(maxlength=100)
-        author = models.CharField(maxlength=50)
+        title = models.CharField(max_length=100)
+        author = models.CharField(max_length=50)
 
         objects = models.Manager() # The default manager.
         dahl_objects = DahlBookManager() # The Dahl-specific manager.
@@ -1819,9 +1829,9 @@ For example::
             return super(FemaleManager, self).get_query_set().filter(sex='F')
 
     class Person(models.Model):
-        first_name = models.CharField(maxlength=50)
-        last_name = models.CharField(maxlength=50)
-        sex = models.CharField(maxlength=1, choices=(('M', 'Male'), ('F', 'Female')))
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
+        sex = models.CharField(max_length=1, choices=(('M', 'Male'), ('F', 'Female')))
         people = models.Manager()
         men = MaleManager()
         women = FemaleManager()
@@ -1851,11 +1861,11 @@ model.
 For example, this model has a few custom methods::
 
     class Person(models.Model):
-        first_name = models.CharField(maxlength=50)
-        last_name = models.CharField(maxlength=50)
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
         birth_date = models.DateField()
-        address = models.CharField(maxlength=100)
-        city = models.CharField(maxlength=50)
+        address = models.CharField(max_length=100)
+        city = models.CharField(max_length=50)
         state = models.USStateField() # Yes, this is America-centric...
 
         def baby_boomer_status(self):
@@ -1897,8 +1907,8 @@ Although this isn't required, it's strongly encouraged (see the description of
 For example::
 
     class Person(models.Model):
-        first_name = models.CharField(maxlength=50)
-        last_name = models.CharField(maxlength=50)
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
 
         def __str__(self):
             # Note use of django.utils.encoding.smart_str() here because
@@ -1915,8 +1925,8 @@ method for your model. The example in the previous section could be written
 more simply as::
 
     class Person(models.Model):
-        first_name = models.CharField(maxlength=50)
-        last_name = models.CharField(maxlength=50)
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
 
         def __unicode__(self):
             return u'%s %s' % (self.first_name, self.last_name)
@@ -1942,10 +1952,12 @@ Django uses this in its admin interface. If an object defines
 link that will jump you directly to the object's public view, according to
 ``get_absolute_url()``.
 
-Also, a couple of other bits of Django, such as the syndication-feed framework,
+Also, a couple of other bits of Django, such as the `syndication feed framework`_,
 use ``get_absolute_url()`` as a convenience to reward people who've defined the
 method.
 
+.. syndication feed framework: ../syndication_feeds/
+
 It's good practice to use ``get_absolute_url()`` in templates, instead of
 hard-coding your objects' URLs. For example, this template code is bad::
 
@@ -2056,7 +2068,7 @@ A classic use-case for overriding the built-in methods is if you want something
 to happen whenever you save an object. For example::
 
     class Blog(models.Model):
-        name = models.CharField(maxlength=100)
+        name = models.CharField(max_length=100)
         tagline = models.TextField()
 
         def save(self):
@@ -2067,7 +2079,7 @@ to happen whenever you save an object. For example::
 You can also prevent saving::
 
     class Blog(models.Model):
-        name = models.CharField(maxlength=100)
+        name = models.CharField(max_length=100)
         tagline = models.TextField()
 
         def save(self):