Document use of single actions without lists

astrality/module.py

@@ -93,6 +93,7 @@ def populate_event_blocks(self) -> None:
                 'import_context': [],
                 'compile': [],
                 'run': [],
+                'trigger': [],
             }
             self.module_config[event_block].update(configured_event_block)
 
@@ -105,6 +106,7 @@ def populate_event_blocks(self) -> None:
                     'import_context': [],
                     'compile': [],
                     'run': [],
+                    'trigger': [],
                 }
                 self.module_config['on_modified'][template_name].update(configured_event_block)
 
@@ -117,7 +119,7 @@ def populate_event_blocks(self) -> None:
             self.module_config['on_exit'],
             *self.module_config['on_modified'].values(),
         ):
-            for action in ('import_context', 'compile', 'run',):
+            for action in ('import_context', 'compile', 'run', 'trigger',):
                 if not isinstance(event_block[action], list):  # type: ignore
                     event_block[action] = [event_block[action]]  # type: ignore
 

astrality/tests/module/test_configuration.py

@@ -1,8 +1,9 @@
 from astrality.module import Module
 
-def test_that_all_arguments_are_converted_to_lists():
+def test_that_module_configuration_is_processed_correctly_before_use():
     """
-    Test that all list item configurations can be given as single strings.
+    Test that all list item configurations can be given as single strings,
+    and that missing configuration options are inserted.
     """
     module_config = {'module/A': {
         'on_startup': {
@@ -11,6 +12,7 @@ def test_that_all_arguments_are_converted_to_lists():
         'on_event': {
             'import_context': {'from_file': '/test'},
             'run': ['echo 1', 'echo 2'],
+            'trigger': 'on_modified./some/file',
         },
         'on_modified': {
             '/some/file': {
@@ -26,22 +28,26 @@ def test_that_all_arguments_are_converted_to_lists():
             'run': ['echo hi!'],
             'compile': [],
             'import_context': [],
+            'trigger': [],
         },
         'on_event': {
             'import_context': [{'from_file': '/test'}],
             'run': ['echo 1', 'echo 2'],
-            'compile': [],
+            'compile': [{'template': '/some/template'}],
+            'trigger': ['on_modified./some/file'],
         },
         'on_exit': {
             'run': [],
             'compile': [],
             'import_context': [],
+            'trigger': [],
         },
         'on_modified': {
             '/some/file': {
                 'compile': [{'template': '/some/template'}],
                 'run': [],
                 'import_context': [],
+                'trigger': [],
             },
         },
     }

docs/modules.rst

@@ -151,7 +151,7 @@ Actions are tasks for Astrality to perform, and are placed within :ref:`event bl
 Context imports
 ---------------
 
-Context imports are defined as a list of dictionaries under the ``import_context`` keyword in an :ref:`event block <events>` of a module.
+Context imports are defined as a dictionary, or a list of dictionaries, under the ``import_context`` keyword in an :ref:`event block <events>` of a module.
 
 This is best explained with an example. Let us create a color schemes file:
 
@@ -172,9 +172,9 @@ Then let us import the gruvbox color scheme into the "colors" :ref:`context <con
     module/color_scheme:
         on_startup:
             import_context:
-                - from_path: contexts/color_schemes.yaml
-                  from_section: gruvbox_dark
-                  to_section: colors
+                from_path: contexts/color_schemes.yaml
+                from_section: gruvbox_dark
+                to_section: colors
 
 This is functionally equivalent to writing:
 
@@ -215,7 +215,7 @@ The available attributes for ``import_context`` are:
 Compile templates
 -----------------
 
-Template compilations are defined as a list of dictionaries under the ``compile`` keyword in an :ref:`event block <events>` of a module.
+Template compilations are defined as a dictionary, or a list of dictionaries, under the ``compile`` keyword in an :ref:`event block <events>` of a module.
 
 Each template compilation action has the following available attributes:
 
@@ -277,8 +277,7 @@ Example:
             type: weekday
 
         on_startup:
-            run:
-                - notify-send "You just started Astrality, and the day is {event}"
+            run: notify-send "You just started Astrality, and the day is {event}"
 
         on_event:
             run:
@@ -310,8 +309,7 @@ An example of a module using ``trigger`` actions:
                 type: weekday
 
             on_startup:
-                run:
-                    - startup_command
+                run: startup_command
 
                 trigger:
                     - on_event
@@ -328,10 +326,9 @@ An example of a module using ``trigger`` actions:
             on_modified:
                 templates/A.template:
                     compile:
-                        - template: templates/A.template
+                        template: templates/A.template
 
-                    run:
-                        - shell_command_dependent_on_templateA
+                    run: shell_command_dependent_on_templateA
 
 This is equivalent to writing the following module:
 
@@ -349,31 +346,29 @@ This is equivalent to writing the following module:
                       to_section: a_stuff
 
                 compile:
-                    - template: templates/templateA
+                    template: templates/templateA
 
                 run:
                     - startup_command
                     - shell_command_dependent_on_templateA
 
             on_event:
                 import_context:
-                    - from_path: contexts/A.yaml
-                      from_section: '{event}'
-                      to_section: a_stuff
+                    from_path: contexts/A.yaml
+                    from_section: '{event}'
+                    to_section: a_stuff
 
                 compile:
-                    - template: templateA
+                    template: templateA
 
-                run:
-                    - shell_command_dependent_on_templateA
+                run: shell_command_dependent_on_templateA
 
             on_modified:
                 templates/templateA:
                     compile:
-                        - template: templates/templateA
+                        template: templates/templateA
 
-                    run:
-                        - shell_command_dependent_on_templateA
+                    run: shell_command_dependent_on_templateA
 
 
 .. hint::