API

Core modules

class opslib.components.Component(**kwargs)

The basic building block to define the stack. See Components.

add_commands(cli)

Called when the CLI is constructed. Override this method to add custom commands.

Parameters:

cli – A ComponentGroup that represents the CLI of this component.

build()

Called when the component is attached to a parent. Override this method to add sub-components.

class opslib.components.Stack(import_name=None, stateroot=None, **kwargs)

Bases: Component

opslib.components.walk(component)

Iterate depth-first over all child components. The first item is component itself.

class opslib.props.Prop(type, default=<object object>, lazy=False)

The Prop class is the definition of a component Prop. See Props.

Parameters:

  • type – The type that the value must match.

  • default – Default value if the prop is not specified. Falls back to None if not specified.

  • lazy – If True, the value may be Lazy, and its type will be checked when it’s evaluated.

class opslib.props.InstanceProps(instance, kwargs)

The InstanceProps class is a container for instance props (see Props). Typically it’s found as the .props attribute of a Component instance. The props themselves are attributes of this object.

class opslib.lazy.Lazy(func, *args, **kwargs)

A Lazy object wraps a value that will be available at a later time.

When evaluated, it invokes its arguments as func(*args, **kwargs), caches the result and returns it.

class opslib.lazy.NotAvailable

Bases: KeyError

The NotAvailable exception indicates that the requested Lazy value depends on some data that is not available at this time.

opslib.lazy.evaluate(ob)

Evaluate Lazy objects and return the result. If invoked with a non-Lazy argument, it traverses nested lists and dictionaries, making copies of them, and evaluating any Lazy values inside.

opslib.lazy.lazy_property(func)

Similar to @property, makes a method function like an instance property. When the property is retrieved, it returns a Lazy object, that invokes the method when evaluated.

class opslib.operations.Operation(**kwargs)

The Operation class represents an operation to be performed on a selection of Component objects.

Parameters:

  • dry_run – If True, the operation will not have effects on the target, just show what would change.

  • deploy – If True, apply changes to the target. May be combined with dry_run.

  • refresh – If True, inspect the state of the target and save it in local state.

  • destroy – If True, destroy the target resource.

opslib.operations.apply(component, **kwargs)

Apply the specified operation on component. It will also be applied recursively, depth-first, to all child components.

The order differs depending on the operation. For refresh and deploy, children are processed first. For destroy, the parent component is processed first, then its children.

Parameters:

  • component – The Component on which to apply the operation.

  • kwargs – Keyword arguments are forwarded to Operation.

class opslib.results.Result(changed=False, output='', failed=False)

The Results class wraps the outcome and output of an operation.

Variables:

  • changed – True if the operation changed anything.

  • output – Textual output.

  • failed – True if the operation ended in failure.

raise_if_failed(*args)

Check if the failed flag is set, and if so, raises OperationError.

Parameters:

args – Arguments to be passed to OperationError.

class opslib.results.OperationError(*args, result)

Exception raised when an operation fails.

Variables:

result – The operation’s Result, useful to figure out what went wrong.

class opslib.local.LocalRunResult(completed, encoding=None)

Bases: Result

The result of a call to run(). In addition to the fields inherited from Result, it contains the following:

Variables:

  • completed – Exit code of the subprocess.

  • stderr – Standard error from the subprocess (str).

  • stdout – Standard output from the subprocess (str).

opslib.local.run(*args, input=None, capture_output=True, encoding='utf8', extra_env=None, exit=False, check=True, exec=False, **kwargs)

The run function is a thin wrapper around subprocess.run(). It captures output and exit code and returns them as a LocalRunResult object.

Parameters:

  • input – Content to send to stdin (optional).

  • capture_output – Capture stdout and stderr. Enabled by default.

  • encoding – Text encoding for stdin, stdout and stderr. Defaults to "utf8". Set to None to disable encoding and use raw bytes.

  • extra_env – A dictionary of environment variables to send to the subprocess, in addition to the ones in os.environ.

  • exit – If set, when the subprocess is complete, call sys.exit() with the subprocess exit code. Useful when wrapping commands for the CLI.

  • check – If True (default), when the subprocess exits with an error code, raise OperationError.

  • exec – Instead of calling subprocess.run(), invoke the command using os.execvpe(). This will replace the current program with the new one. Useful when wrapping commands for the CLI.

opslib.cli.get_main_cli(get_stack)

Create a click.Group for the given stack.

Parameters:

get_stack – Callable that returns a Stack.

opslib.cli.main()

Main entry point for the opslib CLI command. It tries to run import stack and expects to find a stack named stack.stack, which it sends to get_main_cli().

The OPSLIB_STACK environment variable can be set to import something other than stack.

class opslib.cli.ComponentGroup(name=None, commands=None, **attrs)

Bases: Group

forward_command(*args, **kwargs)

A specialized click.Group.command() for commands that invoke another command. Any unprocessed arguments are sent as an args tuple, to be forwarded to the other command. It’s equivalent to the following:

@cli.command(
    context_settings=dict(
        ignore_unknown_options=True,
        allow_interspersed_args=False,
    )
)
@click.argument("args", nargs=-1, type=click.UNPROCESSED)
def foo(args):
    print("foo called with:", args)

Batteries

class opslib.places.BaseHost(**kwargs)

Abstract component for a host.

add_commands(cli)

Called when the CLI is constructed. Override this method to add custom commands.

Parameters:

cli – A ComponentGroup that represents the CLI of this component.

ansible_action(**props)

Shorthand function that returns an AnsibleAction component with hostname and ansible_variables set from this host. Keyword arguments are forwarded as props to AnsibleAction.

command(**props)

Shorthand function that returns a Command component with host set to this host. Keyword arguments are forwarded as props to the Command.

directory(path, **props)

Shorthand function that returns a Directory component with host set to this host. Keyword arguments are forwarded as props to the Directory.

file(**props)

Shorthand function that returns a File component with host set to this host. Keyword arguments are forwarded as props to the File.

sudo()

Returns a copy of this host that has the with_sudo flag set. This means that commands will be run using sudo, and Ansible will be invoked with become=True.

class opslib.places.LocalHost(**kwargs)

Bases: BaseHost

The local host on which opslib is running. It receives no props.

Variables:

  • hostname – Set to localhost.

  • ansible_variables – Two variables are set: ansible_connection is local; ansible_python_interpreter is set to sys.executable.

run(*args, **kwargs)

Run a command on the local host. If args is empty, it defaults to a single argument, $SHELL.

It invokes run() with the arguments.

class opslib.places.SshHost(**kwargs)

Bases: BaseHost

Connect to a remote host over SSH. Most props configure how the ssh subcommand is invoked. If you have already configured the host in ~/.ssh/config, it’s enough to specify hostname, as you would in the terminal.

Parameters:

  • hostname – Name of the remote host.

  • username – Username to log in.

  • port – Port number.

  • private_key_file – Path to an SSH identity file to be used for authentication.

  • config_file – SSH configuration file to use instead of ~/.ssh/config.

  • interpreter – Python interpreter to be used by Ansible. Set as the ansible_python_interpreter variable. Defaults to "python3".

run(*args, **kwargs)

Run a command on the remote host.

It uses run() to invoke ssh with the given arguments.

class opslib.places.Directory(**kwargs)

The Directory component creates a directory on the host.

Parameters:

  • host – The parent host.

  • path – Absolute path of the directory.

  • mode – Unix file permissions (optional).

  • owner – The name of the user owning the directory (optional).

  • group – The name of the group owning the directory (optional).

__truediv__(name)

Same as subdir().

command(**props)

Shorthand function that returns a Command component with cwd set to this directory and host set to this host. Keyword arguments are forwarded as props to the Command.

file(name, **kwargs)

Shorthand function that returns a File with the same host, and the path being a child path of self.path.

run(*args, **kwargs)

Run a command inside this directory. If args is empty, it defaults to a single argument, $SHELL.

It invokes run() with the arguments.

subdir(name, **kwargs)

Shorthand function that returns a Directory with the same host, and the path being a child path of self.path.

class opslib.places.File(**kwargs)

The File component creates a regular file on the host.

Parameters:

  • host – The parent host.

  • path – Absolute path of the file.

  • content – Content to write to the file. May be str or bytes. May be Lazy.

  • mode – Unix file permissions (optional).

  • owner – The name of the user owning the directory (optional).

  • group – The name of the group owning the directory (optional).

class opslib.places.Command(**kwargs)

The Command component represents a command that should be run on the host during deployment.

