feat: subcommands in the config file

Author: e3rd

docs/Changelog.md

@@ -2,6 +2,7 @@
 
 ## unreleased
 * feat: [`run`][mininterface.run] add_config flag
+* feat: [subcommands](Supported-types.md/#dataclasses-union-subcommand) allowed in the config file
 
 ## 1.1.4 (2025-10-13)
 * enh: Python 3.14 compatible

docs/Config-file.md

@@ -8,10 +8,10 @@ By default, we try to find one in the current working dir, whose name stem is th
 
 ## Search order by highest priority
 
-* `$ program.py --config PATH` with `run(add_config=True)` will load `PATH`
-* `$ MININTERFACE_CONFIG=PATH program.py` will load `PATH`
-* `$ program.py` with `run(config_file=PATH)` will load `PATH`
-* `$ program.py` with `run(config_file=True)` will load `program.yaml`
+*  will load `conf.yaml`: `$ program.py --config conf.yaml` with `run(add_config=True)`
+*  will load `conf.yaml`: `$ MININTERFACE_CONFIG=conf.yaml program.py`
+*  will load `conf.yaml`: `$ program.py` with `run(config_file=conf.yaml)`
+*  will load `program.yaml`: `$ program.py` with `run(config_file=True)`
 
 ## Basic example
 

docs/Supported-types.md

@@ -243,7 +243,7 @@ run(Env)
 
 ![SelectTag multiple](asset/selecttag-multiple.avif)
 
-### Nested dataclasses or their unions (subcommands)
+### Dataclass (→ subgroup)
 
 You can nest the classes to create a subgroup:
 
@@ -261,6 +261,15 @@ run(Env)
 
 ![Nested dataclass](asset/nested-dataclass.avif)
 
+In the config file, it behaves like a dict:
+
+```yaml
+val:
+    text: text from a config file
+```
+
+### Dataclasses union (→ subcommand)
+
 You can union the classes to create subcommands:
 
 ```python
@@ -323,14 +332,21 @@ First, we've chosen `Console`, then `Console rich`.
 
 ??? "Shorter CLI notation"
 
-    Instead of plain `Env`, we can annotate it
+    This is how in looks in CLI:
+
+    ```bash
+    $ ./program.py --help
+    usage: program.py [-h] [-v] {val:message,val:console}
+    ```
+
+    Is that too long for you? Instead of plain `Env`, use the settings:
 
     ```python
     from mininterface.settings import CliSettings
     m = run(Env, settings=CliSettings(omit_subcommand_prefixes=True))
     ```
 
-    In the background, it does the same thing as applying an annotation from the underlying CLI library `tyro`.
+    In the background, it does the same thing as applying an annotation marker from the underlying CLI library `tyro`.
 
     ```python
     from tyro.conf import OmitSubcommandPrefixes
@@ -344,11 +360,16 @@ First, we've chosen `Console`, then `Console rich`.
     usage: program.py [-h] [-v] {message,console}
     ```
 
-    Without:
-    ```bash
-    $ ./program.py --help
-    usage: program.py [-h] [-v] {val:message,val:console}
-    ```
+In the config file, put a dict where subcommands are in the kebab case. Here, we define some config defaults for `ConsoleRich`, leaving `Message` and `ConsolePlain` without config defaults.
+
+```yaml
+val:
+    console:
+        bot-id: id-two
+        style:
+            console-rich:
+                color:  green
+```
 
 ### Well-known objects
 

mininterface/_lib/cli_parser.py

@@ -3,9 +3,11 @@
 #
 from dataclasses import asdict
 from functools import reduce
+from io import StringIO
+from multiprocessing import Value
 import sys
 from collections import deque
-from contextlib import ExitStack
+from contextlib import ExitStack, redirect_stderr, redirect_stdout
 from typing import Annotated, Optional, Sequence, Type, Union
 from unittest.mock import patch
 
@@ -21,10 +23,11 @@
     flatten,
 )
 from .dataclass_creation import (
-    ChosenSubcommand,
     _unwrap_annotated,
     choose_subcommand,
     create_with_missing,
+    get_chosen,
+    pop_from_passage,
     to_kebab_case,
 )
 from .form_dict import EnvClass, TagDict, dataclass_to_tagdict, MissingTagValue, dict_added_main
@@ -68,14 +71,17 @@ def assure_args(args: Optional[Sequence[str]] = None):
             args = []
     return args
 
+def _subcommands_default_appliable(kwargs, _crawling):
+    if len(_crawling.get()):
+                return kwargs.get("subcommands_default")
 
 def parse_cli(
     env_or_list: Type[EnvClass] | list[Type[EnvClass]],
     kwargs: dict,
     m: "Mininterface",
     cf: Optional[CliFlags] = None,
     ask_for_missing: bool = True,
-    args: Optional[Sequence[str]] = None,
+    args: Optional[Sequence[str]] = None,  # NOTE no more Optional, change the arg order
     ask_on_empty_cli: Optional[bool] = None,
     cli_settings: Optional[CliSettings] = None,
     _crawled=None,
@@ -89,6 +95,7 @@ def parse_cli(
     """
     # Xint: The depth we crawled into. The number of subcommands in args.
     # NOTE ask_on_empty_cli might reveal all fields (in cli_parser), not just wrongs. Eg. when using a subparser `$ prog run`, reveal all subparsers.
+    _req_fields = _req_fields or {}
 
     if isinstance(env_or_list, list):
         # We have to convert the list of possible classes (subcommands) to union for tyro.
@@ -149,17 +156,72 @@ def annot(type_form):
                 warn(f"Cannot apply {annotations} on Python <= 3.11.")
         return type_form
 
+
+    #
+    # --- Begin to launch tyro.cli ---
+    # This will be divided into four sections.
+    # (A) First parse section
+    # (B) Re-parse with subcommand-config ensured section
+    # (C) The dialog missing section
+    # (D) The nothing was missing section
+    #
+    enforce_dialog = False
+    """ When subcommand-chooser was raised (hence the CLI input was not completely working and without mininterface it would raise an error),
+    we make sure we display whole CLI overview form at the end."""
+
     try:
         with ExitStack() as stack:
             [stack.enter_context(p) for p in patches]  # apply just the chosen mocks
+
+            # --- (A) First parse section ---
+
+            # Let me explain this awful structure.
+            # If we have subcommanded-config file, we first need the tyro to do the parsing as it leaks the crawled path (through the subcommands).
+            # Then, we can fill the kwargs['default'] from the subcommanded-config and do the second parsing with some field filled up.
+            buffer = StringIO()
+            helponly = False
             try:
-                env = cli(annot(type_form), args=args, registry=_custom_registry, **kwargs)
-            except BaseException:
-                # Why this exception handling? Try putting this out and test_strange_error_mitigation fails.
-                if len(env_classes) > 1 and kwargs.get("default"):
-                    env = cli(annot(kwargs["default"].__class__), args=args[1:], registry=_custom_registry, **kwargs)
+                # Why redirect_stdout? Help-text shows the defaults, which also uses the subcommanded-config.
+                with redirect_stdout(buffer):
+                    try:
+                        # Standard way.
+                        env = cli(annot(type_form), args=args, registry=_custom_registry, **kwargs)
+                    except BaseException:
+                        # Why this exception handling? Try putting this out and test_strange_error_mitigation fails.
+                        if len(env_classes) > 1 and kwargs.get("default"):
+                            env = cli(annot(kwargs["default"].__class__), args=args[1:], registry=_custom_registry, **kwargs)
+                        else:
+                            raise
+            except SystemExit as exception:
+                # This catch handling is just for the subcommanded-config.
+                # Not raising this exception means it worked well and we re-parse with the subcommand-config data just below.
+                if _crawled is None and exception.code == 0 and _subcommands_default_appliable(kwargs, _crawling):
+                    # Help-text exception, continue here and try again with subcommands. As it raises SystemExit first,
+                    # it will raise SystemExit in the second run too.
+                    helponly = True
+                elif _crawled is None and _subcommands_default_appliable(kwargs, _crawling) and exception.code == 2 and failed_fields.get():
+                    # Some fields are missing, directly try again. If it raises again
+                    # (some fields are really missing which cannot be filled from the subcommanded-config),
+                    # it will immediately raise again and trigger the (C) dialog missing section.
+                    # If it worked (and no fields are missing), we continue here without triggering the (C) dialog missing section.
+                    _crawled = True
+                    env, enforce_dialog = _try_with_subcommands(kwargs, m, args, type_form, env_classes, _custom_registry, annot,  _req_fields)
                 else:
+                    # This is either a recurrent call from the (C) dialog missing section (and thus subcommand-config re-parsing was done),
+                    # or there is no subcommand-config data and thus we continue as if this exception handling did not happen.
+                    if content := buffer.getvalue():
+                        print(content)
                     raise
+
+            # --- (B) Re-parse with subcommand-config ensured section ---
+
+            # Re-parse with subcommand-config.
+            # It either raises (if it raised before and subcommand-config did not bring the missing fields) or works well if it worked well before.
+            if _crawled is None and _subcommands_default_appliable(kwargs, _crawling):
+                # Why not catching enforce_dialog here? As we are here, calling tyro.cli worked for the first time.
+                # For sure then, there were no choose_subcommand dialog, subcommands for sure are all written in the CLI.
+                env, _ = _try_with_subcommands(kwargs, None if helponly else m, args, type_form, env_classes, _custom_registry, annot,  _req_fields)
+
             # Why setting m.env instead of putting into into a constructor of a new get_interface() call?
             # 1. Getting the interface is a costly operation
             # 2. There is this bug so that we need to use single interface:
@@ -170,17 +232,18 @@ def annot(type_form):
             #    m = get_interface("gui")
             #    m.select([1,2,3])
             m.env = env
-    except BaseException as exception:
-        if ask_for_missing and getattr(exception, "code", None) == 2 and failed_fields.get():
+    except SystemExit as exception:
+        # --- (C) The dialog missing section ---
+        # Some fields are needed to be filled up.
+        if ask_for_missing and exception.code == 2 and failed_fields.get():
             env = _dialog_missing(
                 env_classes, kwargs, m, cf, ask_for_missing, args, cli_settings, _crawled, _req_fields
             )
 
             if final_call:
                 # Ask for the wrong fields
-                # Why first_attempt? We display the wrong-fields-form only once.
+                # Why final_call? We display the wrong-fields-form only once in the `parse_cli` uppermost call.
                 _ensure_command_init(env, m)
-
                 try:
                     m.form(env)
                 except Cancelled as e:
@@ -201,6 +264,7 @@ def annot(type_form):
         # Parsing wrong fields failed. The program ends with a nice tyro message.
         raise
     else:
+        # --- (D) The nothing was missing section ---
         dialog_raised = False
         if final_call:
             _ensure_command_init(env, m)
@@ -219,14 +283,44 @@ def annot(type_form):
 
             # Empty CLI → GUI edit
             subcommand_count = len(_crawling.get())
-            if not dialog_raised and ask_on_empty_cli and len(sys.argv) <= 1 + subcommand_count:
+            if not dialog_raised and (ask_on_empty_cli and len(args) <= subcommand_count) or enforce_dialog:
                 # Raise a dialog if the command line is empty.
                 # This still means empty because 'run' and 'message' are just subcommands: `program.py run message`
                 m.form()
                 dialog_raised = True
 
         return env, dialog_raised
 
+def _try_with_subcommands(kwargs, m, args, type_form, env_classes, _custom_registry, annot, _req_fields):
+    """ This awful method is here to re-parse the tyro.cli with the subcommand-config """
+
+    failed_fields.set([])
+    old_defs = kwargs.get("default", {})
+    if old_defs:
+        old_defs = asdict(old_defs)
+    passage = [cl_name for _, cl_name, _ in _crawling.get()]
+
+    if len(env_classes) > 1:
+        if len(passage):
+            env, cl_name = pop_from_passage(passage, env_classes)
+            if not old_defs:
+                old_defs = kwargs["subcommands_default_union"][cl_name]
+            subc = kwargs["subcommands_default"].get(cl_name)
+        else: # we should never come here
+            raise ValueError("Subcommands parsing failed")
+    else:
+        env = env_classes[0]
+        subc = kwargs["subcommands_default"]
+    kwargs["default"] = create_with_missing(env, old_defs, _req_fields, m, subc=subc, subc_passage=passage)
+    dialog_used = False
+    if hasattr(m, "__subcommand_dialog_used"):
+        delattr(m, "__subcommand_dialog_used")
+        dialog_used = True
+
+    env = cli(annot(type_form), args=args, registry=_custom_registry, **kwargs)
+
+    return env, dialog_used
+
 
 def _apply_patches(cf: Optional[CliFlags], ask_for_missing, env_classes, kwargs):
     patches = []
@@ -272,7 +366,7 @@ def _dialog_missing(
     args: Optional[Sequence[str]],
     cli_settings,
     crawled,
-    req_fields: Optional[TagDict],
+    req_fields: TagDict,
 ) -> EnvClass:
     """Some required arguments are missing. Determine which and ask for them.
 
@@ -288,10 +382,8 @@ def _dialog_missing(
     * env – Tyro's merge of CLI and kwargs["default"].
 
     """
-    req_fields = req_fields or {}
-
     # There are multiple dataclasses, query which is chosen
-    m, env_cl = _ensure_chosen_env(env_classes, args, m)
+    env_cl = _ensure_chosen_env(env_classes, args, m, kwargs)
 
     if crawled is None:
         # This is the first correction attempt.
@@ -302,16 +394,12 @@ def _dialog_missing(
         # So in further run, there is no need to rebuild the data. We just process new failed_fields reported by tyro.
 
         # Merge with the config file defaults.
-        disk = d = asdict(dc) if (dc := kwargs.get("default")) else {}
-        crawled = [None]
-        for _, val, field_name in _crawling.get():
-            # NOTE this might be ameliorated so that config file can define subcommands too, now we throw everything out
-            subd = {}
-            d[field_name] = ChosenSubcommand(val, subd)
-            d = subd
-            crawled.append(val)
-
-        kwargs["default"] = create_with_missing(env_cl, disk, req_fields, m)
+        if len(env_classes) > 1:
+            disk = kwargs.get("subcommands_default_union", {})
+        else:
+            disk = asdict(dc) if (dc := kwargs.get("default")) else {}
+        crawled = True
+        kwargs["default"] = create_with_missing(env_cl, disk, req_fields, m, subc=kwargs.get("subcommands_default"), subc_passage=[cl_name for _, cl_name, _ in _crawling.get()])
 
     missing_req = _fetch_currently_failed(req_fields)
     """ Fields required and missing from CLI """
@@ -341,10 +429,15 @@ def _dialog_missing(
     return env
 
 
-def _ensure_chosen_env(env_classes, args, m):
+def _ensure_chosen_env(env_classes, args, m, kwargs):
+    # NOTE by preference, handling subclasses union should be done
+    # by making an arbitrary dataclass, having single subcommands attribute.
+    # That way, all the mendling with the env_classes list would disappear from many places in the code as
+    # we already support subclasses in attribute – and this awful function would disappear.
     env = None
     if len(env_classes) == 1:
         env = env_classes[0]
+        return env
     elif len(args):
         env = next(
             (env for env in env_classes if to_kebab_case(env.__name__) == args[0]),
@@ -356,7 +449,14 @@ def _ensure_chosen_env(env_classes, args, m):
         env = choose_subcommand(env_classes, m)
     if not env:
         raise NotImplementedError("This case of nested dataclasses is not implemented. Raise an issue please.")
-    return m, env
+
+    cl_name = to_kebab_case(env.__name__)
+    if kwargs.get("subcommands_default"):
+        kwargs["subcommands_default"] = kwargs["subcommands_default"].get(cl_name)
+    if kwargs.get("subcommands_default_union"):
+        kwargs["subcommands_default_union"] = kwargs["subcommands_default_union"].get(cl_name)
+
+    return env
 
 
 def _fetch_currently_failed(requireds) -> TagDict: