Created
November 17, 2012 19:38
-
-
Save fuho/4099249 to your computer and use it in GitHub Desktop.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | |
| <!-- saved from url=(0037)https://www.djangoproject.com/weblog/ --> | |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> | |
| <meta http-equiv="Content-Language" content="en-us"> | |
| <title>Inject Django Docs UI</title> | |
| <meta name="ROBOTS" content="ALL"> | |
| <meta http-equiv="imagetoolbar" content="no"> | |
| <meta name="MSSmartTagsPreventParsing" content="true"> | |
| <meta name="Copyright" content="Django Software Foundation"> | |
| <meta name="keywords" content="Python, Django, framework, open-source, documentation, docs"> | |
| <meta name="description" content="Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design."> | |
| <link href="./addui_files/base.css" rel="stylesheet" type="text/css" media="screen"> | |
| <link href="./addui_files/print.css" rel="stylesheet" type="text/css" media="print"> | |
| </head> | |
| <body id="weblog" class="default"> | |
| <div id="container"> | |
| <div id="header"> | |
| <h1 id="logo"> | |
| <a href="https://www.djangoproject.com/"><img src="https://www.djangoproject.com/m/img/site/hdr_logo.gif" alt="Django"></a> | |
| <div id="shoutout">... needs a better documentation UI ;) <a href="javascript:(function(){var script=document.createElement('script');script.type='text/javascript';script.src='https://raw.github.com/gist/4079908/DjangoDocsUI.js';document.head.appendChild(script);})();document.getElementById('logo').removeChild(document.getElementById('shoutout'))">ENGAGE!</a></div> | |
| </h1> | |
| </div> | |
| <!-- END Header --> | |
| <div id="columnwrap"> | |
| <div id="content-main"> | |
| <h1>Better UI for Django Documentation</h1> | |
| <p><strong>Often I find myself burried in Django Documentation and even though | |
| I love the contents I couldn't get over the fact that 30% of screen is | |
| wasted on index. Index which is usually a lot shorter than the content, | |
| so when you are reading "page 3" there really is no reason to stare at | |
| that green block on the right hand side. | |
| </strong></p> | |
| <p>Trying to avoid working on a | |
| project I was supposed to be working on I started writing a bookmarklet | |
| which in my had was suppsoed to be around 5 lines of code. A day later | |
| I present to you <strong>Django Docs UI Inject</strong> | |
| </p> | |
| <h2><a name="how_to_install" href="#how_to_install">Installation</a></h2> | |
| <p>There really isn't any, Here, drag the link below to your bookmark bar:</p> | |
| <br/><center> | |
| <a style="font-family:Verdana; font-size: 30px; font-weight:900; | |
| color: rgb(252, 181, 0); margin:5px; padding: 3px; | |
| background-color: rgb(49, 85, 44); -webkit-border-radius: 5px; | |
| -moz-border-radius: 5px; border-radius: 5px; text-decoration:none;" | |
| href="javascript:(function(){var script=document.createElement('script'); | |
| script.type='text/javascript';script.src='https://raw.github.com/gist/4079908/DjangoDocsUI.js';document.head.appendChild(script);})()"> | |
| DUI! | |
| </a></center><br/> | |
| <p>... and you're done. Now click it an play with it. I have stolen some | |
| 'garbage' content fro Django Documenaton website just for you to try! | |
| </p> | |
| <h2><a name="how_to_use" href="#how_to_use">Usage</a></h2> | |
| <p> | |
| <ol> | |
| <li>Go to <a href="https://docs.djangoproject.com/en/dev//">Django Documentation site</a></li> | |
| <li>Click on the bookmarklet</li> | |
| <li>Start using the UI | |
| <ul> | |
| <li>Drag the index to either side</li> | |
| <li>Toggle the index when you want to fill as much data as possible.</li> | |
| <li>Adjust the content/index ratio to your liking. | |
| (This is useful when there is lot of stuff in the index and | |
| line breaks make it difficuilt to decode.)</li> | |
| <li>Try scrolling down, index will always stay close at hand in case you want to use it.</li> | |
| </ul> | |
| </li> | |
| </ol> | |
| </p> | |
| <h2><a name="features" href="#features">Features</a></h2> | |
| <p> Mostly covered in <a href="#how_to_use">Usage</a> but here you go again: | |
| <ul> | |
| <li>Move (drag) index to either side (Left/Right - Left is the one which have thumb on the right hand side.)</li> | |
| <li>Toggle index (Remembers ratio and position)</li> | |
| <li>Keep index in view when scrolling up or down (In a very smart like manner!)</li> | |
| <li>Slider to adjust content/index ratio.(For those times when you really feel like adjusting stuff)</li> | |
| <li>...want more? Leave me a comment <a href="https://gist.github.com/4079908">here</a> and I'll see what I can do ;)</li> | |
| </ul> | |
| </p> | |
| <h2><a name="notes" href="#notes">Notes</a></h2> | |
| <p>Notes? You mean bills?</p> | |
| <h2><a name="todo" href="#todo">Future plans</a></h2> | |
| <p>Here is a list of things I think the bookmarklet could still use: | |
| <ul> | |
| <li>A way to scroll faster, I started writing implementation for middle mouse drag, but then relized I should probably get back to work.</li> | |
| <li>It should be an extension, not just bookmarklet. Preferably using the same codebase.</li> | |
| <li>It should work on more websites (currently not limited, you might get lucky)</li> | |
| <li>When you click on nchor it should end up covered by UI (just found this one).</li> | |
| </ul></p> | |
| <p class="date small">Posted by <strong>fuho</strong> on November 17, 2012</p> | |
| <div id="garbage-index" > | |
| <div class="section" id="s-module-django.db.models.fields"> | |
| <span id="s-model-field-reference"></span><span id="module-django.db.models.fields"></span><span id="model-field-reference"></span> | |
| <h1>Model field reference, but in this case just a space filler<a class="headerlink" href="#module-django.db.models.fields" title="Permalink to this headline">¶</a></h1> | |
| <p>This document contains all the gory details about all the <a class="reference internal" href="#field-options">field options</a> and | |
| <a class="reference internal" href="#field-types">field types</a> Django’s got to offer.</p> | |
| <div class="admonition-see-also admonition seealso"> | |
| <p class="first admonition-title">See also</p> | |
| <p class="last">If the built-in fields don’t do the trick, you can try | |
| <a class="reference internal" href="../../contrib/localflavor/#module-django.contrib.localflavor" title="django.contrib.localflavor: A collection of various Django snippets that are useful only for a particular country or culture."><tt class="xref py py-mod docutils literal"><span class="pre">django.contrib.localflavor</span></tt></a>, which contains assorted pieces of code | |
| that are useful for particular countries or cultures. Also, you can easily | |
| <a class="reference internal" href="../../../howto/custom-model-fields/"><em>write your own custom model fields</em></a>.</p> | |
| </div> | |
| <div class="admonition note"> | |
| <p class="first admonition-title">Note</p> | |
| <p class="last">Technically, these models are defined in <a class="reference internal" href="#module-django.db.models.fields" title="django.db.models.fields: Built-in field types."><tt class="xref py py-mod docutils literal"><span class="pre">django.db.models.fields</span></tt></a>, but | |
| for convenience they’re imported into <a class="reference internal" href="../../../topics/db/models/#module-django.db.models" title="django.db.models"><tt class="xref py py-mod docutils literal"><span class="pre">django.db.models</span></tt></a>; the standard | |
| convention is to use <tt class="docutils literal"><span class="pre">from</span> <span class="pre">django.db</span> <span class="pre">import</span> <span class="pre">models</span></tt> and refer to fields as | |
| <tt class="docutils literal"><span class="pre">models.<Foo>Field</span></tt>.</p> | |
| </div> | |
| <div class="section" id="s-field-options"> | |
| <span id="s-common-model-field-options"></span><span id="field-options"></span><span id="common-model-field-options"></span><h2>Field options<a class="headerlink" href="#field-options" title="Permalink to this headline">¶</a></h2> | |
| <p>The following arguments are available to all field types. All are optional.</p> | |
| <div class="section" id="s-null"> | |
| <span id="null"></span><h3><tt class="docutils literal"><span class="pre">null</span></tt><a class="headerlink" href="#null" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.null"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">null</tt><a class="headerlink" href="#django.db.models.Field.null" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>If <tt class="xref docutils literal"><span class="pre">True</span></tt>, Django will store empty values as <tt class="docutils literal"><span class="pre">NULL</span></tt> in the database. Default | |
| is <tt class="xref docutils literal"><span class="pre">False</span></tt>.</p> | |
| <p>Note that empty string values will always get stored as empty strings, not as | |
| <tt class="docutils literal"><span class="pre">NULL</span></tt>. Only use <tt class="docutils literal"><span class="pre">null=True</span></tt> for non-string fields such as integers, | |
| booleans and dates. For both types of fields, you will also need to set | |
| <tt class="docutils literal"><span class="pre">blank=True</span></tt> if you wish to permit empty values in forms, as the | |
| <a class="reference internal" href="#django.db.models.Field.null" title="django.db.models.Field.null"><tt class="xref py py-attr docutils literal"><span class="pre">null</span></tt></a> parameter only affects database storage (see | |
| <a class="reference internal" href="#django.db.models.Field.blank" title="django.db.models.Field.blank"><tt class="xref py py-attr docutils literal"><span class="pre">blank</span></tt></a>).</p> | |
| <p>Avoid using <a class="reference internal" href="#django.db.models.Field.null" title="django.db.models.Field.null"><tt class="xref py py-attr docutils literal"><span class="pre">null</span></tt></a> on string-based fields such as | |
| <a class="reference internal" href="#django.db.models.CharField" title="django.db.models.CharField"><tt class="xref py py-class docutils literal"><span class="pre">CharField</span></tt></a> and <a class="reference internal" href="#django.db.models.TextField" title="django.db.models.TextField"><tt class="xref py py-class docutils literal"><span class="pre">TextField</span></tt></a> unless you have an excellent reason. | |
| If a string-based field has <tt class="docutils literal"><span class="pre">null=True</span></tt>, that means it has two possible values | |
| for “no data”: <tt class="docutils literal"><span class="pre">NULL</span></tt>, and the empty string. In most cases, it’s redundant to | |
| have two possible values for “no data;” Django convention is to use the empty | |
| string, not <tt class="docutils literal"><span class="pre">NULL</span></tt>.</p> | |
| <div class="admonition note"> | |
| <p class="first admonition-title">Note</p> | |
| <p class="last">When using the Oracle database backend, the <tt class="docutils literal"><span class="pre">null=True</span></tt> option will be | |
| coerced for string-based fields that have the empty string as a possible | |
| value, and the value <tt class="docutils literal"><span class="pre">NULL</span></tt> will be stored to denote the empty string.</p> | |
| </div> | |
| <p>If you want to accept <a class="reference internal" href="#django.db.models.Field.null" title="django.db.models.Field.null"><tt class="xref py py-attr docutils literal"><span class="pre">null</span></tt></a> values with <a class="reference internal" href="#django.db.models.BooleanField" title="django.db.models.BooleanField"><tt class="xref py py-class docutils literal"><span class="pre">BooleanField</span></tt></a>, | |
| use <a class="reference internal" href="#django.db.models.NullBooleanField" title="django.db.models.NullBooleanField"><tt class="xref py py-class docutils literal"><span class="pre">NullBooleanField</span></tt></a> instead.</p> | |
| </div> | |
| <div class="section" id="s-blank"> | |
| <span id="blank"></span><h3><tt class="docutils literal"><span class="pre">blank</span></tt><a class="headerlink" href="#blank" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.blank"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">blank</tt><a class="headerlink" href="#django.db.models.Field.blank" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>If <tt class="xref docutils literal"><span class="pre">True</span></tt>, the field is allowed to be blank. Default is <tt class="xref docutils literal"><span class="pre">False</span></tt>.</p> | |
| <p>Note that this is different than <a class="reference internal" href="#django.db.models.Field.null" title="django.db.models.Field.null"><tt class="xref py py-attr docutils literal"><span class="pre">null</span></tt></a>. <a class="reference internal" href="#django.db.models.Field.null" title="django.db.models.Field.null"><tt class="xref py py-attr docutils literal"><span class="pre">null</span></tt></a> is | |
| purely database-related, whereas <a class="reference internal" href="#django.db.models.Field.blank" title="django.db.models.Field.blank"><tt class="xref py py-attr docutils literal"><span class="pre">blank</span></tt></a> is validation-related. If | |
| a field has <tt class="docutils literal"><span class="pre">blank=True</span></tt>, form validation will allow entry of an empty value. | |
| If a field has <tt class="docutils literal"><span class="pre">blank=False</span></tt>, the field will be required.</p> | |
| </div> | |
| <div class="section" id="s-choices"> | |
| <span id="s-field-choices"></span><span id="choices"></span><span id="field-choices"></span><h3><tt class="docutils literal"><span class="pre">choices</span></tt><a class="headerlink" href="#choices" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.choices"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">choices</tt><a class="headerlink" href="#django.db.models.Field.choices" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this | |
| field. If this is given, the default form widget will be a select box with | |
| these choices instead of the standard text field.</p> | |
| <p>The first element in each tuple is the actual value to be stored, and the | |
| second element is the human-readable name. For example:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="n">YEAR_IN_SCHOOL_CHOICES</span> <span class="o">=</span> <span class="p">(</span> | |
| <span class="p">(</span><span class="s">'FR'</span><span class="p">,</span> <span class="s">'Freshman'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'SO'</span><span class="p">,</span> <span class="s">'Sophomore'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'JR'</span><span class="p">,</span> <span class="s">'Junior'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'SR'</span><span class="p">,</span> <span class="s">'Senior'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'GR'</span><span class="p">,</span> <span class="s">'Graduate'</span><span class="p">),</span> | |
| <span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>The first element in each tuple is the actual value to be stored. The second | |
| element is the human-readable name for the option.</p> | |
| <p>The choices list can be defined either as part of your model class:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</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">YEAR_IN_SCHOOL_CHOICES</span> <span class="o">=</span> <span class="p">(</span> | |
| <span class="p">(</span><span class="s">'FR'</span><span class="p">,</span> <span class="s">'Freshman'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'SO'</span><span class="p">,</span> <span class="s">'Sophomore'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'JR'</span><span class="p">,</span> <span class="s">'Junior'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'SR'</span><span class="p">,</span> <span class="s">'Senior'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'GR'</span><span class="p">,</span> <span class="s">'Graduate'</span><span class="p">),</span> | |
| <span class="p">)</span> | |
| <span class="n">year_in_school</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="n">YEAR_IN_SCHOOL_CHOICES</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>or outside your model class altogether:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="n">YEAR_IN_SCHOOL_CHOICES</span> <span class="o">=</span> <span class="p">(</span> | |
| <span class="p">(</span><span class="s">'FR'</span><span class="p">,</span> <span class="s">'Freshman'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'SO'</span><span class="p">,</span> <span class="s">'Sophomore'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'JR'</span><span class="p">,</span> <span class="s">'Junior'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'SR'</span><span class="p">,</span> <span class="s">'Senior'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'GR'</span><span class="p">,</span> <span class="s">'Graduate'</span><span class="p">),</span> | |
| <span class="p">)</span> | |
| <span class="k">class</span> <span class="nc">Foo</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">year_in_school</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="n">YEAR_IN_SCHOOL_CHOICES</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>You can also collect your available choices into named groups that can | |
| be used for organizational purposes:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="n">MEDIA_CHOICES</span> <span class="o">=</span> <span class="p">(</span> | |
| <span class="p">(</span><span class="s">'Audio'</span><span class="p">,</span> <span class="p">(</span> | |
| <span class="p">(</span><span class="s">'vinyl'</span><span class="p">,</span> <span class="s">'Vinyl'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'cd'</span><span class="p">,</span> <span class="s">'CD'</span><span class="p">),</span> | |
| <span class="p">)</span> | |
| <span class="p">),</span> | |
| <span class="p">(</span><span class="s">'Video'</span><span class="p">,</span> <span class="p">(</span> | |
| <span class="p">(</span><span class="s">'vhs'</span><span class="p">,</span> <span class="s">'VHS Tape'</span><span class="p">),</span> | |
| <span class="p">(</span><span class="s">'dvd'</span><span class="p">,</span> <span class="s">'DVD'</span><span class="p">),</span> | |
| <span class="p">)</span> | |
| <span class="p">),</span> | |
| <span class="p">(</span><span class="s">'unknown'</span><span class="p">,</span> <span class="s">'Unknown'</span><span class="p">),</span> | |
| <span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>The first element in each tuple is the name to apply to the group. The | |
| second element is an iterable of 2-tuples, with each 2-tuple containing | |
| a value and a human-readable name for an option. Grouped options may be | |
| combined with ungrouped options within a single list (such as the | |
| <cite>unknown</cite> option in this example).</p> | |
| <p>For each model field that has <a class="reference internal" href="#django.db.models.Field.choices" title="django.db.models.Field.choices"><tt class="xref py py-attr docutils literal"><span class="pre">choices</span></tt></a> set, Django will add a | |
| method to retrieve the human-readable name for the field's current value. See | |
| <a class="reference internal" href="../instances/#django.db.models.Model.get_FOO_display" title="django.db.models.Model.get_FOO_display"><tt class="xref py py-meth docutils literal"><span class="pre">get_FOO_display()</span></tt></a> in the database API | |
| documentation.</p> | |
| <p>Finally, note that choices can be any iterable object -- not necessarily a list | |
| or tuple. This lets you construct choices dynamically. But if you find yourself | |
| hacking <a class="reference internal" href="#django.db.models.Field.choices" title="django.db.models.Field.choices"><tt class="xref py py-attr docutils literal"><span class="pre">choices</span></tt></a> to be dynamic, you're probably better off using a | |
| proper database table with a <a class="reference internal" href="#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a>. <a class="reference internal" href="#django.db.models.Field.choices" title="django.db.models.Field.choices"><tt class="xref py py-attr docutils literal"><span class="pre">choices</span></tt></a> is | |
| meant for static data that doesn't change much, if ever.</p> | |
| </div> | |
| <div class="section" id="s-db-column"> | |
| <span id="db-column"></span><h3><tt class="docutils literal"><span class="pre">db_column</span></tt><a class="headerlink" href="#db-column" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.db_column"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">db_column</tt><a class="headerlink" href="#django.db.models.Field.db_column" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>The name of the database column to use for this field. If this isn't given, | |
| Django will use the field's name.</p> | |
| <p>If your database column name is an SQL reserved word, or contains | |
| characters that aren't allowed in Python variable names -- notably, the | |
| hyphen -- that's OK. Django quotes column and table names behind the | |
| scenes.</p> | |
| </div> | |
| <div class="section" id="s-db-index"> | |
| <span id="db-index"></span><h3><tt class="docutils literal"><span class="pre">db_index</span></tt><a class="headerlink" href="#db-index" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.db_index"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">db_index</tt><a class="headerlink" href="#django.db.models.Field.db_index" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>If <tt class="xref docutils literal"><span class="pre">True</span></tt>, djadmin:<cite>django-admin.py sqlindexes <sqlindexes></cite> will output a | |
| <tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">INDEX</span></tt> statement for this field.</p> | |
| </div> | |
| <div class="section" id="s-db-tablespace"> | |
| <span id="db-tablespace"></span><h3><tt class="docutils literal"><span class="pre">db_tablespace</span></tt><a class="headerlink" href="#db-tablespace" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.db_tablespace"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">db_tablespace</tt><a class="headerlink" href="#django.db.models.Field.db_tablespace" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>The name of the <a class="reference internal" href="../../../topics/db/tablespaces/"><em>database tablespace</em></a> to use for | |
| this field's index, if this field is indexed. The default is the project's | |
| <a class="reference internal" href="../../settings/#std:setting-DEFAULT_INDEX_TABLESPACE"><tt class="xref std std-setting docutils literal"><span class="pre">DEFAULT_INDEX_TABLESPACE</span></tt></a> setting, if set, or the | |
| <a class="reference internal" href="../options/#django.db.models.Options.db_tablespace" title="django.db.models.Options.db_tablespace"><tt class="xref py py-attr docutils literal"><span class="pre">db_tablespace</span></tt></a> of the model, if any. If the backend doesn't | |
| support tablespaces for indexes, this option is ignored.</p> | |
| </div> | |
| <div class="section" id="s-default"> | |
| <span id="default"></span><h3><tt class="docutils literal"><span class="pre">default</span></tt><a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.default"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">default</tt><a class="headerlink" href="#django.db.models.Field.default" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>The default value for the field. This can be a value or a callable object. If | |
| callable it will be called every time a new object is created.</p> | |
| <p>The default cannot be a mutable object (model instance, list, set, etc.), as a | |
| reference to the same instance of that object would be used as the default | |
| value in all new model instances. Instead, wrap the desired default in a | |
| callable. For example, if you had a custom <tt class="docutils literal"><span class="pre">JSONField</span></tt> and wanted to specify | |
| a dictionary as the default, use a <tt class="docutils literal"><span class="pre">lambda</span></tt> as follows:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="n">contact_info</span> <span class="o">=</span> <span class="n">JSONField</span><span class="p">(</span><span class="s">"ContactInfo"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="k">lambda</span><span class="p">:{</span><span class="s">"email"</span><span class="p">:</span> <span class="s">"[email protected]"</span><span class="p">})</span> | |
| </pre></div> | |
| </div> | |
| </div> | |
| <div class="section" id="s-editable"> | |
| <span id="editable"></span><h3><tt class="docutils literal"><span class="pre">editable</span></tt><a class="headerlink" href="#editable" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.editable"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">editable</tt><a class="headerlink" href="#django.db.models.Field.editable" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>If <tt class="xref docutils literal"><span class="pre">False</span></tt>, the field will not be displayed in the admin or any other | |
| <a class="reference internal" href="../../../topics/forms/modelforms/#django.forms.ModelForm" title="django.forms.ModelForm"><tt class="xref py py-class docutils literal"><span class="pre">ModelForm</span></tt></a>. Default is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p> | |
| </div> | |
| <div class="section" id="s-error-messages"> | |
| <span id="error-messages"></span><h3><tt class="docutils literal"><span class="pre">error_messages</span></tt><a class="headerlink" href="#error-messages" title="Permalink to this headline">¶</a></h3> | |
| <div class="versionadded"> | |
| <span class="title">New in Django 1.2:</span> <a class="reference internal" href="../../../releases/1.2/"><em>Please see the release notes</em></a></div> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.error_messages"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">error_messages</tt><a class="headerlink" href="#django.db.models.Field.error_messages" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>The <tt class="docutils literal"><span class="pre">error_messages</span></tt> argument lets you override the default messages that the | |
| field will raise. Pass in a dictionary with keys matching the error messages you | |
| want to override.</p> | |
| <p>Error message keys include <tt class="docutils literal"><span class="pre">null</span></tt>, <tt class="docutils literal"><span class="pre">blank</span></tt>, <tt class="docutils literal"><span class="pre">invalid</span></tt>, <tt class="docutils literal"><span class="pre">invalid_choice</span></tt>, | |
| and <tt class="docutils literal"><span class="pre">unique</span></tt>. Additional error message keys are specified for each field in | |
| the <a class="reference internal" href="#field-types">Field types</a> section below.</p> | |
| </div> | |
| <div class="section" id="s-help-text"> | |
| <span id="help-text"></span><h3><tt class="docutils literal"><span class="pre">help_text</span></tt><a class="headerlink" href="#help-text" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.help_text"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">help_text</tt><a class="headerlink" href="#django.db.models.Field.help_text" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>Extra "help" text to be displayed with the form widget. It's useful for | |
| documentation even if your field isn't used on a form.</p> | |
| <p>Note that this value is <em>not</em> HTML-escaped in automatically-generated | |
| forms. This lets you include HTML in <a class="reference internal" href="#django.db.models.Field.help_text" title="django.db.models.Field.help_text"><tt class="xref py py-attr docutils literal"><span class="pre">help_text</span></tt></a> if you so | |
| desire. For example:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="n">help_text</span><span class="o">=</span><span class="s">"Please use the following format: <em>YYYY-MM-DD</em>."</span> | |
| </pre></div> | |
| </div> | |
| <p>Alternatively you can use plain text and | |
| <tt class="docutils literal"><span class="pre">django.utils.html.escape()</span></tt> to escape any HTML special characters.</p> | |
| </div> | |
| <div class="section" id="s-primary-key"> | |
| <span id="primary-key"></span><h3><tt class="docutils literal"><span class="pre">primary_key</span></tt><a class="headerlink" href="#primary-key" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.primary_key"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">primary_key</tt><a class="headerlink" href="#django.db.models.Field.primary_key" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>If <tt class="xref docutils literal"><span class="pre">True</span></tt>, this field is the primary key for the model.</p> | |
| <p>If you don't specify <tt class="docutils literal"><span class="pre">primary_key=True</span></tt> for any fields in your model, Django | |
| will automatically add an <a class="reference internal" href="#django.db.models.IntegerField" title="django.db.models.IntegerField"><tt class="xref py py-class docutils literal"><span class="pre">IntegerField</span></tt></a> to hold the primary key, so you | |
| don't need to set <tt class="docutils literal"><span class="pre">primary_key=True</span></tt> on any of your fields unless you want to | |
| override the default primary-key behavior. For more, see | |
| <a class="reference internal" href="../../../topics/db/models/#automatic-primary-key-fields"><em>Automatic primary key fields</em></a>.</p> | |
| <p><tt class="docutils literal"><span class="pre">primary_key=True</span></tt> implies <a class="reference internal" href="#django.db.models.Field.null" title="django.db.models.Field.null"><tt class="xref py py-attr docutils literal"><span class="pre">null=False</span></tt></a> and <a class="reference internal" href="#django.db.models.Field.unique" title="django.db.models.Field.unique"><tt class="xref py py-attr docutils literal"><span class="pre">unique=True</span></tt></a>. | |
| Only one primary key is allowed on an object.</p> | |
| </div> | |
| <div class="section" id="s-unique"> | |
| <span id="unique"></span><h3><tt class="docutils literal"><span class="pre">unique</span></tt><a class="headerlink" href="#unique" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.unique"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">unique</tt><a class="headerlink" href="#django.db.models.Field.unique" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>If <tt class="xref docutils literal"><span class="pre">True</span></tt>, this field must be unique throughout the table.</p> | |
| <p>This is enforced at the database level and by model validation. If | |
| you try to save a model with a duplicate value in a <a class="reference internal" href="#django.db.models.Field.unique" title="django.db.models.Field.unique"><tt class="xref py py-attr docutils literal"><span class="pre">unique</span></tt></a> | |
| field, a <a class="reference internal" href="../../exceptions/#django.db.IntegrityError" title="django.db.IntegrityError"><tt class="xref py py-exc docutils literal"><span class="pre">django.db.IntegrityError</span></tt></a> will be raised by the model's | |
| <a class="reference internal" href="../instances/#django.db.models.Model.save" title="django.db.models.Model.save"><tt class="xref py py-meth docutils literal"><span class="pre">save()</span></tt></a> method.</p> | |
| <p>This option is valid on all field types except <a class="reference internal" href="#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><tt class="xref py py-class docutils literal"><span class="pre">ManyToManyField</span></tt></a> and | |
| <a class="reference internal" href="#django.db.models.FileField" title="django.db.models.FileField"><tt class="xref py py-class docutils literal"><span class="pre">FileField</span></tt></a>.</p> | |
| </div> | |
| <div class="section" id="s-unique-for-date"> | |
| <span id="unique-for-date"></span><h3><tt class="docutils literal"><span class="pre">unique_for_date</span></tt><a class="headerlink" href="#unique-for-date" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.unique_for_date"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">unique_for_date</tt><a class="headerlink" href="#django.db.models.Field.unique_for_date" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>Set this to the name of a <a class="reference internal" href="#django.db.models.DateField" title="django.db.models.DateField"><tt class="xref py py-class docutils literal"><span class="pre">DateField</span></tt></a> or <a class="reference internal" href="#django.db.models.DateTimeField" title="django.db.models.DateTimeField"><tt class="xref py py-class docutils literal"><span class="pre">DateTimeField</span></tt></a> to | |
| require that this field be unique for the value of the date field.</p> | |
| <p>For example, if you have a field <tt class="docutils literal"><span class="pre">title</span></tt> that has | |
| <tt class="docutils literal"><span class="pre">unique_for_date="pub_date"</span></tt>, then Django wouldn't allow the entry of two | |
| records with the same <tt class="docutils literal"><span class="pre">title</span></tt> and <tt class="docutils literal"><span class="pre">pub_date</span></tt>.</p> | |
| <p>This is enforced by model validation but not at the database level.</p> | |
| </div> | |
| <div class="section" id="s-unique-for-month"> | |
| <span id="unique-for-month"></span><h3><tt class="docutils literal"><span class="pre">unique_for_month</span></tt><a class="headerlink" href="#unique-for-month" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.unique_for_month"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">unique_for_month</tt><a class="headerlink" href="#django.db.models.Field.unique_for_month" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>Like <a class="reference internal" href="#django.db.models.Field.unique_for_date" title="django.db.models.Field.unique_for_date"><tt class="xref py py-attr docutils literal"><span class="pre">unique_for_date</span></tt></a>, but requires the field to be unique with | |
| respect to the month.</p> | |
| </div> | |
| <div class="section" id="s-unique-for-year"> | |
| <span id="unique-for-year"></span><h3><tt class="docutils literal"><span class="pre">unique_for_year</span></tt><a class="headerlink" href="#unique-for-year" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.unique_for_year"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">unique_for_year</tt><a class="headerlink" href="#django.db.models.Field.unique_for_year" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>Like <a class="reference internal" href="#django.db.models.Field.unique_for_date" title="django.db.models.Field.unique_for_date"><tt class="xref py py-attr docutils literal"><span class="pre">unique_for_date</span></tt></a> and <a class="reference internal" href="#django.db.models.Field.unique_for_month" title="django.db.models.Field.unique_for_month"><tt class="xref py py-attr docutils literal"><span class="pre">unique_for_month</span></tt></a>.</p> | |
| </div> | |
| <div class="section" id="s-verbose-name"> | |
| <span id="verbose-name"></span><h3><tt class="docutils literal"><span class="pre">verbose_name</span></tt><a class="headerlink" href="#verbose-name" title="Permalink to this headline">¶</a></h3> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.verbose_name"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">verbose_name</tt><a class="headerlink" href="#django.db.models.Field.verbose_name" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A human-readable name for the field. If the verbose name isn't given, Django | |
| will automatically create it using the field's attribute name, converting | |
| underscores to spaces. See <a class="reference internal" href="../../../topics/db/models/#verbose-field-names"><em>Verbose field names</em></a>.</p> | |
| </div> | |
| <div class="section" id="s-validators"> | |
| <span id="validators"></span><h3><tt class="docutils literal"><span class="pre">validators</span></tt><a class="headerlink" href="#validators" title="Permalink to this headline">¶</a></h3> | |
| <div class="versionadded"> | |
| <span class="title">New in Django 1.2:</span> <a class="reference internal" href="../../../releases/1.2/"><em>Please see the release notes</em></a></div> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.Field.validators"> | |
| <tt class="descclassname">Field.</tt><tt class="descname">validators</tt><a class="headerlink" href="#django.db.models.Field.validators" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A list of validators to run for this field. See the <a class="reference internal" href="../../validators/"><em>validators | |
| documentation</em></a> for more information.</p> | |
| </div> | |
| </div> | |
| <div class="section" id="s-field-types"> | |
| <span id="s-model-field-types"></span><span id="field-types"></span><span id="model-field-types"></span><h2>Field types<a class="headerlink" href="#field-types" title="Permalink to this headline">¶</a></h2> | |
| <div class="section" id="s-autofield"> | |
| <span id="autofield"></span><h3><tt class="docutils literal"><span class="pre">AutoField</span></tt><a class="headerlink" href="#autofield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.AutoField"> | |
| <em class="property">class </em><tt class="descname">AutoField</tt>(<em>**options</em>)<a class="headerlink" href="#django.db.models.AutoField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>An <a class="reference internal" href="#django.db.models.IntegerField" title="django.db.models.IntegerField"><tt class="xref py py-class docutils literal"><span class="pre">IntegerField</span></tt></a> that automatically increments | |
| according to available IDs. You usually won't need to use this directly; a | |
| primary key field will automatically be added to your model if you don't specify | |
| otherwise. See <a class="reference internal" href="../../../topics/db/models/#automatic-primary-key-fields"><em>Automatic primary key fields</em></a>.</p> | |
| </div> | |
| <div class="section" id="s-bigintegerfield"> | |
| <span id="bigintegerfield"></span><h3><tt class="docutils literal"><span class="pre">BigIntegerField</span></tt><a class="headerlink" href="#bigintegerfield" title="Permalink to this headline">¶</a></h3> | |
| <div class="versionadded"> | |
| <span class="title">New in Django 1.2:</span> <a class="reference internal" href="../../../releases/1.2/"><em>Please see the release notes</em></a></div> | |
| <dl class="class"> | |
| <dt id="django.db.models.BigIntegerField"> | |
| <em class="property">class </em><tt class="descname">BigIntegerField</tt>(<span class="optional">[</span><em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.BigIntegerField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A 64 bit integer, much like an <a class="reference internal" href="#django.db.models.IntegerField" title="django.db.models.IntegerField"><tt class="xref py py-class docutils literal"><span class="pre">IntegerField</span></tt></a> except that it is | |
| guaranteed to fit numbers from -9223372036854775808 to 9223372036854775807. The | |
| default form widget for this field is a <a class="reference internal" href="../../forms/widgets/#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a>.</p> | |
| </div> | |
| <div class="section" id="s-booleanfield"> | |
| <span id="booleanfield"></span><h3><tt class="docutils literal"><span class="pre">BooleanField</span></tt><a class="headerlink" href="#booleanfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.BooleanField"> | |
| <em class="property">class </em><tt class="descname">BooleanField</tt>(<em>**options</em>)<a class="headerlink" href="#django.db.models.BooleanField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A true/false field.</p> | |
| <p>The default form widget for this field is a | |
| <a class="reference internal" href="../../forms/widgets/#django.forms.CheckboxInput" title="django.forms.CheckboxInput"><tt class="xref py py-class docutils literal"><span class="pre">CheckboxInput</span></tt></a>.</p> | |
| <p>If you need to accept <a class="reference internal" href="#django.db.models.Field.null" title="django.db.models.Field.null"><tt class="xref py py-attr docutils literal"><span class="pre">null</span></tt></a> values then use | |
| <a class="reference internal" href="#django.db.models.NullBooleanField" title="django.db.models.NullBooleanField"><tt class="xref py py-class docutils literal"><span class="pre">NullBooleanField</span></tt></a> instead.</p> | |
| <div class="versionchanged"> | |
| <span class="title">Changed in Django 1.2:</span> In previous versions of Django when running under MySQL <tt class="docutils literal"><span class="pre">BooleanFields</span></tt> | |
| would return their data as <tt class="docutils literal"><span class="pre">ints</span></tt>, instead of true <tt class="docutils literal"><span class="pre">bools</span></tt>. See the | |
| release notes for a complete description of the change.</div> | |
| </div> | |
| <div class="section" id="s-charfield"> | |
| <span id="charfield"></span><h3><tt class="docutils literal"><span class="pre">CharField</span></tt><a class="headerlink" href="#charfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.CharField"> | |
| <em class="property">class </em><tt class="descname">CharField</tt>(<em>max_length=None</em><span class="optional">[</span>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.CharField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A string field, for small- to large-sized strings.</p> | |
| <p>For large amounts of text, use <a class="reference internal" href="#django.db.models.TextField" title="django.db.models.TextField"><tt class="xref py py-class docutils literal"><span class="pre">TextField</span></tt></a>.</p> | |
| <p>The default form widget for this field is a <a class="reference internal" href="../../forms/widgets/#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a>.</p> | |
| <p><a class="reference internal" href="#django.db.models.CharField" title="django.db.models.CharField"><tt class="xref py py-class docutils literal"><span class="pre">CharField</span></tt></a> has one extra required argument:</p> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.CharField.max_length"> | |
| <tt class="descclassname">CharField.</tt><tt class="descname">max_length</tt><a class="headerlink" href="#django.db.models.CharField.max_length" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>The maximum length (in characters) of the field. The max_length is enforced | |
| at the database level and in Django's validation.</p> | |
| </dd></dl> | |
| <div class="admonition note"> | |
| <p class="first admonition-title">Note</p> | |
| <p class="last">If you are writing an application that must be portable to multiple | |
| database backends, you should be aware that there are restrictions on | |
| <tt class="docutils literal"><span class="pre">max_length</span></tt> for some backends. Refer to the <a class="reference internal" href="../../databases/"><em>database backend | |
| notes</em></a> for details.</p> | |
| </div> | |
| <div class="admonition-mysql-users admonition "> | |
| <p class="first admonition-title">MySQL users</p> | |
| <p class="last">If you are using this field with MySQLdb 1.2.2 and the <tt class="docutils literal"><span class="pre">utf8_bin</span></tt> | |
| collation (which is <em>not</em> the default), there are some issues to be aware | |
| of. Refer to the <a class="reference internal" href="../../databases/#mysql-collation"><em>MySQL database notes</em></a> for | |
| details.</p> | |
| </div> | |
| </div> | |
| <div class="section" id="s-commaseparatedintegerfield"> | |
| <span id="commaseparatedintegerfield"></span><h3><tt class="docutils literal"><span class="pre">CommaSeparatedIntegerField</span></tt><a class="headerlink" href="#commaseparatedintegerfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.CommaSeparatedIntegerField"> | |
| <em class="property">class </em><tt class="descname">CommaSeparatedIntegerField</tt>(<em>max_length=None</em><span class="optional">[</span>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.CommaSeparatedIntegerField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A field of integers separated by commas. As in <a class="reference internal" href="#django.db.models.CharField" title="django.db.models.CharField"><tt class="xref py py-class docutils literal"><span class="pre">CharField</span></tt></a>, the | |
| <a class="reference internal" href="#django.db.models.CharField.max_length" title="django.db.models.CharField.max_length"><tt class="xref py py-attr docutils literal"><span class="pre">max_length</span></tt></a> argument is required and the note about database | |
| portability mentioned there should be heeded.</p> | |
| </div> | |
| <div class="section" id="s-datefield"> | |
| <span id="datefield"></span><h3><tt class="docutils literal"><span class="pre">DateField</span></tt><a class="headerlink" href="#datefield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.DateField"> | |
| <em class="property">class </em><tt class="descname">DateField</tt>(<span class="optional">[</span><em>auto_now=False</em>, <em>auto_now_add=False</em>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.DateField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A date, represented in Python by a <tt class="docutils literal"><span class="pre">datetime.date</span></tt> instance. Has a few extra, | |
| optional arguments:</p> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.DateField.auto_now"> | |
| <tt class="descclassname">DateField.</tt><tt class="descname">auto_now</tt><a class="headerlink" href="#django.db.models.DateField.auto_now" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Automatically set the field to now every time the object is saved. Useful | |
| for "last-modified" timestamps. Note that the current date is <em>always</em> | |
| used; it's not just a default value that you can override.</p> | |
| </dd></dl> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.DateField.auto_now_add"> | |
| <tt class="descclassname">DateField.</tt><tt class="descname">auto_now_add</tt><a class="headerlink" href="#django.db.models.DateField.auto_now_add" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Automatically set the field to now when the object is first created. Useful | |
| for creation of timestamps. Note that the current date is <em>always</em> used; | |
| it's not just a default value that you can override.</p> | |
| </dd></dl> | |
| <p>The default form widget for this field is a | |
| <a class="reference internal" href="../../forms/widgets/#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a>. The admin adds a JavaScript calendar, | |
| and a shortcut for "Today". Includes an additional <tt class="docutils literal"><span class="pre">invalid_date</span></tt> error | |
| message key.</p> | |
| <div class="admonition note"> | |
| <p class="first admonition-title">Note</p> | |
| <p class="last">As currently implemented, setting <tt class="docutils literal"><span class="pre">auto_now</span></tt> or <tt class="docutils literal"><span class="pre">auto_now_add</span></tt> to | |
| <tt class="xref docutils literal"><span class="pre">True</span></tt> will cause the field to have <tt class="docutils literal"><span class="pre">editable=False</span></tt> and <tt class="docutils literal"><span class="pre">blank=True</span></tt> | |
| set.</p> | |
| </div> | |
| </div> | |
| <div class="section" id="s-datetimefield"> | |
| <span id="datetimefield"></span><h3><tt class="docutils literal"><span class="pre">DateTimeField</span></tt><a class="headerlink" href="#datetimefield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.DateTimeField"> | |
| <em class="property">class </em><tt class="descname">DateTimeField</tt>(<span class="optional">[</span><em>auto_now=False</em>, <em>auto_now_add=False</em>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.DateTimeField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A date and time, represented in Python by a <tt class="docutils literal"><span class="pre">datetime.datetime</span></tt> instance. | |
| Takes the same extra arguments as <a class="reference internal" href="#django.db.models.DateField" title="django.db.models.DateField"><tt class="xref py py-class docutils literal"><span class="pre">DateField</span></tt></a>.</p> | |
| <p>The default form widget for this field is a single | |
| <a class="reference internal" href="../../forms/widgets/#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a>. The admin uses two separate | |
| <a class="reference internal" href="../../forms/widgets/#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a> widgets with JavaScript shortcuts.</p> | |
| </div> | |
| <div class="section" id="s-decimalfield"> | |
| <span id="decimalfield"></span><h3><tt class="docutils literal"><span class="pre">DecimalField</span></tt><a class="headerlink" href="#decimalfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.DecimalField"> | |
| <em class="property">class </em><tt class="descname">DecimalField</tt>(<em>max_digits=None</em>, <em>decimal_places=None</em><span class="optional">[</span>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.DecimalField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A fixed-precision decimal number, represented in Python by a | |
| <a class="reference external" href="http://docs.python.org/2.7/library/decimal.html#decimal.Decimal" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">Decimal</span></tt></a> instance. Has two <strong>required</strong> arguments:</p> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.DecimalField.max_digits"> | |
| <tt class="descclassname">DecimalField.</tt><tt class="descname">max_digits</tt><a class="headerlink" href="#django.db.models.DecimalField.max_digits" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>The maximum number of digits allowed in the number. Note that this number | |
| must be greater than or equal to <tt class="docutils literal"><span class="pre">decimal_places</span></tt>, if it exists.</p> | |
| </dd></dl> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.DecimalField.decimal_places"> | |
| <tt class="descclassname">DecimalField.</tt><tt class="descname">decimal_places</tt><a class="headerlink" href="#django.db.models.DecimalField.decimal_places" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>The number of decimal places to store with the number.</p> | |
| </dd></dl> | |
| <p>For example, to store numbers up to 999 with a resolution of 2 decimal places, | |
| you'd use:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="n">models</span><span class="o">.</span><span class="n">DecimalField</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">max_digits</span><span class="o">=</span><span class="mi">5</span><span class="p">,</span> <span class="n">decimal_places</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>And to store numbers up to approximately one billion with a resolution of 10 | |
| decimal places:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="n">models</span><span class="o">.</span><span class="n">DecimalField</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">max_digits</span><span class="o">=</span><span class="mi">19</span><span class="p">,</span> <span class="n">decimal_places</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>The default form widget for this field is a <a class="reference internal" href="../../forms/widgets/#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a>.</p> | |
| <div class="admonition note"> | |
| <p class="first admonition-title">Note</p> | |
| <p class="last">For more information about the differences between the | |
| <a class="reference internal" href="#django.db.models.FloatField" title="django.db.models.FloatField"><tt class="xref py py-class docutils literal"><span class="pre">FloatField</span></tt></a> and <a class="reference internal" href="#django.db.models.DecimalField" title="django.db.models.DecimalField"><tt class="xref py py-class docutils literal"><span class="pre">DecimalField</span></tt></a> classes, please | |
| see <a class="reference internal" href="#floatfield-vs-decimalfield"><em>FloatField vs. DecimalField</em></a>.</p> | |
| </div> | |
| </div> | |
| <div class="section" id="s-emailfield"> | |
| <span id="emailfield"></span><h3><tt class="docutils literal"><span class="pre">EmailField</span></tt><a class="headerlink" href="#emailfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.EmailField"> | |
| <em class="property">class </em><tt class="descname">EmailField</tt>(<span class="optional">[</span><em>max_length=75</em>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.EmailField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A <a class="reference internal" href="#django.db.models.CharField" title="django.db.models.CharField"><tt class="xref py py-class docutils literal"><span class="pre">CharField</span></tt></a> that checks that the value is a valid email address.</p> | |
| </div> | |
| <div class="section" id="s-filefield"> | |
| <span id="filefield"></span><h3><tt class="docutils literal"><span class="pre">FileField</span></tt><a class="headerlink" href="#filefield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.FileField"> | |
| <em class="property">class </em><tt class="descname">FileField</tt>(<em>upload_to=None</em><span class="optional">[</span>, <em>max_length=100</em>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.FileField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A file-upload field.</p> | |
| <div class="admonition note"> | |
| <p class="first admonition-title">Note</p> | |
| <p class="last">The <tt class="docutils literal"><span class="pre">primary_key</span></tt> and <tt class="docutils literal"><span class="pre">unique</span></tt> arguments are not supported, and will | |
| raise a <tt class="docutils literal"><span class="pre">TypeError</span></tt> if used.</p> | |
| </div> | |
| <p>Has one <strong>required</strong> argument:</p> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.FileField.upload_to"> | |
| <tt class="descclassname">FileField.</tt><tt class="descname">upload_to</tt><a class="headerlink" href="#django.db.models.FileField.upload_to" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>A local filesystem path that will be appended to your <a class="reference internal" href="../../settings/#std:setting-MEDIA_ROOT"><tt class="xref std std-setting docutils literal"><span class="pre">MEDIA_ROOT</span></tt></a> | |
| setting to determine the value of the <tt class="xref py py-attr docutils literal"><span class="pre">url</span></tt> | |
| attribute.</p> | |
| <p>This path may contain <a class="reference external" href="http://docs.python.org/2.7/library/time.html#time.strftime" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">strftime()</span></tt></a> formatting, which will be | |
| replaced by the date/time of the file upload (so that uploaded files don't | |
| fill up the given directory).</p> | |
| <p>This may also be a callable, such as a function, which will be called to | |
| obtain the upload path, including the filename. This callable must be able | |
| to accept two arguments, and return a Unix-style path (with forward slashes) | |
| to be passed along to the storage system. The two arguments that will be | |
| passed are:</p> | |
| <table class="docutils"> | |
| <colgroup> | |
| <col width="32%" /> | |
| <col width="68%" /> | |
| </colgroup> | |
| <thead valign="bottom"> | |
| <tr><th class="head">Argument</th> | |
| <th class="head">Description</th> | |
| </tr> | |
| </thead> | |
| <tbody valign="top"> | |
| <tr><td><tt class="docutils literal"><span class="pre">instance</span></tt></td> | |
| <td><p class="first">An instance of the model where the | |
| <tt class="docutils literal"><span class="pre">FileField</span></tt> is defined. More specifically, | |
| this is the particular instance where the | |
| current file is being attached.</p> | |
| <p class="last">In most cases, this object will not have been | |
| saved to the database yet, so if it uses the | |
| default <tt class="docutils literal"><span class="pre">AutoField</span></tt>, <em>it might not yet have a | |
| value for its primary key field</em>.</p> | |
| </td> | |
| </tr> | |
| <tr><td><tt class="docutils literal"><span class="pre">filename</span></tt></td> | |
| <td>The filename that was originally given to the | |
| file. This may or may not be taken into account | |
| when determining the final destination path.</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </dd></dl> | |
| <p>Also has one optional argument:</p> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.FileField.storage"> | |
| <tt class="descclassname">FileField.</tt><tt class="descname">storage</tt><a class="headerlink" href="#django.db.models.FileField.storage" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Optional. A storage object, which handles the storage and retrieval of your | |
| files. See <a class="reference internal" href="../../../topics/files/"><em>Managing files</em></a> for details on how to provide this object.</p> | |
| </dd></dl> | |
| <p>The default form widget for this field is a | |
| <tt class="xref py py-class docutils literal"><span class="pre">FileInput</span></tt>.</p> | |
| <p>Using a <a class="reference internal" href="#django.db.models.FileField" title="django.db.models.FileField"><tt class="xref py py-class docutils literal"><span class="pre">FileField</span></tt></a> or an <a class="reference internal" href="#django.db.models.ImageField" title="django.db.models.ImageField"><tt class="xref py py-class docutils literal"><span class="pre">ImageField</span></tt></a> (see below) in a model | |
| takes a few steps:</p> | |
| <ol class="arabic simple"> | |
| <li>In your settings file, you'll need to define <a class="reference internal" href="../../settings/#std:setting-MEDIA_ROOT"><tt class="xref std std-setting docutils literal"><span class="pre">MEDIA_ROOT</span></tt></a> as the | |
| full path to a directory where you'd like Django to store uploaded files. | |
| (For performance, these files are not stored in the database.) Define | |
| <a class="reference internal" href="../../settings/#std:setting-MEDIA_URL"><tt class="xref std std-setting docutils literal"><span class="pre">MEDIA_URL</span></tt></a> as the base public URL of that directory. Make sure | |
| that this directory is writable by the Web server's user account.</li> | |
| <li>Add the <a class="reference internal" href="#django.db.models.FileField" title="django.db.models.FileField"><tt class="xref py py-class docutils literal"><span class="pre">FileField</span></tt></a> or <a class="reference internal" href="#django.db.models.ImageField" title="django.db.models.ImageField"><tt class="xref py py-class docutils literal"><span class="pre">ImageField</span></tt></a> to your model, making | |
| sure to define the <a class="reference internal" href="#django.db.models.FileField.upload_to" title="django.db.models.FileField.upload_to"><tt class="xref py py-attr docutils literal"><span class="pre">upload_to</span></tt></a> option to tell Django | |
| to which subdirectory of <a class="reference internal" href="../../settings/#std:setting-MEDIA_ROOT"><tt class="xref std std-setting docutils literal"><span class="pre">MEDIA_ROOT</span></tt></a> it should upload files.</li> | |
| <li>All that will be stored in your database is a path to the file | |
| (relative to <a class="reference internal" href="../../settings/#std:setting-MEDIA_ROOT"><tt class="xref std std-setting docutils literal"><span class="pre">MEDIA_ROOT</span></tt></a>). You'll most likely want to use the | |
| convenience <tt class="xref py py-attr docutils literal"><span class="pre">url</span></tt> function provided by | |
| Django. For example, if your <a class="reference internal" href="#django.db.models.ImageField" title="django.db.models.ImageField"><tt class="xref py py-class docutils literal"><span class="pre">ImageField</span></tt></a> is called <tt class="docutils literal"><span class="pre">mug_shot</span></tt>, | |
| you can get the absolute path to your image in a template with | |
| <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">object.mug_shot.url</span> <span class="pre">}}</span></tt>.</li> | |
| </ol> | |
| <p>For example, say your <a class="reference internal" href="../../settings/#std:setting-MEDIA_ROOT"><tt class="xref std std-setting docutils literal"><span class="pre">MEDIA_ROOT</span></tt></a> is set to <tt class="docutils literal"><span class="pre">'/home/media'</span></tt>, and | |
| <a class="reference internal" href="#django.db.models.FileField.upload_to" title="django.db.models.FileField.upload_to"><tt class="xref py py-attr docutils literal"><span class="pre">upload_to</span></tt></a> is set to <tt class="docutils literal"><span class="pre">'photos/%Y/%m/%d'</span></tt>. The <tt class="docutils literal"><span class="pre">'%Y/%m/%d'</span></tt> | |
| part of <a class="reference internal" href="#django.db.models.FileField.upload_to" title="django.db.models.FileField.upload_to"><tt class="xref py py-attr docutils literal"><span class="pre">upload_to</span></tt></a> is <a class="reference external" href="http://docs.python.org/2.7/library/time.html#time.strftime" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">strftime()</span></tt></a> formatting; | |
| <tt class="docutils literal"><span class="pre">'%Y'</span></tt> is the four-digit year, <tt class="docutils literal"><span class="pre">'%m'</span></tt> is the two-digit month and <tt class="docutils literal"><span class="pre">'%d'</span></tt> is | |
| the two-digit day. If you upload a file on Jan. 15, 2007, it will be saved in | |
| the directory <tt class="docutils literal"><span class="pre">/home/media/photos/2007/01/15</span></tt>.</p> | |
| <p>If you wanted to retrieve the uploaded file's on-disk filename, or the file's | |
| size, you could use the <a class="reference internal" href="../../files/file/#django.core.files.File.name" title="django.core.files.File.name"><tt class="xref py py-attr docutils literal"><span class="pre">name</span></tt></a> and | |
| <a class="reference internal" href="../../files/file/#django.core.files.File.size" title="django.core.files.File.size"><tt class="xref py py-attr docutils literal"><span class="pre">size</span></tt></a> attributes respectively; for more | |
| information on the available attributes and methods, see the | |
| <a class="reference internal" href="../../files/file/#django.core.files.File" title="django.core.files.File"><tt class="xref py py-class docutils literal"><span class="pre">File</span></tt></a> class reference and the <a class="reference internal" href="../../../topics/files/"><em>Managing files</em></a> | |
| topic guide.</p> | |
| <div class="admonition note"> | |
| <p class="first admonition-title">Note</p> | |
| <p class="last">The file is saved as part of saving the model in the database, so the actual | |
| file name used on disk cannot be relied on until after the model has been | |
| saved.</p> | |
| </div> | |
| <p>The uploaded file's relative URL can be obtained using the | |
| <tt class="xref py py-attr docutils literal"><span class="pre">url</span></tt> attribute. Internally, | |
| this calls the <a class="reference internal" href="../../files/storage/#django.core.files.storage.Storage.url" title="django.core.files.storage.Storage.url"><tt class="xref py py-meth docutils literal"><span class="pre">url()</span></tt></a> method of the | |
| underlying <a class="reference internal" href="../../files/storage/#django.core.files.storage.Storage" title="django.core.files.storage.Storage"><tt class="xref py py-class docutils literal"><span class="pre">Storage</span></tt></a> class.</p> | |
| <p id="file-upload-security">Note that whenever you deal with uploaded files, you should pay close attention | |
| to where you're uploading them and what type of files they are, to avoid | |
| security holes. <em>Validate all uploaded files</em> so that you're sure the files are | |
| what you think they are. For example, if you blindly let somebody upload files, | |
| without validation, to a directory that's within your Web server's document | |
| root, then somebody could upload a CGI or PHP script and execute that script by | |
| visiting its URL on your site. Don't allow that.</p> | |
| <p>Also note that even an uploaded HTML file, since it can be executed by the | |
| browser (though not by the server), can pose security threats that are | |
| equivalent to XSS or CSRF attacks.</p> | |
| <p>By default, <a class="reference internal" href="#django.db.models.FileField" title="django.db.models.FileField"><tt class="xref py py-class docutils literal"><span class="pre">FileField</span></tt></a> instances are | |
| created as <tt class="docutils literal"><span class="pre">varchar(100)</span></tt> columns in your database. As with other fields, you | |
| can change the maximum length using the <a class="reference internal" href="#django.db.models.CharField.max_length" title="django.db.models.CharField.max_length"><tt class="xref py py-attr docutils literal"><span class="pre">max_length</span></tt></a> argument.</p> | |
| <div class="section" id="s-filefield-and-fieldfile"> | |
| <span id="filefield-and-fieldfile"></span><h4>FileField and FieldFile<a class="headerlink" href="#filefield-and-fieldfile" title="Permalink to this headline">¶</a></h4> | |
| <p>When you access a <a class="reference internal" href="#django.db.models.FileField" title="django.db.models.FileField"><tt class="xref py py-class docutils literal"><span class="pre">FileField</span></tt></a> on a model, you are given an instance | |
| of <tt class="xref py py-class docutils literal"><span class="pre">FieldFile</span></tt> as a proxy for accessing the underlying file. This | |
| class has several methods that can be used to interact with file data:</p> | |
| <dl class="method"> | |
| <dt id="django.db.models.FieldFile.open"> | |
| <tt class="descclassname">FieldFile.</tt><tt class="descname">open</tt>(<em>mode='rb'</em>)<a class="headerlink" href="#django.db.models.FieldFile.open" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>Behaves like the standard Python <tt class="docutils literal"><span class="pre">open()</span></tt> method and opens the file | |
| associated with this instance in the mode specified by <tt class="docutils literal"><span class="pre">mode</span></tt>.</p> | |
| <dl class="method"> | |
| <dt id="django.db.models.FieldFile.close"> | |
| <tt class="descclassname">FieldFile.</tt><tt class="descname">close</tt>()<a class="headerlink" href="#django.db.models.FieldFile.close" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>Behaves like the standard Python <tt class="docutils literal"><span class="pre">file.close()</span></tt> method and closes the file | |
| associated with this instance.</p> | |
| <dl class="method"> | |
| <dt id="django.db.models.FieldFile.save"> | |
| <tt class="descclassname">FieldFile.</tt><tt class="descname">save</tt>(<em>name</em>, <em>content</em>, <em>save=True</em>)<a class="headerlink" href="#django.db.models.FieldFile.save" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>This method takes a filename and file contents and passes them to the storage | |
| class for the field, then associates the stored file with the model field. | |
| If you want to manually associate file data with <a class="reference internal" href="#django.db.models.FileField" title="django.db.models.FileField"><tt class="xref py py-class docutils literal"><span class="pre">FileField</span></tt></a> | |
| instances on your model, the <tt class="docutils literal"><span class="pre">save()</span></tt> method is used to persist that file | |
| data.</p> | |
| <p>Takes two required arguments: <tt class="docutils literal"><span class="pre">name</span></tt> which is the name of the file, and | |
| <tt class="docutils literal"><span class="pre">content</span></tt> which is an object containing the file's contents. The | |
| optional <tt class="docutils literal"><span class="pre">save</span></tt> argument controls whether or not the instance is | |
| saved after the file has been altered. Defaults to <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p> | |
| <p>Note that the <tt class="docutils literal"><span class="pre">content</span></tt> argument should be an instance of | |
| <a class="reference internal" href="../../files/file/#django.core.files.File" title="django.core.files.File"><tt class="xref py py-class docutils literal"><span class="pre">django.core.files.File</span></tt></a>, not Python's built-in file object. | |
| You can construct a <a class="reference internal" href="../../files/file/#django.core.files.File" title="django.core.files.File"><tt class="xref py py-class docutils literal"><span class="pre">File</span></tt></a> from an existing | |
| Python file object like this:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.core.files</span> <span class="kn">import</span> <span class="n">File</span> | |
| <span class="c"># Open an existing file using Python's built-in open()</span> | |
| <span class="n">f</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s">'/tmp/hello.world'</span><span class="p">)</span> | |
| <span class="n">myfile</span> <span class="o">=</span> <span class="n">File</span><span class="p">(</span><span class="n">f</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>Or you can construct one from a Python string like this:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.core.files.base</span> <span class="kn">import</span> <span class="n">ContentFile</span> | |
| <span class="n">myfile</span> <span class="o">=</span> <span class="n">ContentFile</span><span class="p">(</span><span class="s">"hello world"</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>For more information, see <a class="reference internal" href="../../../topics/files/"><em>Managing files</em></a>.</p> | |
| <dl class="method"> | |
| <dt id="django.db.models.FieldFile.delete"> | |
| <tt class="descclassname">FieldFile.</tt><tt class="descname">delete</tt>(<em>save=True</em>)<a class="headerlink" href="#django.db.models.FieldFile.delete" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>Deletes the file associated with this instance and clears all attributes on | |
| the field. Note: This method will close the file if it happens to be open when | |
| <tt class="docutils literal"><span class="pre">delete()</span></tt> is called.</p> | |
| <p>The optional <tt class="docutils literal"><span class="pre">save</span></tt> argument controls whether or not the instance is saved | |
| after the file has been deleted. Defaults to <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p> | |
| <p>Note that when a model is deleted, related files are not deleted. If you need | |
| to cleanup orphaned files, you'll need to handle it yourself (for instance, | |
| with a custom management command that can be run manually or scheduled to run | |
| periodically via e.g. cron).</p> | |
| </div> | |
| </div> | |
| <div class="section" id="s-filepathfield"> | |
| <span id="filepathfield"></span><h3><tt class="docutils literal"><span class="pre">FilePathField</span></tt><a class="headerlink" href="#filepathfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.FilePathField"> | |
| <em class="property">class </em><tt class="descname">FilePathField</tt>(<em>path=None</em><span class="optional">[</span>, <em>match=None</em>, <em>recursive=False</em>, <em>max_length=100</em>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.FilePathField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A <a class="reference internal" href="#django.db.models.CharField" title="django.db.models.CharField"><tt class="xref py py-class docutils literal"><span class="pre">CharField</span></tt></a> whose choices are limited to the filenames in a certain | |
| directory on the filesystem. Has three special arguments, of which the first is | |
| <strong>required</strong>:</p> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.FilePathField.path"> | |
| <tt class="descclassname">FilePathField.</tt><tt class="descname">path</tt><a class="headerlink" href="#django.db.models.FilePathField.path" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Required. The absolute filesystem path to a directory from which this | |
| <a class="reference internal" href="#django.db.models.FilePathField" title="django.db.models.FilePathField"><tt class="xref py py-class docutils literal"><span class="pre">FilePathField</span></tt></a> should get its choices. Example: <tt class="docutils literal"><span class="pre">"/home/images"</span></tt>.</p> | |
| </dd></dl> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.FilePathField.match"> | |
| <tt class="descclassname">FilePathField.</tt><tt class="descname">match</tt><a class="headerlink" href="#django.db.models.FilePathField.match" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Optional. A regular expression, as a string, that <a class="reference internal" href="#django.db.models.FilePathField" title="django.db.models.FilePathField"><tt class="xref py py-class docutils literal"><span class="pre">FilePathField</span></tt></a> | |
| will use to filter filenames. Note that the regex will be applied to the | |
| base filename, not the full path. Example: <tt class="docutils literal"><span class="pre">"foo.*\.txt$"</span></tt>, which will | |
| match a file called <tt class="docutils literal"><span class="pre">foo23.txt</span></tt> but not <tt class="docutils literal"><span class="pre">bar.txt</span></tt> or <tt class="docutils literal"><span class="pre">foo23.gif</span></tt>.</p> | |
| </dd></dl> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.FilePathField.recursive"> | |
| <tt class="descclassname">FilePathField.</tt><tt class="descname">recursive</tt><a class="headerlink" href="#django.db.models.FilePathField.recursive" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Optional. Either <tt class="xref docutils literal"><span class="pre">True</span></tt> or <tt class="xref docutils literal"><span class="pre">False</span></tt>. Default is <tt class="xref docutils literal"><span class="pre">False</span></tt>. Specifies | |
| whether all subdirectories of <a class="reference internal" href="#django.db.models.FilePathField.path" title="django.db.models.FilePathField.path"><tt class="xref py py-attr docutils literal"><span class="pre">path</span></tt></a> should be included</p> | |
| </dd></dl> | |
| <p>Of course, these arguments can be used together.</p> | |
| <p>The one potential gotcha is that <a class="reference internal" href="#django.db.models.FilePathField.match" title="django.db.models.FilePathField.match"><tt class="xref py py-attr docutils literal"><span class="pre">match</span></tt></a> applies to the | |
| base filename, not the full path. So, this example:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="n">FilePathField</span><span class="p">(</span><span class="n">path</span><span class="o">=</span><span class="s">"/home/images"</span><span class="p">,</span> <span class="n">match</span><span class="o">=</span><span class="s">"foo.*"</span><span class="p">,</span> <span class="n">recursive</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>...will match <tt class="docutils literal"><span class="pre">/home/images/foo.gif</span></tt> but not <tt class="docutils literal"><span class="pre">/home/images/foo/bar.gif</span></tt> | |
| because the <a class="reference internal" href="#django.db.models.FilePathField.match" title="django.db.models.FilePathField.match"><tt class="xref py py-attr docutils literal"><span class="pre">match</span></tt></a> applies to the base filename | |
| (<tt class="docutils literal"><span class="pre">foo.gif</span></tt> and <tt class="docutils literal"><span class="pre">bar.gif</span></tt>).</p> | |
| <p>By default, <a class="reference internal" href="#django.db.models.FilePathField" title="django.db.models.FilePathField"><tt class="xref py py-class docutils literal"><span class="pre">FilePathField</span></tt></a> instances are | |
| created as <tt class="docutils literal"><span class="pre">varchar(100)</span></tt> columns in your database. As with other fields, you | |
| can change the maximum length using the <a class="reference internal" href="#django.db.models.CharField.max_length" title="django.db.models.CharField.max_length"><tt class="xref py py-attr docutils literal"><span class="pre">max_length</span></tt></a> argument.</p> | |
| </div> | |
| <div class="section" id="s-floatfield"> | |
| <span id="floatfield"></span><h3><tt class="docutils literal"><span class="pre">FloatField</span></tt><a class="headerlink" href="#floatfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.FloatField"> | |
| <em class="property">class </em><tt class="descname">FloatField</tt>(<span class="optional">[</span><em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.FloatField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A floating-point number represented in Python by a <tt class="docutils literal"><span class="pre">float</span></tt> instance.</p> | |
| <p>The default form widget for this field is a <a class="reference internal" href="../../forms/widgets/#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a>.</p> | |
| <div class="admonition-floatfield-vs-decimalfield admonition " id="floatfield-vs-decimalfield"> | |
| <p class="first admonition-title"><tt class="docutils literal"><span class="pre">FloatField</span></tt> vs. <tt class="docutils literal"><span class="pre">DecimalField</span></tt></p> | |
| <p class="last">The <a class="reference internal" href="#django.db.models.FloatField" title="django.db.models.FloatField"><tt class="xref py py-class docutils literal"><span class="pre">FloatField</span></tt></a> class is sometimes mixed up with the | |
| <a class="reference internal" href="#django.db.models.DecimalField" title="django.db.models.DecimalField"><tt class="xref py py-class docutils literal"><span class="pre">DecimalField</span></tt></a> class. Although they both represent real numbers, they | |
| represent those numbers differently. <tt class="docutils literal"><span class="pre">FloatField</span></tt> uses Python's <tt class="docutils literal"><span class="pre">float</span></tt> | |
| type internally, while <tt class="docutils literal"><span class="pre">DecimalField</span></tt> uses Python's <tt class="docutils literal"><span class="pre">Decimal</span></tt> type. For | |
| information on the difference between the two, see Python's documentation | |
| for the <a class="reference external" href="http://docs.python.org/2.7/library/decimal.html#decimal" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">decimal</span></tt></a> module.</p> | |
| </div> | |
| </div> | |
| <div class="section" id="s-imagefield"> | |
| <span id="imagefield"></span><h3><tt class="docutils literal"><span class="pre">ImageField</span></tt><a class="headerlink" href="#imagefield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.ImageField"> | |
| <em class="property">class </em><tt class="descname">ImageField</tt>(<em>upload_to=None</em><span class="optional">[</span>, <em>height_field=None</em>, <em>width_field=None</em>, <em>max_length=100</em>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.ImageField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>Inherits all attributes and methods from <a class="reference internal" href="#django.db.models.FileField" title="django.db.models.FileField"><tt class="xref py py-class docutils literal"><span class="pre">FileField</span></tt></a>, but also | |
| validates that the uploaded object is a valid image.</p> | |
| <p>In addition to the special attributes that are available for <a class="reference internal" href="#django.db.models.FileField" title="django.db.models.FileField"><tt class="xref py py-class docutils literal"><span class="pre">FileField</span></tt></a>, | |
| an <a class="reference internal" href="#django.db.models.ImageField" title="django.db.models.ImageField"><tt class="xref py py-class docutils literal"><span class="pre">ImageField</span></tt></a> also has <tt class="xref py py-attr docutils literal"><span class="pre">height</span></tt> and | |
| <tt class="xref py py-attr docutils literal"><span class="pre">width</span></tt> attributes.</p> | |
| <p>To facilitate querying on those attributes, <a class="reference internal" href="#django.db.models.ImageField" title="django.db.models.ImageField"><tt class="xref py py-class docutils literal"><span class="pre">ImageField</span></tt></a> has two extra | |
| optional arguments:</p> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.ImageField.height_field"> | |
| <tt class="descclassname">ImageField.</tt><tt class="descname">height_field</tt><a class="headerlink" href="#django.db.models.ImageField.height_field" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Name of a model field which will be auto-populated with the height of the | |
| image each time the model instance is saved.</p> | |
| </dd></dl> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.ImageField.width_field"> | |
| <tt class="descclassname">ImageField.</tt><tt class="descname">width_field</tt><a class="headerlink" href="#django.db.models.ImageField.width_field" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Name of a model field which will be auto-populated with the width of the | |
| image each time the model instance is saved.</p> | |
| </dd></dl> | |
| <p>Requires the <a class="reference external" href="http://www.pythonware.com/products/pil/">Python Imaging Library</a>.</p> | |
| <p>By default, <a class="reference internal" href="#django.db.models.ImageField" title="django.db.models.ImageField"><tt class="xref py py-class docutils literal"><span class="pre">ImageField</span></tt></a> instances are created as <tt class="docutils literal"><span class="pre">varchar(100)</span></tt> | |
| columns in your database. As with other fields, you can change the maximum | |
| length using the <a class="reference internal" href="#django.db.models.CharField.max_length" title="django.db.models.CharField.max_length"><tt class="xref py py-attr docutils literal"><span class="pre">max_length</span></tt></a> argument.</p> | |
| </div> | |
| <div class="section" id="s-integerfield"> | |
| <span id="integerfield"></span><h3><tt class="docutils literal"><span class="pre">IntegerField</span></tt><a class="headerlink" href="#integerfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.IntegerField"> | |
| <em class="property">class </em><tt class="descname">IntegerField</tt>(<span class="optional">[</span><em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.IntegerField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>An integer. The default form widget for this field is a | |
| <a class="reference internal" href="../../forms/widgets/#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a>.</p> | |
| </div> | |
| <div class="section" id="s-ipaddressfield"> | |
| <span id="ipaddressfield"></span><h3><tt class="docutils literal"><span class="pre">IPAddressField</span></tt><a class="headerlink" href="#ipaddressfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.IPAddressField"> | |
| <em class="property">class </em><tt class="descname">IPAddressField</tt>(<span class="optional">[</span><em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.IPAddressField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>An IP address, in string format (e.g. "192.0.2.30"). The default form widget | |
| for this field is a <a class="reference internal" href="../../forms/widgets/#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a>.</p> | |
| </div> | |
| <div class="section" id="s-genericipaddressfield"> | |
| <span id="genericipaddressfield"></span><h3><tt class="docutils literal"><span class="pre">GenericIPAddressField</span></tt><a class="headerlink" href="#genericipaddressfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.GenericIPAddressField"> | |
| <em class="property">class </em><tt class="descname">GenericIPAddressField</tt>(<span class="optional">[</span><em>protocol=both</em>, <em>unpack_ipv4=False</em>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.GenericIPAddressField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <div class="versionadded"> | |
| <span class="title">New in Django 1.4:</span> <a class="reference internal" href="../../../releases/1.4/"><em>Please see the release notes</em></a></div> | |
| <p>An IPv4 or IPv6 address, in string format (e.g. <tt class="docutils literal"><span class="pre">192.0.2.30</span></tt> or | |
| <tt class="docutils literal"><span class="pre">2a02:42fe::4</span></tt>). The default form widget for this field is a | |
| <a class="reference internal" href="../../forms/widgets/#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a>.</p> | |
| <p>The IPv6 address normalization follows <span class="target" id="index-0"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc4291.html#section-2.2"><strong>RFC 4291</strong></a> section 2.2, | |
| including using the IPv4 format suggested in paragraph 3 of that section, like | |
| <tt class="docutils literal"><span class="pre">::ffff:192.0.2.0</span></tt>. For example, <tt class="docutils literal"><span class="pre">2001:0::0:01</span></tt> would be normalized to | |
| <tt class="docutils literal"><span class="pre">2001::1</span></tt>, and <tt class="docutils literal"><span class="pre">::ffff:0a0a:0a0a</span></tt> to <tt class="docutils literal"><span class="pre">::ffff:10.10.10.10</span></tt>. All characters | |
| are converted to lowercase.</p> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.GenericIPAddressField.protocol"> | |
| <tt class="descclassname">GenericIPAddressField.</tt><tt class="descname">protocol</tt><a class="headerlink" href="#django.db.models.GenericIPAddressField.protocol" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Limits valid inputs to the specified protocol. | |
| Accepted values are <tt class="docutils literal"><span class="pre">'both'</span></tt> (default), <tt class="docutils literal"><span class="pre">'IPv4'</span></tt> | |
| or <tt class="docutils literal"><span class="pre">'IPv6'</span></tt>. Matching is case insensitive.</p> | |
| </dd></dl> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.GenericIPAddressField.unpack_ipv4"> | |
| <tt class="descclassname">GenericIPAddressField.</tt><tt class="descname">unpack_ipv4</tt><a class="headerlink" href="#django.db.models.GenericIPAddressField.unpack_ipv4" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Unpacks IPv4 mapped addresses like <tt class="docutils literal"><span class="pre">::ffff::192.0.2.1</span></tt>. | |
| If this option is enabled that address would be unpacked to | |
| <tt class="docutils literal"><span class="pre">192.0.2.1</span></tt>. Default is disabled. Can only be used | |
| when <tt class="docutils literal"><span class="pre">protocol</span></tt> is set to <tt class="docutils literal"><span class="pre">'both'</span></tt>.</p> | |
| </dd></dl> | |
| </div> | |
| <div class="section" id="s-nullbooleanfield"> | |
| <span id="nullbooleanfield"></span><h3><tt class="docutils literal"><span class="pre">NullBooleanField</span></tt><a class="headerlink" href="#nullbooleanfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.NullBooleanField"> | |
| <em class="property">class </em><tt class="descname">NullBooleanField</tt>(<span class="optional">[</span><em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.NullBooleanField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>Like a <a class="reference internal" href="#django.db.models.BooleanField" title="django.db.models.BooleanField"><tt class="xref py py-class docutils literal"><span class="pre">BooleanField</span></tt></a>, but allows <tt class="docutils literal"><span class="pre">NULL</span></tt> as one of the options. Use | |
| this instead of a <a class="reference internal" href="#django.db.models.BooleanField" title="django.db.models.BooleanField"><tt class="xref py py-class docutils literal"><span class="pre">BooleanField</span></tt></a> with <tt class="docutils literal"><span class="pre">null=True</span></tt>. The default form | |
| widget for this field is a <a class="reference internal" href="../../forms/widgets/#django.forms.NullBooleanSelect" title="django.forms.NullBooleanSelect"><tt class="xref py py-class docutils literal"><span class="pre">NullBooleanSelect</span></tt></a>.</p> | |
| </div> | |
| <div class="section" id="s-positiveintegerfield"> | |
| <span id="positiveintegerfield"></span><h3><tt class="docutils literal"><span class="pre">PositiveIntegerField</span></tt><a class="headerlink" href="#positiveintegerfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.PositiveIntegerField"> | |
| <em class="property">class </em><tt class="descname">PositiveIntegerField</tt>(<span class="optional">[</span><em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.PositiveIntegerField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>Like an <a class="reference internal" href="#django.db.models.IntegerField" title="django.db.models.IntegerField"><tt class="xref py py-class docutils literal"><span class="pre">IntegerField</span></tt></a>, but must be either positive or zero (<cite>0</cite>). | |
| The value <cite>0</cite> is accepted for backward compatibility reasons.</p> | |
| </div> | |
| <div class="section" id="s-positivesmallintegerfield"> | |
| <span id="positivesmallintegerfield"></span><h3><tt class="docutils literal"><span class="pre">PositiveSmallIntegerField</span></tt><a class="headerlink" href="#positivesmallintegerfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.PositiveSmallIntegerField"> | |
| <em class="property">class </em><tt class="descname">PositiveSmallIntegerField</tt>(<span class="optional">[</span><em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.PositiveSmallIntegerField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>Like a <a class="reference internal" href="#django.db.models.PositiveIntegerField" title="django.db.models.PositiveIntegerField"><tt class="xref py py-class docutils literal"><span class="pre">PositiveIntegerField</span></tt></a>, but only allows values under a certain | |
| (database-dependent) point.</p> | |
| </div> | |
| <div class="section" id="s-slugfield"> | |
| <span id="slugfield"></span><h3><tt class="docutils literal"><span class="pre">SlugField</span></tt><a class="headerlink" href="#slugfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.SlugField"> | |
| <em class="property">class </em><tt class="descname">SlugField</tt>(<span class="optional">[</span><em>max_length=50</em>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.SlugField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p><a class="reference internal" href="../../../glossary/#term-slug"><em class="xref std std-term">Slug</em></a> is a newspaper term. A slug is a short label for something, | |
| containing only letters, numbers, underscores or hyphens. They're generally used | |
| in URLs.</p> | |
| <p>Like a CharField, you can specify <a class="reference internal" href="#django.db.models.CharField.max_length" title="django.db.models.CharField.max_length"><tt class="xref py py-attr docutils literal"><span class="pre">max_length</span></tt></a> (read the note | |
| about database portability and <a class="reference internal" href="#django.db.models.CharField.max_length" title="django.db.models.CharField.max_length"><tt class="xref py py-attr docutils literal"><span class="pre">max_length</span></tt></a> in that section, | |
| too). If <a class="reference internal" href="#django.db.models.CharField.max_length" title="django.db.models.CharField.max_length"><tt class="xref py py-attr docutils literal"><span class="pre">max_length</span></tt></a> is not specified, Django will use a | |
| default length of 50.</p> | |
| <p>Implies setting <a class="reference internal" href="#django.db.models.Field.db_index" title="django.db.models.Field.db_index"><tt class="xref py py-attr docutils literal"><span class="pre">Field.db_index</span></tt></a> to <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p> | |
| <p>It is often useful to automatically prepopulate a SlugField based on the value | |
| of some other value. You can do this automatically in the admin using | |
| <a class="reference internal" href="../../contrib/admin/#django.contrib.admin.ModelAdmin.prepopulated_fields" title="django.contrib.admin.ModelAdmin.prepopulated_fields"><tt class="xref py py-attr docutils literal"><span class="pre">prepopulated_fields</span></tt></a>.</p> | |
| </div> | |
| <div class="section" id="s-smallintegerfield"> | |
| <span id="smallintegerfield"></span><h3><tt class="docutils literal"><span class="pre">SmallIntegerField</span></tt><a class="headerlink" href="#smallintegerfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.SmallIntegerField"> | |
| <em class="property">class </em><tt class="descname">SmallIntegerField</tt>(<span class="optional">[</span><em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.SmallIntegerField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>Like an <a class="reference internal" href="#django.db.models.IntegerField" title="django.db.models.IntegerField"><tt class="xref py py-class docutils literal"><span class="pre">IntegerField</span></tt></a>, but only allows values under a certain | |
| (database-dependent) point.</p> | |
| </div> | |
| <div class="section" id="s-textfield"> | |
| <span id="textfield"></span><h3><tt class="docutils literal"><span class="pre">TextField</span></tt><a class="headerlink" href="#textfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.TextField"> | |
| <em class="property">class </em><tt class="descname">TextField</tt>(<span class="optional">[</span><em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.TextField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A large text field. The default form widget for this field is a | |
| <a class="reference internal" href="../../forms/widgets/#django.forms.Textarea" title="django.forms.Textarea"><tt class="xref py py-class docutils literal"><span class="pre">Textarea</span></tt></a>.</p> | |
| <div class="admonition-mysql-users admonition "> | |
| <p class="first admonition-title">MySQL users</p> | |
| <p class="last">If you are using this field with MySQLdb 1.2.1p2 and the <tt class="docutils literal"><span class="pre">utf8_bin</span></tt> | |
| collation (which is <em>not</em> the default), there are some issues to be aware | |
| of. Refer to the <a class="reference internal" href="../../databases/#mysql-collation"><em>MySQL database notes</em></a> for | |
| details.</p> | |
| </div> | |
| </div> | |
| <div class="section" id="s-timefield"> | |
| <span id="timefield"></span><h3><tt class="docutils literal"><span class="pre">TimeField</span></tt><a class="headerlink" href="#timefield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.TimeField"> | |
| <em class="property">class </em><tt class="descname">TimeField</tt>(<span class="optional">[</span><em>auto_now=False</em>, <em>auto_now_add=False</em>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.TimeField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A time, represented in Python by a <tt class="docutils literal"><span class="pre">datetime.time</span></tt> instance. Accepts the same | |
| auto-population options as <a class="reference internal" href="#django.db.models.DateField" title="django.db.models.DateField"><tt class="xref py py-class docutils literal"><span class="pre">DateField</span></tt></a>.</p> | |
| <p>The default form widget for this field is a <a class="reference internal" href="../../forms/widgets/#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a>. | |
| The admin adds some JavaScript shortcuts.</p> | |
| </div> | |
| <div class="section" id="s-urlfield"> | |
| <span id="urlfield"></span><h3><tt class="docutils literal"><span class="pre">URLField</span></tt><a class="headerlink" href="#urlfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.URLField"> | |
| <em class="property">class </em><tt class="descname">URLField</tt>(<span class="optional">[</span><em>verify_exists=False</em>, <em>max_length=200</em>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.URLField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A <a class="reference internal" href="#django.db.models.CharField" title="django.db.models.CharField"><tt class="xref py py-class docutils literal"><span class="pre">CharField</span></tt></a> for a URL. Has one extra optional argument:</p> | |
| <div class="deprecated"> | |
| <span class="title">Deprecated in Django 1.4:</span> <tt class="docutils literal"><span class="pre">verify_exists</span></tt> is deprecated for security reasons as of 1.4 and will be | |
| removed in Django 1.5. Prior to 1.3.1, the default value was <tt class="xref docutils literal"><span class="pre">True</span></tt>.</div> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.URLField.verify_exists"> | |
| <tt class="descclassname">URLField.</tt><tt class="descname">verify_exists</tt><a class="headerlink" href="#django.db.models.URLField.verify_exists" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>If <tt class="xref docutils literal"><span class="pre">True</span></tt>, the URL given will be checked for existence (i.e., | |
| the URL actually loads and doesn't give a 404 response) using a | |
| <tt class="docutils literal"><span class="pre">HEAD</span></tt> request. Redirects are allowed, but will not be followed.</p> | |
| <p>Note that when you're using the single-threaded development server, | |
| validating a URL being served by the same server will hang. This should not | |
| be a problem for multithreaded servers.</p> | |
| </dd></dl> | |
| <p>The default form widget for this field is a <a class="reference internal" href="../../forms/widgets/#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a>.</p> | |
| <p>Like all <a class="reference internal" href="#django.db.models.CharField" title="django.db.models.CharField"><tt class="xref py py-class docutils literal"><span class="pre">CharField</span></tt></a> subclasses, <a class="reference internal" href="#django.db.models.URLField" title="django.db.models.URLField"><tt class="xref py py-class docutils literal"><span class="pre">URLField</span></tt></a> takes the optional | |
| <tt class="xref py py-attr docutils literal"><span class="pre">max_length</span></tt>, a default of 200 is used.</p> | |
| </div> | |
| </div> | |
| <div class="section" id="s-module-django.db.models.fields.related"> | |
| <span id="s-relationship-fields"></span><span id="module-django.db.models.fields.related"></span><span id="relationship-fields"></span><h2>Relationship fields<a class="headerlink" href="#module-django.db.models.fields.related" title="Permalink to this headline">¶</a></h2> | |
| <p>Django also defines a set of fields that represent relations.</p> | |
| <div class="section" id="s-foreignkey"> | |
| <span id="s-ref-foreignkey"></span><span id="foreignkey"></span><span id="ref-foreignkey"></span><h3><tt class="docutils literal"><span class="pre">ForeignKey</span></tt><a class="headerlink" href="#foreignkey" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.ForeignKey"> | |
| <em class="property">class </em><tt class="descname">ForeignKey</tt>(<em>othermodel</em><span class="optional">[</span>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.ForeignKey" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A many-to-one relationship. Requires a positional argument: the class to which | |
| the model is related.</p> | |
| <p id="recursive-relationships">To create a recursive relationship -- an object that has a many-to-one | |
| relationship with itself -- use <tt class="docutils literal"><span class="pre">models.ForeignKey('self')</span></tt>.</p> | |
| <p id="lazy-relationships">If you need to create a relationship on a model that has not yet been defined, | |
| you can use the name of the model, rather than the model object itself:</p> | |
| <div class="highlight-python"><pre>class Car(models.Model): | |
| manufacturer = models.ForeignKey('Manufacturer') | |
| # ... | |
| class Manufacturer(models.Model): | |
| # ...</pre> | |
| </div> | |
| <p>To refer to models defined in another application, you can explicitly specify | |
| a model with the full application label. For example, if the <tt class="docutils literal"><span class="pre">Manufacturer</span></tt> | |
| model above is defined in another application called <tt class="docutils literal"><span class="pre">production</span></tt>, you'd | |
| need to use:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Car</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">manufacturer</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="s">'production.Manufacturer'</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>This sort of reference can be useful when resolving circular import | |
| dependencies between two applications.</p> | |
| <p>A database index is automatically created on the <tt class="docutils literal"><span class="pre">ForeignKey</span></tt>. You can | |
| disable this by setting <a class="reference internal" href="#django.db.models.Field.db_index" title="django.db.models.Field.db_index"><tt class="xref py py-attr docutils literal"><span class="pre">db_index</span></tt></a> to <tt class="xref docutils literal"><span class="pre">False</span></tt>. You may want to | |
| avoid the overhead of an index if you are creating a foreign key for | |
| consistency rather than joins, or if you will be creating an alternative index | |
| like a partial or multiple column index.</p> | |
| <div class="section" id="s-database-representation"> | |
| <span id="database-representation"></span><h4>Database Representation<a class="headerlink" href="#database-representation" title="Permalink to this headline">¶</a></h4> | |
| <p>Behind the scenes, Django appends <tt class="docutils literal"><span class="pre">"_id"</span></tt> to the field name to create its | |
| database column name. In the above example, the database table for the <tt class="docutils literal"><span class="pre">Car</span></tt> | |
| model will have a <tt class="docutils literal"><span class="pre">manufacturer_id</span></tt> column. (You can change this explicitly by | |
| specifying <a class="reference internal" href="#django.db.models.Field.db_column" title="django.db.models.Field.db_column"><tt class="xref py py-attr docutils literal"><span class="pre">db_column</span></tt></a>) However, your code should never have to | |
| deal with the database column name, unless you write custom SQL. You'll always | |
| deal with the field names of your model object.</p> | |
| </div> | |
| <div class="section" id="s-arguments"> | |
| <span id="s-foreign-key-arguments"></span><span id="arguments"></span><span id="foreign-key-arguments"></span><h4>Arguments<a class="headerlink" href="#arguments" title="Permalink to this headline">¶</a></h4> | |
| <p><a class="reference internal" href="#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a> accepts an extra set of arguments -- all optional -- that | |
| define the details of how the relation works.</p> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.ForeignKey.limit_choices_to"> | |
| <tt class="descclassname">ForeignKey.</tt><tt class="descname">limit_choices_to</tt><a class="headerlink" href="#django.db.models.ForeignKey.limit_choices_to" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>A dictionary of lookup arguments and values (see <a class="reference internal" href="../../../topics/db/queries/"><em>Making queries</em></a>) | |
| that limit the available admin or ModelForm choices for this object. Use | |
| this with functions from the Python <tt class="docutils literal"><span class="pre">datetime</span></tt> module to limit choices of | |
| objects by date. For example:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="n">limit_choices_to</span> <span class="o">=</span> <span class="p">{</span><span class="s">'pub_date__lte'</span><span class="p">:</span> <span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">}</span> | |
| </pre></div> | |
| </div> | |
| <p>only allows the choice of related objects with a <tt class="docutils literal"><span class="pre">pub_date</span></tt> before the | |
| current date/time to be chosen.</p> | |
| <p>Instead of a dictionary this can also be a <tt class="xref py py-class docutils literal"><span class="pre">Q</span></tt> | |
| object for more <a class="reference internal" href="../../../topics/db/queries/#complex-lookups-with-q"><em>complex queries</em></a>. However, | |
| if <tt class="docutils literal"><span class="pre">limit_choices_to</span></tt> is a <tt class="xref py py-class docutils literal"><span class="pre">Q</span></tt> object then it | |
| will only have an effect on the choices available in the admin when the | |
| field is not listed in <tt class="docutils literal"><span class="pre">raw_id_fields</span></tt> in the <tt class="docutils literal"><span class="pre">ModelAdmin</span></tt> for the model.</p> | |
| </dd></dl> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.ForeignKey.related_name"> | |
| <tt class="descclassname">ForeignKey.</tt><tt class="descname">related_name</tt><a class="headerlink" href="#django.db.models.ForeignKey.related_name" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>The name to use for the relation from the related object back to this one. | |
| See the <a class="reference internal" href="../../../topics/db/queries/#backwards-related-objects"><em>related objects documentation</em></a> for | |
| a full explanation and example. Note that you must set this value | |
| when defining relations on <a class="reference internal" href="../../../topics/db/models/#abstract-base-classes"><em>abstract models</em></a>; and when you do so | |
| <a class="reference internal" href="../../../topics/db/models/#abstract-related-name"><em>some special syntax</em></a> is available.</p> | |
| <p>If you'd prefer Django not to create a backwards relation, set | |
| <tt class="docutils literal"><span class="pre">related_name</span></tt> to <tt class="docutils literal"><span class="pre">'+'</span></tt> or end it with <tt class="docutils literal"><span class="pre">'+'</span></tt>. For example, this will | |
| ensure that the <tt class="docutils literal"><span class="pre">User</span></tt> model won't have a backwards relation to this | |
| model:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="n">user</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">related_name</span><span class="o">=</span><span class="s">'+'</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| </dd></dl> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.ForeignKey.to_field"> | |
| <tt class="descclassname">ForeignKey.</tt><tt class="descname">to_field</tt><a class="headerlink" href="#django.db.models.ForeignKey.to_field" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>The field on the related object that the relation is to. By default, Django | |
| uses the primary key of the related object.</p> | |
| </dd></dl> | |
| <div class="versionadded"> | |
| <span class="title">New in Django 1.3:</span> <a class="reference internal" href="../../../releases/1.3/"><em>Please see the release notes</em></a></div> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.ForeignKey.on_delete"> | |
| <tt class="descclassname">ForeignKey.</tt><tt class="descname">on_delete</tt><a class="headerlink" href="#django.db.models.ForeignKey.on_delete" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>When an object referenced by a <a class="reference internal" href="#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a> is deleted, Django by | |
| default emulates the behavior of the SQL constraint <tt class="docutils literal"><span class="pre">ON</span> <span class="pre">DELETE</span> <span class="pre">CASCADE</span></tt> | |
| and also deletes the object containing the <tt class="docutils literal"><span class="pre">ForeignKey</span></tt>. This behavior | |
| can be overridden by specifying the <a class="reference internal" href="#django.db.models.ForeignKey.on_delete" title="django.db.models.ForeignKey.on_delete"><tt class="xref py py-attr docutils literal"><span class="pre">on_delete</span></tt></a> argument. For | |
| example, if you have a nullable <a class="reference internal" href="#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a> and you want it to be | |
| set null when the referenced object is deleted:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="n">user</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">blank</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">null</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">on_delete</span><span class="o">=</span><span class="n">models</span><span class="o">.</span><span class="n">SET_NULL</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>The possible values for <a class="reference internal" href="#django.db.models.ForeignKey.on_delete" title="django.db.models.ForeignKey.on_delete"><tt class="xref py py-attr docutils literal"><span class="pre">on_delete</span></tt></a> are found in | |
| <a class="reference internal" href="../../../topics/db/models/#module-django.db.models" title="django.db.models"><tt class="xref py py-mod docutils literal"><span class="pre">django.db.models</span></tt></a>:</p> | |
| <ul> | |
| <li><p class="first"><tt class="xref py py-attr docutils literal"><span class="pre">CASCADE</span></tt>: Cascade deletes; the default.</p> | |
| </li> | |
| <li><p class="first"><tt class="xref py py-attr docutils literal"><span class="pre">PROTECT</span></tt>: Prevent deletion of the referenced | |
| object by raising <tt class="xref py py-exc docutils literal"><span class="pre">django.db.models.ProtectedError</span></tt>, a subclass of | |
| <a class="reference internal" href="../../exceptions/#django.db.IntegrityError" title="django.db.IntegrityError"><tt class="xref py py-exc docutils literal"><span class="pre">django.db.IntegrityError</span></tt></a>.</p> | |
| </li> | |
| <li><p class="first"><tt class="xref py py-attr docutils literal"><span class="pre">SET_NULL</span></tt>: Set the <a class="reference internal" href="#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a> null; | |
| this is only possible if <tt class="xref py py-attr docutils literal"><span class="pre">null</span></tt> is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p> | |
| </li> | |
| <li><p class="first"><tt class="xref py py-attr docutils literal"><span class="pre">SET_DEFAULT</span></tt>: Set the <a class="reference internal" href="#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a> to its | |
| default value; a default for the <a class="reference internal" href="#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a> must be set.</p> | |
| </li> | |
| <li><p class="first"><tt class="xref py py-func docutils literal"><span class="pre">SET()</span></tt>: Set the <a class="reference internal" href="#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a> to the value | |
| passed to <tt class="xref py py-func docutils literal"><span class="pre">SET()</span></tt>, or if a callable is passed in, | |
| the result of calling it. In most cases, passing a callable will be | |
| necessary to avoid executing queries at the time your models.py is | |
| imported:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">get_sentinel_user</span><span class="p">():</span> | |
| <span class="k">return</span> <span class="n">User</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get_or_create</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="s">'deleted'</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span> | |
| <span class="k">class</span> <span class="nc">MyModel</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">user</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">on_delete</span><span class="o">=</span><span class="n">models</span><span class="o">.</span><span class="n">SET</span><span class="p">(</span><span class="n">get_sentinel_user</span><span class="p">))</span> | |
| </pre></div> | |
| </div> | |
| </li> | |
| <li><p class="first"><tt class="xref py py-attr docutils literal"><span class="pre">DO_NOTHING</span></tt>: Take no action. If your database | |
| backend enforces referential integrity, this will cause an | |
| <a class="reference internal" href="../../exceptions/#django.db.IntegrityError" title="django.db.IntegrityError"><tt class="xref py py-exc docutils literal"><span class="pre">IntegrityError</span></tt></a> unless you manually add a SQL <tt class="docutils literal"><span class="pre">ON</span> | |
| <span class="pre">DELETE</span></tt> constraint to the database field (perhaps using | |
| <a class="reference internal" href="../../../howto/initial-data/#initial-sql"><em>initial sql</em></a>).</p> | |
| </li> | |
| </ul> | |
| </dd></dl> | |
| </div> | |
| </div> | |
| <div class="section" id="s-manytomanyfield"> | |
| <span id="s-ref-manytomany"></span><span id="manytomanyfield"></span><span id="ref-manytomany"></span><h3><tt class="docutils literal"><span class="pre">ManyToManyField</span></tt><a class="headerlink" href="#manytomanyfield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.ManyToManyField"> | |
| <em class="property">class </em><tt class="descname">ManyToManyField</tt>(<em>othermodel</em><span class="optional">[</span>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.ManyToManyField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A many-to-many relationship. Requires a positional argument: the class to which | |
| the model is related. This works exactly the same as it does for | |
| <a class="reference internal" href="#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a>, including all the options regarding <a class="reference internal" href="#recursive-relationships"><em>recursive</em></a> and <a class="reference internal" href="#lazy-relationships"><em>lazy</em></a> relationships.</p> | |
| <p>Related objects can be added, removed, or created with the field's | |
| <a class="reference internal" href="../relations/#django.db.models.fields.related.RelatedManager" title="django.db.models.fields.related.RelatedManager"><tt class="xref py py-class docutils literal"><span class="pre">RelatedManager</span></tt></a>.</p> | |
| <div class="section" id="s-id1"> | |
| <span id="id1"></span><h4>Database Representation<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4> | |
| <p>Behind the scenes, Django creates an intermediary join table to | |
| represent the many-to-many relationship. By default, this table name | |
| is generated using the name of the many-to-many field and the model | |
| that contains it. Since some databases don't support table names above | |
| a certain length, these table names will be automatically truncated to | |
| 64 characters and a uniqueness hash will be used. This means you might | |
| see table names like <tt class="docutils literal"><span class="pre">author_books_9cdf4</span></tt>; this is perfectly normal. | |
| You can manually provide the name of the join table using the | |
| <a class="reference internal" href="#django.db.models.ManyToManyField.db_table" title="django.db.models.ManyToManyField.db_table"><tt class="xref py py-attr docutils literal"><span class="pre">db_table</span></tt></a> option.</p> | |
| </div> | |
| <div class="section" id="s-manytomany-arguments"> | |
| <span id="s-id2"></span><span id="manytomany-arguments"></span><span id="id2"></span><h4>Arguments<a class="headerlink" href="#manytomany-arguments" title="Permalink to this headline">¶</a></h4> | |
| <p><a class="reference internal" href="#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><tt class="xref py py-class docutils literal"><span class="pre">ManyToManyField</span></tt></a> accepts an extra set of arguments -- all optional -- | |
| that control how the relationship functions.</p> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.ManyToManyField.related_name"> | |
| <tt class="descclassname">ManyToManyField.</tt><tt class="descname">related_name</tt><a class="headerlink" href="#django.db.models.ManyToManyField.related_name" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Same as <a class="reference internal" href="#django.db.models.ForeignKey.related_name" title="django.db.models.ForeignKey.related_name"><tt class="xref py py-attr docutils literal"><span class="pre">ForeignKey.related_name</span></tt></a>.</p> | |
| <p>If you have more than one <tt class="docutils literal"><span class="pre">ManyToManyField</span></tt> pointing to the same model | |
| and want to suppress the backwards relations, set each <tt class="docutils literal"><span class="pre">related_name</span></tt> | |
| to a unique value ending with <tt class="docutils literal"><span class="pre">'+'</span></tt>:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="n">users</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ManyToManyField</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">related_name</span><span class="o">=</span><span class="s">'u+'</span><span class="p">)</span> | |
| <span class="n">referents</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ManyToManyField</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">related_name</span><span class="o">=</span><span class="s">'ref+'</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| </dd></dl> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.ManyToManyField.limit_choices_to"> | |
| <tt class="descclassname">ManyToManyField.</tt><tt class="descname">limit_choices_to</tt><a class="headerlink" href="#django.db.models.ManyToManyField.limit_choices_to" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Same as <a class="reference internal" href="#django.db.models.ForeignKey.limit_choices_to" title="django.db.models.ForeignKey.limit_choices_to"><tt class="xref py py-attr docutils literal"><span class="pre">ForeignKey.limit_choices_to</span></tt></a>.</p> | |
| <p><tt class="docutils literal"><span class="pre">limit_choices_to</span></tt> has no effect when used on a <tt class="docutils literal"><span class="pre">ManyToManyField</span></tt> with a | |
| custom intermediate table specified using the | |
| <a class="reference internal" href="#django.db.models.ManyToManyField.through" title="django.db.models.ManyToManyField.through"><tt class="xref py py-attr docutils literal"><span class="pre">through</span></tt></a> parameter.</p> | |
| </dd></dl> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.ManyToManyField.symmetrical"> | |
| <tt class="descclassname">ManyToManyField.</tt><tt class="descname">symmetrical</tt><a class="headerlink" href="#django.db.models.ManyToManyField.symmetrical" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Only used in the definition of ManyToManyFields on self. Consider the | |
| following model:</p> | |
| <div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Person</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">friends</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ManyToManyField</span><span class="p">(</span><span class="s">"self"</span><span class="p">)</span> | |
| </pre></div> | |
| </div> | |
| <p>When Django processes this model, it identifies that it has a | |
| <a class="reference internal" href="#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><tt class="xref py py-class docutils literal"><span class="pre">ManyToManyField</span></tt></a> on itself, and as a result, it doesn't add a | |
| <tt class="docutils literal"><span class="pre">person_set</span></tt> attribute to the <tt class="docutils literal"><span class="pre">Person</span></tt> class. Instead, the | |
| <a class="reference internal" href="#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><tt class="xref py py-class docutils literal"><span class="pre">ManyToManyField</span></tt></a> is assumed to be symmetrical -- that is, if I am | |
| your friend, then you are my friend.</p> | |
| <p>If you do not want symmetry in many-to-many relationships with <tt class="docutils literal"><span class="pre">self</span></tt>, set | |
| <a class="reference internal" href="#django.db.models.ManyToManyField.symmetrical" title="django.db.models.ManyToManyField.symmetrical"><tt class="xref py py-attr docutils literal"><span class="pre">symmetrical</span></tt></a> to <tt class="xref docutils literal"><span class="pre">False</span></tt>. This will force Django to | |
| add the descriptor for the reverse relationship, allowing | |
| <a class="reference internal" href="#django.db.models.ManyToManyField" title="django.db.models.ManyToManyField"><tt class="xref py py-class docutils literal"><span class="pre">ManyToManyField</span></tt></a> relationships to be non-symmetrical.</p> | |
| </dd></dl> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.ManyToManyField.through"> | |
| <tt class="descclassname">ManyToManyField.</tt><tt class="descname">through</tt><a class="headerlink" href="#django.db.models.ManyToManyField.through" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>Django will automatically generate a table to manage many-to-many | |
| relationships. However, if you want to manually specify the intermediary | |
| table, you can use the <a class="reference internal" href="#django.db.models.ManyToManyField.through" title="django.db.models.ManyToManyField.through"><tt class="xref py py-attr docutils literal"><span class="pre">through</span></tt></a> option to specify | |
| the Django model that represents the intermediate table that you want to | |
| use.</p> | |
| <p>The most common use for this option is when you want to associate | |
| <a class="reference internal" href="../../../topics/db/models/#intermediary-manytomany"><em>extra data with a many-to-many relationship</em></a>.</p> | |
| </dd></dl> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.ManyToManyField.db_table"> | |
| <tt class="descclassname">ManyToManyField.</tt><tt class="descname">db_table</tt><a class="headerlink" href="#django.db.models.ManyToManyField.db_table" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>The name of the table to create for storing the many-to-many data. If this | |
| is not provided, Django will assume a default name based upon the names of | |
| the two tables being joined.</p> | |
| </dd></dl> | |
| </div> | |
| </div> | |
| <div class="section" id="s-onetoonefield"> | |
| <span id="s-ref-onetoone"></span><span id="onetoonefield"></span><span id="ref-onetoone"></span><h3><tt class="docutils literal"><span class="pre">OneToOneField</span></tt><a class="headerlink" href="#onetoonefield" title="Permalink to this headline">¶</a></h3> | |
| <dl class="class"> | |
| <dt id="django.db.models.OneToOneField"> | |
| <em class="property">class </em><tt class="descname">OneToOneField</tt>(<em>othermodel</em><span class="optional">[</span>, <em>parent_link=False</em>, <em>**options</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.OneToOneField" title="Permalink to this definition">¶</a></dt> | |
| <dd></dd></dl> | |
| <p>A one-to-one relationship. Conceptually, this is similar to a | |
| <a class="reference internal" href="#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a> with <a class="reference internal" href="#django.db.models.Field.unique" title="django.db.models.Field.unique"><tt class="xref py py-attr docutils literal"><span class="pre">unique=True</span></tt></a>, but the | |
| "reverse" side of the relation will directly return a single object.</p> | |
| <p>This is most useful as the primary key of a model which "extends" | |
| another model in some way; <a class="reference internal" href="../../../topics/db/models/#multi-table-inheritance"><em>Multi-table inheritance</em></a> is | |
| implemented by adding an implicit one-to-one relation from the child | |
| model to the parent model, for example.</p> | |
| <p>One positional argument is required: the class to which the model will be | |
| related. This works exactly the same as it does for <a class="reference internal" href="#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a>, | |
| including all the options regarding <a class="reference internal" href="#recursive-relationships"><em>recursive</em></a> | |
| and <a class="reference internal" href="#lazy-relationships"><em>lazy</em></a> relationships.</p> | |
| <p id="onetoone-arguments">Additionally, <tt class="docutils literal"><span class="pre">OneToOneField</span></tt> accepts all of the extra arguments | |
| accepted by <a class="reference internal" href="#django.db.models.ForeignKey" title="django.db.models.ForeignKey"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKey</span></tt></a>, plus one extra argument:</p> | |
| <dl class="attribute"> | |
| <dt id="django.db.models.OneToOneField.parent_link"> | |
| <tt class="descclassname">OneToOneField.</tt><tt class="descname">parent_link</tt><a class="headerlink" href="#django.db.models.OneToOneField.parent_link" title="Permalink to this definition">¶</a></dt> | |
| <dd><p>When <tt class="xref docutils literal"><span class="pre">True</span></tt> and used in a model which inherits from another | |
| (concrete) model, indicates that this field should be used as the | |
| link back to the parent class, rather than the extra | |
| <tt class="docutils literal"><span class="pre">OneToOneField</span></tt> which would normally be implicitly created by | |
| subclassing.</p> | |
| </dd></dl> | |
| </div> | |
| </div> | |
| </div> | |
| <div id="content-secondary"> | |
| <h2 id="comments">Questions/Feedback</h2> | |
| <p>Having trouble? We'd like to help!</p> | |
| <ul> | |
| <li> | |
| Try the <a href="/en/1.4/faq/">FAQ</a> | |
| — it's got answers to many common questions. | |
| </li> | |
| <li> | |
| Search for information in the <a | |
| href="http://groups.google.com/group/django-users/">archives of the | |
| django-users mailing list</a>, or <a | |
| href="http://groups.google.com/group/django-users/">post a question</a>. | |
| </li> | |
| <li> | |
| Ask a question in the <a href="irc://irc.freenode.net/">#django IRC | |
| channel</a>, or search the <a href="http://django-irc-logs.com/">IRC | |
| logs</a> to see if it has been asked before. | |
| </li> | |
| <li> | |
| If you notice errors with this documentation, please <a | |
| href="https://code.djangoproject.com/newticket?component=Documentation"> | |
| open a ticket</a> and let us know! Please only use the ticket tracker for | |
| criticisms and improvements on the docs. For tech support, use the | |
| resources above. | |
| </li> | |
| </ul> | |
| </div> | |
| </div> | |
| <!-- END #garbage-content --> | |
| </div> | |
| <!-- END #content-main --> | |
| <div id="content-related" class="sidebar"> | |
| <br/> | |
| <h2>Index</h2> | |
| <ul class="linklist"> | |
| <li><a href="#how_to_install">How to install</a></li> | |
| <li><a href="#how_to_use">How to use</a></li> | |
| <li><a href="#features">Features</a></li> | |
| <li><a href="#notes">Notes</a></li> | |
| <li><a href="#todo">TODO</a></li> | |
| </ul> | |
| <div id="garbage-index" > | |
| <h2><a href="#engage_garbage">Start of Garbage Text</a></h2> | |
| <!-- More stuff in index for example --> | |
| <h2>Anything below might link you somewhere else</h2> | |
| <h2>But most of the links link to anchors in this document to show how useful this bookmarklet is.</h2> | |
| <ul> | |
| <li><a class="reference internal" href="#">Model field reference</a><ul> | |
| <li><a class="reference internal" href="#field-options">Field options</a><ul> | |
| <li><a class="reference internal" href="#null"><tt class="docutils literal"><span class="pre">null</span></tt></a></li> | |
| <li><a class="reference internal" href="#blank"><tt class="docutils literal"><span class="pre">blank</span></tt></a></li> | |
| <li><a class="reference internal" href="#choices"><tt class="docutils literal"><span class="pre">choices</span></tt></a></li> | |
| <li><a class="reference internal" href="#db-column"><tt class="docutils literal"><span class="pre">db_column</span></tt></a></li> | |
| <li><a class="reference internal" href="#db-index"><tt class="docutils literal"><span class="pre">db_index</span></tt></a> | |
| <ul> | |
| <li><a class="reference internal" href="#autofield"><tt class="docutils literal"><span class="pre">Auto Field</span></tt></a></li> | |
| <li><a class="reference internal" href="#bigintegerfield"><tt class="docutils literal"><span class="pre">BigIn tegerField</span></tt></a></li> | |
| <li><a class="reference internal" href="#booleanfield"><tt class="docutils literal"><span class="pre">Boolea nField</span></tt></a></li> | |
| <li><a class="reference internal" href="#charfield"><tt class="docutils literal"><span class="pre">Char ield</span></tt></a> | |
| <ul> | |
| <li><a class="reference internal" href="#autofield"><tt class="docutils literal"><span class="pre">AutoF ield</span></tt></a></li> | |
| <li><a class="reference internal" href="#bigintegerfield"><tt class="docutils literal"><span class="pre">BigIn tegerField</span></tt></a></li> | |
| <li><a class="reference internal" href="#booleanfield"><tt class="docutils literal"><span class="pre">Boole anField</span></tt></a></li> | |
| <li><a class="reference internal" href="#charfield"><tt class="docutils literal"><span class="pre">CharF ield</span></tt></a></li> | |
| <li><a class="reference internal" href="#commaseparatedintegerfield"><tt class="docutils literal"><span class="pre">Com maSepara tedInt egerField</span></tt></a></li> | |
| <li><a class="reference internal" href="#datefield"><tt class="docutils literal"><span class="pre">DateField</span></tt></a> | |
| <ul> | |
| <li><a class="reference internal" href="#autofield"><tt class="docutils literal"><span class="pre">Auto Field</span></tt></a></li> | |
| <li><a class="reference internal" href="#bigintegerfield"><tt class="docutils literal"><span class="pre">BigIn tegerF ield</span></tt></a></li> | |
| <li><a class="reference internal" href="#booleanfield"><tt class="docutils literal"><span class="pre">Boole anField</span></tt></a></li> | |
| <li><a class="reference internal" href="#charfield"><tt class="docutils literal"><span class="pre">CharField</span></tt></a></li> | |
| <li><a class="reference internal" href="#commaseparatedintegerfield"><tt class="docutils literal"><span class="pre">CommaS eparat edInt egerField</span></tt></a></li> | |
| <li><a class="reference internal" href="#datefield"><tt class="docutils literal"><span class="pre">DateField</span></tt></a></li> | |
| <li><a class="reference internal" href="#datetimefield"><tt class="docutils literal"><span class="pre">Date TimeF ield</span></tt></a></li> | |
| <li><a class="reference internal" href="#decimalfield"><tt class="docutils literal"><span class="pre">Decim alField</span></tt></a></li> | |
| <li><a class="reference internal" href="#emailfield"><tt class="docutils literal"><span class="pre">Emai lField</span></tt></a></li> | |
| <li><a class="reference internal" href="#filefield"><tt class="docutils literal"><span class="pre">File ield</span></tt></a><ul> | |
| <li><a class="reference internal" href="#filefield-and-fieldfile">FileField and FieldFile</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#datetimefield"><tt class="docutils literal"><span class="pre">DateT imeField</span></tt></a></li> | |
| <li><a class="reference internal" href="#decimalfield"><tt class="docutils literal"><span class="pre">Deci malField</span></tt></a></li> | |
| <li><a class="reference internal" href="#emailfield"><tt class="docutils literal"><span class="pre">EmailF ield</span></tt></a></li> | |
| <li><a class="reference internal" href="#filefield"><tt class="docutils literal"><span class="pre">FileField</span></tt></a><ul> | |
| <li><a class="reference internal" href="#filefield-and-fieldfile">FileField and FieldFile</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#commaseparatedintegerfield"><tt class="docutils literal"><span class="pre">CommaS eparatedI ntegerField</span></tt></a></li> | |
| <li><a class="reference internal" href="#datefield"><tt class="docutils literal"><span class="pre">DateField</span></tt></a></li> | |
| <li><a class="reference internal" href="#datetimefield"><tt class="docutils literal"><span class="pre">Date Time Field</span></tt></a></li> | |
| <li><a class="reference internal" href="#decimalfield"><tt class="docutils literal"><span class="pre">Decimal Field</span></tt></a></li> | |
| <li><a class="reference internal" href="#emailfield"><tt class="docutils literal"><span class="pre">Ema ilField</span></tt></a></li> | |
| <li><a class="reference internal" href="#filefield"><tt class="docutils literal"><span class="pre">FileField</span></tt></a><ul> | |
| <li><a class="reference internal" href="#filefield-and-fieldfile">FileField and FieldFile</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#db-tablespace"><tt class="docutils literal"><span class="pre">db_tablespace</span></tt></a></li> | |
| <li><a class="reference internal" href="#default"><tt class="docutils literal"><span class="pre">default</span></tt></a></li> | |
| <li><a class="reference internal" href="#editable"><tt class="docutils literal"><span class="pre">editable</span></tt></a></li> | |
| <li><a class="reference internal" href="#error-messages"><tt class="docutils literal"><span class="pre">error_messages</span></tt></a></li> | |
| <li><a class="reference internal" href="#help-text"><tt class="docutils literal"><span class="pre">help_text</span></tt></a></li> | |
| <li><a class="reference internal" href="#primary-key"><tt class="docutils literal"><span class="pre">primary_key</span></tt></a></li> | |
| <li><a class="reference internal" href="#unique"><tt class="docutils literal"><span class="pre">unique</span></tt></a></li> | |
| <li><a class="reference internal" href="#unique-for-date"><tt class="docutils literal"><span class="pre">unique_for_date</span></tt></a></li> | |
| <li><a class="reference internal" href="#unique-for-month"><tt class="docutils literal"><span class="pre">unique_for_month</span></tt></a></li> | |
| <li><a class="reference internal" href="#unique-for-year"><tt class="docutils literal"><span class="pre">unique_for_year</span></tt></a></li> | |
| <li><a class="reference internal" href="#verbose-name"><tt class="docutils literal"><span class="pre">verbose_name</span></tt></a></li> | |
| <li><a class="reference internal" href="#validators"><tt class="docutils literal"><span class="pre">valid ators</span></tt></a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#field-types">Field types</a><ul> | |
| <li><a class="reference internal" href="#autofield"><tt class="docutils literal"><span class="pre">AutoField</span></tt></a></li> | |
| <li><a class="reference internal" href="#bigintegerfield"><tt class="docutils literal"><span class="pre">BigIntegerField</span></tt></a></li> | |
| <li><a class="reference internal" href="#booleanfield"><tt class="docutils literal"><span class="pre">BooleanField</span></tt></a></li> | |
| <li><a class="reference internal" href="#charfield"><tt class="docutils literal"><span class="pre">CharField</span></tt></a></li> | |
| <li><a class="reference internal" href="#commaseparatedintegerfield"><tt class="docutils literal"><span class="pre">CommaS epara tedInteg erField</span></tt></a></li> | |
| <li><a class="reference internal" href="#datefield"><tt class="docutils literal"><span class="pre">DateField</span></tt></a></li> | |
| <li><a class="reference internal" href="#datetimefield"><tt class="docutils literal"><span class="pre">DateT imeField</span></tt></a></li> | |
| <li><a class="reference internal" href="#decimalfield"><tt class="docutils literal"><span class="pre">Deci malField</span></tt></a></li> | |
| <li><a class="reference internal" href="#emailfield"><tt class="docutils literal"><span class="pre">EmailField</span></tt></a></li> | |
| <li><a class="reference internal" href="#filefield"><tt class="docutils literal"><span class="pre">FileField</span></tt></a><ul> | |
| <li><a class="reference internal" href="#filefield-and-fieldfile">FileField and FieldFile</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#filepathfield"><tt class="docutils literal"><span class="pre">FilePa thField</span></tt></a></li> | |
| <li><a class="reference internal" href="#floatfield"><tt class="docutils literal"><span class="pre">Floa tField</span></tt></a></li> | |
| <li><a class="reference internal" href="#imagefield"><tt class="docutils literal"><span class="pre">Imag eField</span></tt></a></li> | |
| <li><a class="reference internal" href="#integerfield"><tt class="docutils literal"><span class="pre">Integer Field</span></tt></a></li> | |
| <li><a class="reference internal" href="#ipaddressfield"><tt class="docutils literal"><span class="pre">IPAddr essField</span></tt></a></li> | |
| <li><a class="reference internal" href="#genericipaddressfield"><tt class="docutils literal"><span class="pre">Gene ricIPAdd ressField</span></tt></a></li> | |
| <li><a class="reference internal" href="#nullbooleanfield"><tt class="docutils literal"><span class="pre">NullBo oleanField</span></tt></a></li> | |
| <li><a class="reference internal" href="#positiveintegerfield"><tt class="docutils literal"><span class="pre">Positi veIntegerField</span></tt></a></li> | |
| <li><a class="reference internal" href="#positivesmallintegerfield"><tt class="docutils literal"><span class="pre">PositiveSmallIntegerField</span></tt></a></li> | |
| <li><a class="reference internal" href="#slugfield"><tt class="docutils literal"><span class="pre">SlugField</span></tt></a></li> | |
| <li><a class="reference internal" href="#smallintegerfield"><tt class="docutils literal"><span class="pre">SmallI ntegerField</span></tt></a></li> | |
| <li><a class="reference internal" href="#textfield"><tt class="docutils literal"><span class="pre">TextField</span></tt></a></li> | |
| <li><a class="reference internal" href="#timefield"><tt class="docutils literal"><span class="pre">TimeField</span></tt></a></li> | |
| <li><a class="reference internal" href="#urlfield"><tt class="docutils literal"><span class="pre">URLField</span></tt></a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#module-django.db.models.fields.related">Relationship fields</a><ul> | |
| <li><a class="reference internal" href="#foreignkey"><tt class="docutils literal"><span class="pre">Forei gnKey</span></tt></a><ul> | |
| <li><a class="reference internal" href="#database-representation">Database Represe ntation</a></li> | |
| <li><a class="reference internal" href="#arguments">Arguments</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#manytomanyfield"><tt class="docutils literal"><span class="pre">ManyToM anyField</span></tt></a><ul> | |
| <li><a class="reference internal" href="#id1">Database Repre sentation</a></li> | |
| <li><a class="reference internal" href="#manytomany-arguments">Argum ents</a></li> | |
| </ul> | |
| </li> | |
| <li><a class="reference internal" href="#onetoonefield"><tt class="docutils literal"><span class="pre">OneTo OneF ield</span></tt></a></li> | |
| </ul> | |
| </li> | |
| </ul> | |
| </li> | |
| </ul> | |
| </div> | |
| <!-- END #index-garbage --> | |
| </div> | |
| <!-- END #content-related --> | |
| </div> | |
| <!-- END #content --> | |
| <div id="footer"> | |
| <p>© 2012 <a href="https://github.com/fuho">fuho</a> stole this layout, css and sample text from Django website. Django is a registered trademark of the Django Software Foundation. | |
| <a href="https://www.dropbox.com/">Probably Linux Web hosting</a> graciously provided by Dropbox public folder, at least for the time being. | |
| </p> | |
| </div> | |
| <!-- END #footer --> | |
| </div> | |
| <!-- END #container --> | |
| </body><style type="text/css"></style></html> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment