{"payload":{"allShortcutsEnabled":false,"fileTree":{"docs":{"items":[{"name":"man","path":"docs/man","contentType":"directory"},{"name":"add_ons.txt","path":"docs/add_ons.txt","contentType":"file"},{"name":"admin_css.txt","path":"docs/admin_css.txt","contentType":"file"},{"name":"apache_auth.txt","path":"docs/apache_auth.txt","contentType":"file"},{"name":"api_stability.txt","path":"docs/api_stability.txt","contentType":"file"},{"name":"authentication.txt","path":"docs/authentication.txt","contentType":"file"},{"name":"cache.txt","path":"docs/cache.txt","contentType":"file"},{"name":"contributing.txt","path":"docs/contributing.txt","contentType":"file"},{"name":"csrf.txt","path":"docs/csrf.txt","contentType":"file"},{"name":"databases.txt","path":"docs/databases.txt","contentType":"file"},{"name":"databrowse.txt","path":"docs/databrowse.txt","contentType":"file"},{"name":"db-api.txt","path":"docs/db-api.txt","contentType":"file"},{"name":"design_philosophies.txt","path":"docs/design_philosophies.txt","contentType":"file"},{"name":"distributions.txt","path":"docs/distributions.txt","contentType":"file"},{"name":"django-admin.txt","path":"docs/django-admin.txt","contentType":"file"},{"name":"documentation.txt","path":"docs/documentation.txt","contentType":"file"},{"name":"email.txt","path":"docs/email.txt","contentType":"file"},{"name":"faq.txt","path":"docs/faq.txt","contentType":"file"},{"name":"fastcgi.txt","path":"docs/fastcgi.txt","contentType":"file"},{"name":"flatpages.txt","path":"docs/flatpages.txt","contentType":"file"},{"name":"forms.txt","path":"docs/forms.txt","contentType":"file"},{"name":"generic_views.txt","path":"docs/generic_views.txt","contentType":"file"},{"name":"i18n.txt","path":"docs/i18n.txt","contentType":"file"},{"name":"install.txt","path":"docs/install.txt","contentType":"file"},{"name":"legacy_databases.txt","path":"docs/legacy_databases.txt","contentType":"file"},{"name":"middleware.txt","path":"docs/middleware.txt","contentType":"file"},{"name":"model-api.txt","path":"docs/model-api.txt","contentType":"file"},{"name":"modpython.txt","path":"docs/modpython.txt","contentType":"file"},{"name":"newforms.txt","path":"docs/newforms.txt","contentType":"file"},{"name":"outputting_csv.txt","path":"docs/outputting_csv.txt","contentType":"file"},{"name":"outputting_pdf.txt","path":"docs/outputting_pdf.txt","contentType":"file"},{"name":"overview.txt","path":"docs/overview.txt","contentType":"file"},{"name":"redirects.txt","path":"docs/redirects.txt","contentType":"file"},{"name":"release_notes_0.95.txt","path":"docs/release_notes_0.95.txt","contentType":"file"},{"name":"release_notes_0.96.txt","path":"docs/release_notes_0.96.txt","contentType":"file"},{"name":"request_response.txt","path":"docs/request_response.txt","contentType":"file"},{"name":"serialization.txt","path":"docs/serialization.txt","contentType":"file"},{"name":"sessions.txt","path":"docs/sessions.txt","contentType":"file"},{"name":"settings.txt","path":"docs/settings.txt","contentType":"file"},{"name":"sitemaps.txt","path":"docs/sitemaps.txt","contentType":"file"},{"name":"sites.txt","path":"docs/sites.txt","contentType":"file"},{"name":"static_files.txt","path":"docs/static_files.txt","contentType":"file"},{"name":"syndication_feeds.txt","path":"docs/syndication_feeds.txt","contentType":"file"},{"name":"templates.txt","path":"docs/templates.txt","contentType":"file"},{"name":"templates_python.txt","path":"docs/templates_python.txt","contentType":"file"},{"name":"testing.txt","path":"docs/testing.txt","contentType":"file"},{"name":"transactions.txt","path":"docs/transactions.txt","contentType":"file"},{"name":"tutorial01.txt","path":"docs/tutorial01.txt","contentType":"file"},{"name":"tutorial02.txt","path":"docs/tutorial02.txt","contentType":"file"},{"name":"tutorial03.txt","path":"docs/tutorial03.txt","contentType":"file"},{"name":"tutorial04.txt","path":"docs/tutorial04.txt","contentType":"file"},{"name":"url_dispatch.txt","path":"docs/url_dispatch.txt","contentType":"file"},{"name":"webdesign.txt","path":"docs/webdesign.txt","contentType":"file"}],"totalCount":53},"":{"items":[{"name":"django","path":"django","contentType":"directory"},{"name":"docs","path":"docs","contentType":"directory"},{"name":"examples","path":"examples","contentType":"directory"},{"name":"extras","path":"extras","contentType":"directory"},{"name":"scripts","path":"scripts","contentType":"directory"},{"name":"tests","path":"tests","contentType":"directory"},{"name":"AUTHORS","path":"AUTHORS","contentType":"file"},{"name":"INSTALL","path":"INSTALL","contentType":"file"},{"name":"LICENSE","path":"LICENSE","contentType":"file"},{"name":"MANIFEST.in","path":"MANIFEST.in","contentType":"file"},{"name":"README","path":"README","contentType":"file"},{"name":"setup.cfg","path":"setup.cfg","contentType":"file"},{"name":"setup.py","path":"setup.py","contentType":"file"}],"totalCount":13}},"fileTreeProcessingTime":15.859794,"foldersToFetch":[],"repo":{"id":4164482,"defaultBranch":"main","name":"django","ownerLogin":"django","currentUserCanPush":false,"isFork":false,"isEmpty":false,"createdAt":"2012-04-28T02:47:18.000Z","ownerAvatar":"https://avatars.githubusercontent.com/u/27804?v=4","public":true,"private":false,"isOrgOwned":true},"symbolsExpanded":false,"treeExpanded":true,"refInfo":{"name":"042d7e44fa5effd901cf1828d8f6f2058113cbc7","listCacheKey":"v0:1709542684.0","canEdit":false,"refType":"tree","currentOid":"042d7e44fa5effd901cf1828d8f6f2058113cbc7"},"path":"docs/model-api.txt","currentUser":null,"blob":{"rawLines":["===============","Model reference","===============","","A model is the single, definitive source of data about your data. It contains","the essential fields and behaviors of the data you're storing. Generally, each","model maps to a single database table.","","The basics:",""," * Each model is a Python class that subclasses ``django.db.models.Model``."," * Each attribute of the model represents a database field."," * Model metadata (non-field information) goes in an inner class named"," ``Meta``."," * Metadata used for Django's admin site goes into an inner class named"," ``Admin``."," * With all of this, Django gives you an automatically-generated"," database-access API, which is explained in the `Database API reference`_.","","A companion to this document is the `official repository of model examples`_.","(In the Django source distribution, these examples are in the","``tests/modeltests`` directory.)","",".. _Database API reference: ../db-api/",".. _official repository of model examples: http://www.djangoproject.com/documentation/models/","","Quick example","=============","","This example model defines a ``Person``, which has a ``first_name`` and","``last_name``::",""," from django.db import models",""," class Person(models.Model):"," first_name = models.CharField(maxlength=30)"," last_name = models.CharField(maxlength=30)","","``first_name`` and ``last_name`` are *fields* of the model. Each field is","specified as a class attribute, and each attribute maps to a database column.","","The above ``Person`` model would create a database table like this::",""," CREATE TABLE myapp_person ("," \"id\" serial NOT NULL PRIMARY KEY,"," \"first_name\" varchar(30) NOT NULL,"," \"last_name\" varchar(30) NOT NULL"," );","","Some technical notes:",""," * The name of the table, ``myapp_person``, is automatically derived from"," some model metadata but can be overridden. See _`Table names` below."," * An ``id`` field is added automatically, but this behavior can be"," overriden. See `Automatic primary key fields`_ below."," * The ``CREATE TABLE`` SQL in this example is formatted using PostgreSQL"," syntax, but it's worth noting Django uses SQL tailored to the database"," backend specified in your `settings file`_.","",".. _settings file: ../settings/","","Fields","======","","The most important part of a model -- and the only required part of a model --","is the list of database fields it defines. Fields are specified by class","attributes.","","Example::",""," class Musician(models.Model):"," first_name = models.CharField(maxlength=50)"," last_name = models.CharField(maxlength=50)"," instrument = models.CharField(maxlength=100)",""," class Album(models.Model):"," artist = models.ForeignKey(Musician)"," name = models.CharField(maxlength=100)"," release_date = models.DateField()"," num_stars = models.IntegerField()","","Field name restrictions","-----------------------","","Django places only two restrictions on model field names:",""," 1. A field name cannot be a Python reserved word, because that would result"," in a Python syntax error. For example::",""," class Example(models.Model):"," pass = models.IntegerField() # 'pass' is a reserved word!",""," 2. A field name cannot contain more than one underscore in a row, due to"," the way Django's query lookup syntax works. For example::",""," class Example(models.Model):"," foo__bar = models.IntegerField() # 'foo__bar' has two underscores!","","These limitations can be worked around, though, because your field name doesn't","necessarily have to match your database column name. See `db_column`_ below.","","SQL reserved words, such as ``join``, ``where`` or ``select``, *are* allowed as","model field names, because Django escapes all database table names and column","names in every underlying SQL query. It uses the quoting syntax of your","particular database engine.","","Field types","-----------","","Each field in your model should be an instance of the appropriate ``Field``","class. Django uses the field class types to determine a few things:",""," * The database column type (e.g. ``INTEGER``, ``VARCHAR``)."," * The widget to use in Django's admin interface, if you care to use it"," (e.g. ````, ```` (a single-line input).","","``CharField`` has an extra required argument, ``maxlength``, the maximum length","(in characters) of the field. The maxlength is enforced at the database level","and in Django's validation.","","``CommaSeparatedIntegerField``","~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~","","A field of integers separated by commas. As in ``CharField``, the ``maxlength``","argument is required.","","``DateField``","~~~~~~~~~~~~~","","A date field. Has a few extra optional arguments:",""," ====================== ==================================================="," Argument Description"," ====================== ==================================================="," ``auto_now`` Automatically set the field to now every time the"," object is saved. Useful for \"last-modified\""," timestamps. Note that the current date is *always*"," used; it's not just a default value that you can"," override.",""," ``auto_now_add`` Automatically set the field to now when the object"," is first created. Useful for creation of"," timestamps. Note that the current date is *always*"," used; it's not just a default value that you can"," override."," ====================== ===================================================","","The admin represents this as an ```` with a JavaScript","calendar and a shortcut for \"Today.\"","","``DateTimeField``","~~~~~~~~~~~~~~~~~","","A date and time field. Takes the same extra options as ``DateField``.","","The admin represents this as two ```` fields, with","JavaScript shortcuts.","","``DecimalField``","~~~~~~~~~~~~~~~~","","**New in Django development version**","","A fixed-precision decimal number, represented in Python by a ``Decimal`` instance.","Has two **required** arguments:",""," ====================== ==================================================="," Argument Description"," ====================== ==================================================="," ``max_digits`` The maximum number of digits allowed in the number.",""," ``decimal_places`` The number of decimal places to store with the"," number."," ====================== ===================================================","","For example, to store numbers up to 999 with a resolution of 2 decimal places,","you'd use::",""," models.DecimalField(..., max_digits=5, decimal_places=2)","","And to store numbers up to approximately one billion with a resolution of 10","decimal places::",""," models.DecimalField(..., max_digits=19, decimal_places=10)","","The admin represents this as an ```` (a single-line input).","","``EmailField``","~~~~~~~~~~~~~~","","A ``CharField`` that checks that the value is a valid e-mail address.","This doesn't accept ``maxlength``; its ``maxlength`` is automatically set to","75.","","``FileField``","~~~~~~~~~~~~~","","A file-upload field. Has one **required** argument:",""," ====================== ==================================================="," Argument Description"," ====================== ==================================================="," ``upload_to`` A local filesystem path that will be appended to"," your ``MEDIA_ROOT`` setting to determine the"," output of the ``get__url()`` helper"," function."," ====================== ===================================================","","This path may contain `strftime formatting`_, which will be replaced by the","date/time of the file upload (so that uploaded files don't fill up the given","directory).","","The admin represents this field as an ```` (a file-upload","widget).","","Using a ``FileField`` or an ``ImageField`` (see below) in a model takes a few","steps:",""," 1. In your settings file, you'll need to define ``MEDIA_ROOT`` 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 ``MEDIA_URL`` as the base public URL of that directory. Make"," sure that this directory is writable by the Web server's user"," account.",""," 2. Add the ``FileField`` or ``ImageField`` to your model, making sure"," to define the ``upload_to`` option to tell Django to which"," subdirectory of ``MEDIA_ROOT`` it should upload files.",""," 3. All that will be stored in your database is a path to the file"," (relative to ``MEDIA_ROOT``). You'll most likely want to use the"," convenience ``get__url`` function provided by Django. For"," example, if your ``ImageField`` is called ``mug_shot``, you can get"," the absolute URL to your image in a template with ``{{"," object.get_mug_shot_url }}``.","","For example, say your ``MEDIA_ROOT`` is set to ``'/home/media'``, and","``upload_to`` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` part of","``upload_to`` is strftime formatting; ``'%Y'`` is the four-digit year,","``'%m'`` is the two-digit month and ``'%d'`` is the two-digit day. If you","upload a file on Jan. 15, 2007, it will be saved in the directory","``/home/media/photos/2007/01/15``.","","If you want to retrieve the upload file's on-disk filename, or a URL that","refers to that file, or the file's size, you can use the","``get_FOO_filename()``, ``get_FOO_url()`` and ``get_FOO_size()`` methods.","They are all documented here__.","","__ ../db-api/#get-foo-filename","","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. *Validate all uploaded files* 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.","",".. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941","","``FilePathField``","~~~~~~~~~~~~~~~~~","","A field whose choices are limited to the filenames in a certain directory","on the filesystem. Has three special arguments, of which the first is","**required**:",""," ====================== ==================================================="," Argument Description"," ====================== ==================================================="," ``path`` Required. The absolute filesystem path to a"," directory from which this ``FilePathField`` should"," get its choices. Example: ``\"/home/images\"``.",""," ``match`` Optional. A regular expression, as a string, that"," ``FilePathField`` will use to filter filenames."," Note that the regex will be applied to the"," base filename, not the full path. Example:"," ``\"foo.*\\.txt^\"``, which will match a file called"," ``foo23.txt`` but not ``bar.txt`` or ``foo23.gif``.",""," ``recursive`` Optional. Either ``True`` or ``False``. Default is"," ``False``. Specifies whether all subdirectories of"," ``path`` should be included."," ====================== ===================================================","","Of course, these arguments can be used together.","","The one potential gotcha is that ``match`` applies to the base filename,","not the full path. So, this example::",""," FilePathField(path=\"/home/images\", match=\"foo.*\", recursive=True)","","...will match ``/home/images/foo.gif`` but not ``/home/images/foo/bar.gif``","because the ``match`` applies to the base filename (``foo.gif`` and","``bar.gif``).","","``FloatField``","~~~~~~~~~~~~~~","","**Changed in Django development version**","","A floating-point number represented in Python by a ``float`` instance.","","The admin represents this as an ```` (a single-line input).","","**NOTE:** The semantics of ``FloatField`` have changed in the Django","development version. See the `Django 0.96 documentation`_ for the old behavior.","",".. _Django 0.96 documentation: http://www.djangoproject.com/documentation/0.96/model-api/#floatfield","","``ImageField``","~~~~~~~~~~~~~~","","Like ``FileField``, but validates that the uploaded object is a valid","image. Has two extra optional arguments, ``height_field`` and","``width_field``, which, if set, will be auto-populated with the height and","width of the image each time a model instance is saved.","","In addition to the special ``get_FOO_*`` methods that are available for","``FileField``, an ``ImageField`` also has ``get_FOO_height()`` and","``get_FOO_width()`` methods. These are documented elsewhere_.","","Requires the `Python Imaging Library`_.","",".. _Python Imaging Library: http://www.pythonware.com/products/pil/",".. _elsewhere: ../db-api/#get-foo-height-and-get-foo-width","","``IntegerField``","~~~~~~~~~~~~~~~~","","An integer.","","The admin represents this as an ```` (a single-line input).","","``IPAddressField``","~~~~~~~~~~~~~~~~~~","","An IP address, in string format (i.e. \"24.124.1.30\").","","The admin represents this as an ```` (a single-line input).","","``NullBooleanField``","~~~~~~~~~~~~~~~~~~~~","","Like a ``BooleanField``, but allows ``NULL`` as one of the options. Use this","instead of a ``BooleanField`` with ``null=True``.","","The admin represents this as a ```` (a","single-line input).","","``SmallIntegerField``","~~~~~~~~~~~~~~~~~~~~~","","Like an ``IntegerField``, but only allows values under a certain","(database-dependent) point.","","``TextField``","~~~~~~~~~~~~~","","A large text field.","","The admin represents this as a ``