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. AllModule
-objects are managed by a singleModuleManager
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.
- key (
-
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.
- options (
-
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'>}¶
-
execute
(default_timeout, dry_run=False)[source]¶ Execute all actions in action block.
- The order of execution is:
- Perform all context imports into the context store.
- Compile all templates.
- Run all shell commands.
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.
- 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.
- key (
-
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.
- key (
-
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.
- key (
-
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.
- default_timeout (
-
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.
- key (
-
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:
- Perform all context imports into the context store.
- Compile all templates.
- 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 exitReturn 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
(dry_run=False)¶ Symlink files.
Return type: None
-
-
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.
- key (
-
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.
- key (
-
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.
- key (
-
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.
-