freckles

This is the documentation of freckles.

Contents

License

The Parity Public License 6.0.0

Contributor: Markus Binsteiner

Source Code: https://gitlab.com/freckles-io/freckles

This license lets you use and share this software for free, as long as you contribute software you make with it. Specifically:

If you follow the rules below, you may do everything with this software that would otherwise infringe either the contributor’s copyright in it, any patent claim the contributor can license, or both.

  1. Contribute changes and additions you make to this software.
  2. If you combine this software with other software, contribute that other software.
  3. Contribute software you develop, deploy, monitor, or run with this software.
  4. Ensure everyone who gets a copy of this software from you, in source code or any other form, gets the text of this license and the contributor and source code lines above.
  5. Do not make any legal claim against anyone accusing this software, with or without changes, alone or with other software, of infringing any patent claim.

To contribute software, publish all its source code, in the preferred form for making changes, through a freely accessible distribution system widely used for similar source code, and license contributions not already licensed to the public on terms as permissive as this license accordingly.

You are excused for unknowingly breaking 1, 2, or 3 if you contribute as required, or stop doing anything requiring this license, within 30 days of learning you broke the rule.

As far as the law allows, this software comes as is, without any warranty, and the contributor will not be liable to anyone for any damages related to this software or this license, for any kind of legal claim.

Contributors

Changelog

Version 0.9 (Upcoming)

  • first release of freckles

freckles

freckles package

Subpackages
freckles.adapters package
Subpackages
freckles.adapters.freckles package
Submodules
freckles.adapters.freckles.freckles_adapter_freckles module
class freckles.adapters.freckles.freckles_adapter_freckles.FrecklesAdapterFreckles(name, context)[source]

Bases: freckles.adapters.adapters.FrecklesAdapter

get_extra_frecklets()[source]
get_folders_for_alias(alias)[source]
get_resources_for_task(task)[source]

Return a map of paths to all resources that are necessary for this task.

get_supported_resource_types()[source]
get_supported_task_types()[source]

Return a list of supported frecklet types to run.

prepare_execution_requirements(run_config, parent_task)[source]

Prepares all external dependencies that are needed for this adapter to successfully run an execution.

Should throw an exception if it fails.

Returns:a version indicator
Return type:int
run(tasklist, run_vars, run_config, run_secrets, run_env, result_callback, parent_task)[source]
Module contents
freckles.adapters.shell package
Submodules
freckles.adapters.shell.freckles_adapter_shell module
class freckles.adapters.shell.freckles_adapter_shell.FrecklesAdapterShell(name, context)[source]

Bases: freckles.adapters.adapters.FrecklesAdapter

get_extra_frecklets()[source]
get_folders_for_alias(alias)[source]
get_processor(proc_name)[source]
get_resources_for_task(task)[source]

Return a map of paths to all resources that are necessary for this task.

get_supported_resource_types()[source]
get_supported_task_types()[source]

Return a list of supported frecklet types to run.

prepare_execution_requirements(run_config, parent_task)[source]

Prepares all external dependencies that are needed for this adapter to successfully run an execution.

Should throw an exception if it fails.

Returns:a version indicator
Return type:int
run(tasklist, run_vars, run_config, run_secrets, run_env, result_callback, parent_task)[source]
shell_adapter_contex
class freckles.adapters.shell.freckles_adapter_shell.ScriptlingContext(context_name, cnf, repos)[source]

Bases: object

scriptling_index
freckles.adapters.shell.processors module
class freckles.adapters.shell.processors.ShellCommandProcessor[source]

Bases: freckles.adapters.shell.processors.ShellTaskTypeProcessor

process_task(task)[source]

Takes a task description, returns a list of shell script parts incl. optional external dependencies.

class freckles.adapters.shell.processors.ShellScriptProcessor(scriptling_index)[source]

Bases: freckles.adapters.shell.processors.ShellTaskTypeProcessor

get_all_dependency_functions(functions, scriptling_name, result=None)[source]
process_task(task)[source]

Takes a task description, returns a list of shell script parts incl. optional external dependencies.

class freckles.adapters.shell.processors.ShellScriptTemplateProcessor[source]

Bases: freckles.adapters.shell.processors.ShellTaskTypeProcessor

process_task(task)[source]

Takes a task description, returns a list of shell script parts incl. optional external dependencies.

class freckles.adapters.shell.processors.ShellTaskTypeProcessor[source]

Bases: object

process_task(task)[source]

Takes a task description, returns a list of shell script parts incl. optional external dependencies.

freckles.adapters.shell.shell_runner module
class freckles.adapters.shell.shell_runner.ShellRunner[source]

Bases: object

render_environment(run_env_dir, tasklist, skip_exodus=True)[source]
run(run_properties, run_cnf, result_callback, parent_task, delete_env=False)[source]
Module contents
Submodules
freckles.adapters.adapters module
class freckles.adapters.adapters.FrecklesAdapter(adapter_name, context, config_schema, run_config_schema)[source]

Bases: object

config(*overlays)[source]
config_value(key)[source]
context
get_extra_frecklets()[source]
get_folders_for_alias(alias)[source]
get_resources_for_task(task)[source]

Return a map of paths to all resources that are necessary for this task.

get_supported_resource_types()[source]
get_supported_task_types()[source]

Return a list of supported frecklet types to run.

name
prepare_execution_requirements(run_config, parent_task)[source]

Prepares all external dependencies that are needed for this adapter to successfully run an execution.

Should throw an exception if it fails.

Returns:a version indicator
Return type:int
run(tasklist, run_vars, run_config, run_secrets, run_env, result_callback, parent_task)[source]
run_config(*overlays)[source]
run_config_value(key)[source]
set_resource_folder_map(resource_folders)[source]
freckles.adapters.adapters.create_adapter(adapter_name, context)[source]

Loading a dictlet finder extension.

Returns:the extension manager holding the extensions
Return type:ExtensionManager
Module contents
freckles.context package
Submodules
freckles.context.config module
class freckles.context.config.ContextConfig(alias, config_chain=None, extra_repos=None, use_community=False, config_unlocked=False)[source]

Bases: object

add_cnf_interpreter(interpreter_name, schema)[source]
cnf
config(interpreter_name, *overlays)[source]
config_unlocked
config_value(key, interpreter_name=None)[source]
class freckles.context.config.ContextConfigTingCast[source]

Bases: ting.ting_cast.TingCast

A TingCast to create freckles profiles by reading yaml files.

CNF_PROFILE_ATTRIBUTES = [<ting.ting_attributes.FileStringContentAttribute object>, <ting.ting_attributes.FrontmatterAndContentAttribute object>, <ting.ting_attributes.ValueAttribute object>, <ting.ting_attributes.DictContentAttribute object>]
class freckles.context.config.ContextConfigs(repo_name, tingsets, cnf, **kwargs)[source]

Bases: ting.tings.TingTings

A class to manage freckles profiles.

This reads all ‘*.profile’ files in the freckles config folder. Those are later used to create a freckles context (per profile). It also checks whether there exists a ‘default.profile’ file with the ‘accept_freckles_license’ value set to ‘true’. Only if that is the case will it allow custom profiles (mainly for security reasons - the user should explicitely accept that certain configurations can be insecure).

DEFAULT_TING_CAST

alias of ContextConfigTingCast

create_context_config(context_name, config_chain=None, extra_repos=None, use_community=False)[source]
classmethod load_configs()[source]
freckles.context.freckles_context module
class freckles.context.freckles_context.FrecklesContext(context_name, config)[source]

Bases: object

adapters
add_config_interpreter(interpreter_name, schema)[source]
add_dynamic_frecklet(path_or_frecklet_content, validate=False, check_path=True)[source]
augment_repo(repo_orig)[source]
augment_repos(repo_list)[source]
callbacks
check_repo(repo)[source]
config(interpreter_name, *overlays)[source]
config_value(key, interpreter_name=None)[source]
context_name
create_frecklecutable(frecklet_name, only_from_index=True)[source]
create_run_environment(adapter, env_dir=None)[source]
download_repo(repo, task_parent)[source]
ensure_local_repos(repo_list)[source]
execute_external_command(command, args=None, parent_task=None)[source]
frecklet_index
frkl_pkg
get_frecklet(frecklet_name, validate=False)[source]
get_frecklet_names()[source]
load_frecklet(frecklet_full_path_or_name_or_content, validate=False)[source]

Loads a frecklet.

