Django

Code

Changeset 4281

Show
Ignore:
Timestamp:
01/03/07 16:38:51 (2 years ago)
Author:
jacob
Message:

Oops -- reverted accidentally commited material from [4280]

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/trunk/docs/db-api.txt

    r4280 r4281  
    122122========================= 
    123123 
    124 ``save()`` 
    125 ---------- 
    126  
    127 Use the ``save()`` method to save an object to the database after making 
    128 changes to it:: 
    129  
    130     newblog.name = "Brave New World" 
    131     newblog.save() 
    132  
    133 This performs an ``UPDATE`` SQL statement behind the scenes (see the 
    134 `How Django knows to UPDATE vs. INSERT`_ section below).  Django doesn't hit 
     124To save changes to an object that's already in the database, use ``save()``. 
     125 
     126Given a ``Blog`` instance ``b5`` that has already been saved to the database, 
     127this example changes its name and updates its record in the database:: 
     128 
     129    b5.name = 'New name' 
     130    b5.save() 
     131 
     132This performs an ``UPDATE`` SQL statement behind the scenes. Django doesn't hit 
    135133the database until you explicitly call ``save()``. 
    136134 
    137135The ``save()`` method has no return value. 
    138  
    139 ``update(**kwargs)`` 
    140 -------------------- 
    141  
    142 **New in Django development version** 
    143  
    144 A convenience method for updating and saving an object all in one step, where 
    145 (``**kwargs``) are the attributes to update.  Like ``save()``, the 
    146 ``update()`` method has no return value. 
    147  
    148 Using ``update()``, the above code example could be rewritten as:: 
    149  
    150     newblog.update(name="Brave New World") 
    151  
    152 Since ``update()`` calls ``save()`` behind the scenes, Django will hit the 
    153 database every time ``update()`` is called. 
    154136 
    155137How Django knows to UPDATE vs. INSERT 
    …… 
    803785.. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1 
    804786 
    805 ``update_or_create(**kwargs)`` 
    806 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    807  
    808 **New in Django development version** 
    809  
    810 A convenience method for looking up an object with the given kwargs, and then 
    811 either updating the values of the object if one is found or creating an 
    812 object if one was not found. 
    813  
    814 This method calls ``get_or_create()`` behind the scenes, and similarly 
    815 returns a tuple of ``(object, created)``, where``object`` is the updated or 
    816 created object and ``created`` is a boolean specifying whether a new object 
    817 was created. 
    818  
    819 This is meant as a shortcut to the following type of code:: 
    820  
    821     obj, created = Person.objects.get_or_create(first_name='John', last_name='Lennon', 
    822                        defaults={'birthday': date(1940, 10, 9)}) 
    823     if not created: 
    824             obj.update('birthday'=date(1940, 10, 9)) 
    825  
    826 This pattern gets quite unwieldy as the number of fields in a model goes up. 
    827 The above example can be rewritten using ``update_or_create()`` like so:: 
    828  
    829     obj, created = Person.objects.update_or_create(first_name='John', last_name='Lennon', 
    830                        defaults={'birthday': date(1940, 10, 9)}) 
    831  
    832 Any keyword arguments passed to ``update_or_create()`` will be used in a 
    833 call to ``get_or_create()``. If ``get_or_create()`` creates an object, then 
    834 nothing needs to be done by ``update_or_create()`` and a tuple of the created 
    835 object and ``True`` is returned. If, on the other hand, ``get_or_create()`` 
    836 does not create a new object, then ``update_or_create()`` will update the 
    837 object with the values passed in the ``defaults`` parameter and a tuple of 
    838 the updated object and ``True`` is returned. 
    839  
    840 The ``defaults`` parameter should be a dict of attribute-value pairs that 
    841 you want to update. If ``defaults`` is empty or not specified, then 
    842 ``update_or_create()`` will act exactly like ``get_or_create()`` since there 
    843 would be nothing to update. 
    844  
    845 As with ``get_or_create()``, if you need to use ``update_or_create()`` in a 
    846 view, please make sure to use it only in ``POST`` requests unless you have a 
    847 good reason not to. ``GET`` requests shouldn't have any effect on data; use 
    848 ``POST`` whenever a request to a page has a side effect on your data. For 
    849 more, see `Safe methods`_ in the HTTP spec. 
    850  
    851 .. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1 
    852  
    853787``count()`` 
    854788~~~~~~~~~~~