API documentation

This section contains documentation for the source code of Astrality, and is intended for the developers of Astrality.

The structure of the code base

Here we offer a quick overview of the most relevant python modules in the code base, loosely ordered according to their execution order.

bin.astrality:
The CLI entry point of Astrality, using the standard library argparse module.
astrality.astrality:
The main loop of Astrality, binding everything together. Calls out to the different submodules and handles interruption signals gracefully.
astrality.config:
Compilation and pre-processing of the user configuration according to the heuristics explained in the documentation.
astrality.github:
Retrieval of modules defined in GitHub repositories.
astrality.module:

Execution of actions defined in modules.

Each module in the user configuration is represented by a Module object. All Module-objects are managed by a single ModuleManager object which iterates over them and executes their actions.

astrality.requirements:
Module for checking if module requirements are satisfied.
astrality.actions:
Module for executing actions such as “import_context”, “compile”, “run”, and “trigger”.
astrality.event_listener:
Implements all the types of module event listeners as subclasses of EventListener.
astrality.context:
Defines a dictionary-like data structure which contains context values, passed off to Jinja2 template compilation.
astrality.compiler:
Wrappers around the Jinja2 library for compiling templates with specific context values.
astrality.filewatcher:
Implements a file system watcher which dispatches to event handlers when files are modified on disk.
astrality.utils:
Utility functions which are used all over the code base, most importantly a wrapper function for running shell commands.

Modules

Astrality’s modules are placed within the astrality mother-module. For example, the actions module is importable from astrality.actions.

Actions module

Module defining class-representation of module actions.

Each action class type encapsulates the user specified options available for that specific action type. The action itself can be performed by invoking the object method execute().

One of the main goals with Action, is that the arity of execute is 0. This means that we unfortunately need to pass a reference to global mutable state, i.e. the context store.

Another goal is that none of the subclasses require the global configuration of the entire application, just the action configuration itself. Earlier implementations required GlobalApplicationConfig to be passed arround in the entire run-stack, which was quite combersome. Some of the limitations with this approach could be solved if we implement GlobalApplicationConfig as a singleton which could be imported and accessed independently from other modules.

class astrality.actions.Action(options, directory, replacer, context_store, creation_store)[source]

Bases: abc.ABC

Superclass for module action types.

Parameters:
  • options (Union[_Forwardref, _Forwardref, _Forwardref, _Forwardref, _Forwardref, _Forwardref, _Forwardref]) – A dictionary containing the user options for a given module action type.
  • directory (Path) – The directory used as anchor for relative paths. This must be an absolute path.
  • replacer (Callable[[str], str]) – Placeholder substitutor of string user options.
  • context_store (Context) – A reference to the global context store.
  • creation_store (ModuleCreatedFiles) – ModuleCreatedFiles object which stores which files that are created by the different module actions.
Options = typing.Union[_ForwardRef('CompileDict'), _ForwardRef('CopyDict'), _ForwardRef('ImportContextDict'), _ForwardRef('RunDict'), _ForwardRef('StowDict'), _ForwardRef('SymlinkDict'), _ForwardRef('TriggerDict')]
execute(dry_run=False)[source]

Execute defined action.

Parameters:dry_run (bool) – If external side effects should be skipped.
Return type:Any
option(key, default=None, path=False)[source]

Return user specified action option.

All option value access should go through this helper function, as it replaces relevant placeholders users might have specified.

Parameters:
  • key (str) – The key of the user option that should be retrieved.
  • default (Optional[Any]) – Default return value if key not found.
  • path (bool) – If True, convert string path to Path.is_absolute().
Return type:

Any
Returns:

Processed action configuration value.
replace(string)[source]

Return converted string, substitution defined by replacer.

This is used to replace placeholders such as {event}. This redirection is necessary due to python/mypy/issues/2427

Parameters:string (str) – String configuration option.
Return type:str
Returns:String with placeholders substituted.
class astrality.actions.ActionBlock(action_block, directory, replacer, context_store, global_modules_config, module_name)[source]

Bases: object

Class representing a module action block, e.g. ‘on_startup’.

Parameters:
  • action_block (ActionBlockDict) – Dictionary containing all actions to be performed.
  • directory (Path) – The directory used as anchor for relative paths. This must be an absolute path.
  • replacer (Callable[[str], str]) – Placeholder substitutor of string user options.
  • context_store (Context) – A reference to the global context store.
  • module_name (str) – Name of module owning ActionBlock.
  • global_modules_config (GlobalModulesConfig) – Global configuration object.
action_options(identifier)[source]

Return all action configs of type ‘identifier’.

