text interface

Author: e3rd

docs/Changelog.md

@@ -3,6 +3,7 @@
 ## 0.8.0 (unreleased)
 * better annotated fetching
 * SecretTag
+* much better TextInterface
 
 ## 0.7.5 (2025-01-29)
 * UI [configuration](Configuration.md)

mininterface/__init__.py

@@ -3,6 +3,8 @@
 from pathlib import Path
 from typing import Literal, Optional, Sequence, Type
 
+from .config import Config
+
 from .types.alias import Choices, Validation
 
 from .exceptions import Cancelled, InterfaceNotAvailable
@@ -38,7 +40,8 @@ def run(env_or_list: Type[EnvClass] | list[Type[Command]] | None = None,
         config_file: Path | str | bool = True,
         add_verbosity: bool = True,
         ask_for_missing: bool = True,
-        interface: Type[Mininterface] | Literal["gui"] | Literal["tui"] | None = None,
+        # We do not use InterfaceType as a type here because we want the documentation to show full alias:
+        interface: Type[Mininterface] | Literal["gui"] | Literal["tui"] | Literal["text"] | None = None,
         args: Optional[Sequence[str]] = None,
         **kwargs) -> Mininterface[EnvClass]:
     """ The main access, start here.

mininterface/__main__.py

@@ -1,12 +1,12 @@
-from dataclasses import dataclass
 import sys
+from dataclasses import dataclass
 from typing import Literal, Optional
+
 from tyro.conf import FlagConversionOff
 
+from . import Mininterface, run
 from .exceptions import DependencyRequired
-
-from . import run, Mininterface
-from .showcase import showcase
+from .showcase import ChosenInterface, showcase
 
 __doc__ = """Simple GUI dialog. Outputs the value the user entered."""
 
@@ -25,7 +25,6 @@ class Web:
     port: int = 64646
 
 
-InterfaceType = Literal["gui"] | Literal["tui"] | Literal["all"]
 Showcase = Literal[1] | Literal[2]
 
 
@@ -43,7 +42,7 @@ class CliInteface:
     is_no: str = ""
     """ Display confirm box, focusing 'no'. """
 
-    showcase: Optional[tuple[InterfaceType, Showcase]] = None
+    showcase: Optional[tuple[ChosenInterface, Showcase]] = None
     """ Prints various form just to show what's possible."""
 
 

mininterface/cli_parser.py

