Chapter 5 explains the basics of defining models, and we use them throughout the rest of the book. There is, however, a huge range of model options available not covered elsewhere. This appendix explains each possible model definition option.
Note that although these APIs are considered stable, the Django developers consistently add new shortcuts and conveniences to the model definition. It’s a good idea to always check the latest documentation online at http://docs.djangoproject.com/.
The most important part of a model – and the only required part of a model – is the list of database fields it defines.
Field Name Restrictions
Django places only two restrictions on model field names:
A field name cannot be a Python reserved word, because that would result in a Python syntax error. For example:
class Example(models.Model):
pass = models.IntegerField() # 'pass' is a reserved word!
A field name cannot contain more than one underscore in a row, due to the way Django’s query lookup syntax works. For example:
class Example(
span>models.Model):
foo__bar = models.IntegerField() # 'foo__bar' has two underscores!
These limitations can be worked around, though, because your field name doesn’t necessarily have to match your database column name. See “db_column”, below.
SQL reserved words, such as join, where, or select, are allowed as model field names, because Django escapes all database table names and column names in every underlying SQL query. It uses the quoting syntax of your particular database engine.
Each field in your model should be an instance of the appropriate Field class. Django uses the field class types to determine a few things:
A complete list of field classes follows, sorted alphabetically. Note that relationship fields (ForeignKey, etc.) are handled in the next section.
Chapter 5 explains the basics of defining models, and we use them throughout the rest of the book. There is, however, a huge range of model options available not covered elsewhere. This appendix explains each possible model definition option.
Note that although these APIs are considered stable, the Django developers consistently add new shortcuts and conveniences to the model definition. It’s a good idea to always check the latest documentation online at http://docs.djangoproject.com/.
The most important part of a model – and the only required part of a model – is the list of database fields it defines.
Field Name Restrictions
Django places only two restrictions on model field names:
A field name cannot be a Python reserved word, because that would result in a Python syntax error. For example:
class Example(models.Model):
pass = models.IntegerField() # 'pass' is a reserved word!
A field name cannot contain more than one underscore in a row, due to the way Django’s query lookup syntax works. For example:
class Example(
span>models.Model):
foo__bar = models.IntegerField() # 'foo__bar' has two underscores!
These limitations can be worked around, though, because your field name doesn’t necessarily have to match your database column name. See “db_column”, below.
SQL reserved words, such as join, where, or select, are allowed as model field names, because Django escapes all database table names and column names in every underlying SQL query. It uses the quoting syntax of your particular database engine.
Each field in your model should be an instance of the appropriate Field class. Django uses the field class types to determine a few things:
A complete list of field classes follows, sorted alphabetically. Note that relationship fields (ForeignKey, etc.) are handled in the next section.