operations.api

Provides API to define operations.

class api.OperationError

An exception that indicates an error while executing an operation.

class api.OperationResult

Stores the result of an operation.

Attributes

attr success

success: bool

Whether the operation succeeded.

attr changed

changed: bool

Whether the operation changed something.

attr initial

initial: dict[str, Any]

The initial state of the host.

attr final

final: dict[str, Any]

The final state of the host.

attr failure_message

failure_message: Optional[str] = None

The failure message, if success is False.

class api.Operation

This class is used to ease the building of operations with consistent output and state tracking.

Attributes

attr internal_use_only

internal_use_only: 'Operation' = cast('Operation', None)

operation's op variable is defaulted to this value to indicate that it must not be given by the user.

def Operation.nested()

def Operation.nested(self, has_nested: bool) -> None:

Sets whet this operation spawns nested operations. In this case, this operation will not have separate state, and the printing will be handled differently.

Parameters

• has_nested: Whether the operation has nested operations.

def Operation.add_nested_result()

def Operation.add_nested_result(self, key: str, result: OperationResult
                                ) -> None:

Adds initial and final state of a nested operation under the given key into this operation's state dictionaries.

Parameters

• key: The key under which to add the nested result.

• result: The result to add.

def Operation.desc()

def Operation.desc(self, description: str) -> None:

Sets the description of the operation, and prints an early status via the logger.

Parameters

• description: The new description.

def Operation.defaults()

def Operation.defaults(self, *args: Any, **kwargs: Any
                       ) -> RemoteDefaultsContext:

Sets defaults on the current script. See ScriptWrapper.defaults().

def Operation.initial_state()

def Operation.initial_state(self, **kwargs: Any) -> None:

Sets the initial state.

def Operation.final_state()

def Operation.final_state(self, **kwargs: Any) -> None:

Sets the final state.

def Operation.unchanged()

def Operation.unchanged(self, ignore_none: bool = False) -> bool:

Checks whether the initial and final states differ.

Parameters

• ignore_none: Set to True to not count states where the final value is None.

Returns

• bool: Whether the states differ.

def Operation.changed()

def Operation.changed(self, key: str) -> bool:

Checks whether a specific key will change.

Parameters

• key: The key to check for changes.

Returns

• bool: Whether the states differ.

def Operation.diff()

def Operation.diff(self, file: str, old: Optional[bytes], 
                   new: Optional[bytes]) -> None:

Adds a file to the diffing output.

Parameters

• file: The filename which the diff belongs to.

• old: The previous content or None if the file didn't exist previously.

• new: The new content or None if the file was deleted.

def Operation.failure()

def Operation.failure(self, msg: str) -> OperationResult:

Returns a failed operation result.

Returns

• OperationResult: The OperationResult for this failed operation.

def Operation.success()

def Operation.success(self) -> OperationResult:

Returns a successful operation result.

Returns

• OperationResult: The OperationResult for this successful operation.

Functions

def api.operation()

def api.operation(op_name: str):

Operation function decorator.