feat: add_config flag #26

Author: e3rd

docs/Changelog.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## unreleased
+* feat: [`run`][mininterface.run] add_config flag
+
 ## 1.1.4 (2025-10-13)
 * enh: Python 3.14 compatible
 

docs/Config-file.md

@@ -1,11 +1,18 @@
 # Config file
 Any settings you see in the `--help` command can be modified via a YAML config file.
 
-By default, we try to find one in the current working dir, whose name stem is the same as the program's. Ex: program.py will search for program.yaml. This behaviour can be changed via the [run][mininterface.run] method.
+By default, we try to find one in the current working dir, whose name stem is the same as the program's. Ex: program.py will search for program.yaml. This behaviour can be changed via the [run][mininterface.run] method `config_file` or `add_config` parameters or via `MININTERFACE_CONFIG` environment variable.
 
 !!! Tip
     You do not have to re-define all the settings in the config file, you can choose a few.
 
+## 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`
+
 ## Basic example
 
 We have this nested structure:

mininterface/_lib/cli_flags.py

@@ -15,14 +15,17 @@ class CliFlags:
     default_verbosity: int = logging.WARNING
     _verbosity_sequence: Optional[Sequence[int]] = None
 
+    config: bool = False
+
     def __init__(
         self,
         add_verbose: bool | int | Sequence[int] = False,
         add_version: Optional[str] = None,
         add_version_package: Optional[str] = None,
         add_quiet: bool = False,
+        add_config: bool = False,
     ):
-        self._enabled = {"verbose": True, "version": True, "quiet": True}
+        self._enabled = {"verbose": True, "version": True, "quiet": True, "config": True}
         # verbosity
         match add_verbose:
             case bool():
