Fixed #2101 -- Renamed `maxlength` argument to `max_length` for oldforms `FormField`s and db model `Field`s. This is fully backwards compatible at the moment since the legacy `maxlength` argument is still supported. Using `maxlength` will, however, issue a `PendingDeprecationWarning` when used.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@5803 bcc190cf-cafb-0310-a4f2-bffc1f526a37

10 files changed, 94 insertions, 90 deletions

diff --git a/docs/contributing.txt b/docs/contributing.txt
index 9dbb865a58..faa4c113f1 100644
--- a/docs/contributing.txt
+++ b/docs/contributing.txt
@@ -340,14 +340,14 @@ Model style
       Do this::
 
           class Person(models.Model):
-              first_name = models.CharField(maxlength=20)
-              last_name = models.CharField(maxlength=40)
+              first_name = models.CharField(max_length=20)
+              last_name = models.CharField(max_length=40)
 
       Don't do this::
 
           class Person(models.Model):
-              FirstName = models.CharField(maxlength=20)
-              Last_Name = models.CharField(maxlength=40)
+              FirstName = models.CharField(max_length=20)
+              Last_Name = models.CharField(max_length=40)
 
     * The ``class Meta`` should appear *after* the fields are defined, with
       a single blank line separating the fields and the class definition.
@@ -355,8 +355,8 @@ Model style
       Do this::
 
           class Person(models.Model):
-              first_name = models.CharField(maxlength=20)
-              last_name = models.CharField(maxlength=40)
+              first_name = models.CharField(max_length=20)
+              last_name = models.CharField(max_length=40)
 
               class Meta:
                   verbose_name_plural = 'people'
@@ -364,8 +364,8 @@ Model style
       Don't do this::
 
           class Person(models.Model):
-              first_name = models.CharField(maxlength=20)
-              last_name = models.CharField(maxlength=40)
+              first_name = models.CharField(max_length=20)
+              last_name = models.CharField(max_length=40)
               class Meta:
                   verbose_name_plural = 'people'
 
@@ -375,8 +375,8 @@ Model style
               class Meta:
                   verbose_name_plural = 'people'
 
-              first_name = models.CharField(maxlength=20)
-              last_name = models.CharField(maxlength=40)
+              first_name = models.CharField(max_length=20)
+              last_name = models.CharField(max_length=40)
 
     * The order of model inner classes and standard methods should be as
       follows (noting that these are not all required):
diff --git a/docs/db-api.txt b/docs/db-api.txt
index 080ab0de16..766a6ae519 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -12,14 +12,14 @@ Throughout this reference, we'll refer to the following models, which comprise
 a weblog application::
 
     class Blog(models.Model):
-        name = models.CharField(maxlength=100)
+        name = models.CharField(max_length=100)
         tagline = models.TextField()
 
         def __unicode__(self):
             return self.name
 
     class Author(models.Model):
-        name = models.CharField(maxlength=50)
+        name = models.CharField(max_length=50)
         email = models.EmailField()
 
         def __unicode__(self):
@@ -27,7 +27,7 @@ a weblog application::
 
     class Entry(models.Model):
         blog = models.ForeignKey(Blog)
-        headline = models.CharField(maxlength=255)
+        headline = models.CharField(max_length=255)
         body_text = models.TextField()
         pub_date = models.DateTimeField()
         authors = models.ManyToManyField(Author)
@@ -1806,8 +1806,8 @@ following model::
         ('F', 'Female'),
     )
     class Person(models.Model):
-        name = models.CharField(maxlength=20)
-        gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)
+        name = models.CharField(max_length=20)
+        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
 
 ...each ``Person`` instance will have a ``get_gender_display()`` method. Example::
 
diff --git a/docs/forms.txt b/docs/forms.txt
index 18d3d3fcbe..18d322a8eb 100644
--- a/docs/forms.txt
+++ b/docs/forms.txt
@@ -37,11 +37,11 @@ this document, we'll be working with the following model, a "place" object::
     )
 
     class Place(models.Model):
-        name = models.CharField(maxlength=100)
-        address = models.CharField(maxlength=100, blank=True)
-        city = models.CharField(maxlength=50, blank=True)
+        name = models.CharField(max_length=100)
+        address = models.CharField(max_length=100, blank=True)
+        city = models.CharField(max_length=50, blank=True)
         state = models.USStateField()
-        zip_code = models.CharField(maxlength=5, blank=True)
+        zip_code = models.CharField(max_length=5, blank=True)
         place_type = models.IntegerField(choices=PLACE_TYPES)
 
         class Admin:
@@ -388,7 +388,7 @@ for a "contact" form on a website::
         def __init__(self):
             self.fields = (
                 forms.EmailField(field_name="from", is_required=True),
-                forms.TextField(field_name="subject", length=30, maxlength=200, is_required=True),
+                forms.TextField(field_name="subject", length=30, max_length=200, is_required=True),
                 forms.SelectField(field_name="urgency", choices=urgency_choices),
                 forms.LargeTextField(field_name="contents", is_required=True),
             )
diff --git a/docs/model-api.txt b/docs/model-api.txt
index f2806bbe31..4bf5648bf0 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -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
@@ -698,11 +702,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::
@@ -1027,8 +1031,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 +1078,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 +1100,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:
             # ...
@@ -1270,8 +1274,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 +1434,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 +1451,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 +1469,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 +1497,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 +1748,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 +1770,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 +1789,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 +1823,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 +1855,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 +1901,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 +1919,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)
@@ -2058,7 +2062,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):
@@ -2069,7 +2073,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):
diff --git a/docs/newforms.txt b/docs/newforms.txt
index ce23b3617a..f22f61b8d1 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -1372,7 +1372,7 @@ the full list of conversions:
     ``AutoField``                    Not represented in the form
     ``BooleanField``                 ``BooleanField``
     ``CharField``                    ``CharField`` with ``max_length`` set to
-                                     the model field's ``maxlength``
+                                     the model field's ``max_length``
     ``CommaSeparatedIntegerField``   ``CharField``
     ``DateField``                    ``DateField``
     ``DateTimeField``                ``DateTimeField``
@@ -1452,15 +1452,15 @@ Consider this set of models::
     )
 
     class Author(models.Model):
-        name = models.CharField(maxlength=100)
-        title = models.CharField(maxlength=3, choices=TITLE_CHOICES)
+        name = models.CharField(max_length=100)
+        title = models.CharField(max_length=3, choices=TITLE_CHOICES)
         birth_date = models.DateField(blank=True, null=True)
 
         def __unicode__(self):
             return self.name
 
     class Book(models.Model):
-        name = models.CharField(maxlength=100)
+        name = models.CharField(max_length=100)
         authors = models.ManyToManyField(Author)
 
 With these models, a call to ``form_for_model(Author)`` would return a ``Form``
diff --git a/docs/overview.txt b/docs/overview.txt
index c6d2a2604f..b0311cee96 100644
--- a/docs/overview.txt
+++ b/docs/overview.txt
@@ -25,14 +25,14 @@ far, it's been solving two years' worth of database-schema problems. Here's a
 quick example::
 
     class Reporter(models.Model):
-        full_name = models.CharField(maxlength=70)
+        full_name = models.CharField(max_length=70)
 
         def __unicode__(self):
             return self.full_name
 
     class Article(models.Model):
         pub_date = models.DateTimeField()
-        headline = models.CharField(maxlength=200)
+        headline = models.CharField(max_length=200)
         article = models.TextField()
         reporter = models.ForeignKey(Reporter)
 
@@ -134,7 +134,7 @@ your model classes::
 
     class Article(models.Model):
         pub_date = models.DateTimeField()