@@ -256,8 +256,9 @@ def parse_cli(env_or_list: Type[EnvClass] | list[Type[EnvClass]],
         if mininterface := disk.pop("mininterface", None):
             # Section 'mininterface' in the config file changes the global configuration.
             for key, value in vars(_create_with_missing(MininterfaceConfig, mininterface)).items():
-                setattr(Config, key, value)
-        kwargs["default"] = _create_with_missing(env, disk)
+                if value is not MISSING_NONPROP:
+                    setattr(Config, key, value)
+            kwargs["default"] = _create_with_missing(env, disk)
 
     # Load configuration from CLI
     return run_tyro_parser(subcommands or env, kwargs, add_verbosity, ask_for_missing, args)
@@ -267,6 +268,8 @@ def _create_with_missing(env, disk: dict):
     """
     Create a default instance of an Env object. This is due to provent tyro to spawn warnings about missing fields.
     Nested dataclasses have to be properly initialized. YAML gave them as dicts only.
+
+    The result contains MISSING_NONPROP on the places the original Env object must have a value.
     """
 
     # Determine model

mininterface/config.py

@@ -1,7 +1,10 @@
 # Configuration used by all minterfaces in the program.
 # Might be changed by a 'mininterface' section in a config file.
 from dataclasses import dataclass
-from typing import Literal
+from typing import Literal, Optional
+
+# We do not use InterfaceType as a type in run because we want the documentation to show full alias.
+InterfaceName = Literal["gui"] | Literal["tui"] | Literal["text"]
 
 
 @dataclass
@@ -16,13 +19,19 @@ class Tui:
     ...
 
 
+@dataclass
+class Text:
+    ...
+
+
 @dataclass  # (slots=True)
 class MininterfaceConfig:
     gui: Gui
     tui: Tui
-    interface: Literal["gui"] | Literal["tui"] | None = None
+    text: Text
+    interface: Optional[InterfaceName] = None
     """ Enforce an interface. By default, we choose automatically. """
 
 
-Config = MininterfaceConfig(Gui(), Tui())
+Config = MininterfaceConfig(Gui(), Tui(), Text())
 """ Global configuration singleton to be accessed by all minterfaces. """

mininterface/facet.py

@@ -34,9 +34,8 @@ class BackendAdaptor(ABC):
     post_submit_action: Optional[Callable] = None
     interface: "Mininterface"
 
-    @staticmethod
     @abstractmethod
-    def widgetize(tag: Tag):
+    def widgetize(self, tag: Tag):
         """ Wrap Tag to a UI widget. """
         pass
 
@@ -63,7 +62,7 @@ def __init__(self, interface: "Mininterface"):
         self.facet = Facet(self, interface.env)
         self.interface = interface
 
-    def widgetize(tag: Tag):
+    def widgetize(self, tag: Tag):
         pass
 
     def run_dialog(self, form: TagDict, title: str = "", submit: bool | str = True) -> TagDict:

mininterface/form_dict.py

@@ -106,7 +106,7 @@ def dict_to_tagdict(data: dict, mininterface: Optional["Mininterface"] = None) -
             if not isinstance(val, Tag):
                 tag = Tag(val, "", name=key, _src_dict=data, _src_key=key, **d)
             else:
-                tag = tag_fetch(val, d)
+                tag = tag_fetch(val, d, key)
             tag = tag_assure_type(tag)
             fd[key] = tag
     return fd
@@ -186,7 +186,7 @@ def dataclass_to_tagdict(env: EnvClass | Type[EnvClass], mininterface: Optional[
             if not isinstance(val, Tag):
                 tag = tag_factory(val, _src_key=param, _src_obj=env, **d)
             else:
-                tag = tag_fetch(val, d)
+                tag = tag_fetch(val, d, param)
                 tag = tag_assure_type(tag)
             (subdict if _nested else main)[param] = tag
     return subdict

mininterface/interfaces.py

@@ -3,39 +3,44 @@
 import sys
 from typing import Literal, Type
 
-
-from .config import Config
 from .mininterface import Mininterface
+from .config import Config, InterfaceName
 from .exceptions import InterfaceNotAvailable
-from .text_interface import TextInterface
 
-# We do not use InterfaceType as a type in run because we want the documentation to show full alias.
-InterfaceType = Type[Mininterface] | Literal["gui"] | Literal["tui"] | None
+InterfaceType = Type[Mininterface] | InterfaceName | None
 
 
 def __getattr__(name):
-    # shortcuts
-    if name == "GuiInterface":
-        return __getattr__("TkInterface")
-    if name == "TuiInterface":
-        # if textual not installed or isatty False, return TextInterface
-        return __getattr__("TextualInterface") or TextInterface
-
-    # real interfaces
-    if name == "TkInterface":
-        try:
-            globals()[name] = import_module("..tk_interface", __name__).TkInterface
-            return globals()[name]
-        except InterfaceNotAvailable:
-            return None
-
-    if name == "TextualInterface":
-        try:
-            globals()[name] = import_module("..textual_interface", __name__).TextualInterface
-            return globals()[name]
-        except InterfaceNotAvailable:
-            return None
-    return None  # such attribute does not exist
+    match name:
+        # shortcuts
+        case "GuiInterface":
+            return __getattr__("TkInterface")
+        case "TuiInterface":
+            # if textual not installed or isatty False, return TextInterface
+            return __getattr__("TextualInterface") or __getattr__("TextInterface")
+
+        # real interfaces
+        case "TextInterface":
+            try:
+                globals()[name] = import_module("..text_interface", __name__).TextInterface
+                return globals()[name]
+            except InterfaceNotAvailable:
+                return None
+        case "TkInterface":
+            try:
+                globals()[name] = import_module("..tk_interface", __name__).TkInterface
+                return globals()[name]
+            except InterfaceNotAvailable:
+                return None
+
+        case "TextualInterface":
+            try:
+                globals()[name] = import_module("..textual_interface", __name__).TextualInterface
+                return globals()[name]
+            except InterfaceNotAvailable:
+                return None
+        case _:
+            return None  # such attribute does not exist
 
 
 def get_interface(title="", interface: InterfaceType = None, env=None):
@@ -44,11 +49,17 @@ def get_interface(title="", interface: InterfaceType = None, env=None):
     if isinstance(interface, type) and issubclass(interface, Mininterface):
         # the user gave a specific interface, let them catch InterfaceNotAvailable then
         return interface(*args)
-    if interface == "gui" or interface is None:
-        try:
-            return __getattr__("GuiInterface")(*args)
-        except InterfaceNotAvailable:
-            pass
+    match interface:
+        case "gui" | None:
+            try:
+                return __getattr__("GuiInterface")(*args)
+            except InterfaceNotAvailable:
+                pass
+        case "text":
+            try:
+                return __getattr__("TextInterface")(*args)
+            except InterfaceNotAvailable:
+                pass
     try:
         return __getattr__("TuiInterface")(*args)
     except InterfaceNotAvailable:

mininterface/mininterface.py

@@ -426,6 +426,9 @@ def _form(self,
             # the original dataclass is updated, hence we do not need to catch the output from launch_callback
             adaptor.run_dialog(dataclass_to_tagdict(_form, self), title=title, submit=submit)
             return _form
+        if isinstance(_form, SimpleNamespace) and not vars(_form):
+            # There is no env, return the empty env. Not well documented.
+            return self.env
         raise ValueError(f"Unknown form input {_form}")
 
     def is_yes(self, text: str) -> bool:

mininterface/showcase.py

@@ -1,17 +1,21 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
 from typing import Annotated, Literal
 
-from .types.alias import Validation
+from tyro.conf import Positional
 
-from . import Tag, run
+from .exceptions import ValidationFail
+from .subcommands import Command, SubcommandPlaceholder
+from .types.rich_tags import SecretTag
+
+from . import run, Choices
+from .interfaces import InterfaceName
+from .types.alias import Validation
 from .validators import not_empty
 
-from dataclasses import dataclass, field
-from pathlib import Path
-from mininterface import run
-from mininterface.exceptions import ValidationFail
-from mininterface.subcommands import Command, SubcommandPlaceholder
-from tyro.conf import Positional
+
+ChosenInterface = InterfaceName | Literal["all"]
 
 
 @dataclass
@@ -72,8 +76,17 @@ class Env:
     my_complex: list[tuple[int, str]] = field(default_factory=lambda: [(1, 'foo')])
     """ List of tuples. """
 
+    my_password: Annotated[str, SecretTag()] = "TOKEN"
+    """ Masked input """
+
+    my_time: datetime = datetime.now()
+    """ Nice date handling """
+
+    my_choice: Annotated[str, Choices("one", "two", "three")] = "two"
+    """ Choose between values """
+
 
-def showcase(interface: Literal["gui"] | Literal["tui"] | Literal["all"], case: int):
+def showcase(interface: ChosenInterface, case: int):
     if interface == "all":
         interface = None
     kw = {"args": [], "interface": interface}

mininterface/tag.py

@@ -344,7 +344,7 @@ def __hash__(self):
         # Hence, I add a hash function with no intention yet.
         return hash(str(self))
 
-    def _fetch_from(self, tag: "Self") -> "Self":
+    def _fetch_from(self, tag: "Self", name: str = "") -> "Self":
         """ Fetches attributes from another instance.
         (Skips the attributes that are already set.)
         """
@@ -355,6 +355,8 @@ def _fetch_from(self, tag: "Self") -> "Self":
                 setattr(self, attr, getattr(tag, attr))
         if self.description == "":
             self.description = tag.description
+        if name and self.name is None:
+            self._original_name = self.name = name
         return self
 
     def _is_a_callable(self) -> bool:
@@ -486,8 +488,7 @@ def set_error_text(self, s):
         self.description = f"{s} {o}"
         if self.name:
             # Why checking self.name?
-            # If not set, we would end up with '* None'
-            # `m.form({"my_text": Tag("", validation=validators.not_empty)})`
+            # If for any reason (I do not know the use case) is not set, we would end up with '* None'
             self.name = f"* {n}"
         self._error_text = s
 

mininterface/tag_factory.py

@@ -34,8 +34,8 @@ def _get_tag_type(tag: Tag) -> Type[Tag]:
     return type(tag)
 
 
-def tag_fetch(tag: Tag, ref: dict | None):
-    return tag._fetch_from(Tag(**ref))
+def tag_fetch(tag: Tag, ref: dict | None, name: str):
+    return tag._fetch_from(Tag(**ref), name)
 
 
 def tag_assure_type(tag: Tag):