diff --git a/docs/db-api.txt b/docs/db-api.txt index 066521aa1d6..1109df72c93 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()`` ~~~~~~~~~~~