<p>Chapter 5 explains the basics of defining models, and we use them throughout the rest of the book. There is, however, a <em>huge</em> range of model options available not covered elsewhere. This appendix explains each possible model definition option.</p> <p>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 <a class="reference external" href="http://docs.djangoproject.com/">http://docs.djangoproject.com/</a>.</p> <div class="section" id="fields"> <h2>Fields</h2> <p>The most important part of a model – and the only required part of a model – is the list of database fields it defines.</p> <div class="admonition-field-name-restrictions admonition"> <p class="first admonition-title">Field Name Restrictions</p> <p>Django places only two restrictions on model field names:</p> <ol class="arabic"> <li><p class="first">A field name cannot be a Python reserved word, because that would result in a Python syntax error. For example:</p> <div class="highlight-python"><pre>class Example(models.Model): pass = models.IntegerField() # 'pass' is a reserved word!</pre> </div> </li> <li><p class="first">A field name cannot contain more than one underscore in a row, due to the way Django’s query lookup syntax works. For example:</p> <div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Example</span><span class="p">(</ span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span> <span class="n">foo__bar</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">IntegerField</span><span class="p">()</span> <span class="c"># 'foo__bar' has two underscores!</span> </pre></div> </div> </li> </ol> <p>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.</p> <p class="last">SQL reserved words, such as <tt class="docutils literal"><span class="pre">join</span></tt>, <tt class="docutils literal"><span class="pre">where</span></tt>, or <tt class="docutils literal"><span class="pre">select</span></tt>, <em>are</em> 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.</p> </div> <p>Each field in your model should be an instance of the appropriate <tt class="docutils literal"><span class="pre">Field</span></tt> class. Django uses the field class types to determine a few things:</p> <ul class="simple"> <li>The database column type (e.g., <tt class="docutils literal"><span class="pre">INTEGER</span></tt>, <tt class="docutils literal"><span class="pre">VARCHAR</span></tt>).</li> <li>The widget to use in Django’s forms and admin site, if you care to use it (e.g., <tt class="docutils literal"><span class="pre"><input</span> <span class="pre">type="text"></span></tt>, <tt class="docutils literal"><span class="pre"><select></span></tt>).</li> <li>The minimal validation requirements, which are used in Django’s admin interface and by forms.</li> </ul> <p>A complete list of field classes follows, sorted alphabetically. Note that relationship fields (<tt class="docutils literal"><span class="pre">ForeignKey</span></tt>, etc.) are handled in the next section.</p>
basics of defining models, and we use them throughout the rest of the book. There is, however, a <em>huge</em> range of model options available not covered elsewhere. This appendix explains each possible model definition option.</p> <p>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 <a class="reference external" href="http://docs.djangoproject.com/">http://docs.djangoproject.com/</a>.</p> <div class="section" id="fields"> <h2>Fields</h2> <p>The most important part of a model – and the only required part of a model – is the list of database fields it defines.</p> <div class="admonition-field-name-restrictions admonition"> <p class="first admonition-title">Field Name Restrictions</p> <p>Django places only two restrictions on model field names:</p> <ol class="arabic"> <li><p class="first">A field name cannot be a Python reserved word, because that would result in a Python syntax error. For example:</p> <div class="highlight-python"><pre>class Example(models.Model): pass = models.IntegerField() # 'pass' is a reserved word!</pre> </div> </li> <li><p class="first">A field name cannot contain more than one underscore in a row, due to the way Django’s query lookup syntax works. For example:</p> <div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Example</span><span class="p">(</ span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span> <span class="n">foo__bar</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">IntegerField</span><span class="p">()</span> <span class="c"># 'foo__bar' has two underscores!</span> </pre></div> </div> </li> </ol> <p>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.</p> <p class="last">SQL reserved words, such as <tt class="docutils literal"><span class="pre">join</span></tt>, <tt class="docutils literal"><span class="pre">where</span></tt>, or <tt class="docutils literal"><span class="pre">select</span></tt>, <em>are</em> 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.</p> </div> <p>Each field in your model should be an instance of the appropriate <tt class="docutils literal"><span class="pre">Field</span></tt> class. Django uses the field class types to determine a few things:</p> <ul class="simple"> <li>The database column type (e.g., <tt class="docutils literal"><span class="pre">INTEGER</span></tt>, <tt class="docutils literal"><span class="pre">VARCHAR</span></tt>).</li> <li>The widget to use in Django’s forms and admin site, if you care to use it (e.g., <tt class="docutils literal"><span class="pre"><input</span> <span class="pre">type="text"></span></tt>, <tt class="docutils literal"><span class="pre"><select></span></tt>).</li> <li>The minimal validation requirements, which are used in Django’s admin interface and by forms.</li> </ul> <p>A complete list of field classes follows, sorted alphabetically. Note that relationship fields (<tt class="docutils literal"><span class="pre">ForeignKey</span></tt>, etc.) are handled in the next section.</p>