Source code for ase2sprkkr.common.configuration_transaction

"""Transactional staging and committing of configuration changes."""

from __future__ import annotations

from types import TracebackType
from typing import Any, Callable, Dict, Optional, Sequence, Type, TYPE_CHECKING

from .backward_compatibility import ExceptionGroup
from .warnings import InvalidValuePolicy

if TYPE_CHECKING:
    from .configuration import Configuration as BaseConfiguration


[docs] class PostChangeHookError(RuntimeError, ExceptionGroup): """One or more post-change hooks failed after a successful commit.""" def __init__(self, message: str, exceptions: Sequence[Exception]) -> None: """Initialize the exception-group base explicitly for Python 3.8.""" ExceptionGroup.__init__(self, message, exceptions) def derive(self, exceptions: Sequence[Exception]) -> ExceptionGroup: """Create the same group type for the selected ``exceptions``.""" return type(self)(self.message, exceptions)
[docs] class ConfigurationTransaction: """Context manager for temporary configuration mutations. Staged objects hold their proposed state directly, so ordinary container traversal sees the complete proposal. A normal context exit commits all staged objects; an exceptional exit rolls them back in reverse order. Mutable values are the real objects. Their in-place mutations deliberately cannot be rolled back by this transaction. """
[docs] class _Boundary: """Change-stack marker and explicit savepoint context.""" def __init__(self, transaction: "ConfigurationTransaction") -> None: """Create an inactive boundary owned by ``transaction``.""" self._transaction = transaction self._active = False self._rollback_requested = False def __enter__(self) -> "ConfigurationTransaction._Boundary": if self._active: raise RuntimeError("The savepoint is already active") self._rollback_requested = False self._active = True transaction = self._transaction if not transaction._changes: transaction._container._active_transaction = transaction transaction._changes.append(self) return self def __exit__( self, exception_type: Optional[Type[BaseException]], exception: Optional[BaseException], traceback: Optional[TracebackType], ) -> bool: return self._transaction._leave( self, exception_type is not None or self._rollback_requested, )
[docs] def rollback(self): """Rollback changes registered since the savepoint was created.""" if not self._active: raise RuntimeError("The savepoint is not active") self._transaction._rollback_after(self) self._rollback_requested = True
[docs] def __init__( self, configuration: "BaseConfiguration", policy: Optional[InvalidValuePolicy] = None, ) -> None: """Create a transaction for ``configuration`` and its root tree. ``policy`` is shared by every staged value in a high-level mutation. When omitted, the transaction uses a strict policy for direct, low-level staging. """ self._container = configuration._get_root_container() if getattr(self._container, "_running_post_change_hooks", False): raise RuntimeError( "A configuration cannot be changed from its post-change hooks" ) self.policy = policy or InvalidValuePolicy( "set", retain_invalid="none", report_invalid="raise" ) self._defer_validation = policy is not None self._changes = []
[docs] @classmethod def current( cls, configuration: "BaseConfiguration" ) -> Optional["ConfigurationTransaction"]: """Return the active transaction for ``configuration``, if any.""" root = configuration._get_root_container() return getattr(root, "_active_transaction", None)
[docs] @classmethod def use( cls, configuration: "BaseConfiguration", policy: Optional[InvalidValuePolicy] = None, ) -> "ConfigurationTransaction": """Return a context for the transaction applicable to ``configuration``. An active transaction is entered as a nested savepoint; otherwise a new transaction is returned. A failed nested operation rolls back only its own changes unless its exception escapes the outer transaction. ``policy`` is used only when a new transaction is created; nested operations share the policy of the active transaction. """ transaction = cls.current(configuration) if transaction is not None: return transaction return cls(configuration, policy=policy)
[docs] def _finish_stage(self) -> None: """Report a standalone stage immediately. Transactions created directly are strict low-level transactions. A policy supplied by :meth:`Configuration._mutation` is reported only after the complete mutation, so its results can be aggregated. """ if self._defer_validation: return try: self.policy.report() finally: self.policy.results.clear()
def __enter__(self) -> "ConfigurationTransaction": self._Boundary(self).__enter__() return self def __exit__( self, exception_type: Optional[Type[BaseException]], exception: Optional[BaseException], traceback: Optional[TracebackType], ) -> bool: boundary = self._current_boundary() return self._leave( boundary, exception_type is not None or boundary._rollback_requested, )
[docs] def _leave( self, boundary: "ConfigurationTransaction._Boundary", rollback: bool, ) -> bool: """Close ``boundary``, rolling it back when ``rollback`` is true.""" self._require_active() outermost = self._changes[0] is boundary boundary._active = False hooks = None try: if rollback: self._rollback_after(boundary) if outermost: if not rollback: hooks = self._commit() finally: if outermost: self._changes.clear() self._container.__dict__.pop("_active_transaction", None) if hooks: self._run_hooks(hooks) return False
[docs] def _require_active(self) -> None: if not self._changes: raise RuntimeError( "A configuration transaction can only be used inside its " "active context manager" )
[docs] def push(self, change: Any) -> Any: """Push a staged change and return it; it must implement rollback.""" try: self._require_active() except Exception: change.rollback() raise self._changes.append(change) return change
[docs] def savepoint(self) -> "ConfigurationTransaction._Boundary": """Rollback newly registered changes if the enclosed operation fails.""" self._require_active() return self._Boundary(self)
[docs] def abort(self) -> None: """Roll back changes in the current transaction boundary.""" self._current_boundary().rollback()
[docs] def _current_boundary(self) -> "ConfigurationTransaction._Boundary": for change in reversed(self._changes): if isinstance(change, self._Boundary) and change._active: return change raise RuntimeError("The transaction has no active boundary")
[docs] def _rollback_after( self, boundary: "ConfigurationTransaction._Boundary" ) -> None: """Rollback changes above ``boundary``, leaving it active.""" while self._changes and self._changes[-1] is not boundary: change = self._changes.pop() if isinstance(change, self._Boundary): if change._active: raise RuntimeError( "A nested transaction boundary is still active" ) else: change.rollback() if not self._changes: raise RuntimeError("The transaction boundary is no longer active")
[docs] def _commit(self) -> Dict[Any, Callable[[Any], None]]: """Commit staged objects and collect their post-change hooks.""" hooks = {} while self._changes: changes = self._changes self._changes = [] for change in changes: if isinstance(change, self._Boundary): continue hook = change.commit() if hook: option, callback = hook hooks[option] = callback return hooks
[docs] def _run_hooks(self, hooks: Dict[Any, Callable[[Any], None]]) -> None: """Run registered ``hooks`` after closing the transaction.""" errors = [] self._container._running_post_change_hooks = True try: for option, hook in hooks.items(): try: hook(option) except Exception as error: errors.append(error) finally: self._container.__dict__.pop("_running_post_change_hooks", None) if errors: raise PostChangeHookError( "Configuration was already committed, but post-change hooks failed", errors, )
def __repr__(self) -> str: return f"<Configuration transaction for {self._container}>"