First, checksi if argument is a path and exists. If that is the case, uses that to create the frecklet. If not, tries to find a frecklet with the provided name. If that doesn’t exists either, it tries to interprete the string as frecklet content.

save_run_info_file(new_data=None)[source]

Save the run info file, optionally merge it with new data beforehand.

Parameters:new_data (dict) – new data to be merged on top of current dict, will be ignored if None
unlock_config(user_accepts=False, use_community=False, save=True)[source]
update_pull_cache(path)[source]
update_repos(force=False, timeout=-1)[source]
freckles.context.freckles_context.startup_housekeeping()[source]
Module contents
freckles.frecklet package
Submodules
freckles.frecklet.arguments module
class freckles.frecklet.arguments.CliArgumentsAttribute(target_attr_name='cli_arguments', source_attr_name='vars_frecklet')[source]

Bases: ting.ting_attributes.TingAttribute

CLICK_CEREBUS_ARG_MAP = {'boolean': <class 'bool'>, 'dict': <frutils.parameters.VarsTypeSimple object>, 'float': <class 'float'>, 'integer': <class 'int'>, 'password': <class 'str'>, 'string': <class 'str'>}
DEFAULT_CLI_SCHEMA = {'param_type': 'option', 'show_default': True}
create_parameter(var_name, var)[source]
get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.arguments.VariablesAttribute(target_attr_name='vars_frecklet', default_argument_description=None)[source]

Bases: ting.ting_attributes.TingAttribute

consolidate_vars(vars_tree, ting)[source]
get_attribute(ting, attribute_name=None)[source]
get_vars_from_path(path_to_leaf, tree, ting)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

