diff options
Diffstat (limited to 'parts/django/docs/ref/models/instances.txt')
| -rw-r--r-- | parts/django/docs/ref/models/instances.txt | 570 |
1 files changed, 0 insertions, 570 deletions
diff --git a/parts/django/docs/ref/models/instances.txt b/parts/django/docs/ref/models/instances.txt deleted file mode 100644 index 1730ec6..0000000 --- a/parts/django/docs/ref/models/instances.txt +++ /dev/null @@ -1,570 +0,0 @@ -======================== -Model instance reference -======================== - -.. currentmodule:: django.db.models - -This document describes the details of the ``Model`` API. It builds on the -material presented in the :doc:`model </topics/db/models>` and :doc:`database -query </topics/db/queries>` guides, so you'll probably want to read and -understand those documents before reading this one. - -Throughout this reference we'll use the :ref:`example Weblog models -<queryset-model-example>` presented in the :doc:`database query guide -</topics/db/queries>`. - -Creating objects -================ - -To create a new instance of a model, just instantiate it like any other Python -class: - -.. class:: Model(**kwargs) - -The keyword arguments are simply the names of the fields you've defined on your -model. Note that instantiating a model in no way touches your database; for -that, you need to ``save()``. - -.. _validating-objects: - -Validating objects -================== - -.. versionadded:: 1.2 - -There are three steps involved in validating a model: - - 1. Validate the model fields - 2. Validate the model as a whole - 3. Validate the field uniqueness - -All three steps are performed when you call by a model's -``full_clean()`` method. - -When you use a ``ModelForm``, the call to ``is_valid()`` will perform -these validation steps for all the fields that are included on the -form. (See the :doc:`ModelForm documentation -</topics/forms/modelforms>` for more information.) You should only need -to call a model's ``full_clean()`` method if you plan to handle -validation errors yourself, or if you have excluded fields from the -ModelForm that require validation. - -.. method:: Model.full_clean(exclude=None) - -This method calls ``Model.clean_fields()``, ``Model.clean()``, and -``Model.validate_unique()``, in that order and raises a ``ValidationError`` -that has a ``message_dict`` attribute containing errors from all three stages. - -The optional ``exclude`` argument can be used to provide a list of field names -that can be excluded from validation and cleaning. ``ModelForm`` uses this -argument to exclude fields that aren't present on your form from being -validated since any errors raised could not be corrected by the user. - -Note that ``full_clean()`` will *not* be called automatically when you -call your model's ``save()`` method, nor as a result of ``ModelForm`` -validation. You'll need to call it manually when you want to run model -validation outside of a ``ModelForm``. - -Example:: - - try: - article.full_clean() - except ValidationError, e: - # Do something based on the errors contained in e.message_dict. - # Display them to a user, or handle them programatically. - -The first step ``full_clean()`` performs is to clean each individual field. - -.. method:: Model.clean_fields(exclude=None) - -This method will validate all fields on your model. The optional ``exclude`` -argument lets you provide a list of field names to exclude from validation. It -will raise a ``ValidationError`` if any fields fail validation. - -The second step ``full_clean()`` performs is to call ``Model.clean()``. -This method should be overridden to perform custom validation on your model. - -.. method:: Model.clean() - -This method should be used to provide custom model validation, and to modify -attributes on your model if desired. For instance, you could use it to -automatically provide a value for a field, or to do validation that requires -access to more than a single field:: - - def clean(self): - 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: - raise ValidationError('Draft entries may not have a publication date.') - # Set the pub_date for published items if it hasn't been set already. - if self.status == 'published' and self.pub_date is None: - self.pub_date = datetime.datetime.now() - -Any ``ValidationError`` raised by ``Model.clean()`` will be stored under a -special key that is used for errors that are tied to the entire model instead -of to a specific field. You can access these errors with ``NON_FIELD_ERRORS``:: - - - from django.core.exceptions import ValidationError, NON_FIELD_ERRORS - try: - article.full_clean() - except ValidationError, e: - non_field_errors = e.message_dict[NON_FIELD_ERRORS] - -Finally, ``full_clean()`` will check any unique constraints on your model. - -.. method:: Model.validate_unique(exclude=None) - -This method is similar to ``clean_fields``, but validates all uniqueness -constraints on your model instead of individual field values. The optional -``exclude`` argument allows you to provide a list of field names to exclude -from validation. It will raise a ``ValidationError`` if any fields fail -validation. - -Note that if you provide an ``exclude`` argument to ``validate_unique``, any -``unique_together`` constraint that contains one of the fields you provided -will not be checked. - - -Saving objects -============== - -To save an object back to the database, call ``save()``: - -.. method:: Model.save([force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS]) - -.. versionadded:: 1.0 - The ``force_insert`` and ``force_update`` arguments were added. - -.. versionadded:: 1.2 - The ``using`` argument was added. - -If you want customized saving behavior, you can override this -``save()`` method. See :ref:`overriding-model-methods` for more -details. - -The model save process also has some subtleties; see the sections -below. - -Auto-incrementing primary keys ------------------------------- - -If a model has an ``AutoField`` -- an auto-incrementing primary key -- then -that auto-incremented value will be calculated and saved as an attribute on -your object the first time you call ``save()``:: - - >>> b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.') - >>> b2.id # Returns None, because b doesn't have an ID yet. - >>> b2.save() - >>> b2.id # Returns the ID of your new object. - -There's no way to tell what the value of an ID will be before you call -``save()``, because that value is calculated by your database, not by Django. - -(For convenience, each model has an ``AutoField`` named ``id`` by default -unless you explicitly specify ``primary_key=True`` on a field. See the -documentation for ``AutoField`` for more details. - -The ``pk`` property -~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 1.0 - -.. attribute:: Model.pk - -Regardless of whether you define a primary key field yourself, or let Django -supply one for you, each model will have a property called ``pk``. It behaves -like a normal attribute on the model, but is actually an alias for whichever -attribute is the primary key field for the model. You can read and set this -value, just as you would for any other attribute, and it will update the -correct field in the model. - -Explicitly specifying auto-primary-key values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If a model has an ``AutoField`` but you want to define a new object's ID -explicitly when saving, just define it explicitly before saving, rather than -relying on the auto-assignment of the ID:: - - >>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.') - >>> b3.id # Returns 3. - >>> b3.save() - >>> b3.id # Returns 3. - -If you assign auto-primary-key values manually, make sure not to use an -already-existing primary-key value! If you create a new object with an explicit -primary-key value that already exists in the database, Django will assume you're -changing the existing record rather than creating a new one. - -Given the above ``'Cheddar Talk'`` blog example, this example would override the -previous record in the database:: - - b4 = Blog(id=3, name='Not Cheddar', tagline='Anything but cheese.') - b4.save() # Overrides the previous blog with ID=3! - -See `How Django knows to UPDATE vs. INSERT`_, below, for the reason this -happens. - -Explicitly specifying auto-primary-key values is mostly useful for bulk-saving -objects, when you're confident you won't have primary-key collision. - -What happens when you save? ---------------------------- - -When you save an object, Django performs the following steps: - - 1. **Emit a pre-save signal.** The :doc:`signal </ref/signals>` - :attr:`django.db.models.signals.pre_save` is sent, allowing any - functions listening for that signal to take some customized - action. - - 2. **Pre-process the data.** Each field on the object is asked to - perform any automated data modification that the field may need - to perform. - - Most fields do *no* pre-processing -- the field data is kept as-is. - Pre-processing is only used on fields that have special behavior. - For example, if your model has a ``DateField`` with ``auto_now=True``, - the pre-save phase will alter the data in the object to ensure that - the date field contains the current date stamp. (Our documentation - doesn't yet include a list of all the fields with this "special - behavior.") - - 3. **Prepare the data for the database.** Each field is asked to provide - its current value in a data type that can be written to the database. - - Most fields require *no* data preparation. Simple data types, such as - integers and strings, are 'ready to write' as a Python object. However, - more complex data types often require some modification. - - For example, ``DateFields`` use a Python ``datetime`` object to store - data. Databases don't store ``datetime`` objects, so the field value - must be converted into an ISO-compliant date string for insertion - into the database. - - 4. **Insert the data into the database.** The pre-processed, prepared - data is then composed into an SQL statement for insertion into the - database. - - 5. **Emit a post-save signal.** The signal - :attr:`django.db.models.signals.post_save` is sent, allowing - any functions listening for that signal to take some customized - action. - -How Django knows to UPDATE vs. INSERT -------------------------------------- - -You may have noticed Django database objects use the same ``save()`` method -for creating and changing objects. Django abstracts the need to use ``INSERT`` -or ``UPDATE`` SQL statements. Specifically, when you call ``save()``, Django -follows this algorithm: - - * If the object's primary key attribute is set to a value that evaluates to - ``True`` (i.e., a value other than ``None`` or the empty string), Django - executes a ``SELECT`` query to determine whether a record with the given - primary key already exists. - * If the record with the given primary key does already exist, Django - executes an ``UPDATE`` query. - * If the object's primary key attribute is *not* set, or if it's set but a - record doesn't exist, Django executes an ``INSERT``. - -The one gotcha here is that you should be careful not to specify a primary-key -value explicitly when saving new objects, if you cannot guarantee the -primary-key value is unused. For more on this nuance, see `Explicitly specifying -auto-primary-key values`_ above and `Forcing an INSERT or UPDATE`_ below. - -.. _ref-models-force-insert: - -Forcing an INSERT or UPDATE -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 1.0 - -In some rare circumstances, it's necessary to be able to force the ``save()`` -method to perform an SQL ``INSERT`` and not fall back to doing an ``UPDATE``. -Or vice-versa: update, if possible, but not insert a new row. In these cases -you can pass the ``force_insert=True`` or ``force_update=True`` parameters to -the ``save()`` method. Passing both parameters is an error, since you cannot -both insert *and* update at the same time. - -It should be very rare that you'll need to use these parameters. Django will -almost always do the right thing and trying to override that will lead to -errors that are difficult to track down. This feature is for advanced use -only. - -Updating attributes based on existing fields --------------------------------------------- - -Sometimes you'll need to perform a simple arithmetic task on a field, such -as incrementing or decrementing the current value. The obvious way to -achieve this is to do something like:: - - >>> product = Product.objects.get(name='Venezuelan Beaver Cheese') - >>> product.number_sold += 1 - >>> product.save() - -If the old ``number_sold`` value retrieved from the database was 10, then -the value of 11 will be written back to the database. - -This can be optimized slightly by expressing the update relative to the -original field value, rather than as an explicit assignment of a new value. -Django provides :ref:`F() expressions <query-expressions>` as a way of -performing this kind of relative update. Using ``F()`` expressions, the -previous example would be expressed as:: - - >>> from django.db.models import F - >>> product = Product.objects.get(name='Venezuelan Beaver Cheese') - >>> product.number_sold = F('number_sold') + 1 - >>> product.save() - -This approach doesn't use the initial value from the database. Instead, it -makes the database do the update based on whatever value is current at the -time that the save() is executed. - -Once the object has been saved, you must reload the object in order to access -the actual value that was applied to the updated field:: - - >>> product = Products.objects.get(pk=product.pk) - >>> print product.number_sold - 42 - -For more details, see the documentation on :ref:`F() expressions -<query-expressions>` and their :ref:`use in update queries -<topics-db-queries-update>`. - -Deleting objects -================ - -.. method:: Model.delete([using=DEFAULT_DB_ALIAS]) - -.. versionadded:: 1.2 - The ``using`` argument was added. - -Issues a SQL ``DELETE`` for the object. This only deletes the object -in the database; the Python instance will still be around, and will -still have data in its fields. - -For more details, including how to delete objects in bulk, see -:ref:`topics-db-queries-delete`. - -If you want customized deletion behavior, you can override this -``delete()`` method. See :ref:`overriding-model-methods` for more -details. - -.. _model-instance-methods: - -Other model instance methods -============================ - -A few object methods have special purposes. - -``__str__`` ------------ - -.. method:: Model.__str__() - -``__str__()`` is a Python "magic method" that defines what should be returned -if you call ``str()`` on the object. Django uses ``str(obj)`` (or the related -function, ``unicode(obj)`` -- see below) in a number of places, most notably -as the value displayed to render an object in the Django admin site and as the -value inserted into a template when it displays an object. Thus, you should -always return a nice, human-readable string for the object's ``__str__``. -Although this isn't required, it's strongly encouraged (see the description of -``__unicode__``, below, before putting ``__str__`` methods everywhere). - -For example:: - - class Person(models.Model): - first_name = models.CharField(max_length=50) - last_name = models.CharField(max_length=50) - - def __str__(self): - # Note use of django.utils.encoding.smart_str() here because - # first_name and last_name will be unicode strings. - return smart_str('%s %s' % (self.first_name, self.last_name)) - -``__unicode__`` ---------------- - -.. method:: Model.__unicode__() - -The ``__unicode__()`` method is called whenever you call ``unicode()`` on an -object. Since Django's database backends will return Unicode strings in your -model's attributes, you would normally want to write a ``__unicode__()`` -method for your model. The example in the previous section could be written -more simply as:: - - class Person(models.Model): - first_name = models.CharField(max_length=50) - last_name = models.CharField(max_length=50) - - def __unicode__(self): - return u'%s %s' % (self.first_name, self.last_name) - -If you define a ``__unicode__()`` method on your model and not a ``__str__()`` -method, Django will automatically provide you with a ``__str__()`` that calls -``__unicode__()`` and then converts the result correctly to a UTF-8 encoded -string object. This is recommended development practice: define only -``__unicode__()`` and let Django take care of the conversion to string objects -when required. - -``get_absolute_url`` --------------------- - -.. method:: Model.get_absolute_url() - -Define a ``get_absolute_url()`` method to tell Django how to calculate the -URL for an object. For example:: - - def get_absolute_url(self): - return "/people/%i/" % self.id - -Django uses this in its admin interface. If an object defines -``get_absolute_url()``, the object-editing page will have a "View on site" -link that will jump you directly to the object's public view, according to -``get_absolute_url()``. - -Also, a couple of other bits of Django, such as the :doc:`syndication feed -framework </ref/contrib/syndication>`, use ``get_absolute_url()`` as a -convenience to reward people who've defined the method. - -It's good practice to use ``get_absolute_url()`` in templates, instead of -hard-coding your objects' URLs. For example, this template code is bad:: - - <a href="/people/{{ object.id }}/">{{ object.name }}</a> - -But this template code is good:: - - <a href="{{ object.get_absolute_url }}">{{ object.name }}</a> - -.. note:: - The string you return from ``get_absolute_url()`` must contain only ASCII - characters (required by the URI spec, `RFC 2396`_) that have been - URL-encoded, if necessary. Code and templates using ``get_absolute_url()`` - should be able to use the result directly without needing to do any - further processing. You may wish to use the - ``django.utils.encoding.iri_to_uri()`` function to help with this if you - are using unicode strings a lot. - -.. _RFC 2396: http://www.ietf.org/rfc/rfc2396.txt - -The ``permalink`` decorator -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The problem with the way we wrote ``get_absolute_url()`` above is that it -slightly violates the DRY principle: the URL for this object is defined both -in the URLconf file and in the model. - -You can further decouple your models from the URLconf using the ``permalink`` -decorator: - -.. function:: permalink() - -This decorator is passed the view function, a list of positional parameters and -(optionally) a dictionary of named parameters. Django then works out the correct -full URL path using the URLconf, substituting the parameters you have given into -the URL. For example, if your URLconf contained a line such as:: - - (r'^people/(\d+)/$', 'people.views.details'), - -...your model could have a ``get_absolute_url`` method that looked like this:: - - from django.db import models - - @models.permalink - def get_absolute_url(self): - return ('people.views.details', [str(self.id)]) - -Similarly, if you had a URLconf entry that looked like:: - - (r'/archive/(?P<year>\d{4})/(?P<month>\d{1,2})/(?P<day>\d{1,2})/$', archive_view) - -...you could reference this using ``permalink()`` as follows:: - - @models.permalink - def get_absolute_url(self): - return ('archive_view', (), { - 'year': self.created.year, - 'month': self.created.month, - 'day': self.created.day}) - -Notice that we specify an empty sequence for the second parameter in this case, -because we only want to pass keyword parameters, not positional ones. - -In this way, you're tying the model's absolute path to the view that is used -to display it, without repeating the URL information anywhere. You can still -use the ``get_absolute_url`` method in templates, as before. - -In some cases, such as the use of generic views or the re-use of -custom views for multiple models, specifying the view function may -confuse the reverse URL matcher (because multiple patterns point to -the same view). - -For that problem, Django has **named URL patterns**. Using a named -URL pattern, it's possible to give a name to a pattern, and then -reference the name rather than the view function. A named URL -pattern is defined by replacing the pattern tuple by a call to -the ``url`` function):: - - from django.conf.urls.defaults import * - - url(r'^people/(\d+)/$', - 'django.views.generic.list_detail.object_detail', - name='people_view'), - -...and then using that name to perform the reverse URL resolution instead -of the view name:: - - from django.db import models - - @models.permalink - def get_absolute_url(self): - return ('people_view', [str(self.id)]) - -More details on named URL patterns are in the :doc:`URL dispatch documentation -</topics/http/urls>`. - -Extra instance methods -====================== - -In addition to ``save()``, ``delete()``, a model object might get any or all -of the following methods: - -.. method:: Model.get_FOO_display() - -For every field that has ``choices`` set, the object will have a -``get_FOO_display()`` method, where ``FOO`` is the name of the field. This -method returns the "human-readable" value of the field. For example, in the -following model:: - - GENDER_CHOICES = ( - ('M', 'Male'), - ('F', 'Female'), - ) - class Person(models.Model): - name = models.CharField(max_length=20) - gender = models.CharField(max_length=1, choices=GENDER_CHOICES) - -...each ``Person`` instance will have a ``get_gender_display()`` method. Example:: - - >>> p = Person(name='John', gender='M') - >>> p.save() - >>> p.gender - 'M' - >>> p.get_gender_display() - 'Male' - -.. method:: Model.get_next_by_FOO(\**kwargs) -.. method:: Model.get_previous_by_FOO(\**kwargs) - -For every ``DateField`` and ``DateTimeField`` that does not have ``null=True``, -the object will have ``get_next_by_FOO()`` and ``get_previous_by_FOO()`` -methods, where ``FOO`` is the name of the field. This returns the next and -previous object with respect to the date field, raising the appropriate -``DoesNotExist`` exception when appropriate. - -Both methods accept optional keyword arguments, which should be in the format -described in :ref:`Field lookups <field-lookups>`. - -Note that in the case of identical date values, these methods will use the ID -as a fallback check. This guarantees that no records are skipped or duplicated. |