it-ebooks - Mastering Django Core

Chapter 4 explains the basics of defining models, and we use them throughout the rest of the book. There is, however, a huge range of model options available not covered elsewhere. This appendix explains each possible model definition option.

Note that although these APIs are considered stable, the Django developers consistently add new shortcuts and conveniences to the model definition. Its a good idea to always check the latest documentation online at http://docs.djangoproject.com/.

The most important part of a model and the only required part of a model is the list of database fields it defines.

Field Name Restrictions

Django places only two restrictions on model field names:

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 Djangos query lookup syntax works. For example:

   class Example(models.Model): foo__bar = models.IntegerField() # 'foo__bar' has two underscores!

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 Djangos forms and admin site, if you care to use it (e.g., ,

Djangos database API is the other half of the model API discussed in Appendix A. Once youve defined a model, youll use this API any time you need to access the database. Youve seen examples of this API in use throughout the book; this appendix explains all the various options in detail.

Like the model APIs discussed in Appendix A, though these APIs are considered very stable, the Django developers consistently add new shortcuts and conveniences. Its a good idea to always check the latest documentation online, available at http://docs.djangoproject.com/.

Throughout this guide (and in the reference), well refer to the following models, which comprise a Weblog application:

To represent database-table data in Python objects, Django uses an intuitive system: A model class represents a database table, and an instance of that class represents a particular record in the database table.

To create an object, instantiate it using keyword arguments to the model class, then call save() to save it to the database.

Assuming models live in a file mysite/blog/models.py, heres an example:

This performs an INSERT SQL statement behind the scenes. Django doesnt hit the database until you explicitly call save().

The save() method has no return value.

See also

save() takes a number of advanced options not described here. See the documentation for save() for complete details.

To create and save an object in a single step, use the create() method.

To save changes to an object thats already in the database, use save().

Given a Blog instance b5 that has already been saved to the database, this example changes its name and updates its record in the database:

This performs an UPDATE SQL statement behind the scenes. Django doesnt hit the database until you explicitly call save().

Updating a ForeignKey field works exactly the same way as saving a normal field simply assign an object of the right type to the field in question. This example updates the blog attribute of an Entry instance entry, assuming appropriate instances of Entry and Blog are already saved to the database (so we can retrieve them below):

Updating a ManyToManyField works a little differently use the add() method on the field to add a record to the relation. This example adds the Author instance joe to the entry object:

To add multiple records to a ManyToManyField in one go, include multiple arguments in the call to add(), like this:

Django will complain if you try to assign or add an object of the wrong type.

To retrieve objects from your database, construct a QuerySet via a Manager on your model class.

A QuerySet represents a collection of objects from your database. It can have zero, one or many filters. Filters narrow down the query results based on the given parameters. In SQL terms, a QuerySet equates to aSELECT statement, and a filter is a limiting clause such as WHERE or LIMIT.

You get a QuerySet by using your models Manager. Each model has at least one Manager, and its called objectsby default. Access it directly via the model class, like so:

Note

Managers are accessible only via model classes, rather than from model instances, to enforce a separation between table-level operations and record-level operations.

The Manager is the main source of QuerySets for a model. For example, Blog.objects.all() returns a QuerySetthat contains all Blog objects in the database.

The simplest way to retrieve objects from a table is to get all of them. To do this, use the all() method on a Manager: