mininterface 0.1.1__tar.gz

mininterface-0.1.1/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.1
+Name: mininterface
+Version: 0.1.1
+Summary: A minimal access to GUI, TUI, CLI and config
+Home-page: https://github.com/CZ-NIC/mininterface
+License: GPL-3.0-or-later
+Author: Edvard Rejthar
+Author-email: edvard.rejthar@nic.cz
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: envelope
+Requires-Dist: pyyaml
+Requires-Dist: requests
+Requires-Dist: tkinter-tooltip
+Requires-Dist: tkinter_form
+Requires-Dist: tyro
+Description-Content-Type: text/markdown
+
+# Mininterface – access to GUI, TUI, CLI and config files
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+
+Write the program core, do not bother with the input/output.
+
+![hello world example](asset/hello-world.png "A minimal use case")
+
+Check out the code that displays such window, just the code you need. No lengthy blocks of code imposed by an external dependency.
+
+```python
+from dataclasses import dataclass
+from mininterface import run
+
+@dataclass
+class Config:
+    """Set of options."""
+    test: bool = False
+    """My testing flag"""
+    important_number: int = 4
+    """This number is very important"""
+
+if __name__ == "__main__":
+    args: Config = run(Config, prog="My application").get_args()
+    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.
+
+```python
+with run(Config) as m:
+    print(f"Your important number is {m}")
+    boolean = m.is_yes("Is that alright?")
+```
+
+TODO img
+
+Loading config file is a piece of cake. Alongside `program.py`, put `program.yaml`. Instantly loaded.
+
+```yaml
+important_number: 555
+```
+
+TODO img
+
+- [Mininterface – GUI, TUI, CLI and config](#mininterface-gui-tui-cli-and-config)
+- [Background](#background)
+- [Installation](#installation)
+- [Docs](#docs)
+  * [`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)
+  * [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.
+
+Writing a small and useful program might be a task that takes fifteen minutes. Adding a CLI to specify the parameters is not so much overhead. But building a simple GUI around it? HOURS! Hours spent on researching GUI libraries, wondering why the Python desktop app ecosystem lags so far behind the web world. All you need is a few input fields validated through a clickable window... You do not deserve to add hundred of lines of the code just to define some editable fields. `mininterface` is here to help.
+
+The config variables needed by your program are kept in cozy dataclasses. Write less! The syntax of [tyro](https://github.com/brentyi/tyro) does not require any overhead (as its `argparse` alternatives do). You just annotate a class attribute, append a simple docstring and get a fully functional application:
+* Call it as `program.py --help` to display full help.
+* Use any flag in CLI: `program.py --test`  causes `args.test` be set to `True`.
+* The main benefit: Launch it without parameters as `program.py` to get a full working window with all the flags ready to be edited.
+* Running on a remote machine? Automatic regression to the text interface.
+
+# Installation
+
+Install with a single command from [PyPi](https://pypi.org/project/mininterface/).
+
+```python3
+pip install mininterface
+```
+
+# Docs
+
+You can easily nest the configuration. (See also [Tyro Hierarchical Configs](https://brentyi.github.io/tyro/examples/02_nesting/01_nesting/)).
+
+Just put another dataclass inside the config file:
+
+```python3
+@dataclass
+class FurtherConfig:
+    token: str
+    host: str = "example.org"
+
+@dataclass
+class Config:
+    further: FurtherConfig
+
+...
+print(config.further.host)  # example.org
+```
+
+A subset might be defaulted in YAML:
+
+```yaml
+further:
+  host: example.com
+```
+
+Or by CLI:
+
+```
+$./program.py --further.host example.net
+```
+
+## `mininterface`
+
+### `run(config=None, interface=GuiInterface, **kwargs)`
+Wrap your configuration dataclass into `run` to access the interface. Normally, an interface is chosen automatically. We prefer the graphical one, regressed to a text interface on a machine without display.
+Besides, if given a configuration dataclass, the function enriches it with the CLI commands and possibly with the default from a config file if such exists. It searches the config file in the current working directory, with the program name ending on *.yaml*, ex: `program.py` will fetch `./program.yaml`.
+
+* `config:ConfigClass`: Dataclass with the configuration.
+* `interface`: Which interface to prefer. By default, we use the GUI, the fallback is the REPL.
+* `**kwargs`: The same as for [`argparse.ArgumentParser`](https://docs.python.org/3/library/argparse.html).
+* Returns: `interface` Interface used.
+
+You cay context manage the function by a `with` statement. The stdout will be redirected to the interface (GUI window).
+
+See the [initial examples](#mininterface-gui-tui-cli-and-config).
+
+## Interfaces
+
+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.
+* `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.
+
+```python
+with TuiInterface("My program") as m:
+    number = m.ask_number("Returns number")
+```
+
+### `Mininterface(title: str = '')`
+Initialize.
+### `alert(self, text: str)`
+Prompt the user to confirm the text.
+### `ask(self, text: str) -> str`
+Prompt the user to input a text.
+### `ask_args(self) -> ~ConfigInstance`
+Allow the user to edit whole configuration. (Previously fetched from CLI and config file by parse_args.)
+### `ask_form(self, args: FormDict, title="") -> dict`
+Prompt the user to fill up whole form.
+* `args`: Dict of `{labels: default value}`. The form widget infers from the default value type.
+  The dict can be nested, it can contain a subgroup.
+  The default value might be `mininterface.Value` that allows you to add descriptions.
+  A checkbox example: `{"my label": Value(True, "my description")}`
+* `title`: Optional form title.
+### `ask_number(self, text: str) -> int`
+Prompt the user to input a number. Empty input = 0.
+### `get_args(self, ask_on_empty_cli=True) -> ~ConfigInstance`
+Returns whole configuration (previously fetched from CLI and config file by parse_args).
+If program was launched with no arguments (empty CLI), invokes self.ask_args() to edit the fields.
+### `is_no(self, text: str) -> bool`
+Display confirm box, focusing no.
+### `is_yes(self, text: str) -> bool`
+Display confirm box, focusing yes.
+
+```python
+m = run(prog="My program")
+print(m.ask_yes("Is it true?"))  # True/False
+```
+
+### `parse_args(self, config: Callable[..., ~ConfigInstance], config_file: pathlib.Path | None = None, **kwargs) -> ~ConfigInstance`
+Parse CLI arguments, possibly merged from a config file.
+* `config`: Dataclass with the configuration.
+* `config_file`: File to load YAML to be merged with the configuration. You do not have to re-define all the settings, you can choose a few.
+* `**kwargs` The same as for argparse.ArgumentParser.
+* Returns: `ConfigInstance` Configuration namespace.
+
+## Standalone
+
+When invoked directly, it creates simple GUI dialogs.
+
+```bash
+$ mininterface  --help
+usage: Mininterface [-h] [OPTIONS]
+
+Simple GUI dialog. Outputs the value the user entered.
+
+╭─ options ─────────────────────────────────────────────────────────────────────────────────╮
+│ -h, --help              show this help message and exit                                   │
+│ --alert STR             Display the OK dialog with text. (default: '')                    │
+│ --ask STR               Prompt the user to input a text. (default: '')                    │
+│ --ask-number STR        Prompt the user to input a number. Empty input = 0. (default: '') │
+│ --is-yes STR            Display confirm box, focusing yes. (default: '')                  │
+│ --is-no STR             Display confirm box, focusing no. (default: '')                   │
+╰───────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+You can fetch a value to i.e. a bash script.
+
+```bash
+$ mininterface  --ask-number "What's your age?"  # GUI window invoked
+18
+```
+

mininterface-0.1.1/README.md

@@ -0,0 +1,213 @@
+# Mininterface – access to GUI, TUI, CLI and config files
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+
+Write the program core, do not bother with the input/output.
+
+![hello world example](asset/hello-world.png "A minimal use case")
+
+Check out the code that displays such window, just the code you need. No lengthy blocks of code imposed by an external dependency.
+
+```python
+from dataclasses import dataclass
+from mininterface import run
+
+@dataclass
+class Config:
+    """Set of options."""
+    test: bool = False
+    """My testing flag"""
+    important_number: int = 4
+    """This number is very important"""
+
+if __name__ == "__main__":
+    args: Config = run(Config, prog="My application").get_args()
+    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.
+
+```python
+with run(Config) as m:
+    print(f"Your important number is {m}")
+    boolean = m.is_yes("Is that alright?")
+```
+
+TODO img
+
+Loading config file is a piece of cake. Alongside `program.py`, put `program.yaml`. Instantly loaded.
+
+```yaml
+important_number: 555
+```
+
+TODO img
+
+- [Mininterface – GUI, TUI, CLI and config](#mininterface-gui-tui-cli-and-config)
+- [Background](#background)
+- [Installation](#installation)
+- [Docs](#docs)
+  * [`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)
+  * [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.
+
+Writing a small and useful program might be a task that takes fifteen minutes. Adding a CLI to specify the parameters is not so much overhead. But building a simple GUI around it? HOURS! Hours spent on researching GUI libraries, wondering why the Python desktop app ecosystem lags so far behind the web world. All you need is a few input fields validated through a clickable window... You do not deserve to add hundred of lines of the code just to define some editable fields. `mininterface` is here to help.
+
+The config variables needed by your program are kept in cozy dataclasses. Write less! The syntax of [tyro](https://github.com/brentyi/tyro) does not require any overhead (as its `argparse` alternatives do). You just annotate a class attribute, append a simple docstring and get a fully functional application:
+* Call it as `program.py --help` to display full help.
+* Use any flag in CLI: `program.py --test`  causes `args.test` be set to `True`.
+* The main benefit: Launch it without parameters as `program.py` to get a full working window with all the flags ready to be edited.
+* Running on a remote machine? Automatic regression to the text interface.
+
+# Installation
+
+Install with a single command from [PyPi](https://pypi.org/project/mininterface/).
+
+```python3
+pip install mininterface
+```
+
+# Docs
+
+You can easily nest the configuration. (See also [Tyro Hierarchical Configs](https://brentyi.github.io/tyro/examples/02_nesting/01_nesting/)).
+
+Just put another dataclass inside the config file:
+
+```python3
+@dataclass
+class FurtherConfig:
+    token: str
+    host: str = "example.org"
+
+@dataclass
+class Config:
+    further: FurtherConfig
+
+...
+print(config.further.host)  # example.org
+```
+
+A subset might be defaulted in YAML:
+
+```yaml
+further:
+  host: example.com
+```
+
+Or by CLI:
+
+```
+$./program.py --further.host example.net
+```
+
+## `mininterface`
+
+### `run(config=None, interface=GuiInterface, **kwargs)`
+Wrap your configuration dataclass into `run` to access the interface. Normally, an interface is chosen automatically. We prefer the graphical one, regressed to a text interface on a machine without display.
+Besides, if given a configuration dataclass, the function enriches it with the CLI commands and possibly with the default from a config file if such exists. It searches the config file in the current working directory, with the program name ending on *.yaml*, ex: `program.py` will fetch `./program.yaml`.
+
+* `config:ConfigClass`: Dataclass with the configuration.
+* `interface`: Which interface to prefer. By default, we use the GUI, the fallback is the REPL.
+* `**kwargs`: The same as for [`argparse.ArgumentParser`](https://docs.python.org/3/library/argparse.html).
+* Returns: `interface` Interface used.
+
+You cay context manage the function by a `with` statement. The stdout will be redirected to the interface (GUI window).
+
+See the [initial examples](#mininterface-gui-tui-cli-and-config).
+
+## Interfaces
+
+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.
+* `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.
+
+```python
+with TuiInterface("My program") as m:
+    number = m.ask_number("Returns number")
+```
+
+### `Mininterface(title: str = '')`
+Initialize.
+### `alert(self, text: str)`
+Prompt the user to confirm the text.
+### `ask(self, text: str) -> str`
+Prompt the user to input a text.
+### `ask_args(self) -> ~ConfigInstance`
+Allow the user to edit whole configuration. (Previously fetched from CLI and config file by parse_args.)
+### `ask_form(self, args: FormDict, title="") -> dict`
+Prompt the user to fill up whole form.
+* `args`: Dict of `{labels: default value}`. The form widget infers from the default value type.
+  The dict can be nested, it can contain a subgroup.
+  The default value might be `mininterface.Value` that allows you to add descriptions.
+  A checkbox example: `{"my label": Value(True, "my description")}`
+* `title`: Optional form title.
+### `ask_number(self, text: str) -> int`
+Prompt the user to input a number. Empty input = 0.
+### `get_args(self, ask_on_empty_cli=True) -> ~ConfigInstance`
+Returns whole configuration (previously fetched from CLI and config file by parse_args).
+If program was launched with no arguments (empty CLI), invokes self.ask_args() to edit the fields.
+### `is_no(self, text: str) -> bool`
+Display confirm box, focusing no.
+### `is_yes(self, text: str) -> bool`
+Display confirm box, focusing yes.
+
+```python
+m = run(prog="My program")
+print(m.ask_yes("Is it true?"))  # True/False
+```
+
+### `parse_args(self, config: Callable[..., ~ConfigInstance], config_file: pathlib.Path | None = None, **kwargs) -> ~ConfigInstance`
+Parse CLI arguments, possibly merged from a config file.
+* `config`: Dataclass with the configuration.
+* `config_file`: File to load YAML to be merged with the configuration. You do not have to re-define all the settings, you can choose a few.
+* `**kwargs` The same as for argparse.ArgumentParser.
+* Returns: `ConfigInstance` Configuration namespace.
+
+## Standalone
+
+When invoked directly, it creates simple GUI dialogs.
+
+```bash
+$ mininterface  --help
+usage: Mininterface [-h] [OPTIONS]
+
+Simple GUI dialog. Outputs the value the user entered.
+
+╭─ options ─────────────────────────────────────────────────────────────────────────────────╮
+│ -h, --help              show this help message and exit                                   │
+│ --alert STR             Display the OK dialog with text. (default: '')                    │
+│ --ask STR               Prompt the user to input a text. (default: '')                    │
+│ --ask-number STR        Prompt the user to input a number. Empty input = 0. (default: '') │
+│ --is-yes STR            Display confirm box, focusing yes. (default: '')                  │
+│ --is-no STR             Display confirm box, focusing no. (default: '')                   │
+╰───────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+You can fetch a value to i.e. a bash script.
+
+```bash
+$ mininterface  --ask-number "What's your age?"  # GUI window invoked
+18
+```

mininterface-0.1.1/mininterface/GuiInterface.py

@@ -0,0 +1,174 @@
+import sys
+from typing import Any, Callable
+
+try:
+    from tkinter import TclError, LEFT, Button, Frame, Label, Text, Tk
+    from tktooltip import ToolTip
+    from tkinter_form import Form
+except ImportError:
+    from mininterface.common import InterfaceNotAvailable
+    raise InterfaceNotAvailable
+
+
+from .common import InterfaceNotAvailable
+from .auxiliary import FormDict, RedirectText, dataclass_to_dict, dict_to_dataclass, recursive_set_focus, normalize_types
+from .Mininterface import Cancelled, ConfigInstance, Mininterface
+
+
+class GuiInterface(Mininterface):
+    def __init__(self, *args, **kwargs):
+        try:
+            super().__init__(*args, **kwargs)
+        except TclError:
+            raise InterfaceNotAvailable
+        self.window = TkWindow(self)
+        self._always_shown = False
+        self._original_stdout = sys.stdout
+
+    def __enter__(self) -> "Mininterface":
+        """ When used in the with statement, the GUI window does not vanish between dialogues. """
+        self._always_shown = True
+        sys.stdout = RedirectText(self.window.text_widget, self.window.pending_buffer, self.window)
+        return self
+
+    def __exit__(self, *_):
+        self._always_shown = False
+        sys.stdout = self._original_stdout
+        if self.window.pending_buffer:  # display text sent to the window but not displayed
+            print("".join(self.window.pending_buffer), end="")
+
+    def alert(self, text: str) -> None:
+        """ Display the OK dialog with text. """
+        return self.window.buttons(text, [("Ok", None)])
+
+    def ask(self, text: str) -> str:
+        return self.window.run_dialog({text: ""})[text]
+
+    def ask_args(self) -> ConfigInstance:
+        """ Display a window form with all parameters. """
+        params_ = dataclass_to_dict(self.args, self.descriptions)
+
+        # fetch the dict of dicts values from the form back to the namespace of the dataclasses
+        data = self.window.run_dialog(params_)
+        dict_to_dataclass(self.args, data)
+        return self.args
+
+    def ask_form(self, args: FormDict, title: str = "") -> dict:
+        """ Prompt the user to fill up whole form.
+            :param args: Dict of `{labels: default value}`. The form widget infers from the default value type.
+                The dict can be nested, it can contain a subgroup.
+                The default value might be `mininterface.Value` that allows you to add descriptions.
+                A checkbox example: {"my label": Value(True, "my description")}
+            :param title: Optional form title.
+        """
+        return self.window.run_dialog(args, title=title)
+
+    def ask_number(self, text: str) -> int:
+        return self.window.run_dialog({text: 0})[text]
+
+    def is_yes(self, text):
+        return self.window.yes_no(text, False)
+
+    def is_no(self, text):
+        return self.window.yes_no(text, True)
+
+
+class TkWindow(Tk):
+    """ An editing window. """
+
+    def __init__(self, interface: GuiInterface):
+        super().__init__()
+        self.params = None
+        self._result = None
+        self._event_bindings = {}
+        self.interface = interface
+        self.title(interface.title)
+        self.bind('<Escape>', lambda _: self._ok(Cancelled))
+
+        self.frame = Frame(self)
+        """ dialog frame """
+
+        self.text_widget = Text(self, wrap='word', height=20, width=80)
+        self.text_widget.pack_forget()
+        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:
+        """ Let the user edit the form_dict values in a GUI window.
+        On abrupt window close, the program exits.
+        """
+        if title:
+            label = Label(self.frame, text=title)
+            label.pack(pady=10)
+
+        self.form = Form(self.frame,
+                         name_form="",
+                         form_dict=formDict,
+                         name_config="Ok",
+                         )
+        self.form.pack()
+
+        # Set the enter 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>")
+        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))
+
+        # focus the first element and run
+        recursive_set_focus(self.form)
+        return self.mainloop(lambda: self.validate(formDict, title))
+
+    def validate(self, formDict: FormDict, title: str):
+        if data := normalize_types(formDict, self.form.get()):
+            return data
+        return self.run_dialog(formDict, title)
+
+    def yes_no(self, text: str, focus_no=True):
+        return self.buttons(text, [("Yes", True), ("No", False)], int(focus_no)+1)
+
+    def buttons(self, text: str, buttons: list[tuple[str, Any]], focused: int = 1):
+        label = Label(self.frame, text=text)
+        label.pack(pady=10)
+
+        for text, value in buttons:
+            button = Button(self.frame, text=text, command=lambda v=value: self._ok(v))
+            button.bind("<Return>", lambda _: button.invoke())
+            button.pack(side=LEFT, padx=10)
+        self.frame.winfo_children()[focused].focus_set()
+        return self.mainloop()
+
+    def _bind_event(self, event, handler):
+        self._event_bindings[event] = handler
+        self.bind(event, handler)
+
+    def mainloop(self, callback: Callable = None):
+        self.frame.pack(pady=5)
+        self.deiconify()  # show if hidden
+        self.pending_buffer.clear()
+        super().mainloop()
+        if not self.interface._always_shown:
+            self.withdraw()  # hide
+
+        if self._result is Cancelled:
+            raise Cancelled
+        if callback:
+            return callback()
+        return self._result
+
+    def _ok(self, val=None):
+        # self.destroy()
+        self.quit()
+        # self.withdraw()
+        self._clear_dialog()
+        self._result = val
+
+    def _clear_dialog(self):
+        self.frame.pack_forget()
+        for widget in self.frame.winfo_children():
+            widget.destroy()
+        for key in self._event_bindings:
+            self.unbind(key)
+        self._event_bindings.clear()
+        self._result = None

mininterface-0.1.1/mininterface/Mininterface.py

@@ -0,0 +1,116 @@
+import logging
+import sys
+from argparse import ArgumentParser
+from dataclasses import MISSING
+from pathlib import Path
+from types import SimpleNamespace
+
+import yaml
+from tyro.extras import get_parser
+
+from .auxiliary import (ConfigClass, ConfigInstance, FormDict, get_args_allow_missing,
+                        get_descriptions)
+
+logger = logging.getLogger(__name__)
+
+
+class Cancelled(SystemExit):
+    # We inherit from SystemExit so that the program exits without a traceback on GUI Escape.
+    pass
+
+
+class Mininterface:
+    """ The base interface.
+        Does not require any user input and hence is suitable for headless testing.
+    """
+
+    def __init__(self, title: str = ""):
+        self.title = title or "Mininterface"
+        self.args: ConfigInstance = SimpleNamespace()
+        """ Parsed arguments, fetched from cli by parse.args """
+        self.descriptions = {}
+        """ Field descriptions """
+
+    def __enter__(self) -> "Mininterface":
+        """ When used in the with statement, the GUI window does not vanish between dialogs
+            and it redirects the stdout to a text area. """
+        return self
+
+    def __exit__(self, *_):
+        pass
+
+    def alert(self, text: str) -> None:
+        """ Prompt the user to confirm the text.  """
+        print("Alert text", text)
+        return
+
+    def ask(self, text: str) -> str:
+        """ Prompt the user to input a text.  """
+        print("Asking", text)
+        raise Cancelled(".. cancelled")
+
+    def ask_args(self) -> ConfigInstance:
+        """ Allow the user to edit whole configuration. (Previously fetched from CLI and config file by parse_args.) """
+        print("Asking the args", self.args)
+        return self.args
+
+    def ask_form(self, args: FormDict, title: str = "") -> dict:
+        """ Prompt the user to fill up whole form.
+            :param args: Dict of `{labels: default value}`. The form widget infers from the default value type.
+                The dict can be nested, it can contain a subgroup.
+                The default value might be `mininterface.Value` that allows you to add descriptions.
+                A checkbox example: `{"my label": Value(True, "my description")}`
+        """
+        print(f"Asking the form {title}", args)
+        return args  # NOTE – this should return dict, not FormDict (get rid of auxiliary.Value values)
+
+    def ask_number(self, text: str) -> int:
+        """ Prompt the user to input a number. Empty input = 0. """
+        print("Asking number", text)
+        return 0
+
+    def get_args(self, ask_on_empty_cli=True) -> ConfigInstance:
+        """ Returns whole configuration (previously fetched from CLI and config file by parse_args).
+            If program was launched with no arguments (empty CLI), invokes self.ask_args() to edit the fields. """
+        # Empty CLI → GUI edit
+        if ask_on_empty_cli and len(sys.argv) <= 1:
+            return self.ask_args()
+        return self.args
+
+    def parse_args(self, config: ConfigClass,
+                   config_file: Path | None = None,
+                   **kwargs) -> ConfigInstance:
+        """ Parse CLI arguments, possibly merged from a config file.
+
+        :param config: Class with the configuration.
+        :param config_file: File to load YAML to be merged with the configuration. You do not have to re-define all the settings, you can choose a few.
+        :param **kwargs The same as for argparse.ArgumentParser.
+        :return: Configuration namespace.
+        """
+        # Load config file
+        if config_file:
+            disk = yaml.safe_load(config_file.read_text()) or {}  # empty file is ok
+            # Nested dataclasses have to be properly initialized. YAML gave them as dicts only.
+            for key in (key for key, val in disk.items() if isinstance(val, dict)):
+                disk[key] = config.__annotations__[key](**disk[key])
+            # To ensure the configuration file does not need to contain all keys, we have to fill in the missing ones.
+            # Otherwise, tyro will spawn warnings about missing fields.
+            static = {key: getattr(config, key, MISSING)
+                      for key in config.__annotations__ if not key.startswith("__") and not key in disk}
+            kwargs["default"] = SimpleNamespace(**(disk | static))
+
+        # Load configuration from CLI
+        parser: ArgumentParser = get_parser(config, **kwargs)
+        self.descriptions = get_descriptions(parser)
+        self.args = get_args_allow_missing(config, kwargs, parser)
+        return self.args
+
+    def is_yes(self, text: str) -> bool:
+        """ Display confirm box, focusing yes. """
+        print("Asking yes:", text)
+        return True
+
+    def is_no(self, text: str) -> bool:
+        """ Display confirm box, focusing no. """
+        print("Asking no:", text)
+        return False

mininterface-0.1.1/mininterface/TuiInterface.py

@@ -0,0 +1,77 @@
+from pprint import pprint
+from .auxiliary import ConfigInstance, FormDict, dataclass_to_dict, dict_to_dataclass
+from .Mininterface import Cancelled, Mininterface
+
+
+class TuiInterface(Mininterface):
+
+    def alert(self, text: str):
+        """ Display text and let the user hit any key. """
+        input(text + " Hit any key.")
+
+    def ask(self, text: str = None):
+        try:
+            txt = input(text + ": ") if text else input()
+        except EOFError:
+            txt = "x"
+        if txt == "x":
+            raise Cancelled(".. cancelled")
+        return txt
+
+    def ask_args(self) -> ConfigInstance:
+        # NOTE: This is minimal implementation that should rather go the ReplInterface.
+        # I might build some menu of changing dict through:
+        #   params_ = dataclass_to_dict(self.args, self.descriptions)
+        #   data = FormDict → dict self.window.run_dialog(params_)
+        #   dict_to_dataclass(self.args, params_)
+        return self.ask_form(self.args)
+
+    def ask_form(self, args: FormDict) -> dict:
+        # NOTE: This is minimal implementation that should rather go the ReplInterface.
+        print("Access `v` (as var) and change values. Then (c)ontinue.")
+        pprint(args)
+        v = args
+        try:
+            import ipdb
+            ipdb.set_trace()
+        except ImportError:
+            import pdb
+            pdb.set_trace()
+        print("*Continuing*")
+        print(args)
+        return args
+
+    def ask_number(self, text):
+        """
+        Let user write number. Empty input = 0.
+        """
+        while True:
+            try:
+                t = self.ask(text=text)
+                if not t:
+                    return 0
+                return int(t)
+            except ValueError:
+                print("This is not a number")
+
+    def is_yes(self, text: str):
+        return self.ask(text=text + " [y]/n").lower() in ("y", "yes", "")
+
+    def is_no(self, text):
+        return self.ask(text=text + " y/[n]").lower() in ("n", "no", "")
+
+
+class ReplInterface(TuiInterface):
+    """ Same as the base TuiInterface, except it starts the REPL. """
+
+    def __getattr__(self, name):
+        """ Run _Mininterface method if exists and starts a REPL. """
+        attr = getattr(super(), name, None)
+        if callable(attr):
+            def wrapper(*args, **kwargs):
+                result = attr(*args, **kwargs)
+                breakpoint()
+                return result
+            return wrapper
+        else:
+            raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'")

mininterface-0.1.1/mininterface/__init__.py

@@ -0,0 +1,56 @@
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Type
+from unittest.mock import patch
+
+try:
+    from mininterface.GuiInterface import GuiInterface
+except ImportError:
+    if TYPE_CHECKING:
+        pass
+    else:
+        GuiInterface = None
+
+from mininterface.Mininterface import ConfigClass, ConfigInstance, Mininterface
+from mininterface.TuiInterface import ReplInterface, TuiInterface
+from mininterface.auxiliary import Value
+
+# TODO auto-handle verbosity https://brentyi.github.io/tyro/examples/04_additional/12_counters/ ?
+# TODO example on missing required options.
+
+
+def run(config: ConfigClass | None = None,
+        interface: Type[Mininterface] = GuiInterface or ReplInterface,  # NOTE we shuold use TuiInterface as a fallback
+        **kwargs) -> Mininterface:
+    """
+    Wrap your configuration dataclass into `run` to access the interface. Normally, an interface is chosen automatically.
+    We prefer the graphical one, regressed to a text interface on a machine without display.
+    Besides, if given a configuration dataclass, the function enriches it with the CLI commands and possibly
+    with the default from a config file if such exists.
+    It searches the config file in the current working directory, with the program name ending on *.yaml*, ex: `program.py` will fetch `./program.yaml`.
+
+    :param config: Dataclass with the configuration.
+    :param interface: Which interface to prefer. By default, we use the GUI, the fallback is the REPL.
+    :param **kwargs The same as for [argparse.ArgumentParser](https://docs.python.org/3/library/argparse.html).
+    :return: Interface used.
+
+    Undocumented: The `config` may be function as well. We invoke its paramters.
+    However, Mininterface.args stores the output of the function instead of the Argparse namespace
+    and methods like `Mininterface.ask_args()` will work unpredictibly..
+    """
+    # Build the interface
+    prog = kwargs.get("prog") or sys.argv[0]
+    # try:
+    interface: GuiInterface | Mininterface = interface(prog)
+    # except InterfaceNotAvailable:  # Fallback to a different interface
+    #     interface = TuiInterface(prog)
+
+    # Load configuration from CLI and a config file
+    if config:
+        cf = Path(sys.argv[0]).with_suffix(".yaml")
+        interface.parse_args(config, cf if cf.exists() and not kwargs.get("default") else None, **kwargs)
+
+    return interface
+
+
+__all__ = ["run", "Value"]

mininterface-0.1.1/mininterface/__main__.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+from typing import List
+
+from .GuiInterface import GuiInterface
+
+from . import run
+
+from tyro.conf import UseCounterAction, UseAppendAction
+__doc__ = """Simple GUI dialog. Outputs the value the user entered."""
+
+
+@dataclass
+class CliInteface:
+    alert: str = ""
+    """ Display the OK dialog with text. """
+    ask: str = ""
+    """ Prompt the user to input a text.  """
+    ask_number: str = ""
+    """ Prompt the user to input a number. Empty input = 0. """
+    is_yes: str = ""
+    """ Display confirm box, focusing yes. """
+    is_no: str = ""
+    """ Display confirm box, focusing no. """
+
+# TODO does not work in REPL interface: mininterface --alert "ahoj"
+def main():
+    # It does make sense to invoke GuiInterface only. Other interface would use STDOUT, hence make this impractical when fetching variable to i.e. a bash script.
+    # TODO It DOES make sense. Change in README. It s a good fallback.
+    result = []
+    with run(CliInteface, prog="Mininterface", description=__doc__) as m:
+        for method, label in vars(m.args).items():
+            if label:
+                result.append(getattr(m, method)(label))
+    # Displays each result on a new line. Currently, this is an undocumented feature.
+    # As we use the script for a single value only and it is not currently possible
+    # to ask two numbers or determine a dialog order etc.
+    [print(val) for val in result]
+
+if __name__ == "__main__":
+    main()

mininterface-0.1.1/mininterface/auxiliary.py

@@ -0,0 +1,195 @@
+import logging
+import os
+import re
+from argparse import Action, ArgumentParser
+from dataclasses import dataclass
+from typing import Any, Callable, Literal, Optional, 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
+except ImportError:
+    tkinter = None
+    END, Entry, Text, Tk, Widget = (None,)*5
+
+from tkinter_form import Value
+from tyro import cli
+from tyro._argparse_formatter import TyroArgumentParser
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Value(Value):
+    """ Override val/description class with additional stuff. """
+
+    annotation: Any | None = None
+    """ Used for validation. To convert an empty '' to None. """
+
+    def __post_init__(self):
+        self._original_desc = self.description
+
+    def set_error_text(self, s):
+        self.description = f"{s} {self._original_desc}"
+
+
+ConfigInstance = TypeVar("ConfigInstance")
+ConfigClass = Callable[..., ConfigInstance]
+FormDict = dict[str, Union[Value, Any, 'FormDict']]
+""" Nested form that can have descriptions (through Value) instead of plain values. """
+
+
+def dataclass_to_dict(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] = dataclass_to_dict(val, descr, _path=f"{_path}{param}.")
+        elif not _path:  # scalar value in root
+            params[main][param] = Value(val, descr.get(param), annotation)
+        else:  # scalar value in nested
+            params[param] = Value(val, descr.get(f"{_path}{param}"), annotation)
+    return params
+
+
+def normalize_types(origin: FormDict, data: dict) -> dict:
+    """ Run validators of all Value objects. If fails, outputs info.
+        Return corrected data. (Ex: Some values might be nulled from "".)
+    """
+    for (group, params), params2 in zip(data.items(), origin.values()):
+        for (key, val), pattern in zip(params.items(), params2.values()):
+            if isinstance(pattern, Value) and pattern.annotation:
+                if val == "" and type(None) in get_args(pattern.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`
+                    data[group][key] = val = None
+                elif pattern.annotation == Optional[int]:
+                    try:
+                        data[group][key] = val = int(val)
+                    except ValueError:
+                        pass
+
+                if not isinstance(val, pattern.annotation):
+                    pattern.set_error_text(f"Type must be `{pattern.annotation}`!")
+                    return False
+    return data
+
+
+def dict_to_dataclass(args: ConfigInstance, data: dict):
+    """ Convert 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)
+            else:
+                setattr(args, key, 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

mininterface-0.1.1/mininterface/common.py

@@ -0,0 +1,2 @@
+class InterfaceNotAvailable(ImportError):
+    pass

mininterface-0.1.1/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "mininterface"
+version = "0.1.1"
+description = "A minimal access to GUI, TUI, CLI and config"
+authors = ["Edvard Rejthar <edvard.rejthar@nic.cz>"]
+license = "GPL-3.0-or-later"
+homepage = "https://github.com/CZ-NIC/mininterface"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+tyro = "*"
+pyyaml = "*"
+envelope = "*"
+requests = "*"
+tkinter-tooltip = "*"
+tkinter_form = "*"
+
+[tool.poetry.scripts]
+mininterface = "mininterface.__main__:main"