Rewrite dispatching mechanism

The dispatcher code has grown organically since the beginning of the
project and has been patched along the way to include new features. This
has made it increasingly harder to maintain and add new features to.

This change is a rewrite of the dispatching mechanism. This includes the
way that environments are loaded and how actions are executed in them as
well as in the top-level and subprocess dispatch.

Also, there is now no longer a default environment. Actions declared in
the static configuration are executed in the ambient environment unless
they also have an environment declared.

README.md

@@ -89,6 +89,23 @@ Bygg will check for the presence of `Byggfile.py` in the current directory. The
 actions above would be built with `bygg build1` and `bygg build2`,
 respectively. See the `examples/` directory for worked examples.
 
+### Environments
+
+Bygg can manage virtual environments. See `examples/environments/Byggfile.yml`
+for an example.
+
+Python files and the actions declared therein will run in the environment that
+the Python file was declared to belong to in the static configuration.
+
+No environment will be managed or loaded implicitly for actions that are
+declared in the static configuration. Actions that need an environment must
+declare the `environment` property.
+
+Any `shell` commands will need to have their respective environments activated
+as needed (e.g. by prefacing them with `. .venv/bin/activate`) even if they are
+declared from Python code that runs in an environment. This is because shells
+are not intrinsically aware of virtual environments.
+
 ### Settings files
 
 There is also support for declaring actions, environments and settings in YAML

examples/environments/Byggfile.yml

@@ -9,9 +9,10 @@ actions:
       rm -Rf .venv .venv1 .venv2
 
   default_action:
-    description: "The default action. Runs in the default environment."
-    message: "Running in default env"
+    description: "The default action. Runs in the base environment."
+    message: "Running in base env"
     dependencies: ["default_action_python"]
+    environment: base
 
   action1:
     description: "Action that runs in env1."
@@ -60,8 +61,8 @@ environments:
         .venv2/bin/pip install -e ../../
       fi
 
-  default:
-    name: "Default environment"
+  base:
+    name: "Base environment"
     byggfile: "Byggfile.py"
     inputs:
       - requirements.txt

src/bygg/cmd/completions.py

@@ -163,9 +163,9 @@ def __call__(
     ):
         import textwrap
 
-        from bygg.cmd.dispatcher import dispatcher
+        from bygg.cmd.dispatcher import parent_dispatcher
 
-        subprocess_data = dispatcher(parser, parsed_args)
+        subprocess_data = parent_dispatcher(parser, parsed_args)
         if not subprocess_data:
             return {}
 

src/bygg/cmd/configuration.py

@@ -14,7 +14,7 @@
 TOML_INPUTFILE = "Byggfile.toml"
 YAML_INPUTFILE = "Byggfile.yml"
 
-DEFAULT_ENVIRONMENT_NAME = "default"
+DEFAULT_ENVIRONMENT_NAME = "_BYGG_DEFAULT_NULL_ENVIRONMENT"
 
 
 @dataclasses.dataclass
@@ -35,7 +35,7 @@ def merge(self, other: "Settings"):
 
 @dataclasses.dataclass
 class ActionItem:
-    __doc__ = f"""
+    """
     This is a representation of the Action class used for deserialising from YAML.
     The name of the action is the key in the dictionary in the config file.
 
@@ -56,7 +56,7 @@ class ActionItem:
         executed directly from the command line. If not set, this is treated as true by
         default in Byggfile.yml and false when used from Python. Default is None.
     environment : str, optional
-        The environment for the action. Default is "{DEFAULT_ENVIRONMENT_NAME}".
+        The environment for the action. Default is to run in the ambient environment.
     shell : str, optional
         The shell command to execute when the action is run. Default is None.
     """

src/bygg/cmd/datastructures.py

@@ -1,6 +1,8 @@
+import argparse
 from dataclasses import dataclass, field
 from typing import Optional
 
+from bygg.cmd.argument_parsing import ByggNamespace
 from bygg.cmd.configuration import Byggfile
 from bygg.core.runner import ProcessRunner
 from bygg.core.scheduler import Scheduler
@@ -29,6 +31,7 @@ class SubProcessIpcData:
     found_actions: set[str] = field(default_factory=set)
     list: Optional[SubProcessIpcDataList] = None
     tree: Optional[SubProcessIpcDataTree] = None
+    return_code: int = 0
 
 
 @dataclass
@@ -38,7 +41,10 @@ class ByggContext:
     runner: ProcessRunner
     scheduler: Scheduler
     configuration: Byggfile
-    ipc_data: Optional[SubProcessIpcData] = None
+    parser: argparse.ArgumentParser
+    args_namespace: argparse.Namespace
+    bygg_namespace: ByggNamespace
+    ipc_data: SubProcessIpcData
 
 
 @dataclass