Support parsing optionals as positionals (#692)

Author: mauvilsa

CHANGELOG.rst

@@ -19,6 +19,8 @@ Added
 ^^^^^
 - Support ``shtab`` completion of ``Literal`` types (`#693
   <https://github.com/omni-us/jsonargparse/pull/693>`__).
+- Support for parsing optionals as positionals (`#692
+  <https://github.com/omni-us/jsonargparse/pull/692>`__).
 
 Changed
 ^^^^^^^

DOCUMENTATION.rst

@@ -332,6 +332,53 @@ This can be easily implemented with :func:`.capture_parser` as follows:
     :func:`.auto_cli` is by using :func:`.capture_parser`.
 
 
+Optionals as positionals
+------------------------
+
+It can sometimes be useful to allow optional arguments to be passed both by
+name, such as ``--key=val``, and as positional arguments, such as ``val``. This
+behavior can be enabled by using
+``set_parsing_settings(parse_optionals_as_positionals=True)``. Key points to
+note about this feature are:
+
+- Only optional arguments that accept exactly one value can be passed as
+  positional, i.e., when ``nargs`` is not specified or is set to ``nargs=1``.
+- Optional arguments with subclass types cannot be passed as positional
+  arguments.
+- Optionals are treated as positionals only after the standard positionals and
+  in the order they were added to the parser. The usage section in the help
+  displays the optionals that can be passed as positionals and their order.
+- Optional arguments in parsers with subcommands cannot be passed as
+  positionals. Only the child subparsers, after specifying the subcommand
+  name(s), support this feature.
+
+For instance, consider a parser defined as follows:
+
+.. testcode::
+
+    from jsonargparse import set_parsing_settings
+
+
+    set_parsing_settings(parse_optionals_as_positionals=True)
+
+    parser.add_argument("p1")
+    parser.add_argument("--o2")
+    parser.add_argument("--o3")
+
+The help will display ``p1 [o2 [o3]]`` along with a note indicating that this
+feature is enabled. Name-based parsing, such as ``--o2=val2 --o3=val3 val1``,
+will work as expected. Additionally, the following cases are also valid:
+``--o3=val3 val1 val2`` or ``val1 val2 val3``.
+
+.. note::
+
+    Positional arguments take precedence over optional arguments. This means
+    that if a value is provided both as a positional and as an optional
+    argument, the value from the positional argument will be used, regardless of
+    the order. For example, with the parser above, the command ``val1 val2a
+    --o2=val2b`` would result in ``o2=val1a``.
+
+
 Functions as type
 -----------------
 

jsonargparse/_actions.py

@@ -409,6 +409,7 @@ def print_help(self, call_args):
         if ActionTypeHint.is_callable_typehint(typehint) and hasattr(typehint, "__args__"):
             self.sub_add_kwargs["skip"] = {max(0, len(typehint.__args__) - 1)}
         subparser.add_class_arguments(val_class, dest, **self.sub_add_kwargs)
+        subparser._inner_parser = True
         remove_actions(subparser, (_HelpAction, _ActionPrintConfig, _ActionConfigLoad))
         args = self.get_args_after_opt(parser.args)
         if args:

jsonargparse/_common.py

@@ -34,6 +34,7 @@
 __all__ = [
     "LoggerProperty",
     "null_logger",
+    "set_parsing_settings",
 ]
 
 ClassType = TypeVar("ClassType")
@@ -88,6 +89,63 @@ def parser_context(**kwargs):
             context_var.reset(token)
 
 
+parsing_settings = dict(
+    parse_optionals_as_positionals=False,
+)
+
+
+def set_parsing_settings(*, parse_optionals_as_positionals: Optional[bool] = None) -> None:
+    """
+    Modify settings that affect the parsing behavior.
+
+    Args:
+        parse_optionals_as_positionals: [EXPERIMENTAL] If True, the parser will
+            take extra positional command line arguments as values for optional
+            arguments. This means that optional arguments can be given by name
+            --key=value as usual, but also as positional. The extra positionals
+            are applied to optionals in the order that they were added to the
+            parser.
+    """
+    if isinstance(parse_optionals_as_positionals, bool):
+        parsing_settings["parse_optionals_as_positionals"] = parse_optionals_as_positionals
+    elif parse_optionals_as_positionals is not None:
+        raise ValueError(f"parse_optionals_as_positionals must be a boolean, but got {parse_optionals_as_positionals}.")
+
+
+def get_parsing_setting(name: str):
+    if name not in parsing_settings:
+        raise ValueError(f"Unknown parsing setting {name}.")
+    return parsing_settings[name]
+
+
+def get_optionals_as_positionals_actions(parser, include_positionals=False):
+    from jsonargparse._actions import ActionConfigFile, _ActionConfigLoad, filter_default_actions
+    from jsonargparse._completions import ShtabAction
+    from jsonargparse._typehints import ActionTypeHint
+
+    actions = []
+    for action in filter_default_actions(parser._actions):
+        if isinstance(action, (_ActionConfigLoad, ActionConfigFile, ShtabAction)):
+            continue
+        if ActionTypeHint.is_subclass_typehint(action, all_subtypes=False):
+            continue
+        if action.nargs not in {1, None}:
+            continue
+        if not include_positionals and action.option_strings == []:
+            continue
+        actions.append(action)
+
+    return actions
+
+
+def supports_optionals_as_positionals(parser):
+    return (
+        get_parsing_setting("parse_optionals_as_positionals")
+        and not parser._subcommands_action
+        and not getattr(parser, "_inner_parser", False)
+    )
+
+
 def is_subclass(cls, class_or_tuple) -> bool:
     """Extension of issubclass that supports non-class arguments."""
     try:

jsonargparse/_core.py

@@ -41,9 +41,11 @@
     InstantiatorsDictType,
     class_instantiators,
     debug_mode_active,
+    get_optionals_as_positionals_actions,
     is_dataclass_like,
     lenient_check,
     parser_context,
+    supports_optionals_as_positionals,
 )
 from ._completions import (
     argcomplete_namespace,
@@ -307,6 +309,23 @@ def parse_known_args(self, args=None, namespace=None):
 
         return namespace, args
 
+    def _positional_optionals(self, cfg, unk):
+        if len(unk) == 0 or not supports_optionals_as_positionals(self):
+            return cfg, unk
+
+        for action in get_optionals_as_positionals_actions(self, include_positionals=True):
+            if action.option_strings == []:
+                if cfg.get(action.dest) is None:
+                    self._logger.debug(f"Positional argument {action.dest} missing, aborting _positional_optionals")
+                    break
+                continue
+
+            cfg[action.dest] = self._check_value_key(action, unk.pop(0), action.dest, cfg)
+            if len(unk) == 0:
+                break
+
+        return cfg, unk
+
     def _parse_optional(self, arg_string):
         subclass_arg = ActionTypeHint.parse_argv_item(arg_string)
         if subclass_arg:
@@ -434,6 +453,7 @@ def parse_args(  # type: ignore[override]
 
             with _ActionSubCommands.parse_kwargs_context({"env": env, "defaults": defaults}):
                 cfg, unk = self.parse_known_args(args=args, namespace=cfg)
+                cfg, unk = self._positional_optionals(cfg, unk)
             if unk:
                 self.error(f'Unrecognized arguments: {" ".join(unk)}')
 

jsonargparse/_formatters.py

@@ -23,7 +23,12 @@
     _find_action,
     filter_default_actions,
 )
-from ._common import defaults_cache, parent_parser
+from ._common import (
+    defaults_cache,
+    get_optionals_as_positionals_actions,
+    parent_parser,
+    supports_optionals_as_positionals,
+)
 from ._completions import ShtabAction
 from ._link_arguments import ActionLink
 from ._namespace import Namespace, NSKeyError
@@ -88,15 +93,40 @@ def _get_help_string(self, action: Action) -> str:
 
     def _format_usage(self, *args, **kwargs) -> str:
         usage = super()._format_usage(*args, **kwargs)
+
         parser = parent_parser.get()
-        if parser:
+        if not parser:
+            return usage
+
+        if supports_optionals_as_positionals(parser):
+            actions = get_optionals_as_positionals_actions(parser)
+            if len(actions) > 0:
+                extra_positionals = ""
+                for action in reversed(actions):
+                    extra_positionals = f"{action.dest} {extra_positionals}" if extra_positionals else action.dest
+                    extra_positionals = f"[{extra_positionals}]"
+
+                usage_lines = usage.rstrip().split("\n")
+                last_line = usage_lines[-1] + " " + extra_positionals
+                text_width = self._width - self._current_indent
+                if len(usage_lines) == 1 or len(last_line) <= text_width:
+                    usage_lines[-1] = last_line
+                else:
+                    indent = re.sub(r"^( +)[^ ].*$", r"\1", usage_lines[-1])
+                    usage_lines.append(indent + extra_positionals)
+
+                note = "note: extra positionals are parsed as optionals in the order shown above."
+                usage = "\n".join(usage_lines) + f"\n\n{note}\n\n"
+
+        else:
             for key in parser.required_args:
                 try:
                     default = parser.get_default(key)
                 except NSKeyError:
                     default = None
                 if default is None and f"[--{key} " in usage:
                     usage = re.sub(f"\\[(--{key} [^\\]]+)]", r"\1", usage, count=1)
+
         return usage
 
     def _format_action_invocation(self, action: Action) -> str:

jsonargparse/_typehints.py

@@ -658,6 +658,8 @@ def get_class_parser(val_class, sub_add_kwargs=None, skip_args=0):
         for link_kwargs in nested_links.get():
             parser.link_arguments(**link_kwargs)
 
+        parser._inner_parser = True
+
         return parser
 
     def extra_help(self):

jsonargparse_tests/conftest.py

@@ -32,7 +32,7 @@
     set_docstring_parse_options(style=DocstringStyle.GOOGLE)
 
 
-columns_env = {"COLUMNS": "200"}
+columns = "200"
 
 is_cpython = platform.python_implementation() == "CPython"
 is_posix = os.name == "posix"
@@ -190,9 +190,9 @@ def source_unavailable():
         yield
 
 
-def get_parser_help(parser: ArgumentParser, strip=False) -> str:
+def get_parser_help(parser: ArgumentParser, strip=False, columns=columns) -> str:
     out = StringIO()
-    with patch.dict(os.environ, columns_env):
+    with patch.dict(os.environ, {"COLUMNS": columns}):
         parser.print_help(out)
     if strip:
         return re.sub("  *", " ", out.getvalue())
@@ -201,7 +201,7 @@ def get_parser_help(parser: ArgumentParser, strip=False) -> str:
 
 def get_parse_args_stdout(parser: ArgumentParser, args: List[str]) -> str:
     out = StringIO()
-    with patch.dict(os.environ, columns_env), redirect_stdout(out), pytest.raises(SystemExit):
+    with patch.dict(os.environ, {"COLUMNS": columns}), redirect_stdout(out), pytest.raises(SystemExit):
         parser.parse_args(args)
     return out.getvalue()