Ticket #11527: patch-v1.diff

tests/modeltests/expressions/models.py

@@ -80 +80 @@
 ...
 FieldError: Joined field references are not permitted in this query
 
+# F expressions can be used to update attributes on single objects
+>>> test_gmbh = Company.objects.get(name='Test GmbH')
+>>> test_gmbh.num_employees
+32
+>>> test_gmbh.num_employees = F('num_employees') + 4
+>>> test_gmbh.save()
+>>> test_gmbh = Company.objects.get(pk=test_gmbh.pk)
+>>> test_gmbh.num_employees
+36
+
+# F expressions cannot be used to update attributes which are foreign keys, or
+# attributes which involve joins
+>>> test_gmbh.point_of_contact = None
+>>> test_gmbh.save()
+>>> test_gmbh.point_of_contact is None
+True
+>>> test_gmbh.point_of_contact = F('ceo')
+Traceback (most recent call last):
+...
+ValueError: Cannot assign "<django.db.models.expressions.F object at ...>": "Company.point_of_contact" must be a "Employee" instance.
+
+>>> test_gmbh.point_of_contact = test_gmbh.ceo
+>>> test_gmbh.save()
+>>> test_gmbh.name = F('ceo__last_name')
+>>> test_gmbh.save()
+Traceback (most recent call last):
+...
+FieldError: Joined field references are not permitted in this query
+
+# F expressions cannot be used to update attributes on objects which do not yet
+# exist in the database
+>>> acme = Company(name='The Acme Widget Co.', num_employees=12, num_chairs=5,
+...     ceo=test_gmbh.ceo)
+>>> acme.num_employees = F('num_employees') + 16
+>>> acme.save()
+Traceback (most recent call last):
+...
+TypeError: int() argument must be a string or a number, not 'ExpressionNode'
 """}

docs/ref/models/instances.txt

@@ -104 +104 @@
 Explicitly specifying auto-primary-key values is mostly useful for bulk-saving
 objects, when you're confident you won't have primary-key collision.
 
+Updating attributes using ``F()`` expressions
+---------------------------------------------
+
+Sometimes you'll need to perform a simple arithmetic task on a field: incrementing, decrementing, multiplying or dividing. Usually in Python you would do something like this::
+
+    >>> product = Product.objects.get(name='Venezuelan Beaver Cheese')
+    >>> product.number_sold += 1
+    >>> product.save()
+
+However, this pattern leaves your code open to `race conditions <http://en.wikipedia.org/wiki/Race_condition#Computing>`_, which occur when two processes or threads try to update the same object at the same time. In order to avoid, this, you can use :ref:`F() expressions <query-expressions>` to place the burden of synchronization on the database, which will typically be much better at avoiding these issues due to its ACID-compliant architecture.
+
+Using ``F()`` expressions, the above code would instead be::
+
+    >>> from django.db.models import F
+    >>> product = Product.objects.get(name='Venezuelan Beaver Cheese')
+    >>> product.number_sold = F('number_sold') + 1
+    >>> product.save()
+
+After saving, it is necessary to reload the object in question in order to access the actual value of the updated field. This can be done quite simply::
+
+    >>> product = Products.objects.get(pk=product.pk)
+
+``F()`` expressions work only on numeric fields (such as integers and floats), and support the standard Python operators for addition, subtraction, multiplication and division.
+
 What happens when you save?
 ---------------------------