-        headline = models.CharField(maxlength=200)
+        headline = models.CharField(max_length=200)
         article = models.TextField()
         reporter = models.ForeignKey(Reporter)
         class Admin: pass
diff --git a/docs/sites.txt b/docs/sites.txt
index 8a295f81c1..90a9d0f90f 100644
--- a/docs/sites.txt
+++ b/docs/sites.txt
@@ -46,7 +46,7 @@ that's represented by a ``ManyToManyField`` in the ``Article`` model::
     from django.contrib.sites.models import Site
 
     class Article(models.Model):
-        headline = models.CharField(maxlength=200)
+        headline = models.CharField(max_length=200)
         # ...
         sites = models.ManyToManyField(Site)
 
@@ -87,7 +87,7 @@ like this::
     from django.contrib.sites.models import Site
 
     class Article(models.Model):
-        headline = models.CharField(maxlength=200)
+        headline = models.CharField(max_length=200)
         # ...
         site = models.ForeignKey(Site)
 
@@ -229,7 +229,7 @@ Use ``CurrentSiteManager`` by adding it to your model explicitly. For example::
 
     class Photo(models.Model):
         photo = models.FileField(upload_to='/home/photos')
-        photographer_name = models.CharField(maxlength=100)
+        photographer_name = models.CharField(max_length=100)
         pub_date = models.DateField()
         site = models.ForeignKey(Site)
         objects = models.Manager()
@@ -257,7 +257,7 @@ this::
 
     class Photo(models.Model):
         photo = models.FileField(upload_to='/home/photos')
-        photographer_name = models.CharField(maxlength=100)
+        photographer_name = models.CharField(max_length=100)
         pub_date = models.DateField()
         publish_on = models.ForeignKey(Site)
         objects = models.Manager()
diff --git a/docs/testing.txt b/docs/testing.txt
index f4b78273ce..52285f5e8e 100644
--- a/docs/testing.txt
+++ b/docs/testing.txt
@@ -79,8 +79,8 @@ For example::
         'The cat says "meow"'
         """
 
-        name = models.CharField(maxlength=20)
-        sound = models.CharField(maxlength=20)
+        name = models.CharField(max_length=20)
+        sound = models.CharField(max_length=20)
 
         def speak(self):
             return 'The %s says "%s"' % (self.name, self.sound)
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index 180e30292d..32480ca487 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -251,12 +251,12 @@ These concepts are represented by simple Python classes. Edit the
     from django.db import models
 
     class Poll(models.Model):
-        question = models.CharField(maxlength=200)
+        question = models.CharField(max_length=200)
         pub_date = models.DateTimeField('date published')
 
     class Choice(models.Model):
         poll = models.ForeignKey(Poll)
-        choice = models.CharField(maxlength=200)
+        choice = models.CharField(max_length=200)
         votes = models.IntegerField()
 
 The code is straightforward. Each model is represented by a class that
@@ -279,7 +279,7 @@ name for ``Poll.pub_date``. For all other fields in this model, the field's
 machine-readable name will suffice as its human-readable name.
 
 Some ``Field`` classes have required elements. ``CharField``, for example,
-requires that you give it a ``maxlength``. That's used not only in the database
+requires that you give it a ``max_length``. That's used not only in the database
 schema, but in validation, as we'll soon see.
 
 Finally, note a relationship is defined, using ``models.ForeignKey``. That tells
diff --git a/docs/tutorial02.txt b/docs/tutorial02.txt
index 99f586b4a1..b820701d11 100644
--- a/docs/tutorial02.txt
+++ b/docs/tutorial02.txt
@@ -240,7 +240,7 @@ default, provide enough fields for 3 Choices."
 
 Then change the other fields in ``Choice`` to give them ``core=True``::
 
-    choice = models.CharField(maxlength=200, core=True)
+    choice = models.CharField(max_length=200, core=True)
     votes = models.IntegerField(core=True)
 
 This tells Django: "When you edit a Choice on the Poll admin page, the 'choice'