Carthage Setup Tasks Module

class carthage.setup_tasks.PathMixin(**kwargs)

Provide the commond stamp_path(), log_path(), and state_path(). Requires that subclasses fill in stamp_subdir.

Also provides config_layout.

log_path()

A place to store logs.

stamp_path()

A place to store cached information like completion stamps for setup tasks. Removing config.cache_dir may decrease performance but should not remove hard-to-recover state like keys.

property stamp_subdir

The part of stamp_path() after config.stamp_dir. For example for a podman container called example.com this might be podman/containers/example.com

state_path()

A place to store state that should be preserved like keys, tokens, or assignment databases.

class carthage.setup_tasks.SetupTaskMixin(*args, **kwargs)
async async_ready()

This may need to be overridden, but is provided as a default

check_stamp(stamp, raise_on_error=False)
Returns:

a tuple containing the unix time of the stamp and the text contents of the stamp. The first element of the tuple is False if the stamp does not exist

classmethod class_setup_tasks()

returns a tuple of TaskWrapperBases associated with cls. Handles MRO and methods overriding tasks. This is a relatively expensive operation, so it is memoized per class.

classmethod inspect_class_setup_tasks()

Iterates over all the setup tasks that instances of this class will have and provides an inspector for that task.

inspect_setup_tasks(*, stamp_stem='', instance_id=None)

Iterates over the setup tasks of a ninstance and provides an inspector that can determine if a task would run and what its description is.

readonly()

If bool(readonly), then automated Carthage functions should not disturb the real state of the object:

  • run_setup_tasks will not run setup tasks

  • The deployment engine will not deploy or destroy the object

  • Carthage plugins should not create the object.

Explicit calls to methods like delete() or do_create() will still affect the state of the object.

By default, readonly looks up InjectionKey('readonly') in the object’s injector, and returns False if that injection key is not provided. As a consequence:

  • Setting readonly in the class body of a modeling object affects readonly for that object and any object that inherits from its injector.

  • Setting readonly in a non-modeling class body sets the default readonly state for objects of that class and detaches those objects from looking at their injectors to determine readonly. This should generally be avoided as it produces surprising behavior.

  • Setting readonly on an instance sets the readonly state for that object and detaches the object from tracking injectors.

  • Setting the readonly injection key on an injector affects objects downstream of that object that have not already cached their readonly state.

async run_setup_tasks(context=None)

Run the set of collected setup tasks. If context is provided, it is used as an asynchronous context manager that will be entered before the first task and eventually exited. The context is never entered if no tasks are run. This execution context is different from SetupTaskContext. The SetupTaskContext is an introspection mechanism that tracks which setup task is running and why; the asynchronous context allows a set of tasks for example in a customization to have common resources available.

setup_task_event_keys()

Yield the set of keys that setup_task related events should be dispatc should be dispatched to. In addition to keys yi.yielded by this generator, all setup tasks events are dispatched to InjectionKey(SetupTaskMixin).

exception carthage.setup_tasks.SkipSetupTask
class carthage.setup_tasks.TaskWrapper(func, **kwargs)
class carthage.setup_tasks.cross_object_dependency(task, relationship, **kwargs)

Usage:

# in a client machine's class
fileserver_dependency = cross_object_dependency(FileServer.update_files, 'fileserver')
Parameters:

  • task – a TaskWrapper, typically associated with another class, or alternatively the name of an attribute on relationship containing either a TaskWrapper or TaskMethod.

  • relationship – The string name of a relationship such that calling the relationship method on an instance containing this dependency will yield the instance containing task that we want to depend on.

A cross object dependency will invalidate later tasks in this object if the depended on task has run more recently than these tasks. That is in the example above, if the fileserver’s update_files task has run more recently than this object’s setup_tasks, then re-run this object’s setup_tasks.

Compare to TaskWrapper.depend_on(), which guarantees that when a particular task is running, certain dependencies are available.

carthage.setup_tasks.install_mako_task(relationship, cross_dependency=True, *, relationship_ready=True)
Parameters:

relationship –

The name of an attribute property containing mako_tasks in its setup_tasks().

param cross_dependency:

If true (the default), rerun the installation whenever any of the underlying mako_tasks change.

param relationship_ready:

Bring the relationship to async_become_ready state before installing mako tasks or checking cross-object dependencies. Bringing the relationship to ready state allows the hash block in the mako template to access parts of the instance that are set up as part of bringing the instante to ready. It also guarantees that the mako templates will be generated at least once. However, it can produce dependency loops that hang Carthage in some circumstances.

This task is generally associated on a machine to install mako templates rendered on the model. Typical usage might look like:

install_mako = install_mako_task('model')

class carthage.setup_tasks.mako_task(template, output=None, **injections)

Usage:

dnsmasq_task = mako_task('dnsmasq.conf.mako',
    network = InjectionKey("some_network"))

Typically used in a MachineModel. Introduces a setup task to render a mako template. Extra keyword arguments can be InjectionKey in which case they are instantiated in the context of the injector of the object to which the setup task is attached. These arguments are made available in the mako template context. The instance template context argument is introduced and points to the object on which the setup task is run. Arguments that are not InjectionKeys are passed directly to the template.

If the template has a def called hash, this def will be rendered with the same arguments as the main template body. This value will be stored in the completion stamp; if the hash changes, the template will be re-rendered. For performance reasons, try to keep the hash easy to compute.

carthage.setup_tasks.setup_task(description, *, order=None, before=None)

Mark a method as a setup task. Describe the task for logging. Must be in a class that is a subclass of SetupTaskMixin. Usage:

@setup_task("unpack"
async def unpack(self): ...
Parameters:

  • order – Overrides the order in which tasks are run; an integer; lower numbered tasks are run first, higher numbered tasks are run later. It is recommended that task ordering be a total ordering, but this is not a requirement. It is an error if both order and before are set.

  • before – Run this task before the task referenced in before.