Parameters:

  • host – The parent host.

  • cwd – Optional Path where command should run.

  • args – Command arguments array. The first argument is the command itself. Defaults to [], which invokes the shell, useful with the input parameter.

  • input – Content to be sent to standard input. Defaults to no input.

  • run_after – A list of components that trigger this command to be run. If empty, the command will always be run, otherwise it will run once, and then only run after one of the components changes.

run(**kwargs)

Run the command defined by this component.

Parameters:

kwargs – Extra keyword arguments to be forwarded to the run method of the host.

class opslib.ansible.AnsibleAction(**kwargs)

The AnsibleAction component executes an Ansible module.

Parameters:

  • host – BaseHost to act on.

  • module – Name of the Ansible module to invoke, e.g. "ansible.builtin.copy".

  • args – Dictionary of arguments for the module. Consult each module’s documentation for the args (or Parameters) it supports.

  • format_output – Optional callback used to format the result output. If provided, it will be called with a single parameter, the AnsibleResult object; its return value will be used to overwrite the output attribute of the result.

run(check=False)

Call run_ansible() with the action defined by this component.

class opslib.ansible.AnsibleResult(data, failed)

The result of an AnsibleAction, or a call to run_ansible(). In addition to the fields inherited from Result, it contains the following:

Variables:

  • data – The original result object reported by Ansible. The format varies quite a bit from module to module.

  • exception – If the action failed, this contains the stack trace from Ansible, as str.

  • msg – If the action failed, this contains the error message from Ansible.

  • stdout – The stdout field from data.

  • stderr – The stderr field from data.

opslib.ansible.run_ansible(hostname, ansible_variables, action, check=False)

Invoke Ansible with a single action. This creates and executes an Ansible Play, with a single host, and a single task that contains the given action. Returns an AnsibleResult object.

Instead of directly calling this function, typically one would create an AnsibleAction in the stack, but it’s usable directly if need be. It encapsulates all setup and teardown of the Ansible machinery and exposes only the essential arguments.

Parameters:

  • hostname – Name of the host to act on.

  • ansible_variables – List of variables to configure Ansible.

  • action – The Ansible action. It should be a dictionary with members module and args.

  • check – If True, run Ansible in “check” mode, which will not apply any changes, just show differences.

class opslib.terraform.TerraformProvider(**kwargs)

The TerraformProvider component represents a Provider in the Terraform universe. After a provider is defined, TerraformResource components can be created from it.

Parameters:

  • name – The name of the provider, e.g. "aws".

  • source – Provider source, e.g. "hashicorp/aws".

  • version – Version requirement, e.g. "~> 4.0" (optional but highly recommended).

  • config – Provider configuration (optional). Most providers require some level of configuration, although it can sometimes be set through environment variables; consult each provider’s documentation for details.

data(**props)

Shorthand method to create a TerraformDataSource, with provider set to this component.

resource(**props)

Shorthand method to create a TerraformResource, with provider set to this component.

class opslib.terraform.TerraformResource(**kwargs)

The TerraformResource component creates a single Resource through Terraform.

Parameters:

  • provider – The TerraformProvider for this resource. Technically optional because some builtin resource types of Terraform don’t belong to any provider.

  • type – Type of resource, e.g. "aws_vpc".

  • args – Arguments of the resource (dict). Consult the provider’s documentation for the arguments supported by each resource. May be Lazy.

  • output – List of attributes exported by the resource to be fetched from Terraform. They are available on the output property. (optional)

import_resource(resource_id)

Import an existing resource into Terraform.

property output

Output values returned from Terraform.

run(*args, terraform_init=True, **kwargs)

Run the terraform command with the given arguments.

class opslib.terraform.TerraformDataSource(**kwargs)

The TerraformDataSource component retrieves data through a Terraform data source.

Parameters:

  • provider – The TerraformProvider for this data source. Technically optional because some builtin data source types of Terraform don’t belong to any provider.

  • type – Type of data source, e.g. "aws_vpc".

  • args – Arguments of the data source (dict). Consult the provider’s documentation for the arguments supported by each data source. May be Lazy.

  • output – List of attributes exported by the data source to be fetched from Terraform. They are available on the output property. (optional)

property output

Output values returned from Terraform.

run(*args, terraform_init=True, **kwargs)

Run the terraform command with the given arguments.

class opslib.terraform.TerraformResult(tf_result)

The result of an invocation of terraform. In addition to the fields inherited from Result, it contains the following:

Variables:

tf_result – The original LocalRunResult of invoking the terraform command.