mininterface 0.4.1__tar.gz → 0.4.3__tar.gz

{mininterface-0.4.1 → mininterface-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mininterface
-Version: 0.4.1
+Version: 0.4.3
 Summary: A minimal access to GUI, TUI, CLI and config
 Home-page: https://github.com/CZ-NIC/mininterface
 License: GPL-3.0-or-later
@@ -15,8 +15,9 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Dist: envelope
 Requires-Dist: pyyaml
 Requires-Dist: requests
+Requires-Dist: textual
 Requires-Dist: tkinter-tooltip
-Requires-Dist: tkinter_form
+Requires-Dist: tkinter_form (==0.1.5.2)
 Requires-Dist: tyro
 Description-Content-Type: text/markdown
 
@@ -26,9 +27,10 @@ Description-Content-Type: text/markdown
 
 Write the program core, do not bother with the input/output.
 
-![hello world example](asset/hello-world.png "A minimal use case")
+![Hello world example: GUI window](asset/hello-world.png "A minimal use case – GUI")
+![Hello world example: TUI fallback](asset/hello-tui.webp "A minimal use case – TUI fallback")
 
-Check out the code that displays such window, just the code you need. No lengthy blocks of code imposed by an external dependency.
+Check out the code that displays such window or its textual fallback.
 
 ```python
 from dataclasses import dataclass
@@ -47,7 +49,22 @@ if __name__ == "__main__":
     print(args.important_number)    # suggested by the IDE with the hint text "This number is very important"
 ```
 
-Or bound the interface to a `with` statement that redirects stdout directly to the window.
+It's all the code you need. No lengthy blocks of code imposed by an external dependency. Besides the GUI/TUI, you receive powerful YAML-configurable CLI parsing.
+
+```bash
+$ ./hello.py
+usage: My application [-h] [--test | --no-test] [--important-number INT]
+
+Set of options.
+
+╭─ options ──────────────────────────────────────────────────────────╮
+│ -h, --help              show this help message and exit            │
+│ --test, --no-test       My testing flag (default: False)           │
+│ --important-number INT  This number is very important (default: 4) │
+╰────────────────────────────────────────────────────────────────────╯
+```
+
+You get several useful methods to handle user dialogues. Here we bound the interface to a `with` statement that redirects stdout directly to the window.
 
 ```python
 with run(Config) as m:
@@ -55,16 +72,15 @@ with run(Config) as m:
     boolean = m.is_yes("Is that alright?")
 ```
 
-TODO img
+![Small window with the text 'Your important number'](asset/hello-with-statement.webp "With statement to redirect the output")
+![The same in terminal'](asset/hello-with-statement-tui.webp "With statement in TUI fallback")
 
-Loading config file is a piece of cake. Alongside `program.py`, put `program.yaml`. Instantly loaded.
+Loading config file is a piece of cake. Alongside `program.py`, put `program.yaml` and put there some of the arguments. Instantly loaded.
 
 ```yaml
 important_number: 555
 ```
 
-TODO img
-
 - [Mininterface – GUI, TUI, CLI and config](#mininterface-gui-tui-cli-and-config)
 - [Background](#background)
 - [Installation](#installation)
@@ -72,21 +88,18 @@ TODO img
   * [`mininterface`](#mininterface)
     + [`run(config=None, interface=GuiInterface, **kwargs)`](#runconfignone-interfaceguiinterface-kwargs)
   * [Interfaces](#interfaces)
-    + [`Mininterface(title: str = '')`](#Mininterface-title-str--)
-    + [`alert(self, text: str)`](#alert-self-text-str)
-    + [`ask(self, text: str) -> str`](#ask-self-text-str-str)
-    + [`ask_args(self) -> ~ConfigInstance`](#ask-args-self-configinstance)
-    + [`ask_form(self, args: FormDict, title="") -> int`](#ask-form-self-args-FormDict-title)
-    + [`ask_number(self, text: str) -> int`](#ask-number-self-text-str-int)
-    + [`get_args(self, ask_on_empty_cli=True) -> ~ConfigInstance`](#get-args-self-ask-on-empty-cli-true-configinstance)
-    + [`is_no(self, text: str) -> bool`](#is-no-self-text-str-bool)
-    + [`is_yes(self, text: str) -> bool`](#is-yes-self-text-str-bool)
-    + [`parse_args(self, config: Callable[..., ~ConfigInstance], config_file: pathlib.Path | None = None, **kwargs) -> ~ConfigInstance`](#parse-args-self-config-callable-configinstance-config-file-pathlibpath-none-none-kwargs-configinstance)
+    + [`Mininterface(title: str = '')`](#mininterfacetitle-str--)
+    + [`alert(self, text: str)`](#alertself-text-str)
+    + [`ask(self, text: str) -> str`](#askself-text-str---str)
+    + [`ask_args(self) -> ~ConfigInstance`](#ask_argsself---configinstance)
+    + [`ask_form(self, args: FormDict, title="") -> int`](#ask_formself-args-formdict-title---dict)
+    + [`ask_number(self, text: str) -> int`](#ask_numberself-text-str---int)
+    + [`get_args(self, ask_on_empty_cli=True) -> ~ConfigInstance`](#get_argsself-ask_on_empty_clitrue---configinstance)
+    + [`is_no(self, text: str) -> bool`](#is_noself-text-str---bool)
+    + [`is_yes(self, text: str) -> bool`](#is_yesself-text-str---bool)
+    + [`parse_args(self, config: Callable[..., ~ConfigInstance], config_file: pathlib.Path | None = None, **kwargs) -> ~ConfigInstance`](#parse_argsself-config-callable-configinstance-config_file-pathlibpath--none--none-kwargs---configinstance)
   * [Standalone](#standalone)
 
-<small><i><a href='http://ecotrust-canada.github.io/markdown-toc/'>Table of contents generated with markdown-toc</a></i></small>
-
-
 # Background
 
 Wrapper between the [tyro](https://github.com/brentyi/tyro) `argparse` replacement and [tkinter_form](https://github.com/JohanEstebanCuervo/tkinter_form/) that converts dicts into a GUI.
@@ -162,6 +175,8 @@ Several interfaces exist:
 * `Mininterface` – The base interface. Does not require any user input and hence is suitable for headless testing.
 * `GuiInterface` – A tkinter window.
 * `TuiInterface` – An interactive terminal.
+  * `TextualInterface` – If [textual](https://github.com/Textualize/textual) installed, rich interface is used.
+  * `TextInterface` – Plain text only interface with no dependency as a fallback.
 * `ReplInterface` – A debug terminal. Invokes a breakpoint after every dialog.
 
 You can invoke one directly instead of using [mininterface.run](#run-config-none-interface-guiinterface-kwargs). Then, you can connect a configuration object to the CLI and config file with `parse_args` if needed.

{mininterface-0.4.1 → mininterface-0.4.3}/README.md

@@ -4,9 +4,10 @@
 
 Write the program core, do not bother with the input/output.
 
-![hello world example](asset/hello-world.png "A minimal use case")
+![Hello world example: GUI window](asset/hello-world.png "A minimal use case – GUI")
+![Hello world example: TUI fallback](asset/hello-tui.webp "A minimal use case – TUI fallback")
 
-Check out the code that displays such window, just the code you need. No lengthy blocks of code imposed by an external dependency.
+Check out the code that displays such window or its textual fallback.
 
 ```python
 from dataclasses import dataclass
@@ -25,7 +26,22 @@ if __name__ == "__main__":
     print(args.important_number)    # suggested by the IDE with the hint text "This number is very important"
 ```
 
-Or bound the interface to a `with` statement that redirects stdout directly to the window.
+It's all the code you need. No lengthy blocks of code imposed by an external dependency. Besides the GUI/TUI, you receive powerful YAML-configurable CLI parsing.
+
+```bash
+$ ./hello.py
+usage: My application [-h] [--test | --no-test] [--important-number INT]
+
+Set of options.
+
+╭─ options ──────────────────────────────────────────────────────────╮
+│ -h, --help              show this help message and exit            │
+│ --test, --no-test       My testing flag (default: False)           │
+│ --important-number INT  This number is very important (default: 4) │
+╰────────────────────────────────────────────────────────────────────╯
+```
+
+You get several useful methods to handle user dialogues. Here we bound the interface to a `with` statement that redirects stdout directly to the window.
 
 ```python
 with run(Config) as m:
@@ -33,16 +49,15 @@ with run(Config) as m:
     boolean = m.is_yes("Is that alright?")
 ```
 
-TODO img
+![Small window with the text 'Your important number'](asset/hello-with-statement.webp "With statement to redirect the output")
+![The same in terminal'](asset/hello-with-statement-tui.webp "With statement in TUI fallback")
 
-Loading config file is a piece of cake. Alongside `program.py`, put `program.yaml`. Instantly loaded.
+Loading config file is a piece of cake. Alongside `program.py`, put `program.yaml` and put there some of the arguments. Instantly loaded.
 
 ```yaml
 important_number: 555
 ```
 
-TODO img
-
 - [Mininterface – GUI, TUI, CLI and config](#mininterface-gui-tui-cli-and-config)
 - [Background](#background)
 - [Installation](#installation)
@@ -50,21 +65,18 @@ TODO img
   * [`mininterface`](#mininterface)
     + [`run(config=None, interface=GuiInterface, **kwargs)`](#runconfignone-interfaceguiinterface-kwargs)
   * [Interfaces](#interfaces)
-    + [`Mininterface(title: str = '')`](#Mininterface-title-str--)
-    + [`alert(self, text: str)`](#alert-self-text-str)
-    + [`ask(self, text: str) -> str`](#ask-self-text-str-str)
-    + [`ask_args(self) -> ~ConfigInstance`](#ask-args-self-configinstance)
-    + [`ask_form(self, args: FormDict, title="") -> int`](#ask-form-self-args-FormDict-title)
-    + [`ask_number(self, text: str) -> int`](#ask-number-self-text-str-int)
-    + [`get_args(self, ask_on_empty_cli=True) -> ~ConfigInstance`](#get-args-self-ask-on-empty-cli-true-configinstance)
-    + [`is_no(self, text: str) -> bool`](#is-no-self-text-str-bool)
-    + [`is_yes(self, text: str) -> bool`](#is-yes-self-text-str-bool)
-    + [`parse_args(self, config: Callable[..., ~ConfigInstance], config_file: pathlib.Path | None = None, **kwargs) -> ~ConfigInstance`](#parse-args-self-config-callable-configinstance-config-file-pathlibpath-none-none-kwargs-configinstance)
+    + [`Mininterface(title: str = '')`](#mininterfacetitle-str--)
+    + [`alert(self, text: str)`](#alertself-text-str)
+    + [`ask(self, text: str) -> str`](#askself-text-str---str)
+    + [`ask_args(self) -> ~ConfigInstance`](#ask_argsself---configinstance)
+    + [`ask_form(self, args: FormDict, title="") -> int`](#ask_formself-args-formdict-title---dict)
+    + [`ask_number(self, text: str) -> int`](#ask_numberself-text-str---int)
+    + [`get_args(self, ask_on_empty_cli=True) -> ~ConfigInstance`](#get_argsself-ask_on_empty_clitrue---configinstance)
+    + [`is_no(self, text: str) -> bool`](#is_noself-text-str---bool)
+    + [`is_yes(self, text: str) -> bool`](#is_yesself-text-str---bool)
+    + [`parse_args(self, config: Callable[..., ~ConfigInstance], config_file: pathlib.Path | None = None, **kwargs) -> ~ConfigInstance`](#parse_argsself-config-callable-configinstance-config_file-pathlibpath--none--none-kwargs---configinstance)
   * [Standalone](#standalone)
 
-<small><i><a href='http://ecotrust-canada.github.io/markdown-toc/'>Table of contents generated with markdown-toc</a></i></small>
-
-
 # Background
 
 Wrapper between the [tyro](https://github.com/brentyi/tyro) `argparse` replacement and [tkinter_form](https://github.com/JohanEstebanCuervo/tkinter_form/) that converts dicts into a GUI.
@@ -140,6 +152,8 @@ Several interfaces exist:
 * `Mininterface` – The base interface. Does not require any user input and hence is suitable for headless testing.
 * `GuiInterface` – A tkinter window.
 * `TuiInterface` – An interactive terminal.
+  * `TextualInterface` – If [textual](https://github.com/Textualize/textual) installed, rich interface is used.
+  * `TextInterface` – Plain text only interface with no dependency as a fallback.
 * `ReplInterface` – A debug terminal. Invokes a breakpoint after every dialog.
 
 You can invoke one directly instead of using [mininterface.run](#run-config-none-interface-guiinterface-kwargs). Then, you can connect a configuration object to the CLI and config file with `parse_args` if needed.

mininterface-0.4.3/mininterface/FormDict.py

@@ -0,0 +1,107 @@
+""" FormDict tools.
+    FormDict is not a real class, just a normal dict. But we need to put somewhere functions related to it.
+"""
+import logging
+from argparse import Action, ArgumentParser
+from typing import Callable, Optional, TypeVar, Union, get_type_hints
+from unittest.mock import patch
+
+from tyro import cli
+from tyro._argparse_formatter import TyroArgumentParser
+
+from .FormField import FormField
+
+logger = logging.getLogger(__name__)
+
+ConfigInstance = TypeVar("ConfigInstance")
+ConfigClass = Callable[..., ConfigInstance]
+FormDict = dict[str, Union[FormField, 'FormDict']]
+""" Nested form that can have descriptions (through FormField) instead of plain values. """
+
+
+def formdict_repr(d: FormDict) -> dict:
+    """ For the testing purposes, returns a new dict when all FormFields are replaced with their values. """
+    out = {}
+    for k, v in d.items():
+        if isinstance(v, FormField):
+            v = v.val
+        out[k] = formdict_repr(v) if isinstance(v, dict) else v
+    return out
+
+
+def dict_to_formdict(data: dict) -> FormDict:
+    fd = {}
+    for key, val in data.items():
+        if isinstance(val, dict):  # nested config hierarchy
+            fd[key] = dict_to_formdict(val)
+        else:  # scalar value
+            # NOTE name=param is not set (yet?) in `config_to_formdict`, neither `src`
+            fd[key] = FormField(val, "", name=key, src=(data, key))
+    return fd
+
+
+def config_to_formdict(args: ConfigInstance, descr: dict, _path="") -> FormDict:
+    """ Convert the dataclass produced by tyro into dict of dicts. """
+    main = ""
+    params = {main: {}} if not _path else {}
+    for param, val in vars(args).items():
+        annotation = None
+        if val is None:
+            wanted_type = get_type_hints(args.__class__).get(param)
+            if wanted_type in (Optional[int], Optional[str]):
+                # Since tkinter_form does not handle None yet, we have help it.
+                # We need it to be able to write a number and if empty, return None.
+                # This would fail: `severity: int | None = None`
+                # Here, we convert None to str(""), in normalize_types we convert it back.
+                annotation = wanted_type
+                val = ""
+            else:
+                # An unknown type annotation encountered-
+                # Since tkinter_form does not handle None yet, this will display as checkbox.
+                # Which is not probably wanted.
+                val = False
+                logger.warn(f"Annotation {wanted_type} of `{param}` not supported by Mininterface."
+                            "None converted to False.")
+        if hasattr(val, "__dict__"):  # nested config hierarchy
+            params[param] = config_to_formdict(val, descr, _path=f"{_path}{param}.")
+        elif not _path:  # scalar value in root
+            params[main][param] = FormField(val, descr.get(param), annotation, param, src2=(args, param))
+        else:  # scalar value in nested
+            params[param] = FormField(val, descr.get(f"{_path}{param}"), annotation, param, src2=(args, param))
+    return params
+
+
+def get_args_allow_missing(config: ConfigClass, kwargs: dict, parser: ArgumentParser):
+    """ Fetch missing required options in GUI. """
+    # On missing argument, tyro fail. We cannot determine which one was missing, except by intercepting
+    # the error message function. Then, we reconstruct the missing options.
+    # NOTE But we should rather invoke a GUI with the missing options only.
+    original_error = TyroArgumentParser.error
+    eavesdrop = ""
+
+    def custom_error(self, message: str):
+        nonlocal eavesdrop
+        if not message.startswith("the following arguments are required:"):
+            return original_error(self, message)
+        eavesdrop = message
+        raise SystemExit(2)  # will be catched
+    try:
+        with patch.object(TyroArgumentParser, 'error', custom_error):
+            return cli(config, **kwargs)
+    except BaseException as e:
+        if hasattr(e, "code") and e.code == 2 and eavesdrop:  # Some arguments are missing. Determine which.
+            for arg in eavesdrop.partition(":")[2].strip().split(", "):
+                argument: Action = next(iter(p for p in parser._actions if arg in p.option_strings))
+                argument.default = "DEFAULT"  # NOTE I do not know whether used
+                if "." in argument.dest:  # missing nested required argument handler not implemented, we make tyro fail in CLI
+                    pass
+                else:
+                    match argument.metavar:
+                        case "INT":
+                            setattr(kwargs["default"], argument.dest, 0)
+                        case "STR":
+                            setattr(kwargs["default"], argument.dest, "")
+                        case _:
+                            pass  # missing handler not implemented, we make tyro fail in CLI
+            return cli(config, **kwargs)  # second attempt
+        raise

mininterface-0.4.3/mininterface/FormField.py

@@ -0,0 +1,132 @@
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Iterable, Optional, TypeVar, get_args
+
+from .auxiliary import flatten
+
+if TYPE_CHECKING:
+    from .FormDict import FormDict
+
+try:
+    from tkinter_form import Value
+except ImportError:
+    @dataclass
+    class Value:
+        """ This class helps to enrich the field with a description. """
+        val: Any
+        description: str
+
+
+FFValue = TypeVar("FFValue")
+TD = TypeVar("TD")
+""" dict """
+TK = TypeVar("TK")
+""" dict key """
+
+
+@dataclass
+class FormField(Value):
+    """ Bridge between the input values and a UI widget.
+        Helps to creates a widget from the input value (includes description etc.),
+        then transforms the value back (str to int conversion etc).
+
+        (Ex: Merge the dict of dicts from the GUI back into the object holding the configuration.)
+        """
+
+    annotation: Any | None = None
+    """ Used for validation. To convert an empty '' to None. """
+    name: str | None = None  # NOTE: Only TextualInterface uses this by now.
+
+    src: tuple[TD, TK] | None = None
+    """ The original dict to be updated when UI ends. """
+    src2: tuple[TD, TK] | None = None
+    """ The original object to be updated when UI ends.
+    NOTE should be merged to `src`
+    """
+
+    def __post_init__(self):
+        self._original_desc = self.description
+
+    def set_error_text(self, s):
+        self.description = f"{s} {self._original_desc}"
+
+    def update(self, ui_value):
+        """ UI value → FormField value → original value. (With type conversion and checks.)
+
+            The value has been updated in a UI.
+            Update accordingly the value in the original linked dict
+            the mininterface was invoked with.
+
+            Validates the type and do the transformation.
+            (Ex: Some values might be nulled from "".)
+        """
+        fixed_value = ui_value
+        if self.annotation:
+            if ui_value == "" and type(None) in get_args(self.annotation):
+                # The user is not able to set the value to None, they left it empty.
+                # Cast back to None as None is one of the allowed types.
+                # Ex: `severity: int | None = None`
+                fixed_value = None
+            elif self.annotation == Optional[int]:
+                try:
+                    fixed_value = int(ui_value)
+                except ValueError:
+                    pass
+
+            if not isinstance(fixed_value, self.annotation):
+                self.set_error_text(f"Type must be `{self.annotation}`!")
+                return False  # revision needed
+
+        # keep values if revision needed
+        # We merge new data to the origin. If form is re-submitted, the values will stay there.
+        self.val = ui_value
+
+        # Store to the source user data
+        if self.src:
+            d, k = self.src
+            d[k] = fixed_value
+        elif self.src2:
+            d, k = self.src2
+            setattr(d, k, fixed_value)
+        else:
+            # This might be user-created object. The user reads directly from this. There is no need to update anything.
+            pass
+        return True
+        # Fixing types:
+        # This code would support tuple[int, int]:
+        #
+        #     self.types = get_args(self.annotation) \
+        #     if isinstance(self.annotation, UnionType) else (self.annotation, )
+        # "All possible types in a tuple. Ex 'int | str' -> (int, str)"
+        #
+        #
+        # def convert(self):
+        #     """ Convert the self.value to the given self.type.
+        #         The value might be in str due to CLI or TUI whereas the programs wants bool.
+        #     """
+        #     # if self.value == "True":
+        #     #     return True
+        #     # if self.value == "False":
+        #     #     return False
+        #     if type(self.val) is str and str not in self.types:
+        #         try:
+        #             return literal_eval(self.val)  # ex: int, tuple[int, int]
+        #         except:
+        #             raise ValueError(f"{self.name}: Cannot convert value {self.val}")
+        #     return self.val
+
+    @staticmethod
+    def submit_values(updater: Iterable[tuple["FormField", FFValue]]) -> bool:
+        """ Returns whether the form is alright or whether we should revise it.
+        Input is tuple of the FormFields and their new values from the UI.
+        """
+        # Why list? We need all the FormField values be updates from the UI.
+        # If the revision is needed, the UI fetches the values from the FormField.
+        # We need the keep the values so that the user does not have to re-write them.
+        return all(list(ff.update(ui_value) for ff, ui_value in updater))
+
+    @staticmethod
+    def submit(fd: "FormDict", ui: dict):
+        """ Returns whether the form is alright or whether we should revise it.
+        Input is the FormDict and the UI dict in the very same form.
+        """
+        return FormField.submit_values(zip(flatten(fd), flatten(ui)))

{mininterface-0.4.1 → mininterface-0.4.3}/mininterface/GuiInterface.py

@@ -1,6 +1,9 @@
 import sys
 from typing import Any, Callable
 
+from .auxiliary import flatten
+
+
 try:
     from tkinter import TclError, LEFT, Button, Frame, Label, Text, Tk
     from tktooltip import ToolTip
@@ -11,7 +14,9 @@ except ImportError:
 
 
 from .common import InterfaceNotAvailable
-from .auxiliary import FormDict, RedirectText, config_to_formdict, config_from_dict, flatten, recursive_set_focus, fix_types
+from .FormDict import FormDict, config_to_formdict
+from .auxiliary import RedirectText, recursive_set_focus
+from .FormField import FormField
 from .Mininterface import Cancelled, ConfigInstance, Mininterface
 
 
@@ -20,7 +25,7 @@ class GuiInterface(Mininterface):
         super().__init__(*args, **kwargs)
         try:
             self.window = TkWindow(self)
-        except TclError:
+        except TclError:  # I am not sure whether there might be reasons the Tkinter is not available even when installed
             raise InterfaceNotAvailable
         self._always_shown = False
         self._original_stdout = sys.stdout
@@ -46,11 +51,10 @@ class GuiInterface(Mininterface):
 
     def ask_args(self) -> ConfigInstance:
         """ Display a window form with all parameters. """
-        params_ = config_to_formdict(self.args, self.descriptions)
+        formDict = config_to_formdict(self.args, self.descriptions)
 
-        # fetch the dict of dicts values from the form back to the namespace of the dataclasses
-        self.window.run_dialog(params_)
-        # NOTE remove config_from_dict(self.args, data)
+        # formDict automatically fetches the edited values back to the ConfigInstance
+        self.window.run_dialog(formDict)
         return self.args
 
     def ask_form(self, form: FormDict, title: str = "") -> dict:
@@ -93,7 +97,7 @@ class TkWindow(Tk):
         self.pending_buffer = []
         """ Text that has been written to the text widget but might not be yet seen by user. Because no mainloop was invoked. """
 
-    def run_dialog(self, formDict: FormDict, title: str = "") -> dict:
+    def run_dialog(self, formDict: FormDict, title: str = "") -> FormDict:
         """ Let the user edit the form_dict values in a GUI window.
         On abrupt window close, the program exits.
         """
@@ -108,10 +112,9 @@ class TkWindow(Tk):
                          )
         self.form.pack()
 
-        # Set the enter and exit options
+        # Set the submit and exit options
         self.form.button.config(command=self._ok)
-        # allow Enter for single field, otherwise Ctrl+Enter
-        tip, keysym = ("Ctrl+Enter", '<Control-Return>') if len(formDict) > 1 else ("Enter", "<Return>")
+        tip, keysym = ("Enter", "<Return>")
         ToolTip(self.form.button, msg=tip)  # NOTE is not destroyed in _clear
         self._bind_event(keysym, self._ok)
         self.protocol("WM_DELETE_WINDOW", lambda: sys.exit(0))
@@ -120,14 +123,10 @@ class TkWindow(Tk):
         recursive_set_focus(self.form)
         return self.mainloop(lambda: self.validate(formDict, title))
 
-    def validate(self, formDict: FormDict, title: str):
-        if not all(ff.update(ui_value) for ff, ui_value in zip(flatten(formDict), flatten(self.form.get()))):
-            return self.run_dialog(formDict, title)
-
-        # NOTE remove:
-        # if data := fix_types(formDict, self.form.get()):
-        #     return data
-        # return self.run_dialog(formDict, title)
+    def validate(self, formDict: FormDict, title: str) -> FormDict:
+        if not FormField.submit_values(zip(flatten(formDict), flatten(self.form.get()))):
+             return self.run_dialog(formDict, title)
+        return formDict
 
     def yes_no(self, text: str, focus_no=True):
         return self.buttons(text, [("Yes", True), ("No", False)], int(focus_no)+1)

{mininterface-0.4.1 → mininterface-0.4.3}/mininterface/Mininterface.py

@@ -8,8 +8,8 @@ from types import SimpleNamespace
 import yaml
 from tyro.extras import get_parser
 
-from .auxiliary import (ConfigClass, ConfigInstance, FormDict, get_args_allow_missing,
-                        get_descriptions)
+from .FormDict import ConfigClass, ConfigInstance, FormDict, get_args_allow_missing
+from .auxiliary import get_descriptions
 
 logger = logging.getLogger(__name__)
 

mininterface-0.4.1/mininterface/TuiInterface.py → mininterface-0.4.3/mininterface/TextInterface.py

@@ -1,9 +1,11 @@
 from pprint import pprint
-from .auxiliary import ConfigInstance, FormDict, config_to_formdict, config_from_dict
+
+from .FormDict import ConfigInstance, FormDict
 from .Mininterface import Cancelled, Mininterface
 
 
-class TuiInterface(Mininterface):
+class TextInterface(Mininterface):
+    """ Plain text fallback interface. No dependencies. """
 
     def alert(self, text: str):
         """ Display text and let the user hit any key. """
@@ -61,7 +63,7 @@ class TuiInterface(Mininterface):
         return self.ask(text=text + " y/[n]").lower() in ("n", "no", "")
 
 
-class ReplInterface(TuiInterface):
+class ReplInterface(TextInterface):
     """ Same as the base TuiInterface, except it starts the REPL. """
 
     def __getattr__(self, name):

{mininterface-0.4.1 → mininterface-0.4.3}/mininterface/TextualInterface.py

@@ -1,40 +1,26 @@
 from ast import literal_eval
-from dataclasses import _MISSING_TYPE, dataclass, field
-from types import UnionType
-from typing import Any, Self, get_args, override
-from dataclasses import fields
-from textual import events
-from textual.app import App, ComposeResult
-from textual.containers import VerticalScroll, Container
-from textual.widgets import Checkbox, Header, Footer, Input, Label, Welcome, Button, Static
-from textual.binding import Binding
-
-from mininterface import TuiInterface
-from .common import InterfaceNotAvailable
-
-from .Mininterface import Cancelled, Mininterface
-from .auxiliary import ConfigInstance, FormDict, FormField, config_from_dict, config_to_formdict, dict_to_formdict, flatten
-
-from textual.widgets import Checkbox, Input
-
-# TODO
-# 1. TuiInterface -> TextInterface.
-# 1. TextualInterface inherits from TextInterface.
-# 2. TextualInterface is the default for TuiInterface
-# Add to docs
+from dataclasses import dataclass
+from typing import Any
 
-@dataclass
-class FormFieldTextual(FormField):
-    """ Bridge between the values given in CLI, TUI and real needed values (str to int conversion etc). """
+try:
+    from textual import events
+    from textual.app import App, ComposeResult
+    from textual.binding import Binding
+    from textual.containers import VerticalScroll
+    from textual.widgets import Button, Checkbox, Footer, Header, Input, Label
+except ImportError:
+    from mininterface.common import InterfaceNotAvailable
+    raise InterfaceNotAvailable
 
-    def get_widget(self):
-        if self.annotation is bool or not self.annotation and self.val in [True, False]:
-            o = Checkbox(self.name, self.val)
-        else:
-            o = Input(str(self.val), placeholder=self.name or "")
-        o._link = self  # The Textual widgets need to get back to this value
-        return o
+from .TextInterface import TextInterface
 
+from .auxiliary import flatten
+from .FormDict import (ConfigInstance, FormDict, config_to_formdict,
+                       dict_to_formdict)
+from .FormField import FormField
+from .Mininterface import Cancelled
+
+# TODO with statement hello world example image is wrong – Textual still does not redirect the output as GuiInterface does
 
 @dataclass
 class DummyWrapper:
@@ -43,7 +29,7 @@ class DummyWrapper:
     val: Any
 
 
-class TextualInterface(TuiInterface):
+class TextualInterface(TextInterface):
 
     def alert(self, text: str) -> None:
         """ Display the OK dialog with text. """
@@ -54,15 +40,14 @@ class TextualInterface(TuiInterface):
 
     def ask_args(self) -> ConfigInstance:
         """ Display a window form with all parameters. """
-        params_ = config_to_formdict(self.args, self.descriptions, factory=FormFieldTextual)
+        params_ = config_to_formdict(self.args, self.descriptions)
 
         # fetch the dict of dicts values from the form back to the namespace of the dataclasses
         TextualApp.run_dialog(TextualApp(), params_)
         return self.args
 
     def ask_form(self, form: FormDict, title: str = "") -> dict:
-        TextualApp.run_dialog(TextualApp(), dict_to_formdict(form, factory=FormFieldTextual), title)
-        return form
+        return TextualApp.run_dialog(TextualApp(), dict_to_formdict(form), title)
 
     # NOTE we should implement better, now the user does not know it needs an int
     # def ask_number(self, text):
@@ -94,28 +79,34 @@ class TextualApp(App[bool | None]):
         self.widgets = None
         self.focused_i: int = 0
 
-    def setup(self, title, widgets, focused_i):
+    @staticmethod
+    def get_widget(ff:FormField) -> Checkbox | Input:
+        """ Wrap FormField to a textual widget. """
 
-        self.focused_i = focused_i
-        return self
+        if ff.annotation is bool or not ff.annotation and ff.val in [True, False]:
+            o = Checkbox(ff.name, ff.val)
+        else:
+            o = Input(str(ff.val), placeholder=ff.name or "")
+        o._link = ff  # The Textual widgets need to get back to this value
+        return o
 
     # Why class method? I do not know how to re-create the dialog if needed.
     @classmethod
-    def run_dialog(cls, window, formDict: FormDict, title: str = "") -> None:  # TODO changed from dict, change everywhere
+    def run_dialog(cls, window: "TextualApp", formDict: FormDict, title: str = "") -> FormDict:
         if title:
             window.title = title
 
         # NOTE Sections (~ nested dicts) are not implemented, they flatten
-        fd: dict[str, FormFieldTextual] = formDict
-        widgets: list[Checkbox | Input] = [f.get_widget() for f in flatten(fd)]
+        widgets: list[Checkbox | Input] = [cls.get_widget(f) for f in flatten(formDict)]
         window.widgets = widgets
 
         if not window.run():
             raise Cancelled
 
         # validate and store the UI value → FormField value → original value
-        if not all(field._link.update(field.value) for field in widgets):
+        if not FormField.submit_values((field._link, field.value) for field in widgets):
             return cls.run_dialog(TextualApp(), formDict, title)
+        return formDict
 
     def compose(self) -> ComposeResult:
         if self.title:
@@ -123,7 +114,6 @@ class TextualApp(App[bool | None]):
         yield Footer()
         with VerticalScroll():
             for fieldt in self.widgets:
-                fieldt: FormFieldTextual
                 if isinstance(fieldt, Input):
                     yield Label(fieldt.placeholder)
                 yield fieldt

{mininterface-0.4.1 → mininterface-0.4.3}/mininterface/__init__.py

@@ -3,25 +3,34 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Type
 from unittest.mock import patch
 
+
+from mininterface.Mininterface import ConfigClass, ConfigInstance, Mininterface
+from mininterface.TextInterface import ReplInterface, TextInterface
+from mininterface.FormField import FormField
+
+# Import optional interfaces
 try:
     from mininterface.GuiInterface import GuiInterface
 except ImportError:
     if TYPE_CHECKING:
-        pass
+        pass  # Replace TYPE_CHECKING with `type GuiInterface = None` since Python 3.12
     else:
         GuiInterface = None
+try:
+    from mininterface.TextualInterface import TextualInterface
+except ImportError:
+    TextualInterface = None
 
-from mininterface.Mininterface import ConfigClass, ConfigInstance, Mininterface
-from mininterface.TuiInterface import ReplInterface, TuiInterface
-from mininterface.TextualInterface import TextualInterface
-from mininterface.auxiliary import FormField
 
 # TODO auto-handle verbosity https://brentyi.github.io/tyro/examples/04_additional/12_counters/ ?
 # TODO example on missing required options.
 
+class TuiInterface(TextualInterface or TextInterface):
+    pass
+
 
 def run(config: ConfigClass | None = None,
-        interface: Type[Mininterface] = GuiInterface or ReplInterface,  # NOTE we shuold use TuiInterface as a fallback
+        interface: Type[Mininterface] = GuiInterface or TuiInterface,
         **kwargs) -> Mininterface:
     """
     Wrap your configuration dataclass into `run` to access the interface. Normally, an interface is chosen automatically.

mininterface-0.4.3/mininterface/auxiliary.py

@@ -0,0 +1,76 @@
+import os
+import re
+from argparse import ArgumentParser
+from typing import Iterable, TypeVar
+
+try:
+    # NOTE this should be clean up and tested on a machine without tkinter installable
+    from tkinter import END, Entry, Text, Tk, Widget
+    from tkinter.ttk import Checkbutton, Combobox
+except ImportError:
+    tkinter = None
+    END, Entry, Text, Tk, Widget = (None,)*5
+
+
+
+T = TypeVar("T")
+
+def flatten(d: dict[str, T | dict]) -> Iterable[T]:
+    """ Recursively traverse whole dict """
+    for v in d.values():
+        if isinstance(v, dict):
+            yield from flatten(v)
+        else:
+            yield v
+
+
+def get_terminal_size():
+    try:
+        # XX when piping the input IN, it writes
+        # echo "434" | convey -f base64  --debug
+        # stty: 'standard input': Inappropriate ioctl for device
+        # I do not know how to suppress this warning.
+        height, width = (int(s) for s in os.popen('stty size', 'r').read().split())
+        return height, width
+    except (OSError, ValueError):
+        return 0, 0
+
+def get_descriptions(parser: ArgumentParser) -> dict:
+    """ Load descriptions from the parser. Strip argparse info about the default value as it will be editable in the form. """
+    return {action.dest.replace("-", "_"): re.sub(r"\(default.*\)", "", action.help)
+            for action in parser._actions}
+
+
+class RedirectText:
+    """ Helps to redirect text from stdout to a text widget. """
+
+    def __init__(self, widget: Text, pending_buffer: list, window: Tk) -> None:
+        self.widget = widget
+        self.max_lines = 1000
+        self.pending_buffer = pending_buffer
+        self.window = window
+
+    def write(self, text):
+        self.widget.pack(expand=True, fill='both')
+        self.widget.insert(END, text)
+        self.widget.see(END)  # scroll to the end
+        self.trim()
+        self.window.update_idletasks()
+        self.pending_buffer.append(text)
+
+    def flush(self):
+        pass  # required by sys.stdout
+
+    def trim(self):
+        lines = int(self.widget.index('end-1c').split('.')[0])
+        if lines > self.max_lines:
+            self.widget.delete(1.0, f"{lines - self.max_lines}.0")
+
+
+def recursive_set_focus(widget: Widget):
+    for child in widget.winfo_children():
+        if isinstance(child, (Entry, Checkbutton, Combobox)):
+            child.focus_set()
+            return True
+        if recursive_set_focus(child):
+            return True

{mininterface-0.4.1 → mininterface-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "mininterface"
-version = "0.4.1"
+version = "0.4.3"
 description = "A minimal access to GUI, TUI, CLI and config"
 authors = ["Edvard Rejthar <edvard.rejthar@nic.cz>"]
 license = "GPL-3.0-or-later"
@@ -17,8 +17,9 @@ tyro = "*"
 pyyaml = "*"
 envelope = "*"
 requests = "*"
+textual = "*"
 tkinter-tooltip = "*"
-tkinter_form = "*"
+tkinter_form = "0.1.5.2"
 
 [tool.poetry.scripts]
 mininterface = "mininterface.__main__:main"

mininterface-0.4.1/mininterface/auxiliary.py

@@ -1,327 +0,0 @@
-import logging
-import os
-import re
-from argparse import Action, ArgumentParser
-from dataclasses import dataclass
-from typing import Any, Callable, Iterable, Literal, Optional, Self, TypeVar, Union, get_args, get_type_hints
-from unittest.mock import patch
-
-try:
-    # NOTE this should be clean up and tested on a machine without tkinter installable
-    from tkinter import END, Entry, Text, Tk, Widget
-    from tkinter.ttk import Checkbutton, Combobox
-    from tkinter_form import Value
-except ImportError:
-    tkinter = None
-    END, Entry, Text, Tk, Widget = (None,)*5
-
-    @dataclass
-    class Value:
-        """ This class helps to enrich the field with a description. """
-        val: Any
-        description: str
-
-
-from tyro import cli
-from tyro._argparse_formatter import TyroArgumentParser
-
-logger = logging.getLogger(__name__)
-
-TD = TypeVar("TD")
-""" dict """
-TK = TypeVar("TK")
-""" dict key """
-
-
-@dataclass
-class FormField(Value):
-    """ Bridge between the input values and a UI widget.
-        Helps to creates a widget from the input value (includes description etc.),
-        then transforms the value back (str to int conversion etc). """
-
-    annotation: Any | None = None
-    """ Used for validation. To convert an empty '' to None. """
-    name: str | None = None  # NOTE: Only TextualInterface uses this by now.
-
-    src: tuple[TD, TK] | None = None
-    """ The original dict to be updated when UI ends. """
-    src2: tuple[TD, TK] | None = None
-    """ The original object to be updated when UI ends.
-    NOTE should be merged to `src`
-    """
-
-    def __post_init__(self):
-        self._original_desc = self.description
-
-    def set_error_text(self, s):
-        self.description = f"{s} {self._original_desc}"
-
-    # TODO add testing
-    def update(self, ui_value):
-        """ UI value → FormField value → original value. (With type conversion and checks.)
-
-            The value has been updated in a UI.
-            Update accordingly the value in the original linked dict
-            the mininterface was invoked with.
-
-            Validates the type and do the transformation.
-            (Ex: Some values might be nulled from "".)
-        """
-        fixed_value = ui_value
-        if self.annotation:
-            if ui_value == "" and type(None) in get_args(self.annotation):
-                # The user is not able to set the value to None, they left it empty.
-                # Cast back to None as None is one of the allowed types.
-                # Ex: `severity: int | None = None`
-                fixed_value = None
-            elif self.annotation == Optional[int]:
-                try:
-                    fixed_value = int(ui_value)
-                except ValueError:
-                    pass
-
-            if not isinstance(fixed_value, self.annotation):
-                self.set_error_text(f"Type must be `{self.annotation}`!")
-                return False  # revision needed
-
-        # keep values if revision needed
-        # We merge new data to the origin. If form is re-submitted, the values will stay there.
-        self.val = ui_value
-
-        # Store to the source user data
-        if self.src:
-            d, k = self.src
-            d[k] = fixed_value
-        else:
-            d, k = self.src2
-            setattr(d, k, fixed_value)
-        return True
-
-        # Fixing types:
-        # This code would support tuple[int, int]:
-        #
-        #     self.types = get_args(self.annotation) \
-        #     if isinstance(self.annotation, UnionType) else (self.annotation, )
-        # "All possible types in a tuple. Ex 'int | str' -> (int, str)"
-        #
-        #
-        # def convert(self):
-        #     """ Convert the self.value to the given self.type.
-        #         The value might be in str due to CLI or TUI whereas the programs wants bool.
-        #     """
-        #     # if self.value == "True":
-        #     #     return True
-        #     # if self.value == "False":
-        #     #     return False
-        #     if type(self.val) is str and str not in self.types:
-        #         try:
-        #             return literal_eval(self.val)  # ex: int, tuple[int, int]
-        #         except:
-        #             raise ValueError(f"{self.name}: Cannot convert value {self.val}")
-        #     return self.val
-
-
-
-
-ConfigInstance = TypeVar("ConfigInstance")
-ConfigClass = Callable[..., ConfigInstance]
-FormDict = dict[str, Union[FormField, 'FormDict']]
-""" Nested form that can have descriptions (through FormField) instead of plain values. """
-
-
-def dict_to_formdict(data: dict, factory=FormField) -> FormDict:
-    fd = {}
-    for key, val in data.items():
-        if isinstance(val, dict):  # nested config hierarchy
-            fd[key] = dict_to_formdict(val, factory=factory)
-        else:  # scalar value
-            # NOTE name=param is not set (yet?) in `config_to_formdict`, neither `src`
-            fd[key] = factory(val, "", name=key, src=(data, key))
-    return fd
-
-
-# NOTE: Not used, remove
-def config_to_formdict(args: ConfigInstance, descr: dict, _path="", factory=FormField) -> FormDict:
-    """ Convert the dataclass produced by tyro into dict of dicts. """
-    main = ""
-    params = {main: {}} if not _path else {}
-    for param, val in vars(args).items():
-        annotation = None
-        if val is None:
-            wanted_type = get_type_hints(args.__class__).get(param)
-            if wanted_type in (Optional[int], Optional[str]):
-                # Since tkinter_form does not handle None yet, we have help it.
-                # We need it to be able to write a number and if empty, return None.
-                # This would fail: `severity: int | None = None`
-                # Here, we convert None to str(""), in normalize_types we convert it back.
-                annotation = wanted_type
-                val = ""
-            else:
-                # An unknown type annotation encountered-
-                # Since tkinter_form does not handle None yet, this will display as checkbox.
-                # Which is not probably wanted.
-                val = False
-                logger.warn(f"Annotation {wanted_type} of `{param}` not supported by Mininterface."
-                            "None converted to False.")
-        if hasattr(val, "__dict__"):  # nested config hierarchy
-            params[param] = config_to_formdict(val, descr, _path=f"{_path}{param}.", factory=factory)
-        elif not _path:  # scalar value in root
-            params[main][param] = factory(val, descr.get(param), annotation, param, src2=(args, param))
-        else:  # scalar value in nested
-            params[param] = factory(val, descr.get(f"{_path}{param}"), annotation, param, src2=(args, param))
-    return params
-
-# NOTE: Not used, remove
-def fix_types(origin: FormDict, data: dict) -> dict:
-    """ Run validators of all FormField objects. If fails, outputs info.
-        Return corrected data. (Ex: Some values might be nulled from "".)
-    """
-    def check(ordict, orkey, orval, dataPos: dict, dataKey, val):
-        if isinstance(orval, FormField) and orval.annotation:
-            fixed_val = val
-            if val == "" and type(None) in get_args(orval.annotation):
-                # The user is not able to set the value to None, they left it empty.
-                # Cast back to None as None is one of the allowed types.
-                # Ex: `severity: int | None = None`
-                dataPos[dataKey] = fixed_val = None
-            elif orval.annotation == Optional[int]:
-                try:
-                    dataPos[dataKey] = fixed_val = int(val)
-                except ValueError:
-                    pass
-
-            if not isinstance(fixed_val, orval.annotation):
-                orval.set_error_text(f"Type must be `{orval.annotation}`!")
-                raise RuntimeError  # revision needed
-
-        # keep values if revision needed
-        # We merge new data to the origin. If form is re-submitted, the values will stay there.
-        if isinstance(orval, FormField):
-            orval.val = val
-        else:
-            ordict[orkey] = val
-
-    try:
-        for (key1, val1), (orkey1, orval1) in zip(data.items(), origin.items()):
-            if isinstance(val1, dict):  # nested config hierarchy
-                # NOTE: This allows only single nested dict.
-                for (key2, val2), (orkey2, orval2) in zip(val1.items(), orval1.items()):
-                    check(orval1, orkey2, orval2, data[key1], key2, val2)
-            else:
-                check(origin, orkey1, orval1, data, key1, val1)
-    except RuntimeError:
-        return False
-
-    return data
-
-
-def config_from_dict(args: ConfigInstance, data: dict):
-    """ Fetch back data.
-        Merge the dict of dicts from the GUI back into the object holding the configuration. """
-    for group, params in data.items():
-        for key, val in params.items():
-            if group:
-                setattr(getattr(args, group), key, val.val if isinstance(val, FormField) else val)
-            else:
-                setattr(args, key, val.val if isinstance(val, FormField) else val)
-
-
-def get_terminal_size():
-    try:
-        # XX when piping the input IN, it writes
-        # echo "434" | convey -f base64  --debug
-        # stty: 'standard input': Inappropriate ioctl for device
-        # I do not know how to suppress this warning.
-        height, width = (int(s) for s in os.popen('stty size', 'r').read().split())
-        return height, width
-    except (OSError, ValueError):
-        return 0, 0
-
-
-def get_args_allow_missing(config: ConfigClass, kwargs: dict, parser: ArgumentParser):
-    """ Fetch missing required options in GUI. """
-    # On missing argument, tyro fail. We cannot determine which one was missing, except by intercepting
-    # the error message function. Then, we reconstruct the missing options.
-    # NOTE But we should rather invoke a GUI with the missing options only.
-    original_error = TyroArgumentParser.error
-    eavesdrop = ""
-
-    def custom_error(self, message: str):
-        nonlocal eavesdrop
-        if not message.startswith("the following arguments are required:"):
-            return original_error(self, message)
-        eavesdrop = message
-        raise SystemExit(2)  # will be catched
-    try:
-        with patch.object(TyroArgumentParser, 'error', custom_error):
-            return cli(config, **kwargs)
-    except BaseException as e:
-        if hasattr(e, "code") and e.code == 2 and eavesdrop:  # Some arguments are missing. Determine which.
-            for arg in eavesdrop.partition(":")[2].strip().split(", "):
-                argument: Action = next(iter(p for p in parser._actions if arg in p.option_strings))
-                argument.default = "HALO"
-                if "." in argument.dest:  # missing nested required argument handler not implemented, we make tyro fail in CLI
-                    pass
-                else:
-                    match argument.metavar:
-                        case "INT":
-                            setattr(kwargs["default"], argument.dest, 0)
-                        case "STR":
-                            setattr(kwargs["default"], argument.dest, "")
-                        case _:
-                            pass  # missing handler not implemented, we make tyro fail in CLI
-            return cli(config, **kwargs)  # second attempt
-        raise
-
-
-def get_descriptions(parser: ArgumentParser) -> dict:
-    """ Load descriptions from the parser. Strip argparse info about the default value as it will be editable in the form. """
-    return {action.dest.replace("-", "_"): re.sub(r"\(default.*\)", "", action.help)
-            for action in parser._actions}
-
-
-class RedirectText:
-    """ Helps to redirect text from stdout to a text widget. """
-
-    def __init__(self, widget: Text, pending_buffer: list, window: Tk) -> None:
-        self.widget = widget
-        self.max_lines = 1000
-        self.pending_buffer = pending_buffer
-        self.window = window
-
-    def write(self, text):
-        self.widget.pack(expand=True, fill='both')
-        self.widget.insert(END, text)
-        self.widget.see(END)  # scroll to the end
-        self.trim()
-        self.window.update_idletasks()
-        self.pending_buffer.append(text)
-
-    def flush(self):
-        pass  # required by sys.stdout
-
-    def trim(self):
-        lines = int(self.widget.index('end-1c').split('.')[0])
-        if lines > self.max_lines:
-            self.widget.delete(1.0, f"{lines - self.max_lines}.0")
-
-
-def recursive_set_focus(widget: Widget):
-    for child in widget.winfo_children():
-        if isinstance(child, (Entry, Checkbutton, Combobox)):
-            child.focus_set()
-            return True
-        if recursive_set_focus(child):
-            return True
-
-
-T = TypeVar("T")
-
-
-def flatten(d: dict[str, T | dict]) -> Iterable[T]:
-    """ Recursively traverse whole dict """
-    for v in d.values():
-        if isinstance(v, dict):
-            yield from flatten(v)
-        else:
-            yield v