Permalink
Browse files

Add missing imports and models to the examples in the the model layer…

… documentation
  • Loading branch information...
1 parent d5ce2ff commit e4591debd19361e628317e936ed8123d9897dd6a @frog32 frog32 committed May 18, 2013
@@ -97,6 +97,8 @@ second element is the human-readable name. For example::
Generally, it's best to define choices inside a model class, and to
define a suitably-named constant for each value::
+ from django.db import models
+
class Student(models.Model):
FRESHMAN = 'FR'
SOPHOMORE = 'SO'
@@ -994,12 +996,15 @@ relationship with itself -- use ``models.ForeignKey('self')``.
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::
+ from django.db import models
+
class Car(models.Model):
manufacturer = models.ForeignKey('Manufacturer')
# ...
class Manufacturer(models.Model):
# ...
+ pass
To refer to models defined in another application, you can explicitly specify
a model with the full application label. For example, if the ``Manufacturer``
@@ -1132,6 +1137,9 @@ The possible values for :attr:`~ForeignKey.on_delete` are found in
necessary to avoid executing queries at the time your models.py is
imported::
+ from django.db import models
+ from django.contrib.auth.models import User
+
def get_sentinel_user():
return User.objects.get_or_create(username='deleted')[0]
@@ -1204,6 +1212,8 @@ that control how the relationship functions.
Only used in the definition of ManyToManyFields on self. Consider the
following model::
+ from django.db import models
+
class Person(models.Model):
friends = models.ManyToManyField("self")
@@ -34,6 +34,8 @@ that, you need to :meth:`~Model.save()`.
1. Add a classmethod on the model class::
+ from django.db import models
+
class Book(models.Model):
title = models.CharField(max_length=100)
@@ -105,6 +107,7 @@ individually.
You'll need to call ``full_clean`` manually when you want to run one-step model
validation for your own manually created models. For example::
+ from django.core.exceptions import ValidationError
try:
article.full_clean()
except ValidationError as e:
@@ -132,6 +135,7 @@ automatically provide a value for a field, or to do validation that requires
access to more than a single field::
def clean(self):
+ import datetime
from django.core.exceptions import ValidationError
# Don't allow draft entries to have a pub_date.
if self.status == 'draft' and self.pub_date is not None:
@@ -434,6 +438,8 @@ representation of the model from the ``__unicode__()`` method.
For example::
+ from django.db import models
+
class Person(models.Model):
first_name = models.CharField(max_length=50)
last_name = models.CharField(max_length=50)
@@ -460,6 +466,9 @@ Thus, you should return a nice, human-readable string for the object's
The previous :meth:`~Model.__unicode__()` example could be similarly written
using ``__str__()`` like this::
+ from django.db import models
+ from django.utils.encoding import force_bytes
+
class Person(models.Model):
first_name = models.CharField(max_length=50)
last_name = models.CharField(max_length=50)
@@ -490,6 +499,7 @@ function is usually the best approach.)
For example::
def get_absolute_url(self):
+ from django.core.urlresolvers import reverse
return reverse('people.views.details', args=[str(self.id)])
One place Django uses ``get_absolute_url()`` is in the admin app. If an object
@@ -145,6 +145,12 @@ Django quotes column and table names behind the scenes.
and a question has more than one answer, and the order of answers matters, you'd
do this::
+ from django.db import models
+
+ class Question(models.Model):
+ text = models.TextField()
+ # ...
+
class Answer(models.Model):
question = models.ForeignKey(Question)
# ...
@@ -232,6 +232,7 @@ the model field that is being aggregated.
For example, if you were manipulating a list of blogs, you may want
to determine how many entries have been made in each blog::
+ >>> from django.db.models import Count
>>> q = Blog.objects.annotate(Count('entry'))
# The name of the first blog
>>> q[0].name
@@ -699,6 +700,8 @@ And here's ``select_related`` lookup::
``select_related()`` follows foreign keys as far as possible. If you have the
following models::
+ from django.db import models
+
class City(models.Model):
# ...
pass
@@ -814,6 +817,8 @@ that are supported by ``select_related``. It also supports prefetching of
For example, suppose you have these models::
+ from django.db import models
+
class Topping(models.Model):
name = models.CharField(max_length=30)
@@ -1565,6 +1570,7 @@ aggregated.
For example, when you are working with blog entries, you may want to know the
number of authors that have contributed blog entries::
+ >>> from django.db.models import Count
>>> q = Blog.objects.aggregate(Count('entry'))
{'entry__count': 16}
@@ -2042,6 +2048,7 @@ Range test (inclusive).
Example::
+ import datetime
start_date = datetime.date(2005, 1, 1)
end_date = datetime.date(2005, 3, 31)
Entry.objects.filter(pub_date__range=(start_date, end_date))
@@ -12,8 +12,11 @@ Related objects reference
* The "other side" of a :class:`~django.db.models.ForeignKey` relation.
That is::
+ from django.db import models
+
class Reporter(models.Model):
- ...
+ # ...
+ pass
class Article(models.Model):
reporter = models.ForeignKey(Reporter)
@@ -24,7 +27,8 @@ Related objects reference
* Both sides of a :class:`~django.db.models.ManyToManyField` relation::
class Topping(models.Model):
- ...
+ # ...
+ pass
class Pizza(models.Model):
toppings = models.ManyToManyField(Topping)
@@ -18,27 +18,29 @@ used to track the inventory for a series of online bookstores:
.. code-block:: python
+ from django.db import models
+
class Author(models.Model):
- name = models.CharField(max_length=100)
- age = models.IntegerField()
+ name = models.CharField(max_length=100)
+ age = models.IntegerField()
class Publisher(models.Model):
- name = models.CharField(max_length=300)
- num_awards = models.IntegerField()
+ name = models.CharField(max_length=300)
+ num_awards = models.IntegerField()
class Book(models.Model):
- name = models.CharField(max_length=300)
- pages = models.IntegerField()
- price = models.DecimalField(max_digits=10, decimal_places=2)
- rating = models.FloatField()
- authors = models.ManyToManyField(Author)
- publisher = models.ForeignKey(Publisher)
- pubdate = models.DateField()
+ name = models.CharField(max_length=300)
+ pages = models.IntegerField()
+ price = models.DecimalField(max_digits=10, decimal_places=2)
+ rating = models.FloatField()
+ authors = models.ManyToManyField(Author)
+ publisher = models.ForeignKey(Publisher)
+ pubdate = models.DateField()
class Store(models.Model):
- name = models.CharField(max_length=300)
- books = models.ManyToManyField(Book)
- registered_users = models.PositiveIntegerField()
+ name = models.CharField(max_length=300)
+ books = models.ManyToManyField(Book)
+ registered_users = models.PositiveIntegerField()
Cheat sheet
===========
@@ -123,7 +125,7 @@ If you want to generate more than one aggregate, you just add another
argument to the ``aggregate()`` clause. So, if we also wanted to know
the maximum and minimum price of all books, we would issue the query::
- >>> from django.db.models import Avg, Max, Min, Count
+ >>> from django.db.models import Avg, Max, Min
>>> Book.objects.aggregate(Avg('price'), Max('price'), Min('price'))
{'price__avg': 34.35, 'price__max': Decimal('81.20'), 'price__min': Decimal('12.99')}
@@ -148,6 +150,7 @@ the number of authors:
.. code-block:: python
# Build an annotated queryset
+ >>> from django.db.models import Count
>>> q = Book.objects.annotate(Count('authors'))
# Interrogate the first object in the queryset
>>> q[0]
@@ -192,6 +195,7 @@ and aggregate the related value.
For example, to find the price range of books offered in each store,
you could use the annotation::
+ >>> from django.db.models import Max, Min
>>> Store.objects.annotate(min_price=Min('books__price'), max_price=Max('books__price'))
This tells Django to retrieve the ``Store`` model, join (through the
@@ -222,7 +226,7 @@ For example, we can ask for all publishers, annotated with their respective
total book stock counters (note how we use ``'book'`` to specify the
``Publisher`` -> ``Book`` reverse foreign key hop)::
- >>> from django.db.models import Count, Min, Sum, Max, Avg
+ >>> from django.db.models import Count, Min, Sum, Avg
>>> Publisher.objects.annotate(Count('book'))
(Every ``Publisher`` in the resulting ``QuerySet`` will have an extra attribute
@@ -269,6 +273,7 @@ constraining the objects for which an annotation is calculated. For example,
you can generate an annotated list of all books that have a title starting
with "Django" using the query::
+ >>> from django.db.models import Count, Avg
>>> Book.objects.filter(name__startswith="Django").annotate(num_authors=Count('authors'))
When used with an ``aggregate()`` clause, a filter has the effect of
@@ -407,6 +412,8 @@ particularly, when counting things.
By way of example, suppose you have a model like this::
+ from django.db import models
+
class Item(models.Model):
name = models.CharField(max_length=10)
data = models.IntegerField()
@@ -457,5 +464,6 @@ For example, if you wanted to calculate the average number of authors per
book you first annotate the set of books with the author count, then
aggregate that author count, referencing the annotation field::
+ >>> from django.db.models import Count, Avg
>>> Book.objects.annotate(num_authors=Count('authors')).aggregate(Avg('num_authors'))
{'num_authors__avg': 1.66}
@@ -62,6 +62,8 @@ For example, this custom ``Manager`` offers a method ``with_counts()``, which
returns a list of all ``OpinionPoll`` objects, each with an extra
``num_responses`` attribute that is the result of an aggregate query::
+ from django.db import models
+
class PollManager(models.Manager):
def with_counts(self):
from django.db import connection
@@ -101,6 +103,8 @@ Modifying initial Manager QuerySets
A ``Manager``'s base ``QuerySet`` returns all objects in the system. For
example, using this model::
+ from django.db import models
+
class Book(models.Model):
title = models.CharField(max_length=100)
author = models.CharField(max_length=50)
@@ -236,7 +240,7 @@ class, but still customize the default manager. For example, suppose you have
this base class::
class AbstractBase(models.Model):
- ...
+ # ...
objects = CustomManager()
class Meta:
@@ -246,14 +250,15 @@ If you use this directly in a subclass, ``objects`` will be the default
manager if you declare no managers in the base class::
class ChildA(AbstractBase):
- ...
+ # ...
# This class has CustomManager as the default manager.
+ pass
If you want to inherit from ``AbstractBase``, but provide a different default
manager, you can provide the default manager on the child class::
class ChildB(AbstractBase):
- ...
+ # ...
# An explicit default manager.
default_manager = OtherManager()
@@ -274,9 +279,10 @@ it into the inheritance hierarchy *after* the defaults::
abstract = True
class ChildC(AbstractBase, ExtraManager):
- ...
+ # ...
# Default manager is CustomManager, but OtherManager is
# also available via the "extra_manager" attribute.
+ pass
Note that while you can *define* a custom manager on the abstract model, you
can't *invoke* any methods using the abstract model. That is::
@@ -349,8 +355,7 @@ the manager class::
class MyManager(models.Manager):
use_for_related_fields = True
-
- ...
+ # ...
If this attribute is set on the *default* manager for a model (only the
default manager is considered in these situations), Django will use that class
@@ -396,15 +401,16 @@ it, whereas the following will not work::
# BAD: Incorrect code
class MyManager(models.Manager):
- ...
+ # ...
+ pass
# Sets the attribute on an instance of MyManager. Django will
# ignore this setting.
mgr = MyManager()
mgr.use_for_related_fields = True
class MyModel(models.Model):
- ...
+ # ...
objects = mgr
# End of incorrect code.
Oops, something went wrong.

0 comments on commit e4591de

Please sign in to comment.