kern package

action module

” This module contains the Action class which represents executes a single action assuming all its deps are ready

class hash.kern.action.Action(action: str, resource: Resource, state: ImDict, env: EnvResource, base_path: str, reason: str)

The Action class is used to execute a single action on a single resource with a state and en env, it assumes that all dependencies are ready and all templates are rendered for this resource.

do_action()

Run the actual action on the resource, it searches for <action>_command spec if found then it is ran, if not it searches for <action>_script spec if found then it is ran otherwise it calls action method on the resource and passes to it the action’s name, state and env, the returned value is used as a return for this method, it no return value was found then it returns a default dictionary with one msg key, it also checks if the return value is not a dictionary, it raises an error according to the current action.

do_post_action()

Run post action command or script on the resource, it searches for a spec called post_<action>_command if found then it is executed, if not it searches for post_<action>_script if found then it is executed and if not then the method returns.

Before executing any command or script the values for environment variables are set using setup_env method

do_pre_action()

Run pre action command or script on the resource, it searches for a spec called pre_<action>_command if found then it is executed, if not it searches for pre_<action>_script if found then it is executed and if not then the method returns.

Before executing any command or script the values for environment variables are set using setup_env method

re_action()

Check if we need to re-run the action based on the resource’s specs

run_action()

Run an action on a resource assuming all deps are ready and templates rendered

It first calls pre action code, then calls the actual action and lastly the post action code.

setup_env() → None

This method is used to setup the environment for running a command or script on the resource, it sets these enviornment variables:

R_NAME: It contains the name of the resource. R_PARENT: It contains the ID of parent resource (Kind:Name) R_PARENT_NAME: It contains the name of parent resource R_ENV: It contains the name of environment where the action is being executed. R_ACTION: It contains the current name of action being executed. R_SPEC_{X}: this defines a group of environment variables for every spec element, for example if you have a spec called ‘x’ with a value of ‘abc’ it will create an environment variable called R_SPEC_X with a value of ‘abc’

execute module

This module is used to execute the plan from the generated graph

planner module

This module is used to create an execution plan to run action x on resource y in enviornment z and returns it as a graph

class hash.kern.planner.Planner(store, base_path='')

This class is used to create an execution plan for running action x on resource y in environment z

get_deps(resource, env=None)

This method checks for all deps for the resource and return them as a list of dictionaries, Every dictionary has id key which is the resource’s IDs, action1, action2 and hash keys. First it reads metadata.depends_on for all explicit deps, then it check the deps from the resource’s attributes and then it checks deps from hash templates

get_deps_metadata(resource: Resource)

Retrieve a dictionary of deps and their hashes from the resource’s metadata

get_deps_specs(resource: Resource, spec=None)

Retrieve a dictionary of deps and their hashes from the resource’s specs attributes

get_deps_templates(resource: Resource)

Retrieve a dictionary of deps from the resource’s templates TODO: to be implemented later

static re_action(action: str, resource, state: ~hash.utils.ImDict, _hash: str, deps=<hash.utils.ImDict object>, environment=None, base_path='') → str

This method is used to check if we need to re-run the action on the resource given input state.

Parameters:

• action (str) – The action that we want tocheck if we must re-run it

• resource (resources.Resource) – The resource on which the action will be executed

• state (utils.ImDict) – The current state for the resource

• _hash (str) – The current hash of the resource

• deps (dict) – A dictionary of deps IDs and their hashes, these will be compared with current deps in state to check if deps changed or not.

• environment (resources.EnvResource) – The env to check against, use the object’s env if passed as none.

• base_path (str) – A base path used to create absolute paths for scripts

Returns:

The reason for re-running the action given the state and env, None otherwise.

Return type:

str

state module

State module defines State class with all the methods, functions needed to manage state, it ensures that the internal state structure is hidden from consumers of the module and that only methods are used to manipulate or read state.

class hash.kern.state.State(_hash: str, resource_id: str)

This class defines a single state for a single resource, hash and resource ID combination make the state unique.

add_dep(dep_id: str, dep_hash: str)

Add a new dependency with its hash

Parameters:

• dep_id (str) – The id of the dependency to add

• dep_hash (str) – The hash of the dependecny to add

copy_state(st)

A method to copy everything from another state object except for hash and resource ID

Parameters:

st (State) – The other state object to copy

get_artifacts(action: str, env=None) → ImDict

Retrieve the artifacts in this state.

Parameters:

• action (str) – The action which we want to retrieve artifacts for it

• env (str|None) – The env where the action was executed.

