Database Transactions

# Transaction management
from django.db import transaction

# Transaction functions
from django.db.transaction import (
    atomic, commit, rollback,
    savepoint, savepoint_commit, savepoint_rollback,
    get_autocommit, set_autocommit,
    get_rollback, set_rollback,
    on_commit, mark_for_rollback_on_error
)

# Transaction exceptions
from django.db.transaction import TransactionManagementError

class Atomic:
    """
    Context manager and decorator for atomic database operations.
    
    Can be used as decorator or context manager to ensure all database
    operations within the block execute atomically.
    """
    using: str | None
    savepoint: bool
    
    def __init__(self, using: str | None, savepoint: bool, durable: bool) -> None: ...
    def __call__(self, func: Callable) -> Callable: ...
    def __enter__(self) -> None: ...
    def __exit__(self, exc_type: type[BaseException] | None, exc_value: BaseException | None, exc_tb: TracebackType | None) -> None: ...

def atomic(using: str | None = None, savepoint: bool = True, durable: bool = False) -> Atomic:
    """
    Create atomic transaction block.
    
    Args:
        using: Database alias to use for transaction
        savepoint: Whether to create savepoint for nested transactions
        durable: Whether to ensure transaction durability
        
    Returns:
        Atomic context manager/decorator
    """

# As decorator
@transaction.atomic
def create_user_with_profile(user_data, profile_data):
    user = User.objects.create(**user_data)
    Profile.objects.create(user=user, **profile_data)
    return user

# As context manager
def transfer_funds(from_account, to_account, amount):
    with transaction.atomic():
        from_account.balance -= amount
        from_account.save()
        to_account.balance += amount
        to_account.save()

# With specific database
with transaction.atomic(using='db_alias'):
    # Operations on specific database
    pass

def commit(using: str | None = None) -> None:
    """
    Commit the current transaction.
    
    Args:
        using: Database alias to commit transaction on
    """

def rollback(using: str | None = None) -> None:
    """
    Roll back the current transaction.
    
    Args:
        using: Database alias to rollback transaction on
    """

def get_autocommit(using: str | None = None) -> bool:
    """
    Get autocommit mode for database connection.
    
    Args:
        using: Database alias
        
    Returns:
        Current autocommit setting
    """

def set_autocommit(autocommit: bool, using: str | None = None) -> None:
    """
    Set autocommit mode for database connection.
    
    Args:
        autocommit: Whether to enable autocommit
        using: Database alias
    """

def get_rollback(using: str | None = None) -> bool:
    """
    Get rollback flag for current transaction.
    
    Args:
        using: Database alias
        
    Returns:
        Whether transaction is marked for rollback
    """

def set_rollback(rollback: bool, using: str | None = None) -> None:
    """
    Mark current transaction for rollback.
    
    Args:
        rollback: Whether to mark for rollback
        using: Database alias
    """

def savepoint(using: str | None = None) -> str:
    """
    Create a transaction savepoint.
    
    Args:
        using: Database alias
        
    Returns:
        Savepoint identifier
    """

def savepoint_commit(sid: str, using: str | None = None) -> None:
    """
    Commit a transaction savepoint.
    
    Args:
        sid: Savepoint identifier
        using: Database alias
    """

def savepoint_rollback(sid: str, using: str | None = None) -> None:
    """
    Rollback to a transaction savepoint.
    
    Args:
        sid: Savepoint identifier
        using: Database alias
    """

def clean_savepoints(using: str | None = None) -> None:
    """
    Clean all savepoints for current transaction.
    
    Args:
        using: Database alias
    """

def complex_operation():
    with transaction.atomic():
        # Main transaction
        create_user()
        
        # Create savepoint for risky operation
        sid = transaction.savepoint()
        try:
            risky_operation()
            transaction.savepoint_commit(sid)
        except Exception:
            transaction.savepoint_rollback(sid)
            # Continue with main transaction

def on_commit(func: Callable[[], object], using: str | None = None, robust: bool = True) -> None:
    """
    Register function to run after current transaction commits.
    
    Args:
        func: Function to execute after commit
        using: Database alias
        robust: Whether to catch and log exceptions from func
    """

def send_welcome_email(user_id):
    user = User.objects.get(id=user_id)
    send_email(user.email, 'Welcome!')

def create_user(email, password):
    with transaction.atomic():
        user = User.objects.create(email=email, password=password)
        # Email only sent if transaction commits successfully
        transaction.on_commit(lambda: send_welcome_email(user.id))
        return user

def mark_for_rollback_on_error(using: str | None = None) -> Iterator[None]:
    """
    Context manager that marks transaction for rollback on any exception.
    
    Args:
        using: Database alias
        
    Yields:
        None
    """

with transaction.atomic():
    with transaction.mark_for_rollback_on_error():
        # Any exception here will mark transaction for rollback
        potentially_failing_operation()
    # Transaction continues but will be rolled back

def non_atomic_requests(using: str | None = None) -> Callable:
    """
    Decorator to disable atomic request handling for views.
    
    Args:
        using: Database alias
        
    Returns:
        Decorator function
    """

from django.db import transaction

@transaction.non_atomic_requests
def my_view(request):
    # This view won't be wrapped in automatic transaction
    pass

# For specific database
@transaction.non_atomic_requests(using='read_only_db')
def read_only_view(request):
    pass

class TransactionManagementError(ProgrammingError):
    """
    Exception raised for transaction management errors.
    
    Indicates improper use of transaction management functions
    or invalid transaction state.
    """

def complex_business_operation():
    with transaction.atomic():  # Outer transaction
        step_one()
        
        with transaction.atomic():  # Inner savepoint
            step_two()  # If this fails, only step_two is rolled back
        
        step_three()  # This still executes

def multi_database_operation():
    with transaction.atomic(using='primary'):
        # Operations on primary database
        primary_operation()
        
        with transaction.atomic(using='analytics'):
            # Operations on analytics database
            analytics_operation()

def conditional_operation():
    with transaction.atomic():
        result = risky_operation()
        if not result.is_valid():
            transaction.set_rollback(True)