deps (tyro): 2× faster CLI parser

Author: e3rd

docs/Changelog.md

@@ -1,10 +1,12 @@
 # Changelog
 
+## unreleased
+* deps (tyro): new (2× faster) backend for CLI parser
+
 ## 1.3.1 (2026-06-13)
 * fix: catch all tkinter import/startup failures as InterfaceNotAvailable
 * fix (security): replace eval() with ast.literal_eval in file picker
 
-
 ## 1.3.0 (2026-06-11)
 * feat: tkinter and textual in a separated processes
 * feat: robust exception propagation from child processes

mininterface/_lib/cli_flags.py

@@ -1,9 +1,8 @@
-from argparse import ArgumentParser
 import logging
 import sys
 from typing import Optional, Sequence
 
-from tyro.conf import FlagConversionOff
+from tyro.conf import FlagConversionOff, FlagCreatePairsOff, UseCounterAction
 
 from .form_dict import EnvClass
 
@@ -70,7 +69,6 @@ def __init__(
         self.field_list: list[FieldDefinition] = []
         """ List of FieldDefinitions corresponding to the arguments added via this helper"""
 
-        self.arguments_prepared: list[dict[str, Any]] = []
         self.setup_done = False
         """ Setup might be called multiple times – ex. parsing fails and we call tyro.cli in recursion. """
 
@@ -143,25 +141,34 @@ def add_typed_argument(
         default: Any = False,
         helptext: Optional[str] = None,
         metavar: Optional[str] = None,
-        version: Optional[str] = None,
     ) -> FieldDefinition:
         # Prepare FieldDefinition
         name = aliases[0]
         aliases_ = tuple((prefix * (1 if len(n) == 1 else 2) + n) for n in aliases) if aliases else None
         typ_ = bool if action in ("store_true", "store_false") else int if action == "count" else str
 
+        # Markers drive the lowering when the FieldDefinition is parsed by the native
+        # tyro backend (with the argparse backend, parsing is done by parser.add_argument
+        # and the FieldDefinition is used for the helptext only).
+        if action == "count":
+            markers = {UseCounterAction}
+        elif action in ("store_true", "store_false"):
+            markers = {FlagCreatePairsOff}
+        else:
+            markers = {FlagConversionOff}
+
         field = FieldDefinition(
             intern_name=name,
             extern_name=name,
             type=typ_,
             type_stripped=typ_,
             default=default,
             helptext=helptext,
-            markers={FlagConversionOff},
+            markers=markers,
             custom_constructor=False,
             argconf=_ArgConfig(
                 name=aliases_[0],
-                metavar="",
+                metavar=metavar or "",
                 help=helptext,
                 help_behavior_hint="",
                 aliases=aliases_[1:] or None,
@@ -175,29 +182,16 @@ def add_typed_argument(
 
         self.field_list.append(field)
 
-        # prepare argparse
-        self.arguments_prepared.append(
-            {
-                "field": field,
-                "names": aliases_,
-                "kwargs": {
-                    "action": action,
-                    "default": default,
-                    "help": helptext,
-                    "metavar": metavar,
-                    "version": version,
-                },
-            }
-        )
-
         return field
 
-    def setup(self, parser: ArgumentParser):
+    def setup(self):
+        """Build the field_list; the fields are then injected into the ParserSpecification
+        in tyro_patches.tyro_parse_args."""
         if self.setup_done:
             # tyro.cli might be called multiple times if some missing required fields
             return
         self.setup_done = True
-        prefix = "-" if "-" in parser.prefix_chars else parser.prefix_chars[0]
+        prefix = "-"
         if self.add_verbose:
             self.add_typed_argument(
                 prefix,
@@ -209,11 +203,11 @@ def setup(self, parser: ArgumentParser):
             )
 
         if self.add_version:
+            # The flag itself is handled by a pre-scan in tyro_patches.tyro_parse_args,
+            # the field serves the helptext.
             self.add_typed_argument(
                 prefix,
                 "version",
-                action="version",
-                version=self.version,
                 default="",
                 helptext=f"show program's version number ({self.version}) and exit",
             )
@@ -228,7 +222,39 @@ def setup(self, parser: ArgumentParser):
                 prefix, "config", helptext=f"path to config file to fetch the defaults from", metavar="PATH"
             )
 
-    def apply_to_parser(self, parser):
-        for item in self.arguments_prepared:
-            kwargs = {k: v for k, v in item["kwargs"].items() if v is not None}
-            parser.add_argument(*item["names"], **kwargs)
+    def consume_output(self, out: dict):
+        """Pop our injected flags from the parsed output dict
+        (so that they do not reach the env dataclass construction) and apply them."""
+        if self.add_verbose and "verbose" in out:
+            verbose = out.pop("verbose") or 0
+            self.apply_verbosity(verbose)
+        if self.add_quiet and "quiet" in out:
+            if out.pop("quiet"):
+                self.apply_verbosity(-1, quiet=True)
+        if self.add_version:
+            out.pop("version", None)
+        if self.add_config:
+            out.pop("config", None)
+
+    def apply_verbosity(self, count: int, quiet=False):
+        """Set up the root logger according to the number of -v flags (or -q for count=-1)."""
+        root = logging.getLogger()
+        if quiet:
+            new_level = self.get_log_level(-1)
+            if not root.handlers:
+                logging.basicConfig(level=new_level, format="%(message)s", stream=self.orig_stream)
+            else:
+                root.setLevel(new_level)
+                for handler in root.handlers:
+                    if handler.level < new_level:  # edit just benevolent handlers
+                        handler.setLevel(new_level)
+            return
+        if not root.handlers:
+            level = self.get_log_level(count) if count > 0 else self.default_verbosity
+            logging.basicConfig(level=level, format="%(message)s", stream=self.orig_stream)
+        elif count > 0:
+            level = self.get_log_level(count)
+            root.setLevel(level)
+            for handler in root.handlers:
+                if handler.level > level:  # increase verbosity for strict handlers
+                    handler.setLevel(level)

mininterface/_lib/cli_parser.py

@@ -34,31 +34,24 @@
 try:
     from .cli_flags import CliFlags
     from tyro import cli
-
-    try:  # tyro >= 0.10
-        from tyro import _experimental_options
-
-        _experimental_options["backend"] = "argparse"
-        from tyro._backends._argparse import _SubParsersAction, ArgumentParser
-        from tyro._backends._argparse_formatter import TyroArgumentParser
-    except ImportError:
-        from tyro._argparse import _SubParsersAction, ArgumentParser
-        from tyro._argparse_formatter import TyroArgumentParser
-    from tyro._parsers import ParserSpecification
+    from tyro import _experimental_options
+    from tyro._backends import _tyro_help_formatting
+    from tyro._backends._tyro_backend import TyroBackend
+    from tyro._parsers import ParserSpecification, SubparsersSpecification, ArgWithContext
 
     from tyro.conf import OmitArgPrefixes, OmitSubcommandPrefixes, DisallowNone, FlagCreatePairsOff
 
     from .tyro_patches import (
         _crawling,
-        custom_error,
-        custom_init,
-        custom_parse_known_args,
         failed_fields,
-        patched__parse_known_args,
-        patched__format_help,
-        subparser_call,
-        argparse_init,
+        tyro_required_args_error,
+        tyro_error_and_exit,
+        tyro_parse_args,
     )
+
+    # The native backend (tyro >= 1.0) is ~2-3× faster than the argparse one
+    # (HeavyNesting: 15 ms → 5 ms) and is the only one mininterface patches support.
+    _experimental_options["backend"] = "tyro"
 except ImportError:
     from ..exceptions import DependencyRequired
 
@@ -250,7 +243,7 @@ def annot(type_form):
                     if sys.version_info < (3, 11):
                         raise
                     # Form did not work, cancelled or run through minadaptor.
-                    # We use the original tyro exception message, caught in tyro_patches.custom_error
+                    # We use the original tyro exception message, noted in tyro_patches.tyro_required_args_error
                     # instead of a validation error the minadaptor might produce.
                     # NOTE We might add minadaptor validation error. But it seems too similar to the better tyro's one.
                     # if str(e):
@@ -297,7 +290,7 @@ def _try_with_subcommands(kwargs, m, args, type_form, env_classes, _custom_regis
     old_defs = kwargs.get("default", {})
     if old_defs:
         old_defs = asdict(old_defs)
-    passage = [cl_name for _, cl_name, _ in _crawling.get()]
+    passage = [cl_name for cl_name, _ in _crawling.get()]
 
     if len(env_classes) > 1:
         if len(passage):
@@ -322,42 +315,21 @@ def _try_with_subcommands(kwargs, m, args, type_form, env_classes, _custom_regis
 
 
 def _apply_patches(cf: Optional[CliFlags], ask_for_missing, env_classes, kwargs):
-    patches = []
-
-    patches.append(patch.object(_SubParsersAction, "__call__", subparser_call))
-    patches.append(patch.object(TyroArgumentParser, "_parse_known_args", patched__parse_known_args))
-    kw = {
-        k: v for k, v in kwargs.items() if k != "default"
-    }  # NOTE I might separate kwargs['default'] and do not do this filtering
-    if kw:
-        patches.append(patch.object(ArgumentParser, "__init__", argparse_init(kw)))
-
-    if ask_for_missing:  # Get the missing flags from the parser
-        patches.append(patch.object(TyroArgumentParser, "error", custom_error))
-    if cf and cf.should_add(env_classes):
-        # Mock parser to add some flags
-        # Flags are added only if neither the env_class nor any of the subcommands have the same-name flag already
-        patches.extend(
-            (
-                patch.object(
-                    TyroArgumentParser,
-                    "__init__",
-                    custom_init(cf),
-                ),
-                patch.object(
-                    TyroArgumentParser,
-                    "format_help",
-                    patched__format_help(cf),
-                ),
-                patch.object(
-                    TyroArgumentParser,
-                    "parse_known_args",
-                    custom_parse_known_args(cf),
-                ),
-            )
-        )
-
-    return patches
+    """Patches for the native tyro backend. See tyro_patches for details.
+    CliFlags are added only if neither the env_class nor any of the subcommands
+    have the same-name flag already."""
+    return [
+        patch.object(_tyro_help_formatting, "required_args_error", tyro_required_args_error(ask_for_missing)),
+        patch.object(_tyro_help_formatting, "error_and_exit", tyro_error_and_exit(ask_for_missing)),
+        patch.object(
+            TyroBackend,
+            "parse_args",
+            tyro_parse_args(
+                cf if cf and cf.should_add(env_classes) else None,
+                allow_abbrev=kwargs.get("allow_abbrev", False),
+            ),
+        ),
+    ]
 
 
 def _dialog_missing(
@@ -375,7 +347,7 @@ def _dialog_missing(
 
     * kwargs["default"]. Struct (dataclass). The fields that must be filled are marked as MISSING_NONPROP.
         If marked directly with `tag._make_default_value()`, tyro would resolve CLI instantly with no further problem but we would never known which were missing CLI flags were missing.
-    * failed_fields – Argparse Actions. Parser needs them filled. (It might not tell us about all of them. There is a use-case when superparser is resolved after subparser. And if whole subparser command is missing, its fields are not there either.)
+    * failed_fields – ArgWithContext / SubparsersSpecification. Parser needs them filled. (It might not tell us about all of them. There is a use-case when superparser is resolved after subparser. And if whole subparser command is missing, its fields are not there either.)
     * req_fields – Tags. The same form as kwargs["default"]. Recursively all fields, needed to build up a dataclass for mininterface. The fields that must be filled are marked as MissingTagValue().
     * missing_req – Tags. Those req_fields which are missing from CLI. Merge of failed_fields and req_fields. (Subset of req_fields.)
         Their values are `tag._make_default_value()`.
@@ -408,7 +380,7 @@ def _dialog_missing(
             req_fields,
             m,
             subc=kwargs.get("subcommands_default"),
-            subc_passage=[cl_name for _, cl_name, _ in _crawling.get()],
+            subc_passage=[cl_name for cl_name, _ in _crawling.get()],
         )
 
     missing_req = _fetch_currently_failed(req_fields)
@@ -475,16 +447,24 @@ def _fetch_currently_failed(requireds) -> TagDict:
     who pose problem for tyro (through implanted failed_fields)."""
     missing_req = {}
     for field in failed_fields.get():
-        # ex: `_subcommands._nested_subcommands (positional)`
+        # Determine the dest-like dotted name, ex: `_subcommands._nested_subcommands (positional)`
+        if isinstance(field, SubparsersSpecification):
+            # a whole subcommand is missing
+            dest = field.intern_prefix
+        else:
+            # ArgWithContext, a required argument is missing
+            # (get_output_key gives lowered.dest, or the positional name)
+            dest = field.arg.get_output_key()
+
         fname = (
-            field.dest.replace(" (positional)", "")
+            dest.replace(" (positional)", "")
             .replace("-", "_")
             .replace("__tyro_dummy_inner__.", "")
             .replace("__tyro_dummy_inner__", "")
         )  # `_subcommands._nested_subcommands`
         fname_raw = fname.rsplit(".", 1)[-1]  # `_nested_subcommands`
 
-        if isinstance(field, _SubParsersAction):
+        if isinstance(field, SubparsersSpecification):
             # The function create_with_missing don't makes every encountered field a wrong field
             # (with the exception of the config fields, defined in the kwargs["default"] earlier).
             # The CLI options are unknown to it.