mininterface 0.6.2rc2__tar.gz → 0.7.0__tar.gz

{mininterface-0.6.2rc2 → mininterface-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mininterface
-Version: 0.6.2rc2
+Version: 0.7.0
 Summary: A minimal access to GUI, TUI, CLI and config
 Home-page: https://github.com/CZ-NIC/mininterface
 License: GPL-3.0-or-later
@@ -13,24 +13,26 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: all
+Provides-Extra: web
 Requires-Dist: autocombobox (==1.4.2)
 Requires-Dist: pyyaml
-Requires-Dist: requests
-Requires-Dist: textual
+Requires-Dist: textual (>=0.84,<0.85)
 Requires-Dist: tkinter-tooltip
 Requires-Dist: tkinter_form (==0.1.5.2)
+Requires-Dist: typing_extensions
 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)
 [![Build Status](https://github.com/CZ-NIC/mininterface/actions/workflows/run-unittest.yml/badge.svg)](https://github.com/CZ-NIC/mininterface/actions)
-[![Downloads](https://pepy.tech/badge/mininterface)](https://pepy.tech/project/mininterface)
+[![Downloads](https://static.pepy.tech/badge/mininterface)](https://pepy.tech/project/mininterface)
 
 Write the program core, do not bother with the input/output.
 
-![Hello world example: GUI window](https://github.com/CZ-NIC/mininterface/blob/main/asset/hello-world.png?raw=True "A minimal use case – GUI")
-![Hello world example: TUI fallback](https://github.com/CZ-NIC/mininterface/blob/main/asset/hello-tui.webp?raw=True "A minimal use case – TUI fallback")
+![Hello world example: GUI window](https://github.com/CZ-NIC/mininterface/blob/main/asset/hello-gui.avif?raw=True "A minimal use case – GUI")
+![Hello world example: TUI fallback](https://github.com/CZ-NIC/mininterface/blob/main/asset/hello-tui.avif?raw=True "A minimal use case – TUI fallback")
 
 Check out the code, which is surprisingly short, that displays such a window or its textual fallback.
 
@@ -49,10 +51,11 @@ class Env:
     """ This number is very important """
 
 if __name__ == "__main__":
-    env = run(Env, prog="My application").env
+    m = run(Env, prog="My application")
+    m.form()
     # Attributes are suggested by the IDE
     # along with the hint text 'This number is very important'.
-    print(env.my_number)
+    print(m.env.my_number)
 ```
 
 # Contents
@@ -69,16 +72,18 @@ It was all the code you need. No lengthy blocks of code imposed by an external d
 
 
 ```bash
-$ ./hello.py
-usage: My application [-h] [--test | --no-test] [--important-number INT]
+$ ./hello.py    --help
+usage: My application [-h] [-v] [--my-flag | --no-my-flag] [--my-number INT]
 
 This calculates something.
 
-╭─ 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) │
-╰────────────────────────────────────────────────────────────────────╯
+╭─ options ───────────────────────────────────────────────────────────────╮
+│ -h, --help             show this help message and exit                  │
+│ -v, --verbose          Verbosity level. Can be used twice to increase.  │
+│ --my-flag, --no-my-flag                                                 │
+│                        This switches the functionality (default: False) │
+│ --my-number INT        This number is very important (default: 4)       │
+╰─────────────────────────────────────────────────────────────────────────╯
 ```
 
 ## You got config file management
@@ -120,11 +125,22 @@ Install with a single command from [PyPi](https://pypi.org/project/mininterface/
 pip install mininterface
 ```
 
+## Minimal installation
+
+Should you need just the CLI part and you are happy with basic text dialogs, use these commands instead:
+
+```bash
+pip install --no-dependencies mininterface
+pip install tyro typing_extensions pyyaml
+```
+
 # Docs
 See the docs overview at [https://cz-nic.github.io/mininterface/](https://cz-nic.github.io/mininterface/Overview/).
 
 # Examples
 
+A powerful [`m.form`][mininterface.Mininterface.form] dialog method accepts either a dataclass or a dict. Take a look on both.
+
 ## A complex dataclass.
 
 ```python3
@@ -143,7 +159,7 @@ class Env:
   nested_config: NestedEnv
 
   mandatory_str: str
-  """ As there is not default value, you will be prompted automatically to fill up the field """
+  """ As there is no default value, you will be prompted automatically to fill up the field """
 
   my_number: int | None = None
   """ This is not just a dummy number, if left empty, it is None. """
@@ -167,6 +183,14 @@ print(m.env)
 m.form()
 ```
 
+As the attribute `mandatory_str` requires a value, a prompt appears automatically:
+
+![Complex example missing field](https://github.com/CZ-NIC/mininterface/blob/main/asset/complex_example_missing_field.avif?raw=True)
+
+Then, full form appears:
+
+![Complex example](https://github.com/CZ-NIC/mininterface/blob/main/asset/complex_example.avif?raw=True)
+
 ## Form with paths
 
 We have a dict with some paths. Here is how it looks.
@@ -187,16 +211,3 @@ m.form(my_dictionary)
 
 ![List of paths](https://github.com/CZ-NIC/mininterface/blob/main/asset/list_of_paths.avif?raw=True)
 
-
-
-
-
-
-
-
-
-
-
-
-
-

{mininterface-0.6.2rc2 → mininterface-0.7.0}/README.md

@@ -1,12 +1,12 @@
 # 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)
 [![Build Status](https://github.com/CZ-NIC/mininterface/actions/workflows/run-unittest.yml/badge.svg)](https://github.com/CZ-NIC/mininterface/actions)
-[![Downloads](https://pepy.tech/badge/mininterface)](https://pepy.tech/project/mininterface)
+[![Downloads](https://static.pepy.tech/badge/mininterface)](https://pepy.tech/project/mininterface)
 
 Write the program core, do not bother with the input/output.
 
-![Hello world example: GUI window](https://github.com/CZ-NIC/mininterface/blob/main/asset/hello-world.png?raw=True "A minimal use case – GUI")
-![Hello world example: TUI fallback](https://github.com/CZ-NIC/mininterface/blob/main/asset/hello-tui.webp?raw=True "A minimal use case – TUI fallback")
+![Hello world example: GUI window](https://github.com/CZ-NIC/mininterface/blob/main/asset/hello-gui.avif?raw=True "A minimal use case – GUI")
+![Hello world example: TUI fallback](https://github.com/CZ-NIC/mininterface/blob/main/asset/hello-tui.avif?raw=True "A minimal use case – TUI fallback")
 
 Check out the code, which is surprisingly short, that displays such a window or its textual fallback.
 
@@ -25,10 +25,11 @@ class Env:
     """ This number is very important """
 
 if __name__ == "__main__":
-    env = run(Env, prog="My application").env
+    m = run(Env, prog="My application")
+    m.form()
     # Attributes are suggested by the IDE
     # along with the hint text 'This number is very important'.
-    print(env.my_number)
+    print(m.env.my_number)
 ```
 
 # Contents
@@ -45,16 +46,18 @@ It was all the code you need. No lengthy blocks of code imposed by an external d
 
 
 ```bash
-$ ./hello.py
-usage: My application [-h] [--test | --no-test] [--important-number INT]
+$ ./hello.py    --help
+usage: My application [-h] [-v] [--my-flag | --no-my-flag] [--my-number INT]
 
 This calculates something.
 
-╭─ 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) │
-╰────────────────────────────────────────────────────────────────────╯
+╭─ options ───────────────────────────────────────────────────────────────╮
+│ -h, --help             show this help message and exit                  │
+│ -v, --verbose          Verbosity level. Can be used twice to increase.  │
+│ --my-flag, --no-my-flag                                                 │
+│                        This switches the functionality (default: False) │
+│ --my-number INT        This number is very important (default: 4)       │
+╰─────────────────────────────────────────────────────────────────────────╯
 ```
 
 ## You got config file management
@@ -96,11 +99,22 @@ Install with a single command from [PyPi](https://pypi.org/project/mininterface/
 pip install mininterface
 ```
 
+## Minimal installation
+
+Should you need just the CLI part and you are happy with basic text dialogs, use these commands instead:
+
+```bash
+pip install --no-dependencies mininterface
+pip install tyro typing_extensions pyyaml
+```
+
 # Docs
 See the docs overview at [https://cz-nic.github.io/mininterface/](https://cz-nic.github.io/mininterface/Overview/).
 
 # Examples
 
+A powerful [`m.form`][mininterface.Mininterface.form] dialog method accepts either a dataclass or a dict. Take a look on both.
+
 ## A complex dataclass.
 
 ```python3
@@ -119,7 +133,7 @@ class Env:
   nested_config: NestedEnv
 
   mandatory_str: str
-  """ As there is not default value, you will be prompted automatically to fill up the field """
+  """ As there is no default value, you will be prompted automatically to fill up the field """
 
   my_number: int | None = None
   """ This is not just a dummy number, if left empty, it is None. """
@@ -143,6 +157,14 @@ print(m.env)
 m.form()
 ```
 
+As the attribute `mandatory_str` requires a value, a prompt appears automatically:
+
+![Complex example missing field](https://github.com/CZ-NIC/mininterface/blob/main/asset/complex_example_missing_field.avif?raw=True)
+
+Then, full form appears:
+
+![Complex example](https://github.com/CZ-NIC/mininterface/blob/main/asset/complex_example.avif?raw=True)
+
 ## Form with paths
 
 We have a dict with some paths. Here is how it looks.
@@ -162,16 +184,3 @@ m.form(my_dictionary)
 ```
 
 ![List of paths](https://github.com/CZ-NIC/mininterface/blob/main/asset/list_of_paths.avif?raw=True)
-
-
-
-
-
-
-
-
-
-
-
-
-

mininterface-0.7.0/mininterface/ValidationFail.py

@@ -0,0 +1,5 @@
+class ValidationFail(ValueError):
+    """ Signal to the form that submit failed and we want to restore it.
+    """
+    # NOTE example
+    pass

{mininterface-0.6.2rc2 → mininterface-0.7.0}/mininterface/__init__.py

@@ -1,31 +1,22 @@
 import sys
+from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Type
+from types import UnionType
+from typing import TYPE_CHECKING, Literal, Optional, Sequence, Type, Union
 
-from .types import Validation, Choices, PathTag
-from .cli_parser import _parse_cli
-from .common import InterfaceNotAvailable, Cancelled
+from .exceptions import Cancelled, InterfaceNotAvailable
+
+from .interfaces import get_interface
+
+from . import validators
+from .cli_parser import _parse_cli, assure_args
+from .subcommands import Command, SubcommandPlaceholder
 from .form_dict import DataClass, EnvClass
-from .tag import Tag
 from .mininterface import EnvClass, Mininterface
+from .start import Start
+from .tag import Tag
 from .text_interface import ReplInterface, TextInterface
-from . import validators
-
-# Import optional interfaces
-try:
-    from mininterface.tk_interface import TkInterface
-except ImportError:
-    if TYPE_CHECKING:
-        pass  # Replace TYPE_CHECKING with `type GuiInterface = None` since Python 3.12
-    else:
-        TkInterface = None
-try:
-    from mininterface.textual_interface import TextualInterface
-except ImportError:
-    TextualInterface = None
-
-GuiInterface = TkInterface
-TuiInterface = TextualInterface or TextInterface
+from .types import Choices, PathTag, Validation
 
 # NOTE:
 # ask_for_missing does not work with tyro Positional, stays missing.
@@ -33,14 +24,22 @@ TuiInterface = TextualInterface or TextInterface
 # class Env:
 #   files: Positional[list[Path]]
 
+# NOTE: imgs missing in Interfaces.md
+
+
+@dataclass
+class _Empty:
+    pass
+
 
-def run(env_class: Type[EnvClass] | None = None,
+def run(env_or_list: Type[EnvClass] | list[Type[Command]] | None = None,
         ask_on_empty_cli: bool = False,
         title: str = "",
         config_file: Path | str | bool = True,
         add_verbosity: bool = True,
         ask_for_missing: bool = True,
-        interface: Type[Mininterface] = GuiInterface or TuiInterface,
+        interface: Type[Mininterface] | Literal["gui"] | Literal["tui"] = None,
+        args: Optional[Sequence[str]] = None,
         **kwargs) -> Mininterface[EnvClass]:
     """ The main access, start here.
     Wrap your configuration dataclass into `run` to access the interface. An interface is chosen automatically,
@@ -51,7 +50,12 @@ def run(env_class: Type[EnvClass] | None = None,
     with the program name ending on *.yaml*, ex: `program.py` will fetch `./program.yaml`.
 
     Args:
-        env_class: Dataclass with the configuration. Their values will be modified with the CLI arguments.
+        env_or_list:
+            * `dataclass` Dataclass with the configuration. Their values will be modified with the CLI arguments.
+            * `list` of [Commands][mininterface.subcommands.Command] let you create multiple commands within a single program, each with unique options.
+            * `None` You need just the dialogs, no CLI/config file parsing.
+
+
         ask_on_empty_cli: If program was launched with no arguments (empty CLI), invokes self.form() to edit the fields.
             (Withdrawn when `ask_for_missing` happens.)
             ```python
@@ -106,8 +110,10 @@ def run(env_class: Type[EnvClass] | None = None,
             $ program.py  # omitting --required-number
             # Dialog for `required_number` appears
             ```
-        interface: Which interface to prefer. By default, we use the GUI, the fallback is the TUI. See the full [list](Overview.md#all-possible-interfaces) of possible interfaces.
-
+        interface: Which interface to prefer. By default, we use the GUI, the fallback is the TUI.
+            You may write "gui" or "tui" literal or pass a specific Mininterface type,
+            see the full [list](Interfaces.md) of possible interfaces.
+        args: Parse arguments from a sequence instead of the command line.
     Kwargs:
         The same as for [argparse.ArgumentParser](https://docs.python.org/3/library/argparse.html).
 
@@ -119,8 +125,15 @@ def run(env_class: Type[EnvClass] | None = None,
     The stdout will be redirected to the interface (ex. a GUI window).
 
     ```python
+    from dataclasses import dataclass
+    from mininterface import run
+
+    @dataclass
+    class Env:
+        my_number: int = 4
+
     with run(Env) as m:
-        print(f"Your important number is {m.env.important_number}")
+        print(f"Your important number is {m.env.my_number}")
         boolean = m.is_yes("Is that alright?")
     ```
 
@@ -139,7 +152,7 @@ def run(env_class: Type[EnvClass] | None = None,
     # Undocumented experimental: `default` keyword argument for tyro may serve for default values instead of a config file.
 
     # Prepare the config file
-    if config_file is True and not kwargs.get("default") and env_class:
+    if config_file is True and not kwargs.get("default") and env_or_list:
         # Undocumented feature. User put a namespace into kwargs["default"]
         # that already serves for defaults. We do not fetch defaults yet from a config file.
         try:
@@ -155,26 +168,29 @@ def run(env_class: Type[EnvClass] | None = None,
     elif isinstance(config_file, str):
         config_file = Path(config_file)
 
-    # Load configuration from CLI and a config file
+    # Determine title
+    title = title or kwargs.get("prog") or Path(sys.argv[0]).name
+    start = Start(title, interface)
+
+    # Hidden meta-commands in args
+    args = assure_args(args)
+    if len(args) == 1 and args[0] == "--integrate-to-system":
+        start.integrate(env_or_list or _Empty)
+        quit()
+
     env, wrong_fields = None, {}
-    if env_class:
-        verb_ = add_verbosity and "verbose" not in env_class.__annotations__
-        env, wrong_fields = _parse_cli(env_class, config_file, verb_, ask_for_missing, **kwargs)
+    if isinstance(env_or_list, list) and SubcommandPlaceholder in env_or_list and args and args[0] == "subcommand":
+        start.choose_subcommand(env_or_list, args=args[1:])
+    elif isinstance(env_or_list, list) and not args:
+        start.choose_subcommand(env_or_list)
+    elif env_or_list:
+        # Load configuration from CLI and a config file
+        env, wrong_fields = _parse_cli(env_or_list, config_file, add_verbosity, ask_for_missing, args, **kwargs)
+    else:  # even though there is no configuration, yet we need to parse CLI for meta-commands like --help or --verbose
+        _parse_cli(_Empty, None, add_verbosity, ask_for_missing, args)
 
     # Build the interface
-    title = title or kwargs.get("prog") or Path(sys.argv[0]).name
-    if "prog" not in kwargs:
-        kwargs["prog"] = title
-    try:
-        if interface == "tui":  # undocumented feature
-            interface = TuiInterface
-        elif interface == "gui":  # undocumented feature
-            interface = GuiInterface
-        if interface is None:
-            raise InterfaceNotAvailable  # GuiInterface might be None when import fails
-        interface = interface(title, env)
-    except InterfaceNotAvailable:  # Fallback to a different interface
-        interface = TuiInterface(title, env)
+    interface = get_interface(title, interface, env)
 
     # Empty CLI → GUI edit
     if ask_for_missing and wrong_fields:
@@ -189,5 +205,4 @@ def run(env_class: Type[EnvClass] | None = None,
 
 __all__ = ["run", "Tag", "validators", "InterfaceNotAvailable", "Cancelled",
            "Validation", "Choices", "PathTag",
-           "Mininterface", "GuiInterface", "TuiInterface", "TextInterface", "TextualInterface", "TkInterface"
-           ]
+           "Mininterface"]

mininterface-0.7.0/mininterface/__main__.py

@@ -0,0 +1,78 @@
+from dataclasses import dataclass
+import sys
+from typing import Literal
+from tyro.conf import FlagConversionOff
+
+from .exceptions import DependencyRequired
+
+from . import run, Mininterface
+from .showcase import showcase
+
+__doc__ = """Simple GUI dialog. Outputs the value the user entered."""
+
+
+@dataclass
+class Web:
+    """ Experimenal undocumented feature. """
+
+    cmd: str = ""
+    """ Launch a miniterface program, while the TextualInterface will be exposed to the web."""
+    # NOTE: The textual app ends after the first submit. We have to correct that before the web makes sense.
+    # with run(interface=TextualInterface) as m:
+    #   m.form({"hello": 1})  # the app ends here
+    #   m.form({"hello": 2})  # we never get here
+
+    port: int = 64646
+
+
+@dataclass
+class CliInteface:
+    web: Web
+    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'. """
+
+    showcase: Literal["gui"] | Literal["tui"] | Literal["all"] = None
+    """ Prints various form just to show what's possible. """
+
+
+def web(m: Mininterface):
+    try:
+        from textual_serve.server import Server
+    except ImportError:
+        raise DependencyRequired("web")
+    server = Server(m.env.web.cmd, port=m.env.web.port)
+    server.serve()
+
+
+def main():
+    result = []
+    # We tested both GuiInterface and TextualInterface are able to pass a variable to i.e. a bash script.
+    # NOTE TextInterface fails (`mininterface --ask Test | grep Hello` – pipe causes no visible output).
+    with run(CliInteface, prog="Mininterface", description=__doc__) as m:
+        for method, label in vars(m.env).items():
+            if method in ["web", "showcase"]:  # processed later
+                continue
+            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 m.env.web.cmd:
+        web(m)
+    if m.env.showcase:
+        showcase(m.env.showcase)
+
+
+if __name__ == "__main__":
+    main()

{mininterface-0.6.2rc2 → mininterface-0.7.0}/mininterface/auxiliary.py

@@ -1,7 +1,8 @@
+from dataclasses import is_dataclass
 import os
 import re
 from argparse import ArgumentParser
-from typing import Iterable, TypeVar
+from typing import Callable, Iterable, Optional, TypeVar
 
 from tyro.extras import get_parser
 
@@ -11,10 +12,12 @@ common_iterables = list, tuple, set
 """ collections, and not a str """
 
 
-def flatten(d: dict[str, T | dict]) -> Iterable[T]:
+def flatten(d: dict[str, T | dict], include_keys: Optional[Callable[[str], list]] = None) -> Iterable[T]:
     """ Recursively traverse whole dict """
-    for v in d.values():
+    for k, v in d.items():
         if isinstance(v, dict):
+            if include_keys:
+                yield from include_keys(k)
             yield from flatten(v)
         else:
             yield v
@@ -53,9 +56,13 @@ def get_terminal_size():
 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. """
     # clean-up tyro stuff that may have a meaning in the CLI, but not in the UI
-    return {action.dest.replace("-", "_"): re.sub(r"\((default|fixed to).*\)", "", action.help or "")
+    return {action.dest.replace("-", "_"): re.sub(r"\((default|fixed to|required).*\)", "", action.help or "")
             for action in parser._actions}
 
 
 def get_description(obj, param: str) -> str:
     return get_descriptions(get_parser(obj))[param]
+
+
+def yield_annotations(dataclass):
+    yield from (cl.__annotations__ for cl in dataclass.__mro__ if is_dataclass(cl))