Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #3226: removed some pre-magic-removal-isms in settings docs. Th…

…anks, ubernostrum.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@4280 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit da9affa8f820d8d3043379a8707511ecaaf11cf0 1 parent 3d38e5d
Jacob Kaplan-Moss authored January 03, 2007
78  docs/db-api.txt
@@ -121,19 +121,37 @@ objects, when you're confident you won't have primary-key collision.
121 121
 Saving changes to objects
122 122
 =========================
123 123
 
124  
-To save changes to an object that's already in the database, use ``save()``.
  124
+``save()``
  125
+----------
125 126
 
126  
-Given a ``Blog`` instance ``b5`` that has already been saved to the database,
127  
-this example changes its name and updates its record in the database::
  127
+Use the ``save()`` method to save an object to the database after making
  128
+changes to it::
128 129
 
129  
-    b5.name = 'New name'
130  
-    b5.save()
  130
+    newblog.name = "Brave New World"
  131
+    newblog.save()
131 132
 
132  
-This performs an ``UPDATE`` SQL statement behind the scenes. Django doesn't hit
  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
133 135
 the database until you explicitly call ``save()``.
134 136
 
135 137
 The ``save()`` method has no return value.
136 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.
  154
+
137 155
 How Django knows to UPDATE vs. INSERT
138 156
 -------------------------------------
139 157
 
@@ -784,6 +802,54 @@ has a side effect on your data. For more, see `Safe methods`_ in the HTTP spec.
784 802
 
785 803
 .. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
786 804
 
  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
+
787 853
 ``count()``
788 854
 ~~~~~~~~~~~
789 855
 
6  docs/settings.txt
@@ -157,13 +157,13 @@ ABSOLUTE_URL_OVERRIDES
157 157
 
158 158
 Default: ``{}`` (Empty dictionary)
159 159
 
160  
-A dictionary mapping ``"app_label.module_name"`` strings to functions that take
  160
+A dictionary mapping ``"app_label.model_name"`` strings to functions that take
161 161
 a model object and return its URL. This is a way of overriding
162 162
 ``get_absolute_url()`` methods on a per-installation basis. Example::
163 163
 
164 164
     ABSOLUTE_URL_OVERRIDES = {
165  
-        'blogs.blogs': lambda o: "/blogs/%s/" % o.slug,
166  
-        'news.stories': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
  165
+        'blogs.Weblog': lambda o: "/blogs/%s/" % o.slug,
  166
+        'news.Story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
167 167
     }
168 168
 
169 169
 ADMIN_FOR

0 notes on commit da9affa

Please sign in to comment.
Something went wrong with that request. Please try again.