resolve_vars(current_args, rest_path, last_node, tree, ting)[source]
class freckles.frecklet.arguments.VariablesFilterAttribute(source_attr_name='vars_frecklet', target_attr_name='vars_required', required=True)[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

freckles.frecklet.describe module
freckles.frecklet.describe.create_auto_vars(params, existing_vars={}, frecklet=None)[source]
freckles.frecklet.describe.describe_frecklet(context, frecklet, vars, auto_vars=False)[source]
freckles.frecklet.describe.print_task_descriptions(task_desc_list)[source]
freckles.frecklet.doc module
class freckles.frecklet.doc.FreckletDocRenderMixin(*args, **kwargs)[source]

Bases: object

render_doc(template_name)[source]
freckles.frecklet.doc.create_doc_jinja_env(name, template_dir, template_filters=None)[source]
freckles.frecklet.doc.render_html(frecklet)[source]
freckles.frecklet.doc.render_markdown(frecklet)[source]
freckles.frecklet.doc.to_cli_help_string_filter(frecklet)[source]
freckles.frecklet.doc.to_code_block_filter(obj, format=None)[source]
freckles.frecklet.doc.to_yaml_filter(obj, empty_string=None, indent=0)[source]
freckles.frecklet.doc.vars_markdown_table(vars, vars_optional=None)[source]
freckles.frecklet.frecklet module
class freckles.frecklet.frecklet.FreckletAugmentMetadataAttribute[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.frecklet.FreckletExplodedAttribute[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.frecklet.FreckletHtmlAttribute[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.frecklet.FreckletMarkdownAttribute[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.frecklet.FreckletMetaAttribute[source]

Bases: ting.ting_attributes.ValueAttribute

get_attribute(ting, attribute_name=None)[source]
class freckles.frecklet.frecklet.FreckletValidAttribute[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.frecklet.FreckletsTemplateKeysAttribute[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.frecklet.PagelingContentAttribute[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.frecklet.PagelingMetadataAttribute[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.frecklet.PagelingNavPathAttribute[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

freckles.frecklet.tasks module
class freckles.frecklet.tasks.AddRootFreckletProcessor(**init_params)[source]

Bases: frkl.processors.ConfigProcessor

process_current_config()[source]

Processes the config url or content.

Returns:processed config url or content
Return type:object
class freckles.frecklet.tasks.CleanupFreckletProcessor(**init_params)[source]

Bases: frkl.processors.ConfigProcessor

process_current_config()[source]

Processes the config url or content.

Returns:processed config url or content
Return type:object
class freckles.frecklet.tasks.CommandNameProcessor(**init_params)[source]

Bases: frkl.processors.ConfigProcessor

Adds potential missing command/name keys.

process_current_config()[source]

Processes the config url or content.

Returns:processed config url or content
Return type:object
class freckles.frecklet.tasks.DirectParentArgsProcessor(**init_params)[source]

Bases: frkl.processors.ConfigProcessor

Adds arguments for ‘direct’ parents.

For example if a frecklet has something like:

  • user-exists:
    name: “{{:: name ::}}”

Where the variable name stays the same, and no filter is involved, the args will be inherited directly.

process_current_config()[source]

Processes the config url or content.

Returns:processed config url or content
Return type:object
class freckles.frecklet.tasks.ExplodedArgsProcessor(**init_params)[source]

Bases: frkl.processors.ConfigProcessor

Sets the exploded args property.

process_current_config()[source]

Processes the config url or content.

Returns:processed config url or content
Return type:object
class freckles.frecklet.tasks.FreckletsAttribute[source]

Bases: ting.ting_attributes.ValueAttribute

get_attribute(ting, attribute_name=None)[source]
class freckles.frecklet.tasks.MoveEmbeddedTaskKeysProcessor(**init_params)[source]

Bases: frkl.processors.ConfigProcessor

Moves keys that start with __task__ from the vars to the task sub-dict.

process_current_config()[source]

Processes the config url or content.

Returns:processed config url or content
Return type:object
class freckles.frecklet.tasks.NodeCounter[source]

Bases: object

current_count
up()[source]
class freckles.frecklet.tasks.SpecialCaseProcessor(**init_params)[source]

Bases: frkl.processors.ConfigProcessor

Makes sure that no keywords are in vars.

process_current_config()[source]

Processes the config url or content.

Returns:processed config url or content
Return type:object
class freckles.frecklet.tasks.TaskListAttribute[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.tasks.TaskListDetailedAttribute[source]

Bases: ting.ting_attributes.TingAttribute

FRECKLET_FORMAT = {'child_marker': 'frecklets', 'default_leaf': 'frecklet', 'default_leaf_key': 'name', 'key_move_map': {'*': ('vars', 'default')}, 'other_keys': ['args', 'doc', 'meta', 'frecklet', 'task'], 'use_context': False}
get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.tasks.TaskListResolvedAttribute[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.tasks.TaskTreeAttribute[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.tasks.TaskTypePrefixProcessor(**init_params)[source]

Bases: frkl.processors.ConfigProcessor

Adds a ‘become’: True key/value pair if the task name is all uppercase.

process_current_config()[source]

Processes the config url or content.

Returns:processed config url or content
Return type:object
freckles.frecklet.tasks.fill_defaults(task_item)[source]
freckles.frecklet.tasks.prettyfiy_task(task_detailed, arg_map)[source]
freckles.frecklet.vars module
class freckles.frecklet.vars.Inventory[source]

Bases: object

get_all(hide_secret=False)[source]
get_secret_args()[source]
retrieve_value(var_name, **task_context)[source]
retrive_arg_schema(var_name, **task_context)[source]
class freckles.frecklet.vars.VarCast(prefix)[source]

Bases: ting.ting_cast.TingCast

VAR_ATTRS = []
class freckles.frecklet.vars.VarPathAttribute(prefix)[source]

Bases: ting.ting_attributes.TingAttribute

get_attribute(ting, attribute_name=None)[source]
provides()[source]

Return a list of attributes this object will add to a Ting.

requires()[source]

Return an list of attributes this object requires to be able to augment the Ting.

class freckles.frecklet.vars.VarsInventory(*vars)[source]

Bases: freckles.frecklet.vars.Inventory

get_all(hide_secret=False)[source]
retrieve_value(var_name, **task_context)[source]
set_value(var_name, new_value, is_secret=False)[source]
vars
Module contents
freckles.utils package
Submodules
freckles.utils.doc_utils module

Generic configuration class.

freckles.utils.doc_utils.describe_tasklist_in_markdown(tasklist, use_short_help_name_as_title=False)[source]
freckles.utils.doc_utils.describe_tasklist_string(tasklist, use_short_help_name_as_title=False)[source]
freckles.utils.doc_utils.flatten_task_hierarchy(task_hierarchy, result=None, remove_children_from_items=True)[source]
freckles.utils.doc_utils.get_task_plan_string(tasklist, indent=0)[source]
freckles.utils.doc_utils.print_task_plan(tasklist, indent=0)[source]
freckles.utils.host_utils module
class freckles.utils.host_utils.FrecklesRunTarget(context, target_dict=None, target_string=None)[source]

Bases: object

become_pass
config
connection_type
host
port
protocol
ssh_key
ssh_pass
user
freckles.utils.host_utils.get_host_details(host_string)[source]

Parse a string to get user, protocol, host, etc.

Parameters:host_string (str) – the string
Returns:a dict containing the differnt parts
Return type:dict
freckles.utils.host_utils.get_pi_details(target_string)[source]
freckles.utils.host_utils.get_vagrant_details(target_string, context)[source]
freckles.utils.host_utils.list_vagrant_hosts()[source]
freckles.utils.host_utils.parse_target_string(target_string, context)[source]
freckles.utils.host_utils.parse_vagrant_ssh_config_string(config_string)[source]
freckles.utils.profile module
freckles.utils.utils module
freckles.utils.utils.print_frecklet_list(frecklet_dict)[source]
freckles.utils.utils.print_multi_column_table(data, headers)[source]
freckles.utils.utils.print_template_error(template_error)[source]
freckles.utils.utils.print_two_column_table(data, header_one, header_two)[source]
freckles.utils.versions module
freckles.utils.versions.get_versions()[source]
Module contents
Submodules
freckles.defaults module
freckles.exceptions module
exception freckles.exceptions.FrecklesConfigException(keys=None, msg=None, solution=None, reason=None, references=None)[source]

Bases: frutils.exceptions.FrklException

exception freckles.exceptions.FrecklesPermissionException(key=None, msg=None, solution=None, reason=None, addition_references=None)[source]

Bases: frutils.exceptions.FrklException

exception freckles.exceptions.FrecklesUnlockException(message)[source]

Bases: frutils.exceptions.FrklException

exception freckles.exceptions.FrecklesVarException(frecklet=None, var_name=None, message=None, errors=None, task_path=None, vars=None, task=None)[source]

Bases: frutils.exceptions.FrklException

exception freckles.exceptions.FreckletBuildException(frecklet, msg, solution=None, reason=None, references=None)[source]

Bases: frutils.exceptions.FrklException

exception freckles.exceptions.FreckletException(frecklet, parent_exception, frecklet_name)[source]

Bases: frutils.exceptions.FrklException

exception freckles.exceptions.InvalidFreckletException(frecklet, parent_exception, frecklet_name=None)[source]

Bases: frutils.exceptions.FrklException

freckles.frecklecutable module
class freckles.frecklecutable.Frecklecutable(frecklet, context)[source]

Bases: object

check_become_pass(run_config, run_secrets, parent_task)[source]
context
frecklet
process_tasks(inventory)[source]

Calculates the tasklist for a given inventory.

run(inventory, run_config, run_vars=None, parent_task=None, elevated=None, env_dir=None)[source]
class freckles.frecklecutable.FrecklecutableMixin(*args, **kwargs)[source]

Bases: object

create_frecklecutable(context)[source]
freckles.frecklecutable.ask_password(prompt)[source]
freckles.frecklecutable.is_duplicate_task(new_task, idempotency_cache)[source]
freckles.frecklecutable.remove_none_values(input)[source]
freckles.freckles module
class freckles.freckles.Freckles(use_community=False, default_context_config=None, extra_repos=None)[source]

Bases: object

create_context(context_name, context_config, set_current=False, extra_repos=None, use_community=False)[source]
create_frecklecutable(frecklet_name, context_name=None)[source]
current_context
frecklets
get_context(context_name=None)[source]
get_frecklet(frecklet_name, context_name=None)[source]
get_frecklet_index(context_name=None)[source]
freckles.output_callback module
class freckles.output_callback.FrecklesResultCallback(result_strategy='merge')[source]

Bases: object

Class to gather results of a frecklecute run.

Parameters:add_strategy –
add_result(overlay_dict)[source]
finish_up()[source]
class freckles.output_callback.FrecklesRun(run_id, adapter_name, task_list, run_vars, run_config, run_env, run_properties)[source]

Bases: object

freckles.schemas module
Module contents
freckles.print_version(ctx, param, value)[source]

Indices and tables