Django

Code

Changeset 2793

Show
Ignore:
Timestamp:
04/29/06 13:53:03 (2 years ago)
Author:
adrian
Message:

magic-removal: Proofread docs/transactions.txt

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/branches/magic-removal/docs/transactions.txt

    r2714 r2793  
    88===================================== 
    99 
    10 The default behavior of Django is to commit on special model functions. If you 
    11 call ``model.save()`` or ``model.delete()``, that change will be committed immediately. 
     10Django's default behavior is to commit automatically when any built-in, 
     11data-altering model function is called. For example, if you call 
     12``model.save()`` or ``model.delete()``, the change will be committed 
     13immediately. 
    1214 
    13 This is much like the auto-commit setting for most databases: as soon as you 
     15This is much like the auto-commit setting for most databases. As soon as you 
    1416perform an action that needs to write to the database, Django produces the 
    15 insert/update/delete statements and then does the commit. There is no implicit 
    16 rollback in Django. 
     17``INSERT``/``UPDATE``/``DELETE`` statements and then does the ``COMMIT``. 
     18There's no implicit ``ROLLBACK``. 
    1719 
    1820Tying transactions to HTTP requests 
    1921=================================== 
    2022 
    21 A useful way to handle transactions is to tie them to the request and response 
    22 phases. 
     23The recommended way to handle transactions in Web requests is to tie them to 
     24the request and response phases via Django's ``TransactionMiddleware``. 
    2325 
    24 When a request starts, you start a transaction. If the response is produced 
    25 without problems, any transactions are committed. If the view function produces 
    26 and exception, a rollback happens. This is one of the more intuitive ways to 
    27 handle transactions. To activate this feature, just add the 
    28 ``TransactionMiddleware`` middleware to your stack:: 
     26It works like this: When a request starts, Django starts a transaction. If the 
     27response is produced without problems, Django commits any pending transactions. 
     28If the view function produces an exception, Django rolls back any pending 
     29transactions. 
     30 
     31To activate this feature, just add the ``TransactionMiddleware`` middleware to 
     32your ``MIDDLEWARE_CLASSES`` setting:: 
    2933 
    3034    MIDDLEWARE_CLASSES = ( 
    …… 
    3539    ) 
    3640 
    37 The order is quite important: the transaction middleware will be relevant not 
    38 only for the view functions called, but for all middleware modules that come 
    39 after it. So if you use the session middleware after the transaction middleware, 
    40 session creation will be part of the transaction. 
     41The order is quite important. The transaction middleware applies not only to 
     42view functions, but also for all middleware modules that come after it. So if 
     43you use the session middleware after the transaction middleware, session 
     44creation will be part of the transaction. 
    4145 
    42 The cache middleware isn't affected, as it uses its own database cursor (which 
    43 is mapped to its own database connection internally), and only the 
    44 database-based cache is affected. 
     46An exception is ``CacheMiddleware``, which is never affected. The cache 
     47middleware uses its own database cursor (which is mapped to its own database 
     48connection internally). 
    4549 
    4650Controlling transaction management in views 
    4751=========================================== 
    4852 
    49 For many people, implicit request-based transactions will work wonderfully. 
    50 However, if you need to control the way that transactions are managed, 
    51 you can use decorators that you can apply to a function to change the way 
    52 transactions are handled. 
     53For most people, implicit request-based transactions work wonderfully. However, 
     54if you need more fine-grained control over how transactions are managed, you 
     55can use Python decorators to change the way transactions are handled by a 
     56particular view function. 
    5357 
    5458.. note:: 
    …… 
    5761    decorators can be applied to non-view functions as well. 
    5862 
    59 ``autocommit`` 
    60 -------------- 
     63``django.db.transaction.autocommit`` 
     64------------------------------------ 
    6165 
    62 You can use the ``autocommit`` decorator to switch a view function to the 
    63 default commit behavior of Django, regardless of the global setting. Just use 
    64 the decorator like this:: 
     66Use the ``autocommit`` decorator to switch a view function to Django's default 
     67commit behavior, regardless of the global transaction setting. 
     68 
     69Example:: 
    6570 
    6671    from django.db import transaction 
    …… 
    7075        .... 
    7176 
    72 Within ``viewfunc`` transactions will be committed as soon as you call 
     77Within ``viewfunc()``, transactions will be committed as soon as you call 
    7378``model.save()``, ``model.delete()``, or any other function that writes to the 
    7479database. 
    7580 
    76 ``commit_on_success`` 
    77 --------------------- 
     81``django.db.transaction.commit_on_success`` 
     82------------------------------------------- 
    7883 
    79 You can use the ``commit_on_success`` decorator to use a single transaction for 
     84Use the ``commit_on_success`` decorator to use a single transaction for 
    8085all the work done in a function:: 
    8186 
    …… 
    8691        .... 
    8792 
    88 If the function returns successfully, then all work done will be committed. If an 
    89 exception is raised beyond the function, however, the transaction will be rolled 
    90 back. 
     93If the function returns successfully, then Django will commit all work done 
     94within the function at that point. If the function raises an exception, though, 
     95Django will roll back the transaction. 
    9196 
    92 ``commit_manually`` 
    93 ------------------- 
     97``django.db.transaction.commit_manually`` 
     98----------------------------------------- 
    9499 
    95 Sometimes you need full control over your transactions. In that case, you can use the 
    96 ``commit_manually`` decorator, which tells Django you'll be managing the transaction 
    97 on your own. 
     100Use the ``commit_manually`` decorator if you need full control over 
     101transactions. It tells Django you'll be managing the transaction on your own. 
    98102 
    99 If you don't commit or rollback and did change data (so that the current 
    100 transaction is marked as dirty), you'll get a ``TransactionManagementError`` 
    101 exception. 
     103If your view changes data and doesn't ``commit()`` or ``rollback()``, Django 
     104will raise a ``TransactionManagementError`` exception. 
    102105 
    103 Manual transaction management looks like:: 
     106Manual transaction management looks like this:: 
    104107 
    105108    from django.db import transaction 
    …… 
    122125..admonition:: An important note to users of earlier Django releases: 
    123126 
    124     The database ``connection.commit`` and ``connection.rollback`` functions 
    125     (also called ``db.commit`` and ``db.rollback`` in 0.91 and earlier), no 
    126     longer exist and have been replaced by the ``transaction.commit`` and 
    127     ``transaction.rollback`` commands. 
     127    The database ``connection.commit()`` and ``connection.rollback()`` methods 
     128    (called ``db.commit()`` and ``db.rollback()`` in 0.91 and earlier) no longer 
     129    exist. They've been replaced by ``transaction.commit()`` and 
     130    ``transaction.rollback()``. 
    128131 
    129132How to globally deactivate transaction management 
    …… 
    133136``DISABLE_TRANSACTION_MANAGEMENT`` to ``True`` in the Django settings file. 
    134137 
    135 If you do this, there will be no management whatsoever. The middleware will no 
    136 longer implicitly commit transactions, and you'll need to roll management 
    137 yourself. This even will require you to commit changes done by middleware 
    138 somewhere else. 
     138If you do this, Django won't provide any automatic transaction management 
     139whatsoever. Middleware will no longer implicitly commit transactions, and 
     140you'll need to roll management yourself. This even requires you to commit 
     141changes done by middleware somewhere else. 
    139142 
    140 Thus, this is best used in situations where you want to run your own transaction 
    141 controlling middleware or do something really strange. In almost all situations, 
    142 you'll be better off using the default behavior or the transaction middleware 
    143 and only modify selected functions as needed. 
     143Thus, this is best used in situations where you want to run your own 
     144transaction-controlling middleware or do something really strange. In almost 
     145all situations, you'll be better off using the default behavior, or the 
     146transaction middleware, and only modify selected functions as needed.