uPlaybook Internals

Internal uPlaybook objects and methods.

These objects and methods typically are used by task developers, though some may be usful for reference by users. These are typically not used directly by end-users, though other parts of the documentation may refer to these classes.

CallDepth

A context manager to increment the call depth when one task calls another task.

Exit

Bases: Exception

The exception raised to exit a playbook early.

Failure

Bases: Exception

The default exception raised if a task fails.

PasswordNeeded

Bases: Exception

An exception which indicates a password is unavailable for decrypting input files.

RawStr

Bases: str

A subclass of str which is not to have Jinja2 template expansion.

Return

A return type from tasks to track success/failure, display status, etc...

This can be used as a context manager if a context_manager function is provided. See fs.cd() for an example.

It can also be used as a boolean, to check success/failure (needs ignore_failure, or failure will raise exception). See core.run() for an exaple.

Parameters:

Name	Type	Description	Default
changed	bool	If True, mark the task as having changed system state. (bool)	required
failure	bool	If True, mark the task as having failed. (optional, bool)	False
success	Optional[bool]	Was the action successful, meaning trigger handlers and if used in an if statement will it evaluate True? If not specified, it defaults to changed. Otherwise, it overrides changed. For situations where no change is made, but the operation should notify handlers and compare True in an if statement. (optional, bool, default None)	None
ignore_failure	bool	If True, failure is not considered fatal, execution can continue on. (bool, default False)	False
extra_message	Optional[str]	An extra message to display in the status line in parens (optional, str)	None
output	Optional[str]	Output of the task to display, for example stdout of a run command. (optional, str)	None
hide_args	bool	If true, do not display any arguments names/values. Useful for debug() which doesn't need to show the message in the status line as well as the output. (bool, default=False)	False
secret_args	set	Arguments that have secrets in them, so obscure the value. (optional, set)	set()
extra	Optional[SimpleNamespace]	Extra data to be returned to the caller, as a types.SimpleNamespace(), for example run() will return exit code and stderr as extra. (optional, types.SimpleNamespace())	None
raise_exc	Optional[Exception]	Raise this exception after handling the return. If failure=True, this exception will be raised, if not specified a Failure() exception will be raised. (optional, Exception())	None
context_manager	Optional[Callable]	This type can optionally behave as a Context Manager, and if so this function will be called with no parameters at the end of the context. Use a closure if you want to associate data with the function call ("lambda: function(args)"). (optional, Callable).	None

Examples:

Return(changed=True)
Return(changed=False)
Return(changed=True, extra_message="Permissions")
Return(changed=True, extra=SimpleNamespace(stderr=s))
Return(changed=True, context_manager=lambda: f(arg))

__bool__()

If checked for truthfulness, return True if not failure.

__enter__()

Begin a context if used as a context manager.

Raises:

Type	Description
AttributeError	if no context_manager was specified.

Returns:

Type	Description
Return	The Return() object, so it can be used as "with fn() as return_obj:"

__exit__(*_)

End the context if used as a context manager.

This will call the context_manager function if it is given.

__repr__()

Format this object for display.

notify(handler)

Register a handler function to call if changed.

Parameters:

Name	Type	Description	Default
handler	Union[Callable, List]	A function or a list of functions to register for calling later, if the task has changed the system. (callable or list)	required

print_status()

Display the output and status of the task.

TemplateStr

Bases: str

A subclass of str to mark what arguments of a task are templated.

UnqualifiedArgumentError

Bases: Exception

An argument was passed without a "keyword=".

UpContext

A singleton object for storing and managing context data.

add_handler(fn)

Add a notify function.

context_pop()

Remove the most recent context from the context stack.

context_push(ctx)

Push a context onto the context stack.

flush_handlers()

Run all the handler functions.

get_env(env_in=None)

Returns the jinja template environment

ignore_failures()

Is ignore_failures mode active?

PlatformInfo()

See Platform Info in docs/templating.md for more information.

calling_context(func)

Decorator to save off the calling function namespace into up_context.calling_context.

This decorator saves off the namespace of the function that calls the wrapped function for later use by templating.

Parameters:

Name	Type	Description	Default
func	Callable	The function to be wrapped.	required

find_file(filename)

Finds and returns the path of a template/file.

This function uses a colon-separated search path, either gotten from the UP_FILES_PATH environment variable or the default. "..." specified in the search path is relative to the directory the playbook is found in.

Returns: Path: The path of the found template file.

Raises: FileNotFoundError: If the template file is not found in the search paths.

import_script_as_module(module_name, paths_to_try)

Imports a Python script as a module, whether it ends in ".py" or not. Given the name of a module to import, and a list of absolute or relative path names (including the filename), import the module. The module is set up so that it can later be imported, but a reference to the module is also returned.

Parameters:

Name	Type	Description	Default
module_name	str	The name of the module to import. This doesn't have to match the filename.	required
paths_to_try	List[str]	A list of file paths to look for the file to load. This can be absolute or relative paths to the file, the first file that exists is used.	required

Returns:

Name	Type	Description
Module	ModuleType	A reference to the imported module.

Raises:

Type	Description
FileNotFoundError	If the module file is not found in any of the specified directory paths.
ImportError	If there are issues importing the module, such as invalid Python syntax in the module file.

Example

my_module = import_script_as_module("my_module", ["my_module", "../my_module"])

Now you can either directly use "my_module"

my_module.function()

Or you can later import it:

import my_module

task(func)

A decorator for tasks, combines @calling_context and @template_args

template_args(func)

Decorator to pre-processes arguments to the function of type TemplateStr through Jinja.

If an argument has a type annotation of TemplateStr this decorator will treat the string value of that argument as a Jinja2 template and render it. The resulting value (after rendering) is then passed to the wrapped function.

Parameters:

Name	Type	Description	Default
func	Callable	The function to be wrapped.	required

Returns:

Name	Type	Description
Callable	Callable[..., Any]	The wrapped function with potentially modified arguments.

Usage: @template_args def example_function(a: Union[TemplateStr, str]): print(a)

example_function("Hello {{ 'World' }}") # Outputs: "Hello World"