@@ -50,13 +53,17 @@ def __init__(
             except PackageNotFoundError:
                 self.version = f"package {add_version_package} not found"
 
+        # config
+        self.config = add_config
+
     def should_add(self, env_classes: list[EnvClass]) -> bool:
         # Flags are added only if neither the env_class nor any of the subcommands have the same-name flag already
         self._enabled["verbose"] = self._add_verbose and self._attr_not_present("verbose", env_classes)
         self._enabled["quiet"] = self._add_quiet and self._attr_not_present("quiet", env_classes)
         self._enabled["version"] = self.version and self._attr_not_present("version", env_classes)
+        self._enabled["config"] = self.config and self._attr_not_present("config", env_classes)
 
-        return self.add_verbose or self.add_version or self.add_quiet
+        return self.add_verbose or self.add_version or self.add_quiet or self.add_config
 
     def _attr_not_present(self, flag, env_classes):
         return all(flag not in cl.__annotations__ for cl in env_classes)
@@ -73,6 +80,10 @@ def add_version(self):
     def add_quiet(self):
         return self._add_quiet and self._enabled["quiet"]
 
+    @property
+    def add_config(self):
+        return self.config and self._enabled["config"]
+
     def get_log_level(self, count):
         """
         Ex.

mininterface/_lib/run.py

@@ -32,6 +32,7 @@ def run(
     title: str = "",
     config_file: Path | str | bool = True,
     *,
+    add_config: bool = False,
     add_help: bool = True,
     add_verbose: bool|int|Sequence[int] = True,
     add_version: Optional[str] = None,
@@ -83,9 +84,13 @@ class Env:
             whose name stem is the same as the program's.
             Ex: `program.py` will search for `program.yaml`.
             If False, no config file is used.
+
+            Might be superseded by `add_config` or `MININTERFACE_CONFIG` environment variable.
+
             See the [Config file](Config-file.md) section.
-        add_help: Adds the help flag.
-        add_verbose: The default base Python verbosity logging level is `logging.WARNING`. Here you can add the verbose flag that automatically increases the level to `logging.INFO` (*-v*) or `logging.DEBUG` (*-vv*).
+        add_config: Adds the `--config` flag to change the config file location.
+        add_help: Adds the `--help` flag.
+        add_verbose: Adds the `--verbose` flag. The default base Python verbosity logging level is `logging.WARNING`. Here you can add the verbose flag that automatically increases the level to `logging.INFO` (*-v*) or `logging.DEBUG` (*-vv*).
             Either, the value is `True` (the default) which means the base logging level stays at `logging.WARNING` and the flag is added. `False` means no flag is added.
             Also, it can be `int` to determine the default logging state (i.g. some programs prefer to show INFO by default) or a sequnce of `int`s for even finer control.
 
@@ -140,7 +145,7 @@ class Env:
 
             When user writes more `-v` than defined, the level sets to `logging.NOTSET`.
 
-        add_version: Your program version. Adds the version flag.
+        add_version: Adds the `--version` flag to print out your program's version.
             ```python
             run(add_version="1.2.5")
             ```
@@ -155,7 +160,7 @@ class Env:
             ╰─────────────────────────────────────────────────────────────────────╯
             ```
 
-        add_quiet: Decrease verbosity, only print warnings and errors.
+        add_quiet: Adds the `--quiet` flag to decrease the verbosity and only print warnings and errors.
             ```python
             import logging
             logger = logging.getLogger(__name__)
@@ -236,7 +241,27 @@ class Env:
     if not add_help:
         kwargs["add_help"] = False
 
+    # Assure args
+    if isinstance(assure_args, DependencyRequired) and not env_or_list:
+        # Basic dependencies missing, we have no CLI capacities
+        # Since the user needs no CLI, we return a bare interface.
+        return get_interface(interface, title)
+    args = assure_args(args)
+
     # Prepare the config file
+    if cf:= environ.get("MININTERFACE_CONFIG"):
+        config_file = cf
+    if add_config and "--config" in args:
+        # Detect the `--config` and pop it.
+        # `--flag --config FILE --flag2` -> `--flag --flag2`
+        args = list(args)
+        idx = args.index("--config")
+        try:
+            config_file = args[idx + 1]
+        except IndexError:
+            raise ValueError("Missing value after --config")
+        else:
+            del args[idx:idx + 2]
     if config_file is True and not kwargs.get("default"):
         # Undocumented feature. User put a namespace into kwargs["default"]
         # that already serves for defaults. We do not fetch defaults yet from a config file.
@@ -260,12 +285,6 @@ class Env:
     if environ.get("MININTERFACE_ENFORCED_WEB"):
         interface = "web"
 
-    if isinstance(assure_args, DependencyRequired) and not env_or_list:
-        # Basic dependencies missing, we have no CLI capacities
-        # Since the user needs no CLI, we return a bare interface.
-        return get_interface(interface, title)
-    args = assure_args(args)
-
     # Hidden meta-commands in args
     if environ.get("MININTERFACE_INTEGRATE_TO_SYSTEM"):
         del environ["MININTERFACE_INTEGRATE_TO_SYSTEM"]
@@ -306,7 +325,7 @@ class Env:
         args[0] = to_kebab_case(choose_subcommand(env_or_list, m).__name__)
 
     # Parse CLI arguments, possibly merged from a config file.
-    cf = _CliFlags(add_verbose, add_version, add_version_package, add_quiet)
+    cf = _CliFlags(add_verbose, add_version, add_version_package, add_quiet, add_config)
     if env_or_list:
         # A single Env object, or a list of such objects (with one is not/being selected via args)
         # Load configuration from CLI and a config file

mininterface/_lib/tyro_patches.py

@@ -347,6 +347,13 @@ def _(self: TyroArgumentParser, *args, **kwargs):
                 help="suppress warnings, display only errors",
             )
 
+        if cf.add_config:
+            self.add_argument(
+                default_prefix * 2 + "config",
+                help=f"path to config file to fetch the defaults from",
+                metavar="PATH"
+            )
+
     return _
 
 
@@ -369,6 +376,11 @@ def _(self: TyroArgumentParser, args=None, namespace=None):
         #         raise SystemExit(0)
         #     delattr(namespace, "version")
 
+        # Note that we do not parse --config here as it is parsed at `run.py`, before CLI parsing.
+        # Since config file serves as default fo CLI parsing.
+        if cf.add_config and hasattr(namespace, "config"):
+            delattr(namespace, "config")
+
         if cf.add_quiet and hasattr(namespace, "quiet"):
             if namespace.quiet:
                 logging.basicConfig(level=cf.get_log_level(-1), format="%(message)s", force=True)

tests/test_run.py

@@ -1,6 +1,7 @@
 from tempfile import NamedTemporaryFile
 from unittest import skipUnless
 from mininterface import Mininterface
+from mininterface._lib import config_file
 from mininterface._lib.config_file import ensure_settings_inheritance
 from mininterface._lib.run import run
 from mininterface.settings import UiSettings, MininterfaceSettings as MSOrig
@@ -258,6 +259,24 @@ def r(model):
                 r(model)
                 self.assertIn("Unknown fields in the configuration file", str(w[0].message))
 
+    def test_add_config(self):
+        for add_config, config_file, expected, args, env_vars in [
+            (True, True, 4, [], {}),
+            (True, True, 10, ["--config", "tests/SimpleEnv.yaml"], {"MININTERFACE_CONFIG": "SimpleEnv.yaml"}),
+            (True, True, 20, ["--config", "tests/SimpleEnv2.yaml"], {"MININTERFACE_CONFIG": "SimpleEnv.yaml"}),
+            (True, True, 10, [], {"MININTERFACE_CONFIG": "tests/SimpleEnv.yaml"}),
+            (True, True, 20, [], {"MININTERFACE_CONFIG": "tests/SimpleEnv2.yaml"}),
+            (False, True, 20, [], {"MININTERFACE_CONFIG": "tests/SimpleEnv2.yaml"}),
+            (False, False, 20, [], {"MININTERFACE_CONFIG": "tests/SimpleEnv2.yaml"}),
+            (True, False, 20, ["--config", "tests/SimpleEnv2.yaml"], {}),
+        ]:
+            with self.subTest(args=args):
+                with patch.dict(os.environ, env_vars):
+                    self.assertEqual(
+                        expected,
+                        runm(SimpleEnv, args, add_config=add_config, config_file=config_file).env.important_number,
+                    )
+
     def test_settings(self):
         # NOTE
         # The settings had little params at the moment of the test writing.