Parameters:identifier (str) – Action type, such as ‘run’ or ‘compile’.
Return type:List[Union[CompileDict, CopyDict, ImportContextDict, RunDict, StowDict, SymlinkDict, TriggerDict]]
Returns:List of action options of that type.
action_types = {'compile': <class 'astrality.actions.CompileAction'>, 'copy': <class 'astrality.actions.CopyAction'>, 'import_context': <class 'astrality.actions.ImportContextAction'>, 'run': <class 'astrality.actions.RunAction'>, 'stow': <class 'astrality.actions.StowAction'>, 'symlink': <class 'astrality.actions.SymlinkAction'>, 'trigger': <class 'astrality.actions.TriggerAction'>}
compile(dry_run=False)[source]

Compile templates.

Return type:None
copy(dry_run=False)[source]

Copy files.

Return type:None
execute(default_timeout, dry_run=False)[source]

Execute all actions in action block.

The order of execution is:
  1. Perform all context imports into the context store.
  2. Compile all templates.
  3. Run all shell commands.
Return type:None
import_context(dry_run=False)[source]

Import context into global context store.

Return type:None
performed_compilations()[source]

Return all earlier performed compilations.

Return type:Defaultdict[Path, Set[Path]]
Returns:Dictionary with template keys and target path set.
run(default_timeout=None, dry_run=False)[source]

Run shell commands.

Parameters:default_timeout (Union[int, float, None]) – How long to wait for run commands to exit
Return type:Tuple[Tuple[str, str], …]
Returns:Tuple of 2-tuples containing (shell_command, stdout,)
stow(dry_run=False)[source]

Stow directory contents.

Return type:None

Symlink files.

Return type:None
triggers(dry_run=False)[source]

Return all trigger instructions specified in action block.

Return type:Tuple[Trigger, …]
Returns:Tuple of Trigger objects specified in action block.
class astrality.actions.CompileAction(*args, **kwargs)[source]

Bases: astrality.actions.Action

Compile template action.

Options = typing.Union[_ForwardRef('CompileDict'), _ForwardRef('CopyDict'), _ForwardRef('ImportContextDict'), _ForwardRef('RunDict'), _ForwardRef('StowDict'), _ForwardRef('SymlinkDict'), _ForwardRef('TriggerDict')]
create_compilation_target(template)[source]

Create compilation target for template with unspecified target.

Compilation targets are stored in $XDG_DATA_HOME/astrality/compilations. For details regarding the implementation see:

Parameters:name – Path to template to be compiled.
Return type:Path
Returns:Path to deterministicly determined compilation target.
execute(dry_run=False)[source]

Compile template source to target destination.

Parameters:dry_run (bool) – If True, skip and log compilation(s).
Return type:Dict[Path, Path]
Returns:Dictionary with template content keys and target path values.
option(key, default=None, path=False)

Return user specified action option.

All option value access should go through this helper function, as it replaces relevant placeholders users might have specified.

Parameters:
  • key (str) – The key of the user option that should be retrieved.
  • default (Optional[Any]) – Default return value if key not found.
  • path (bool) – If True, convert string path to Path.is_absolute().
Return type:

Any
Returns:

Processed action configuration value.
performed_compilations()[source]

Return dictionary containing all performed compilations.

Return type:Defaultdict[Path, Set[Path]]
Returns:Dictinary with keys containing compiled templates, and values as a set of target paths.
priority = 400
replace(string)

Return converted string, substitution defined by replacer.

This is used to replace placeholders such as {event}. This redirection is necessary due to python/mypy/issues/2427

Parameters:string (str) – String configuration option.
Return type:str
Returns:String with placeholders substituted.
class astrality.actions.CopyAction(*args, **kwargs)[source]

Bases: astrality.actions.Action

Copy files Action sub-class.

Options = typing.Union[_ForwardRef('CompileDict'), _ForwardRef('CopyDict'), _ForwardRef('ImportContextDict'), _ForwardRef('RunDict'), _ForwardRef('StowDict'), _ForwardRef('SymlinkDict'), _ForwardRef('TriggerDict')]
execute(dry_run=False)[source]

Copy from content path to target path.

Parameters:dry_run (bool) – If True, skip and log copy creation(s).
Return type:Dict[Path, Path]
Returns:Dictionary with content keys and copy values.
option(key, default=None, path=False)

Return user specified action option.

All option value access should go through this helper function, as it replaces relevant placeholders users might have specified.

Parameters:
  • key (str) – The key of the user option that should be retrieved.
  • default (Optional[Any]) – Default return value if key not found.
  • path (bool) – If True, convert string path to Path.is_absolute().
Return type:

Any
Returns:

Processed action configuration value.
priority = 300
replace(string)

Return converted string, substitution defined by replacer.

This is used to replace placeholders such as {event}. This redirection is necessary due to python/mypy/issues/2427

Parameters:string (str) – String configuration option.
Return type:str
Returns:String with placeholders substituted.
class astrality.actions.ImportContextAction(options, directory, replacer, context_store, creation_store)[source]

Bases: astrality.actions.Action

Import context into global context store.

Parameters:context_store (Context) – A mutable reference to the global context store.

See Action for documentation for the other parameters.

Options = typing.Union[_ForwardRef('CompileDict'), _ForwardRef('CopyDict'), _ForwardRef('ImportContextDict'), _ForwardRef('RunDict'), _ForwardRef('StowDict'), _ForwardRef('SymlinkDict'), _ForwardRef('TriggerDict')]
execute(dry_run=False)[source]

Import context section(s) according to user configuration block.

Parameters:dry_run (bool) – This parameter is ignored, as import_context only has internal side effects.
Return type:None
option(key, default=None, path=False)

Return user specified action option.

All option value access should go through this helper function, as it replaces relevant placeholders users might have specified.

Parameters:
  • key (str) – The key of the user option that should be retrieved.
  • default (Optional[Any]) – Default return value if key not found.
  • path (bool) – If True, convert string path to Path.is_absolute().
Return type:

Any
Returns:

Processed action configuration value.
priority = 100
replace(string)

Return converted string, substitution defined by replacer.

This is used to replace placeholders such as {event}. This redirection is necessary due to python/mypy/issues/2427

Parameters:string (str) – String configuration option.
Return type:str
Returns:String with placeholders substituted.
class astrality.actions.RunAction(options, directory, replacer, context_store, creation_store)[source]

Bases: astrality.actions.Action

Run shell command Action sub-class.

Options = typing.Union[_ForwardRef('CompileDict'), _ForwardRef('CopyDict'), _ForwardRef('ImportContextDict'), _ForwardRef('RunDict'), _ForwardRef('StowDict'), _ForwardRef('SymlinkDict'), _ForwardRef('TriggerDict')]
execute(default_timeout=0, dry_run=False)[source]

Execute shell command action.

Parameters:
  • default_timeout (Union[int, float]) – Run timeout in seconds if no specific value is specified in options.
  • dry_run (bool) – If True, skip and log commands to be executed.
Return type:

Optional[Tuple[str, str]]
Returns:

2-tuple containing the executed command and its resulting stdout.
option(key, default=None, path=False)

Return user specified action option.

All option value access should go through this helper function, as it replaces relevant placeholders users might have specified.

Parameters:
  • key (str) – The key of the user option that should be retrieved.
  • default (Optional[Any]) – Default return value if key not found.
  • path (bool) – If True, convert string path to Path.is_absolute().
Return type:

Any
Returns:

Processed action configuration value.
priority = 600
replace(string)

Return converted string, substitution defined by replacer.

This is used to replace placeholders such as {event}. This redirection is necessary due to python/mypy/issues/2427

Parameters:string (str) – String configuration option.
Return type:str
Returns:String with placeholders substituted.
class astrality.actions.SetupActionBlock(action_block, directory, replacer, context_store, global_modules_config, module_name)[source]

Bases: astrality.actions.ActionBlock

Setup action block which only executes actions once.

action_options(identifier)[source]

Return action configs of ‘identifier’ type that have not been executed.

Parameters:identifier (str) – Action type, such as ‘run’ or ‘compile’.
Return type:List[Union[CompileDict, CopyDict, ImportContextDict, RunDict, StowDict, SymlinkDict, TriggerDict]]
Returns:List of action options of that type.
action_types = {'compile': <class 'astrality.actions.CompileAction'>, 'copy': <class 'astrality.actions.CopyAction'>, 'import_context': <class 'astrality.actions.ImportContextAction'>, 'run': <class 'astrality.actions.RunAction'>, 'stow': <class 'astrality.actions.StowAction'>, 'symlink': <class 'astrality.actions.SymlinkAction'>, 'trigger': <class 'astrality.actions.TriggerAction'>}
compile(dry_run=False)

Compile templates.

Return type:None
copy(dry_run=False)

Copy files.

Return type:None
execute(default_timeout, dry_run=False)

Execute all actions in action block.

The order of execution is:
  1. Perform all context imports into the context store.
  2. Compile all templates.
  3. Run all shell commands.
Return type:None
import_context(dry_run=False)

Import context into global context store.

Return type:None
performed_compilations()

Return all earlier performed compilations.

Return type:Defaultdict[Path, Set[Path]]
Returns:Dictionary with template keys and target path set.
run(default_timeout=None, dry_run=False)

Run shell commands.

Parameters:default_timeout (Union[int, float, None]) – How long to wait for run commands to exit
Return type:Tuple[Tuple[str, str], …]
Returns:Tuple of 2-tuples containing (shell_command, stdout,)
stow(dry_run=False)

Stow directory contents.

Return type:None

Symlink files.

Return type:None
triggers(dry_run=False)

Return all trigger instructions specified in action block.