Returns:

An immutable dictionary or tuple of the artifacts object

Return type:

utils.ImDict or tuple

get_dep(dep_id: str) → str

Return the hash of a single dependency

Parameters:

dep_id (str) – The id of the dependency to return its hash

Returns:

The hash of the dependency, None if the id does not exist

Return type:

str

get_deps() → ImDict

Return an immutable dictionary of all dependencies with their hashes

Returns:

An immutable dictionary of all dependencies with their hashes

Return type:

utils.ImDict

get_env_names(action: str) → list

Returns a list of env names which the action was executed on them, if the action is “” then return only all envs

Parameters:

action (str) – The name of the action

Returns:

A list of strings which contain the env names

Return type:

list (str)

get_envs() → ImDict

Return the immutable version of envs dictionary

Returns:

An immutable dictionary which contains all envs and their execution results

Return type:

utils.ImDict

get_globals(action: str, env=None) → ImDict

Retrieve the global values in this state.

Parameters:

• action (str) – The action which we want to retrieve globals for it

• env (str|None) – The env where the action was executed.

Returns:

An immutable dictionary of the globals object

Return type:

utils.ImDict

get_hash() → str

Return the hash of this state.

Returns:

The hash value

Return type:

str

get_imdict() → ImDict

Return a read only dictionary of the state.

Returns:

An immutable dictionary of the entire state

Return type:

utils.ImDict

get_json(return_id=False) → dict

Return a JSON representation of the state

Parameters:

return_id (bool) – A boolean value that controls if we should return resource ID in state or not

Returns:

The JSON representation

Return type:

dict

get_json_str(return_id=False) → str

Return a string JSON representation of the state

Parameters:

return_id (bool) – A boolean value that controls if we should return resource ID in state or not

Returns:

The string JSON representation

Return type:

str

get_local() → ImDict

Return the local state immutable dictionary of the state

Returns:

An immutable dictionary of the local state

Return type:

utils.ImDict

get_no_env() → ImDict

Return the immutable version of no_env dictionary

Returns:

An immutable dictionary which contains the no_env execution results

Return type:

utils.ImDict

get_resource_id() → str

Return the resource id of this state

Returns:

The id of the resource.

Return type:

str

get_result(action: str, env=None) → ImDict

Retrieve a result immutable dictionary from the state.

Parameters:

• action (str) – The action that we want to retrieve its result.

• env (str|None) – The env where the action was executed.

Returns:

An immutable dictionary of the result as it is stored in state.

Return type:

utils.ImDict

get_result_local(action: str, env=None) → ImDict

Retrieve a result immutable dictionary from the local state.

Parameters:

• action (str) – The action that we want to retrieve its result.

• env (str|None) – The env where the action was executed.

Returns:

An immutable dictionary of the result as it is stored in state.

Return type:

utils.ImDict

get_status() → ImDict

Return the status immutable dictionary of the state

Returns:

An immutable dictionary of the status

Return type:

utils.ImDict

last_action() → str

Return the last action exeucted without an error, if no action was executed return “”

Returns:

The last action without an error

Return type:

str

last_error() → str

Return the last action that caused an error, return “” if no error exists

Returns:

The last action that caused an error

Return type:

str

classmethod read_state(state: dict, resource_id=None)

A classmethod to convert a state dictionary into a valid state object.

Parameters:

• state (dict) – The dictionary that we want to convert into a state

• resource_id (str) – The ID of resource, it is used only if the ID is not stored in state.

Returns:

A State object

Return type:

State

set_local(local)

Set the local state

Parameters:

local (dict) – The local state to set

set_result(result: dict, action: str, env=None)

This method is used to set the result of executing an action on the resource

Parameters:

• result (dict) – The result object that we want to store in state.

• action (str) – The action that generated this result.

• env (str|None) – The env that the action was executed in, if None store the result in no_env

Raises:

errors.StateError – When result, action or env types are wrong

set_result_local(result: dict, action: str, env=None)

This method is used to set the result of executing an action on the resource in local state

Parameters:

• result (dict) – The result object that we want to store in state.

• action (str) – The action that generated this result.

• env (str|None) – The env that the action was executed in, if None store the result in no_env

Raises:

errors.StateError – When result, action or env types are wrong

set_status(last_action: str, error: str)

Set the status of the state, it contains the last action that was ran without errors and the last action that caused an error if possible.

Parameters:

• last_action (str) – The last action without an error

• error (str) – The last action with an error

templates module

This module is used to render templates for a resource and clear them, it needs resource, state and globals as input