=== added directory 'tests/modeltests/update' === added file 'tests/modeltests/update/__init__.py' === added file 'tests/modeltests/update/models.py' --- tests/modeltests/update/models.py 1970-01-01 00:00:00 +0000 +++ tests/modeltests/update/models.py 2006-12-22 06:05:43 +0000 @@ -0,0 +1,69 @@ +""" +34. update() + +update() will update an object's fields with the paramaters passed to it, +and then save the object. +""" + +from django.db import models +from django.core import validators + +class User(models.Model): + username = models.CharField(maxlength=30, unique=True, + validator_list=[validators.isAlphaNumeric]) + first_name = models.CharField(maxlength=100) + last_name = models.CharField(maxlength=100) + + def __str__(self): + return '%s %s "%s"' % (self.first_name, self.last_name, self.username) + + class Meta: + ordering = ('username',) + +__test__ = {'API_TESTS':""" +# Lets create a User. +>>> u1 = User.objects.create(username='brave', first_name='Sir', last_name='Robin') + +# Only one User in the database so far. +>>> User.objects.all() +[] + +# Now we update the user's username and check that it was indeed updated. +>>> u1.update(username='notsobrave') +>>> u1.username +'notsobrave' + +# We should still only have one User in the database. +>>> User.objects.all() +[] + +# We should be able to grab the User by its new username. +>>> u1 = User.objects.get(username='notsobrave') + +# And we should no longer have a User with username 'brave'. +>>> User.objects.filter(username='brave').count() +0L + +# Let's create another User. +>>> u2 = User.objects.create(username='brave', first_name='Sir', last_name='Lancelot') + +# Two Users in the database now, and we also have the first User's updated data. +>>> User.objects.all() +[, ] + +# We can update more than one field at a time. +>>> u1.update(username='pure', last_name='Galahad') + +# The user did indeed get updated. +>>> User.objects.all() +[, ] + +# If we have a dictionary of fields to change, we can pass that to +# update() also. +>>> data = {'username': 'knight', 'first_name': 'Knight'} +>>> u1.update(**data) +>>> u1 + +>>> User.objects.all() +[, ] +"""} === added directory 'tests/modeltests/update_or_create' === added file 'tests/modeltests/update_or_create/__init__.py' === added file 'tests/modeltests/update_or_create/models.py' --- tests/modeltests/update_or_create/models.py 1970-01-01 00:00:00 +0000 +++ tests/modeltests/update_or_create/models.py 2006-12-24 22:33:57 +0000 @@ -0,0 +1,75 @@ +""" +35. update_or_create() + +update_or_create() tries to look up an object with the given parameters. +If an object is found, it updates the object. If an object isn't found, it +creates one with the given parameters. +""" + +from django.db import models + +class Person(models.Model): + first_name = models.CharField(maxlength=100) + last_name = models.CharField(maxlength=100) + birthday = models.DateField() + + def __str__(self): + return '%s %s, Birthday: %s' % (self.first_name, self.last_name, + self.birthday) + + class Meta: + ordering = ('last_name',) + +__test__ = {'API_TESTS':""" +# Create a Person. +>>> from datetime import date +>>> p = Person.objects.create(first_name='John', last_name='Lennon', birthday=date(1940, 10, 9)) + +# Only one Person is in the database at this point. +>>> Person.objects.all() +[] + +# update_or_create() a Person with the same name. +>>> p, created = Person.objects.update_or_create(first_name='John', last_name='Lennon', defaults={'birthday': date(1970, 10, 9)}) + +# update_or_create() didn't have to create an object. +>>> created +False + +# There's still only one Person in the database, and their birthday was updated. +>>> Person.objects.all() +[] + +# update_or_create() a Person with a different name. +>>> p, created = Person.objects.update_or_create(first_name='George', last_name='Harrison', defaults={'birthday': date(1943, 2, 25)}) +>>> created +True + +# Two People in the database now. +>>> Person.objects.all() +[, ] + +# If we execute the exact same statement, it won't create a Person. +>>> p, created = Person.objects.update_or_create(first_name='George', last_name='Harrison', defaults={'birthday': date(1943, 2, 25)}) +>>> created +False + +# The two People in the database haven't changed. +>>> Person.objects.all() +[, ] + +# update_or_create() can take an empty 'defaults' parameter, but in this +# situation behaves exactly like get_or_create(). This is useful if you are +# building the 'defaults' dictionary dynamically. +>>> p, created = Person.objects.update_or_create(first_name='George', last_name='Harrison', defaults={}) +>>> created +False + +# A different name with an empty 'defaults'. +>>> p, created = Person.objects.update_or_create(first_name='John', last_name='Smith', birthday=date(1950, 2, 10), defaults={}) +>>> created +True + +>>> Person.objects.all() +[, , ] +"""} === modified file 'django/db/models/base.py' --- django/db/models/base.py 2006-12-19 04:35:09 +0000 +++ django/db/models/base.py 2006-12-22 06:05:43 +0000 @@ -217,6 +217,19 @@ save.alters_data = True + def update(self, **kwargs): + """ + Set the object's fields to the new values passed in as keyword + arguments and then save the object. Fields not specified in the + keyword arguments will not be altered. + """ + # Nothing to do if we have no keyword arguments. + if kwargs: + self.__dict__.update(kwargs) + self.save() + + update.alters_data = True + def validate(self): """ First coerces all fields on this instance to their proper Python types. === modified file 'django/db/models/manager.py' --- django/db/models/manager.py 2006-12-19 04:35:09 +0000 +++ django/db/models/manager.py 2006-12-22 06:44:11 +0000 @@ -68,7 +68,10 @@ def get_or_create(self, **kwargs): return self.get_query_set().get_or_create(**kwargs) - + + def update_or_create(self, **kwargs): + return self.get_query_set().update_or_create(**kwargs) + def create(self, **kwargs): return self.get_query_set().create(**kwargs) === modified file 'django/db/models/query.py' --- django/db/models/query.py 2006-12-19 04:35:09 +0000 +++ django/db/models/query.py 2006-12-24 22:15:33 +0000 @@ -240,6 +240,19 @@ obj.save() return obj, True + def update_or_create(self, **kwargs): + """ + Looks up an object with the given kwargs, creating one if necessary. + If the object already exists, then its fields are updated with the + values passed in the defaults dictionary. + Returns a tuple of (object, created), where created is a boolean + specifying whether an object was created. + """ + obj, created = self.get_or_create(**kwargs) + if not created: + obj.update(**kwargs.pop('defaults', {})) + return obj, created + def latest(self, field_name=None): """ Returns the latest object, according to the model's 'get_latest_by' === modified file 'docs/db-api.txt' --- docs/db-api.txt 2006-12-19 04:35:09 +0000 +++ docs/db-api.txt 2006-12-26 06:04:05 +0000 @@ -121,19 +121,35 @@ Saving changes to objects ========================= -To save changes to an object that's 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:: - - b5.name = 'New name' - b5.save() - -This performs an ``UPDATE`` SQL statement behind the scenes. Django doesn't hit +``save()`` +---------- + +Use the ``save()`` method to save an object to the database after making +changes to it:: + + newblog.name = "Brave New World" + newblog.save() + +This performs an ``UPDATE`` SQL statement behind the scenes (see the +`How Django knows to UPDATE vs. INSERT`_ section below). Django doesn't hit the database until you explicitly call ``save()``. The ``save()`` method has no return value. +``update(**kwargs)`` +-------------------- + +A convenience method for updating and saving an object all in one step, where +(``**kwargs``) are the attributes to update. Like ``save()``, the +``update()`` method has no return value. + +Using ``update()``, the above code example could be rewritten as:: + + newblog.update(name="Brave New World") + +Since ``update()`` calls ``save()`` behind the scenes, Django will hit the +database every time ``update()`` is called. + How Django knows to UPDATE vs. INSERT ------------------------------------- @@ -784,6 +800,52 @@ .. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1 +``update_or_create(**kwargs)`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A convenience method for looking up an object with the given kwargs, and then +either updating the values of the object if one is found or creating an +object if one was not found. + +This method calls ``get_or_create()`` behind the scenes, and similarly +returns a tuple of ``(object, created)``, where``object`` is the updated or +created object and ``created`` is a boolean specifying whether a new object +was created. + +This is meant as a shortcut to the following type of code:: + + obj, created = Person.objects.get_or_create(first_name='John', last_name='Lennon', + defaults={'birthday': date(1940, 10, 9)}) + if not created: + obj.update('birthday'=date(1940, 10, 9)) + +This pattern gets quite unwieldy as the number of fields in a model goes up. +The above example can be rewritten using ``update_or_create()`` like so:: + + obj, created = Person.objects.update_or_create(first_name='John', last_name='Lennon', + defaults={'birthday': date(1940, 10, 9)}) + +Any keyword arguments passed to ``update_or_create()`` will be used in a +call to ``get_or_create()``. If ``get_or_create()`` creates an object, then +nothing needs to be done by ``update_or_create()`` and a tuple of the created +object and ``True`` is returned. If, on the other hand, ``get_or_create()`` +does not create a new object, then ``update_or_create()`` will update the +object with the values passed in the ``defaults`` parameter and a tuple of +the updated object and ``True`` is returned. + +The ``defaults`` parameter should be a dict of attribute-value pairs that +you want to update. If ``defaults`` is empty or not specified, then +``update_or_create()`` will act exactly like ``get_or_create()`` since there +would be nothing to update. + +As with ``get_or_create()``, if you need to use ``update_or_create()`` in a +view, please make sure to use it only in ``POST`` requests unless you have a +good reason not to. ``GET`` requests shouldn't have any effect on data; use +``POST`` whenever a request to a page has a side effect on your data. For +more, see `Safe methods`_ in the HTTP spec. + +.. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1 + ``count()`` ~~~~~~~~~~~