Added section to docs/db-api.txt get_or_create() section about GET vs. POST

git-svn-id: http://code.djangoproject.com/svn/django/trunk@3096 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 14 insertions, 3 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index 066521aa1d..1109df72c9 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -715,7 +715,8 @@ Returns a tuple of ``(object, created)``, where ``object`` is the retrieved or
 created object and ``created`` is a boolean specifying whether a new object was
 created.
 
-This is meant as a shortcut to boilerplatish code. For example::
+This is meant as a shortcut to boilerplatish code and is mostly useful for
+data-import scripts. For example::
 
     try:
         obj = Person.objects.get(first_name='John', last_name='Lennon')
@@ -747,11 +748,21 @@ doesn't contain a double underscore (which would indicate a non-exact lookup).
 Then add the contents of ``defaults``, overriding any keys if necessary, and
 use the result as the keyword arguments to the model class.
 
-Finally, if you have a field named ``defaults`` and want to use it as an exact
-lookup in ``get_or_create()``, just use ``'defaults__exact'``, like so::
+If you have a field named ``defaults`` and want to use it as an exact lookup in
+``get_or_create()``, just use ``'defaults__exact'``, like so::
 
     Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'})
 
+Finally, a word on using ``get_or_create()`` in Django views. As mentioned
+earlier, ``get_or_create()`` is mostly useful in scripts that need to parse
+data and create new records if existing ones aren't available. But if you need
+to use ``get_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()``
 ~~~~~~~~~~~