Return type:Tuple[Trigger, …]
Returns:Tuple of Trigger objects specified in action block.
class astrality.actions.StowAction(*args, **kwargs)[source]

Bases: astrality.actions.Action

Stow directory action.

Options = typing.Union[_ForwardRef('CompileDict'), _ForwardRef('CopyDict'), _ForwardRef('ImportContextDict'), _ForwardRef('RunDict'), _ForwardRef('StowDict'), _ForwardRef('SymlinkDict'), _ForwardRef('TriggerDict')]
execute(dry_run=False)[source]

Stow directory source to target destination.

Parameters:dry_run (bool) – If True, skip and log copies, symlinks, and compilations.
Return type:Dict[Path, Path]
Returns:Dictionary with source keys and target values. Contains compiled, symlinked, and copied files.
managed_files()[source]

Return dictionary containing content keys and target values.

Return type:Dict[Path, Set[Path]]
Returns:Dictinary with keys containing compiled templates, and values as a set of target paths. If non_templates is ‘copy’, then these will be included as well.
option(key, default=None, path=False)

Return user specified action option.

All option value access should go through this helper function, as it replaces relevant placeholders users might have specified.

Parameters:
  • key (str) – The key of the user option that should be retrieved.
  • default (Optional[Any]) – Default return value if key not found.
  • path (bool) – If True, convert string path to Path.is_absolute().
Return type:

Any
Returns:

Processed action configuration value.
priority = 500
replace(string)

Return converted string, substitution defined by replacer.

This is used to replace placeholders such as {event}. This redirection is necessary due to python/mypy/issues/2427

Parameters:string (str) – String configuration option.
Return type:str
Returns:String with placeholders substituted.
class astrality.actions.SymlinkAction(*args, **kwargs)[source]

Bases: astrality.actions.Action

Symlink files Action sub-class.

Options = typing.Union[_ForwardRef('CompileDict'), _ForwardRef('CopyDict'), _ForwardRef('ImportContextDict'), _ForwardRef('RunDict'), _ForwardRef('StowDict'), _ForwardRef('SymlinkDict'), _ForwardRef('TriggerDict')]
execute(dry_run=False)[source]

Symlink to content path from target path.

Parameters:dry_run (bool) – If True, skip and log symlink creation(s).
Return type:Dict[Path, Path]
Returns:Dictionary with content keys and symlink values.
option(key, default=None, path=False)

Return user specified action option.

All option value access should go through this helper function, as it replaces relevant placeholders users might have specified.

Parameters:
  • key (str) – The key of the user option that should be retrieved.
  • default (Optional[Any]) – Default return value if key not found.
  • path (bool) – If True, convert string path to Path.is_absolute().
Return type:

Any
Returns:

Processed action configuration value.
priority = 200
replace(string)

Return converted string, substitution defined by replacer.

This is used to replace placeholders such as {event}. This redirection is necessary due to python/mypy/issues/2427

Parameters:string (str) – String configuration option.
Return type:str
Returns:String with placeholders substituted.
class astrality.actions.Trigger(block, specified_path=None, relative_path=None, absolute_path=None)[source]

Bases: object

A class representing an instruction to trigger a specific action block.

Variables:
  • block – The block to be trigger, for example ‘on_startup’, ‘on_event’, ‘on_exit’, or ‘on_modified’.
  • specified_path – The string path specified for a ‘on_modified’ block.
  • relative_path – The relative pathlib.Path specified by specified_path.
  • absolute_path – The absolute path specified by specified_path.
class astrality.actions.TriggerAction(options, directory, replacer, context_store, creation_store)[source]

Bases: astrality.actions.Action

Action sub-class representing a trigger action.

Options = typing.Union[_ForwardRef('CompileDict'), _ForwardRef('CopyDict'), _ForwardRef('ImportContextDict'), _ForwardRef('RunDict'), _ForwardRef('StowDict'), _ForwardRef('SymlinkDict'), _ForwardRef('TriggerDict')]
execute(dry_run=False)[source]

Return trigger instruction.

If no trigger is specified, return None.

Parameters:dry_run (bool) – This parameter is ignored.
Return type:Optional[Trigger]
Returns:Optional Trigger instance.
option(key, default=None, path=False)

Return user specified action option.

All option value access should go through this helper function, as it replaces relevant placeholders users might have specified.

Parameters:
  • key (str) – The key of the user option that should be retrieved.
  • default (Optional[Any]) – Default return value if key not found.
  • path (bool) – If True, convert string path to Path.is_absolute().
Return type:

Any
Returns:

Processed action configuration value.
priority = 0
replace(string)

Return converted string, substitution defined by replacer.

This is used to replace placeholders such as {event}. This redirection is necessary due to python/mypy/issues/2427

Parameters:string (str) – String configuration option.
Return type:str
Returns:String with placeholders substituted.