Opened 6 years ago

Closed 6 years ago

#30005 closed Bug (invalid)

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

Reported by: Peter Hull Owned by: Peter Hull
Component: Documentation Version: 2.1
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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?

Change History (5)

comment:1 by Tim Graham, 6 years ago

Triage Stage: UnreviewedAccepted

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

comment:2 by Peter Hull, 6 years ago

Owner: changed from nobody to Peter Hull
Status: newassigned

comment:3 by Peter Hull, 6 years ago

Has patch: set

comment:4 by Simon Charette, 6 years ago

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.

Last edited 6 years ago by Simon Charette (previous) (diff)

comment:5 by Tim Graham, 6 years ago

Resolution: invalid
Status: assignedclosed
Note: See TracTickets for help on using tickets.
Back to Top