Example in documentation of transaction.atomic uses both decorator and context manager

[Peter Hull]

In the documentation of transaction.atomic (​https://docs.djangoproject.com/en/2.1/topics/db/transactions/#controlling-transactions-explicitly), the example below the line "Wrapping atomic in a try/except block allows for natural handling of integrity errors" uses both the decorator and the context manager versions of atomic(). This wouldn't necessarily be a problem except that using the decorator here causes the example to do exactly what the warning a couple paragraphs later says not to do: "Avoid catching exceptions inside atomic!" I suggest that removing the use of the decorator in the example would be the most prudent edit?

[Tim Graham]

I guess it's a typo in the original commit: d7bc4fbc94df6c231d71dffa45cf337ff13512ee.

[Peter Hull]

​PR

[Simon Charette]

I don't think the example is wrong at all as the inner transaction.atomic block creates a SAVEPOINT (because atomic(savepoint) defaults to True) and thus the connection is usable in the event of an IntegrityError because a rollback of the savepoint would happen.

What the example is trying to demonstrate is that you can still nest transaction.atomic() block safely if you wrap code expected to raise database error appropriately and have queries within its outer context be atomic. In this case the create_parent() and add_children() calls will be executed in the same transaction because of the function decorator.

Think of it this way, atomic would be completely impossible to use if you couldn't nest calls this way given each calls to the database can theoretically raise a database exception.