better explain choices usage in the model docs

[radek]

When using choices option as documented in ​http://www.djangoproject.com/documentation/model_api/#general-field-options
it is important to define the choices outside of the class definition (not inside). In the wrong way validation raises error.

WRONG:

class Website(meta.Model):
    "websites"
    TYPE_CHOICES = (
        ('1','Private'),
        ('2','Phorum'),
    )

    ...
    type = meta.CharField('Type', maxlength=200, blank = True, choices=TYPE_CHOICES)

RIGHT:

TYPE_CHOICES = (
    ('1','Private'),
    ('2','Phorum'),
)

class Website(meta.Model):
    "websites"
    ...
    type = meta.CharField('Type', maxlength=200, blank = True, choices=TYPE_CHOICES)

Please, improve docs correspondingly.

[Adrian Holovaty]

This is incorrect. You can define CHOICES either inside or outside the field definition. I'm not sure which validation error you got, but it had to have been unrelated.

[GrumpySimon]

I get the same error ( latest svn version - 1565 ):

class Word( meta.Model ):
    COGNACY_STATES = (
        ( 0, 'Not Done' ),
        ( 1, 'Preliminary' ),
        ( 2, 'Checked' ),
    ) 

    word = meta.CharField( maxlength = 32 )
    slug = meta.SlugField( )
    state = meta.SmallIntegerField( choices = COGNACY_STATES )

gives this traceback:

Traceback (most recent call last):
  File "/usr/local/bin/django-admin.py", line 5, in ?
    management.execute_from_command_line()
  File "/Library/Frameworks/Python.framework/Versions/2.4/lib/python2.4/site-packages/django/core/management.py", line 903, in execute_from_command_line
    action_mapping[action]()
  File "/Library/Frameworks/Python.framework/Versions/2.4/lib/python2.4/site-packages/django/core/management.py", line 505, in createsuperuser
    from django.models.auth import users
  File "/Library/Frameworks/Python.framework/Versions/2.4/lib/python2.4/site-packages/django/models/__init__.py", line 13, in ?
    modules = meta.get_installed_model_modules(__all__)
  File "/Library/Frameworks/Python.framework/Versions/2.4/lib/python2.4/site-packages/django/core/meta/__init__.py", line 111, in get_installed_model_modules
    mod = __import__('django.models.%s' % submodule, '', '', [''])
  File "/Library/Frameworks/Python.framework/Versions/2.4/lib/python2.4/site-packages/language/apps/austronesian/models/austronesian.py", line 21, in ?
    class Word( meta.Model ):
  File "/Library/Frameworks/Python.framework/Versions/2.4/lib/python2.4/site-packages/django/core/meta/__init__.py", line 699, in __new__
    assert callable(v), "%r is an invalid model parameter." % k
AssertionError: 'COGNACY_STATES' is an invalid model parameter.

whilst moving COGNACY_STATES outside of the class seems to work ok.

--Simon

[Adrian Holovaty]

(In [1570]) Fixed #972 -- Improved docs for 'choices' model field option. Thanks, radek