mininterface 1.2.2__tar.gz → 1.3.0__tar.gz

{mininterface-1.2.2 → mininterface-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mininterface
-Version: 1.2.2
+Version: 1.3.0
 Summary: CLI & dialog toolkit – a minimal interface to Python application (GUI, TUI, CLI + config files, web)
 License: LGPL-3.0-or-later
 License-File: LICENSE
@@ -27,7 +27,7 @@ Requires-Dist: humanize ; extra == "basic" or extra == "img" or extra == "tui" o
 Requires-Dist: pillow ; extra == "img" or extra == "gui" or extra == "ui" or extra == "all"
 Requires-Dist: pyyaml ; extra == "basic" or extra == "img" or extra == "tui" or extra == "gui" or extra == "web" or extra == "ui" or extra == "all"
 Requires-Dist: simple_term_menu
-Requires-Dist: textual (<2.0.0) ; extra == "basic" or extra == "img" or extra == "tui" or extra == "gui" or extra == "web" or extra == "ui" or extra == "all"
+Requires-Dist: textual (>=2.0.0,<9.0.0) ; extra == "basic" or extra == "img" or extra == "tui" or extra == "gui" or extra == "web" or extra == "ui" or extra == "all"
 Requires-Dist: textual-serve ; extra == "web" or extra == "ui" or extra == "all"
 Requires-Dist: textual_imageview ; extra == "img" or extra == "tui" or extra == "ui" or extra == "all"
 Requires-Dist: tkcalendar ; extra == "gui" or extra == "ui" or extra == "all"

mininterface-1.3.0/mininterface/__init__.py

@@ -0,0 +1,29 @@
+__all__ = ["run", "Mininterface", "Tag", "Cancelled", "Validation", "Options"]
+
+
+def __getattr__(name: str):
+    if name == "run":
+        from ._lib.run import run
+        globals()["run"] = run
+        return run
+    if name == "Mininterface":
+        from ._mininterface import Mininterface
+        globals()["Mininterface"] = Mininterface
+        return Mininterface
+    if name == "Cancelled":
+        from .exceptions import Cancelled
+        globals()["Cancelled"] = Cancelled
+        return Cancelled
+    if name == "Tag":
+        from .tag import Tag
+        globals()["Tag"] = Tag
+        return Tag
+    if name == "Options":
+        from .tag.alias import Options
+        globals()["Options"] = Options
+        return Options
+    if name == "Validation":
+        from .tag.alias import Validation
+        globals()["Validation"] = Validation
+        return Validation
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{mininterface-1.2.2 → mininterface-1.3.0}/mininterface/_lib/auxiliary.py

@@ -5,11 +5,7 @@ from functools import lru_cache
 from types import UnionType
 from typing import (
     Any,
-    Annotated,
-    Callable,
     Iterable,
-    Optional,
-    TypeVar,
     Union,
     Literal,
     get_args,
@@ -18,50 +14,10 @@ from typing import (
 )
 
 from annotated_types import Ge, Gt, Le, Len, Lt, MultipleOf
+from .dict_utils import T, KT, common_iterables, flatten
 
 logger = logging.getLogger(__name__)
 
-try:
-    import tyro
-    from tyro._docstrings import get_field_docstring as _tyro_get_field_docstring
-    from tyro._docstrings import get_callable_description as _tyro_get_callable_description
-
-    _tyro_docstrings_available = True
-except ImportError:
-    tyro = None
-    _tyro_docstrings_available = False
-    _tyro_get_callable_description = None
-
-try:
-    from humanize import naturalsize as naturalsize_
-except ImportError:
-    naturalsize_ = None
-
-T = TypeVar("T")
-KT = str
-common_iterables = list, tuple, set
-""" collections, and not a str """
-
-
-def flatten(d: dict[str, T | dict], include_keys: Optional[Callable[[str], list]] = None) -> Iterable[T]:
-    """Recursively traverse whole dict"""
-    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
-
-
-# NOTE: Not used.
-def flatten_keys(d: dict[KT, T | dict]) -> Iterable[tuple[KT, T]]:
-    """Recursively traverse whole dict"""
-    for k, v in d.items():
-        if isinstance(v, dict):
-            yield from flatten_keys(v)
-        else:
-            yield k, v
 
 
 def guess_type(val: T) -> type[T]:
@@ -86,72 +42,6 @@ def get_terminal_size():
         return 0, 0
 
 
-def get_class_description(obj) -> str:
-    if _tyro_get_callable_description:
-        return _tyro_get_callable_description(obj)
-    return ""
-
-@lru_cache
-def _get_descriptions_from_docstring(obj) -> dict[str, str]:
-    """Extract field descriptions for all fields of a class.
-
-    Uses tyro's internal helptext extraction (tyro._docstrings.get_field_docstring),
-    which supports the same sources and precedence as tyro's own CLI generation:
-      1. tyro.conf.arg(help=...)
-      2. PEP 727 Doc
-      3. Docstrings (attribute docstrings or class docstring params)
-      4. Comments (inline or preceding)
-
-    We used to rely on tyro.extras.get_parser(), but that was marked deprecated,
-    so we call tyro's internal API directly instead.
-    """
-    if not _tyro_docstrings_available:
-        return {}
-
-    result = {}
-
-    # Highest priority: tyro.conf.arg(help=...) in Annotated metadata.
-    try:
-        hints = get_type_hints(obj, include_extras=True)
-        ArgConfig = tyro.conf._confstruct._ArgConfig
-        for field_name, hint in hints.items():
-            if get_origin(hint) is Annotated:
-                for meta in hint.__metadata__:
-                    if isinstance(meta, ArgConfig) and meta.help:
-                        result[field_name] = meta.help
-    except Exception:
-        hints = {}
-
-    # Mid priority: docstrings and comments via tyro's own extraction.
-    for field_name in hints:
-        doc = _tyro_get_field_docstring(obj, field_name, ())
-        if doc:
-            result.setdefault(field_name, doc)
-
-    # Lowest priority: field.metadata["help"] from dynamically generated
-    # dataclasses (e.g. built from ArgumentParser via make_dataclass).
-    try:
-        for f in fields(obj):  # type: ignore
-            if help_text := f.metadata.get("help"):
-                result.setdefault(f.name, help_text)
-    except TypeError:
-        pass
-
-    return result
-
-
-def get_description(obj, param: str) -> str:
-    desc = _get_descriptions_from_docstring(obj).get(param, "")
-    if desc and desc.replace("-", "_") != param:
-        return desc
-
-    # We are missing mininterface[basic] requirement. Tyro is missing.
-    # Without tyro, we are not able to evaluate the class: m.form(Env),
-    # we can still evaluate its instance: m.form(Env()).
-    # However, without descriptions.
-    return ""
-
-
 def yield_annotations(dataclass):
     yield from (cl.__annotations__ for cl in dataclass.__mro__ if is_dataclass(cl))
 
@@ -349,9 +239,11 @@ def dict_diff(a: dict, b: dict) -> dict:
 
 def naturalsize(value: float | str, *args) -> str:
     """For a bare interface, humanize might not be installed."""
-    if naturalsize_:
-        return naturalsize_(value, *args)
-    return str(value)
+    try:
+        from humanize import naturalsize as _naturalsize
+        return _naturalsize(value, *args)
+    except ImportError:
+        return str(value)
 
 
 def validate_annotated_type(meta, value) -> bool:

{mininterface-1.2.2 → mininterface-1.3.0}/mininterface/_lib/cli_parser.py

@@ -16,10 +16,10 @@ from ..cli import Command
 from ..settings import CliSettings
 
 from ..exceptions import Cancelled
+from .auxiliary import flatten
 from .auxiliary import (
     get_or_create_parent_dict,
     remove_empty_dicts,
-    flatten,
 )
 from .dataclass_creation import (
     _unwrap_annotated,
@@ -65,23 +65,6 @@ except ImportError:
     raise DependencyRequired("basic")
 
 
-def assure_args(args: Optional[Sequence[str]] = None):
-    if args is None:
-        # Set env to determine whether to use sys.argv.
-        # Why settings env? Prevent tyro using sys.argv if we are in an interactive shell like Jupyter,
-        # as sys.argv is non-related there.
-        try:
-            # Note wherease `"get_ipython" in globals()` returns True in Jupyter, it is still False
-            # in a script a Jupyter cell runs. Hence we must put here this lengthty statement.
-            global get_ipython
-            get_ipython()
-        except:
-            args = sys.argv[1:]  # Fetch from the CLI
-        else:
-            args = []
-    return args
-
-
 def _subcommands_default_appliable(kwargs, _crawling):
     if len(_crawling.get()):
         return kwargs.get("subcommands_default")

mininterface-1.3.0/mininterface/_lib/config_file.py

@@ -0,0 +1,97 @@
+from dataclasses import asdict
+import dataclasses
+import warnings
+from pathlib import Path
+from typing import Optional, Type
+
+
+from ..settings import MininterfaceSettings
+from .auxiliary import dataclass_asdict_no_defaults, merge_dicts
+from .form_dict import EnvClass
+
+
+def load_settings_from_config(config_file: Path) -> tuple[dict, dict | None]:
+    """Load yaml config without tyro. Returns (raw_cli_dict, mininterface_settings_dict).
+    raw_cli_dict has the 'mininterface' key already removed."""
+    import yaml
+    raw = yaml.safe_load(config_file.read_text()) or {}
+    return raw, raw.pop("mininterface", None)
+
+
+def ensure_settings_inheritance(
+    base: Optional[MininterfaceSettings], conf: dict, _def_fact=MininterfaceSettings
+) -> MininterfaceSettings:
+    """Merge a config-file settings dict into MininterfaceSettings.
+    Handles direct fields and one level of nested dataclass fields.
+    Applies UI inheritance (ui→gui, ui→tui, etc.)."""
+    if base:
+        conf = merge_dicts(dataclass_asdict_no_defaults(base), conf)
+    for sources in [
+        ("ui", "gui"),
+        ("ui", "tui"),
+        ("ui", "tui", "textual"),
+        ("ui", "tui", "text"),
+        ("ui", "tui", "textual", "web"),
+    ]:
+        target = sources[-1]
+        merged: dict = {}
+        for s in sources:
+            merged.update(conf.get(s, {}))
+        merged.update(conf.get(target, {}))
+        if merged:
+            conf[target] = merged
+    result = base or _def_fact()
+    for key, value in conf.items():
+        if not hasattr(result, key):
+            continue
+        attr = getattr(result, key)
+        if dataclasses.is_dataclass(attr) and isinstance(value, dict):
+            for k2, v2 in value.items():
+                if hasattr(attr, k2):
+                    setattr(attr, k2, v2)
+        else:
+            setattr(result, key, value)
+    return result
+
+
+def parse_config_file(
+    env_or_list: Type[EnvClass] | list[Type[EnvClass]],
+    raw_config: "dict | None" = None,
+    config_file: "Path | None" = None,
+    **kwargs,
+) -> dict:
+    """Fill kwargs["default"] from a pre-loaded config dict. Needs tyro.
+
+    Args:
+        env_or_list: Class(es) with the configuration.
+        raw_config: Pre-loaded yaml dict from load_settings_from_config (mininterface key already removed).
+            Pass None when there is no config file.
+        config_file: Original path, used only for error messages.
+    Kwargs:
+        The same as for argparse.ArgumentParser.
+    """
+    if raw_config is not None and "default" not in kwargs:
+        from .dataclass_creation import create_with_missing, to_kebab_case
+        try:
+            subc = {}
+
+            if isinstance(env_or_list, list):
+                kwargs["subcommands_default_union"] = {}
+                for cl in env_or_list:
+                    cl_name = to_kebab_case(cl.__name__)
+                    subc[cl_name] = {}
+                    ooo = create_with_missing(cl, raw_config.get(cl_name, {}), subc=subc[cl_name])
+                    kwargs["subcommands_default_union"][cl_name] = asdict(ooo)
+                    # `kwargs["default"]` remains empty for now as there is no bare default that tyro would support as everything is hidden under the subcommands
+
+            else:
+                kwargs["default"] = create_with_missing(env_or_list, raw_config, subc=subc)
+
+            if subc:
+                kwargs["subcommands_default"] = subc
+        except TypeError:
+            raise SyntaxError(f"Config file parsing failed for {config_file}")
+
+    return kwargs
+
+

{mininterface-1.2.2 → mininterface-1.3.0}/mininterface/_lib/dataclass_creation.py

@@ -17,7 +17,8 @@ except ImportError:
 from ..tag import Tag
 from ..tag.tag_factory import tag_factory
 from ..validators import not_empty
-from .auxiliary import _get_origin, get_class_description, get_description
+from .auxiliary import _get_origin
+from .docstrings import get_class_description, get_description
 from .form_dict import DataClass, EnvClass, MissingTagValue
 
 # Pydantic is not a project dependency, that is just an optional integration

mininterface-1.3.0/mininterface/_lib/dict_utils.py

@@ -0,0 +1,17 @@
+from typing import Callable, Iterable, Optional, TypeVar
+
+T = TypeVar("T")
+KT = str
+common_iterables = list, tuple, set
+""" collections, and not a str """
+
+
+def flatten(d: dict[str, T | dict], include_keys: Optional[Callable[[str], list]] = None) -> Iterable[T]:
+    """Recursively traverse whole dict"""
+    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

mininterface-1.3.0/mininterface/_lib/docstrings.py

@@ -0,0 +1,101 @@
+"""Tyro-dependent docstring/description helpers, split out from auxiliary.py.
+
+Keeping these separate lets child processes import auxiliary.flatten without
+paying the ~20 ms cost of loading tyro. Tyro itself is imported lazily inside
+the functions that need it, so importing this module is also cheap.
+"""
+from functools import lru_cache
+from typing import Annotated, get_args, get_origin, get_type_hints
+from dataclasses import fields
+
+_tyro_loaded = False
+_tyro_docstrings_available = False
+_tyro_get_field_docstring = None
+_tyro_get_callable_description = None
+tyro = None
+
+
+def _ensure_tyro():
+    global _tyro_loaded, _tyro_docstrings_available, _tyro_get_field_docstring, _tyro_get_callable_description, tyro
+    if _tyro_loaded:
+        return
+    _tyro_loaded = True
+    try:
+        import tyro as _tyro
+        from tyro._docstrings import get_field_docstring as _gfd
+        from tyro._docstrings import get_callable_description as _gcd
+        tyro = _tyro
+        _tyro_get_field_docstring = _gfd
+        _tyro_get_callable_description = _gcd
+        _tyro_docstrings_available = True
+    except ImportError:
+        pass
+
+
+def get_class_description(obj) -> str:
+    _ensure_tyro()
+    if _tyro_get_callable_description:
+        return _tyro_get_callable_description(obj)
+    return ""
+
+
+@lru_cache
+def _get_descriptions_from_docstring(obj) -> dict[str, str]:
+    """Extract field descriptions for all fields of a class.
+
+    Uses tyro's internal helptext extraction (tyro._docstrings.get_field_docstring),
+    which supports the same sources and precedence as tyro's own CLI generation:
+      1. tyro.conf.arg(help=...)
+      2. PEP 727 Doc
+      3. Docstrings (attribute docstrings or class docstring params)
+      4. Comments (inline or preceding)
+
+    We used to rely on tyro.extras.get_parser(), but that was marked deprecated,
+    so we call tyro's internal API directly instead.
+    """
+    _ensure_tyro()
+    if not _tyro_docstrings_available:
+        return {}
+
+    result = {}
+
+    # Highest priority: tyro.conf.arg(help=...) in Annotated metadata.
+    try:
+        hints = get_type_hints(obj, include_extras=True)
+        ArgConfig = tyro.conf._confstruct._ArgConfig
+        for field_name, hint in hints.items():
+            if get_origin(hint) is Annotated:
+                for meta in hint.__metadata__:
+                    if isinstance(meta, ArgConfig) and meta.help:
+                        result[field_name] = meta.help
+    except Exception:
+        hints = {}
+
+    # Mid priority: docstrings and comments via tyro's own extraction.
+    for field_name in hints:
+        doc = _tyro_get_field_docstring(obj, field_name, ())
+        if doc:
+            result.setdefault(field_name, doc)
+
+    # Lowest priority: field.metadata["help"] from dynamically generated
+    # dataclasses (e.g. built from ArgumentParser via make_dataclass).
+    try:
+        for f in fields(obj):  # type: ignore
+            if help_text := f.metadata.get("help"):
+                result.setdefault(f.name, help_text)
+    except TypeError:
+        pass
+
+    return result
+
+
+def get_description(obj, param: str) -> str:
+    desc = _get_descriptions_from_docstring(obj).get(param, "")
+    if desc and desc.replace("-", "_") != param:
+        return desc
+
+    # We are missing mininterface[basic] requirement. Tyro is missing.
+    # Without tyro, we are not able to evaluate the class: m.form(Env),
+    # we can still evaluate its instance: m.form(Env()).
+    # However, without descriptions.
+    return ""

{mininterface-1.2.2 → mininterface-1.3.0}/mininterface/_lib/form_dict.py

@@ -9,8 +9,10 @@ from dataclasses import fields, is_dataclass
 from types import FunctionType, MethodType, SimpleNamespace
 from typing import TYPE_CHECKING, Any, Callable, Hashable, Optional, Type, TypeVar, Union, get_args, get_type_hints
 
+from .form_types import DataClass, EnvClass
 
-from .auxiliary import get_description
+
+from .docstrings import get_description
 from ..tag.tag import MissingTagValue, Tag, TagValue
 from ..tag.tag_factory import tag_assure_type, tag_factory
 
@@ -19,53 +21,35 @@ if TYPE_CHECKING:  # remove the line as of Python3.11 and make `"Self" -> Self`
 
     from .. import Mininterface
 
-try:
-    import attr
-except ImportError:
-    attr = None
-try:
-    from pydantic import BaseModel
-except ImportError:
-    BaseModel = None
+# attr and pydantic are optional integrations — loaded only on first use so that
+# users relying purely on dataclasses never imports the lib.
+_attr = None
+
+def _get_attr():
+    global _attr
+    if _attr is None:
+        try:
+            import attr as _a
+            _attr = _a
+        except ImportError:
+            _attr = False
+    return _attr or None
+
+_BaseModel = None
+
+def _get_BaseModel():
+    global _BaseModel
+    if _BaseModel is None:
+        try:
+            from pydantic import BaseModel as _BM
+            _BaseModel = _BM
+        except ImportError:
+            _BaseModel = False
+    return _BaseModel or None
 
 
 logger = logging.getLogger(__name__)
 
-DataClass = TypeVar("DataClass")
-""" Any dataclass. Or a pydantic model or attrs. """
-EnvClass = TypeVar("EnvClass", bound=DataClass)
-""" Any dataclass. Its instance will be available through [Mininterface.env][mininterface.Mininterface.env] after CLI parsing. Its fields or whole class might be annotated with [tyro conf flags](https://brentyi.github.io/tyro/api/tyro/conf/).
-
-The following example turns down boolean flag conversion.
-
-```python
-from dataclasses import dataclass
-from mininterface import run
-from tyro.conf import FlagConversionOff
-
-@dataclass
-class Env:
-    my_bool: bool = False
-
-m = run(FlagConversionOff[Env])
-```
-
-```bash
-$ program.py --help
-# --my-bool {True,False}  (default: False)
-```
-
-Whereas by default, both flags are generated:
-
-```python
-m = run(Env)
-```
-
-```bash
-$ program.py --help
-# --my-bool, --no-my-bool (default: False)
-```
-"""
 FormDict = dict[Hashable, TypeVar("FormDictRecursiveValue", TagValue, Tag, "Self")]
 """ Nested dict that can have descriptions (through Tag) instead of plain values."""
 # Attention to programmers. Should we to change FormDict type, check these IDE suggestions are still the same.
@@ -192,14 +176,14 @@ def iterate_attributes(env: DataClass):
         # Why using fields instead of vars(env)? There might be some helper parameters in the dataclasses that should not be form editable.
         for f in fields(env):
             yield f.name, getattr(env, f.name)
-    elif BaseModel and isinstance(env, BaseModel):
+    elif (_bm := _get_BaseModel()) and isinstance(env, _bm):
         for param, val in vars(env).items():
             yield param, val
         # NOTE private pydantic attributes might be printed to forms, because this makes test fail for nested models
         # for param, val in env.model_dump().items():
         #     yield param, val
-    elif attr and attr.has(env):
-        for f in attr.fields(env.__class__):
+    elif (_at := _get_attr()) and _at.has(env):
+        for f in _at.fields(env.__class__):
             yield f.name, getattr(env, f.name)
     else:  # might be a normal class; which is unsupported but mostly might work
         for param, val in vars(env).items():
@@ -212,14 +196,14 @@ def iterate_attributes_keys(env: DataClass):
         # Why using fields instead of vars(env)? There might be some helper parameters in the dataclasses that should not be form editable.
         for f in fields(env):
             yield f.name
-    elif BaseModel and isinstance(env, BaseModel):
+    elif (_bm := _get_BaseModel()) and isinstance(env, _bm):
         for param, val in vars(env).items():
             yield param
         # NOTE private pydantic attributes might be printed to forms, because this makes test fail for nested models
         # for param, val in env.model_dump().items():
         #     yield param, val
-    elif attr and attr.has(env):
-        for f in attr.fields(env.__class__):
+    elif (_at := _get_attr()) and _at.has(env):
+        for f in _at.fields(env.__class__):
             yield f.name
     else:  # might be a normal class; which is unsupported but mostly might work
         for param, val in vars(env).items():

mininterface-1.3.0/mininterface/_lib/form_types.py

@@ -0,0 +1,7 @@
+from typing import TypeVar
+
+DataClass = TypeVar("DataClass")
+""" Any dataclass. Or a pydantic model or attrs. """
+
+EnvClass = TypeVar("EnvClass", bound=DataClass)
+""" Any dataclass. Its instance will be available through [Mininterface.env][mininterface.Mininterface.env] after CLI parsing. """

mininterface-1.3.0/mininterface/_lib/ipc_command.py

@@ -0,0 +1,20 @@
+from enum import Enum
+
+
+class IpcCommand(Enum):
+    """Message kinds exchanged over the parent⇄child pipe of every subprocess
+    UI backend — both the Tk GUI and the Textual TUI use the same protocol."""
+
+    FORM = "form"
+    BUTTONS = "buttons"
+    SHUTDOWN = "shutdown"
+    RESULT = "result"
+    CANCEL = "cancel"
+    QUIT = "quit"                # child → parent: window closed (X) → exit the program
+    ERROR = "error"              # child → parent: dialog build crashed (exception + traceback text)
+    CALLBACK = "callback"        # child → parent: callback fired
+    FORM_UPDATE = "form_update"   # parent → child: updated tag values after callback
+    VALIDATE_RESULT = "validate_result"  # parent → child: result of a live validation round-trip
+    OUTPUT = "output"            # parent → child: live print() text to stream
+    CLEAR_OUTPUT = "clear_output"  # parent → child: clear the streamed-output widget
+    SETTINGS = "settings"        # parent → child: the UI settings (sent once after spawn)