mininterface 1.0.3__tar.gz → 1.1.0__tar.gz

{mininterface-1.0.3 → mininterface-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: mininterface
-Version: 1.0.3
+Version: 1.1.0
 Summary: A minimal access to GUI, TUI, CLI and config
 License: LGPL-3.0-or-later
 Author: Edvard Rejthar
@@ -37,7 +37,7 @@ Project-URL: Homepage, https://github.com/CZ-NIC/mininterface
 Description-Content-Type: text/markdown
 
 # Mininterface – access to GUI, TUI, web, CLI and config files
-[![Build Status](https://github.com/CZ-NIC/mininterface/actions/workflows/run-unittest.yml/badge.svg)](https://github.com/CZ-NIC/mininterface/actions)
+[![Build Status](https://github.com/CZ-NIC/mininterface/actions/workflows/run-unittest.yml/badge.svg?branch=main)](https://github.com/CZ-NIC/mininterface/actions)
 [![Downloads](https://static.pepy.tech/badge/mininterface)](https://pepy.tech/project/mininterface)
 
 Write the program core, do not bother with the input/output.
@@ -144,7 +144,7 @@ The config variables needed by your program are kept in cozy dataclasses. Write
 Install with a single command from [PyPi](https://pypi.org/project/mininterface/).
 
 ```bash
-pip install mininterface[all]  # GPLv3 and compatible
+pip install "mininterface[all]<2"  # GPLv3 and compatible
 ```
 
 ## Bundles
@@ -187,7 +187,7 @@ These projects have the code base reduced thanks to the mininterface:
 Take a look at the following example.
 
 1. We define any Env class.
-2. Then, we initialize mininterface with [`run(Env)`][mininterface.run] – the missing fields will be prompter for
+2. Then, we initialize mininterface with [`run(Env)`][mininterface.run] – the missing fields will be prompted for
 3. Then, we use various dialog methods, like [`confirm`][mininterface.Mininterface.confirm], [`select`][mininterface.Mininterface.select] or [`form`][mininterface.Mininterface.form].
 
 Below, you find the screenshots how the program looks in various environments ([graphic](Interfaces.md#guiinterface-or-tkinterface-or-gui) interface, [web](Interfaces.md#webinterface-or-web) interface...).
@@ -280,11 +280,11 @@ from pathlib import Path
 from mininterface import run
 
 parser = ArgumentParser()
-parser.add_argument("input_file", type=Path, help="Path to the input file.")
-parser.add_argument("--time", type=time, help="Given time")
 subparsers = parser.add_subparsers(dest="command", required=True)
 sub1 = subparsers.add_parser("build", help="Build something.")
 sub1.add_argument("--optimize", action="store_true", help="Enable optimizations.")
+parser.add_argument("input_file", type=Path, help="Path to the input file.")
+parser.add_argument("--time", type=time, help="Given time")
 
 # Old version
 # env = parser.parse_args()
@@ -335,4 +335,4 @@ print(m.env.time)  # -> 14:21
 If you're sure enough to start using *Mininterface*, convert the argparse into a dataclass. Then, the IDE will auto-complete the hints as you type.
 
 !!! warning
-    Be aware that in contrast to the argparse, we create default values. This does make sense for most values but might pose a confusion for ex. `parser.add_argument("--path", type=Path)` which becomes `Path('.')`, not `None`.
+    The argparse support is considered mostly for your evaluation as there are some [`differences`](Argparse-caveats.md) for advanced argparse CLI interfaces.

{mininterface-1.0.3 → mininterface-1.1.0}/README.md

@@ -1,5 +1,5 @@
 # Mininterface – access to GUI, TUI, web, CLI and config files
-[![Build Status](https://github.com/CZ-NIC/mininterface/actions/workflows/run-unittest.yml/badge.svg)](https://github.com/CZ-NIC/mininterface/actions)
+[![Build Status](https://github.com/CZ-NIC/mininterface/actions/workflows/run-unittest.yml/badge.svg?branch=main)](https://github.com/CZ-NIC/mininterface/actions)
 [![Downloads](https://static.pepy.tech/badge/mininterface)](https://pepy.tech/project/mininterface)
 
 Write the program core, do not bother with the input/output.
@@ -106,7 +106,7 @@ The config variables needed by your program are kept in cozy dataclasses. Write
 Install with a single command from [PyPi](https://pypi.org/project/mininterface/).
 
 ```bash
-pip install mininterface[all]  # GPLv3 and compatible
+pip install "mininterface[all]<2"  # GPLv3 and compatible
 ```
 
 ## Bundles
@@ -149,7 +149,7 @@ These projects have the code base reduced thanks to the mininterface:
 Take a look at the following example.
 
 1. We define any Env class.
-2. Then, we initialize mininterface with [`run(Env)`][mininterface.run] – the missing fields will be prompter for
+2. Then, we initialize mininterface with [`run(Env)`][mininterface.run] – the missing fields will be prompted for
 3. Then, we use various dialog methods, like [`confirm`][mininterface.Mininterface.confirm], [`select`][mininterface.Mininterface.select] or [`form`][mininterface.Mininterface.form].
 
 Below, you find the screenshots how the program looks in various environments ([graphic](Interfaces.md#guiinterface-or-tkinterface-or-gui) interface, [web](Interfaces.md#webinterface-or-web) interface...).
@@ -242,11 +242,11 @@ from pathlib import Path
 from mininterface import run
 
 parser = ArgumentParser()
-parser.add_argument("input_file", type=Path, help="Path to the input file.")
-parser.add_argument("--time", type=time, help="Given time")
 subparsers = parser.add_subparsers(dest="command", required=True)
 sub1 = subparsers.add_parser("build", help="Build something.")
 sub1.add_argument("--optimize", action="store_true", help="Enable optimizations.")
+parser.add_argument("input_file", type=Path, help="Path to the input file.")
+parser.add_argument("--time", type=time, help="Given time")
 
 # Old version
 # env = parser.parse_args()
@@ -297,4 +297,4 @@ print(m.env.time)  # -> 14:21
 If you're sure enough to start using *Mininterface*, convert the argparse into a dataclass. Then, the IDE will auto-complete the hints as you type.
 
 !!! warning
-    Be aware that in contrast to the argparse, we create default values. This does make sense for most values but might pose a confusion for ex. `parser.add_argument("--path", type=Path)` which becomes `Path('.')`, not `None`.
+    The argparse support is considered mostly for your evaluation as there are some [`differences`](Argparse-caveats.md) for advanced argparse CLI interfaces.

mininterface-1.1.0/mininterface/__init__.py

@@ -0,0 +1,7 @@
+from ._lib.run import run
+from ._mininterface import Mininterface
+from .exceptions import Cancelled
+from .tag import Tag
+from .tag.alias import Options, Validation
+
+__all__ = ["run", "Mininterface", "Tag", "Cancelled", "Validation", "Options"]

{mininterface-1.0.3 → mininterface-1.1.0}/mininterface/__main__.py

@@ -9,9 +9,10 @@ try:
     from tyro.conf import Positional
 except ImportError:
     from .exceptions import DependencyRequired
+
     raise DependencyRequired("basic").exit()
 
-from . import run
+from ._lib.run import run
 from .cli import Command
 from .tag.flag import File
 from .tag.path_tag import PathTag
@@ -36,7 +37,7 @@ Showcase_Type = Literal[1, 2]
 
 @dataclass
 class Alert(Command):
-    """ Dialog: Display the OK dialog with text. """
+    """Dialog: Display the OK dialog with text."""
 
     text: Positional[str]
 
@@ -46,7 +47,7 @@ class Alert(Command):
 
 @dataclass
 class Ask(Command):
-    """ Dialog: Prompt the user to input a value.
+    """Dialog: Prompt the user to input a value.
     By default, we input a str, by the second parameter, you can infer a type,
     ex. `mininterface --ask 'My heading' int`
     """
@@ -77,12 +78,15 @@ class Ask(Command):
                 v = Path
             case "date":
                 from datetime import date
+
                 v = date
             case "datetime":
                 from datetime import datetime
+
                 v = datetime
             case "time":
                 from datetime import time
+
                 v = time
             case "file":
                 v = PathTag(is_file=True)
@@ -95,7 +99,7 @@ class Ask(Command):
 
 @dataclass
 class Confirm(Command):
-    """ Dialog: Display confirm box. Returns 0 / 1. """
+    """Dialog: Display confirm box. Returns 0 / 1."""
 
     text: Positional[str]
     focus: Positional[Literal["yes", "no"]] = "yes"
@@ -108,7 +112,8 @@ class Confirm(Command):
 
 @dataclass
 class Select(Command):
-    """ Dialog: Prompt the user to select. """
+    """Dialog: Prompt the user to select."""
+
     options: Positional[list[str]]
     title: str = ""
 
@@ -118,7 +123,7 @@ class Select(Command):
 
 @dataclass
 class Integrate(Command):
-    """ Integrate to the system. Generates a bash completion for the given program. """
+    """Integrate to the system. Generates a bash completion for the given program."""
 
     cmd: Positional[File]
     """Path to the program using mininterface.
@@ -126,17 +131,18 @@ class Integrate(Command):
     """
 
     def run(self):
-        environ["MININTERFACE_INTEGRATE_TO_SYSTEM"] = '1'
+        environ["MININTERFACE_INTEGRATE_TO_SYSTEM"] = "1"
         srun(self.cmd.absolute(), env=environ)
         quit()
 
 
 @dataclass
 class Showcase:
-    """ Prints various form just to show what's possible.
+    """Prints various form just to show what's possible.
     Choose the interface by MININTERFACE_INTERFACE=...
     Ex. MININTERFACE_INTERFACE=tui mininterface showcase 2
     """
+
     showcase: Positional[Showcase_Type] = 1
 
 
@@ -151,11 +157,17 @@ class Web(Command):
 
     def run(self):
         from ._web_interface import WebInterface
+
         WebInterface(cmd=self.cmd, port=self.port)
 
 
 def main():
-    with run([Alert, Ask, Confirm, Select, Integrate, Showcase,  Web], prog="Mininterface", description=__doc__, ask_for_missing=False) as m:
+    with run(
+        [Alert, Ask, Confirm, Select, Integrate, Showcase, Web],
+        prog="Mininterface",
+        description=__doc__,
+        ask_for_missing=False,
+    ) as m:
         pass
 
     if isinstance(m.env, Showcase):

mininterface-1.1.0/mininterface/_lib/argparse_support.py

@@ -0,0 +1,266 @@
+import re
+import sys
+from argparse import (SUPPRESS, Action, ArgumentParser, _AppendAction,
+                      _AppendConstAction, _CountAction, _HelpAction,
+                      _StoreConstAction, _StoreFalseAction, _StoreTrueAction,
+                      _SubParsersAction, _VersionAction)
+from collections import defaultdict
+from dataclasses import MISSING, Field, dataclass, field, make_dataclass
+from functools import cached_property
+from typing import Annotated, Callable, Optional
+from warnings import warn
+
+from ..tag.alias import Options
+from .form_dict import DataClass
+
+try:
+    from tyro.conf import DisallowNone, OmitSubcommandPrefixes, Positional
+except ImportError:
+    from ..exceptions import DependencyRequired
+
+    raise DependencyRequired("basic")
+
+
+class Property:
+    def __init__(self):
+        self._usages = []
+
+    def add(self, callback: Callable):
+        self._usages.append(callback)
+
+    def generate_property(self):
+        def _(this):
+            for clb in self._usages:
+                v = clb(this)
+                if v is not None:
+                    return v
+
+        return property(_)
+
+
+@dataclass
+class ArgparseField:
+
+    action: Action
+    properties: dict[str, Property]
+
+    @cached_property
+    def name(self):
+        if n := self.action.option_strings:
+            # --get-one → get_one
+            return re.sub(r"^--?", "", self.action.option_strings[0]).replace("-", "_")
+        else:
+            raise ValueError(f"Cannot load argparse, due to field {self.action}")
+
+    def add(self, callback: Callable):
+        if self.action.dest == self.name:
+            raise NotImplementedError(
+                f"Cannot load argparse, due to field {self.action}. It must be visible from CLI and cannot"
+                "be read directly from the program. Solution: Do not use argparse or add a .dest parameter."
+            )
+        self.properties[self.action.dest].add(callback)
+
+    @property
+    def has_property(self):
+        return self.action.dest in self.properties
+
+
+def parser_to_dataclass(parser: ArgumentParser, name: str = "Args") -> tuple[DataClass | list[DataClass], Optional[str]]:
+    """
+    Note: Ex. parser.add_argument("--time", type=time) -> does work at all in argparse, here it works.
+
+    Returns:
+        DataClass | list[DataClass]
+        Optional[str]: add_version flag
+    """
+    subparsers: list[_SubParsersAction] = []
+    add_version = None
+
+    normal_actions: list[Action] = []
+    has_positionals = False
+    for action in parser._actions:
+        match action:
+            case _HelpAction():
+                continue
+            case _SubParsersAction():
+                if has_positionals:
+                    warn(
+                        "This CLI parser have a subcommand placed after positional arguments. The order of arguments changes, see --help."
+                    )
+                subparsers.append(action)
+            case _VersionAction():
+                # We do not want the version to be part of the dataclass (and appear in `m.form()`).
+                add_version = action.version
+            case _:
+                if not action.option_strings:
+                    has_positionals = True
+                normal_actions.append(action)
+
+    if subparsers:
+        return [
+            _make_dataclass_from_actions(
+                normal_actions + subactions._actions,
+                subname,
+                help_,
+                subactions.description,
+            )
+            for subparser in subparsers
+            for subname, subactions, help_ in _loop_SubParsersAction(subparser)
+        ], add_version
+    else:
+        return _make_dataclass_from_actions(normal_actions, name, None, parser.description), add_version
+
+
+def _loop_SubParsersAction(subparser: _SubParsersAction):
+    return [
+        (subname, subactions, ch_act.help)
+        for (subname, subactions), ch_act in zip(subparser.choices.items(), subparser._choices_actions)
+    ]
+
+
+def _make_dataclass_from_actions(
+    actions: list[Action], name, helptext: str | None, description: str | None
+) -> DataClass:
+    const_actions = defaultdict(list[ArgparseField])
+    normal_fields: list[tuple[str, type, Field]] = []
+    pos_fields: list[tuple[str, type, Field]] = []
+    properties = defaultdict(Property)
+    """ Sometimes, the action.dest differs from the field name.
+    Field name is exposed to the CLI, action.dest is used in the program.
+    """
+    subparser_fields: list[tuple[str, type]] = []
+
+    for action in actions:
+        af = ArgparseField(action, properties)
+        opt = {}
+
+        match action:
+            case _HelpAction():
+                continue
+            case _SubParsersAction():
+                # Note that there is only one _SubParsersAction in argparse
+                # but to be sure, we allow multiple of them
+                # This probably makes a different CLI output than the original argparse but should work.
+                for subname, subparser, help_ in _loop_SubParsersAction(action):
+                    sub_dc = _make_dataclass_from_actions(
+                        subparser._actions,
+                        subname.capitalize(),
+                        help_,
+                        subparser.description,
+                    )
+                    subparser_fields.append((subname, sub_dc))  # required, no default
+
+                from functools import reduce
+
+                union_type = reduce(lambda a, b: a | b, [aa[1] for aa in subparser_fields])
+
+                result = OmitSubcommandPrefixes[Positional[union_type]]
+                pos_fields.append(("_subparsers", result))
+                subparser_fields.clear()
+                continue
+            case _AppendAction():
+                arg_type = list[action.type or str]
+                opt["default_factory"] = list
+            case _AppendConstAction():
+                # `--one --two` -> env.section = [one, two]
+                arg_type = bool
+                opt["default"] = False
+                const_actions[af.action.dest].append(af)
+                af.add(
+                    lambda self, af=af: (
+                        [_af.action.const for _af in const_actions[af.action.dest] if getattr(self, _af.name)]
+                    )
+                )
+            case _StoreTrueAction():
+                arg_type = bool
+            case _StoreFalseAction():
+                arg_type = bool
+                opt["default"] = False
+                af.add(lambda self, field_name=af.name: not getattr(self, field_name))
+            case _StoreConstAction():
+                arg_type = bool
+                opt["default"] = False
+                af.add(
+                    lambda self, field_name=af.name, const=action.const: (const if getattr(self, field_name) else None)
+                )
+            case _CountAction():
+                arg_type = int
+            case _:
+                if action.type:
+                    arg_type = action.type
+                elif action.default:
+                    arg_type = type(action.default)
+                else:
+                    arg_type = str
+
+        if "default" not in opt and "default_factory" not in opt:
+            if action.choices:
+                # With the drop of Python 3.10, use mere:
+                # arg_type = Literal[*action.choices]
+                if sys.version_info >= (3,11):
+                    from .future_compatibility import literal
+                    arg_type = literal(action.choices)
+                else:
+                    # we do not prefer this option as tyro does not understand it
+                    # and won't display options in the help
+                    arg_type = Annotated[arg_type, Options(*action.choices)]
+
+            if not action.option_strings and action.default is None and action.nargs != "?":
+                opt["default"] = MISSING
+            else:
+                if action.default is None:
+                    # parser.add_argument("--path", type=Path) -> becomes None, not Path('.').
+                    # By default, argparse put None if not used in the CLI.
+                    # Which makes tyro output the warning: annotated with type `<class 'str'>`, but the default value `None`
+                    # We either make None an option by `arg_type |= None`
+                    # or else we default the value.
+                    if arg_type is not None:
+                        arg_type |= None
+                opt["default"] = action.default if action.default != SUPPRESS else None
+
+        # build a dataclass field, either optional, or positional
+        opt["metadata"] = {"help": action.help}
+        if action.option_strings:
+            # normal_fields.append((action.dest, arg_type, field(**opt, **met)))
+            # Annotated[arg_type, arg(metavar=metavar)]
+            normal_fields.append((af.name, arg_type, field(**opt)))
+
+            # Generate back-compatible property if dest != field_name
+            if af.name != action.dest and not af.has_property:
+                af.add(lambda self, field_name=af.name: getattr(self, field_name))
+        else:
+            pos_fields.append((action.dest, Positional[arg_type], field(**opt)))
+
+    # Subparser can have the same field name as the parser. We use the latter.
+    # Ex:
+    #   parser.add_argument('--level', type=int, default=1)
+    #   subparsers = parser.add_subparsers(dest='command')
+    #   run_parser = subparsers.add_parser('run')
+    #   run_parser.add_argument('--level', type=int, default=5)
+    uniq_fields = []
+    seen = set()
+    # for f in reversed(subparser_fields + pos_fields + normal_fields):
+    for f in reversed(pos_fields + normal_fields):
+        if f[0] not in seen:
+            seen.add(f[0])
+            uniq_fields.append(f)
+
+    # if subparser_fields:
+    #     from functools import reduce
+    #     union_type = reduce(lambda a, b: a | b, [aa[1] for aa in subparser_fields])
+    #     result = OmitSubcommandPrefixes[Positional[union_type]]
+    #     uniq_fields.append(("_subparsers",  result ))
+
+    dc = make_dataclass(
+        name,
+        reversed(uniq_fields),
+        namespace={k: prop.generate_property() for k, prop in properties.items()},
+    )
+    if helptext or description:
+        trimmed = (helptext or "").strip()
+        needs_colon = trimmed and description and trimmed[-1] not in (".", ":", "!", "?", "…")
+
+        separator = ": " if needs_colon else ("\n" if trimmed else "")
+        dc.__doc__ = trimmed + separator + (description or "")
+
+    return DisallowNone[dc]