mininterface 1.0.4__tar.gz → 1.1.1__tar.gz

{mininterface-1.0.4 → mininterface-1.1.1}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: mininterface
-Version: 1.0.4
+Version: 1.1.1
 Summary: A minimal access to GUI, TUI, CLI and config
 License: LGPL-3.0-or-later
+License-File: LICENSE
 Author: Edvard Rejthar
 Author-email: edvard.rejthar@nic.cz
 Requires-Python: >=3.10,<4.0
@@ -12,6 +13,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Provides-Extra: all
 Provides-Extra: basic
 Provides-Extra: gui
@@ -37,7 +39,7 @@ Project-URL: Homepage, https://github.com/CZ-NIC/mininterface
 Description-Content-Type: text/markdown
 
 # Mininterface – access to GUI, TUI, web, CLI and config files
-[![Build Status](https://github.com/CZ-NIC/mininterface/actions/workflows/run-unittest.yml/badge.svg)](https://github.com/CZ-NIC/mininterface/actions)
+[![Build Status](https://github.com/CZ-NIC/mininterface/actions/workflows/run-unittest.yml/badge.svg?branch=main)](https://github.com/CZ-NIC/mininterface/actions)
 [![Downloads](https://static.pepy.tech/badge/mininterface)](https://pepy.tech/project/mininterface)
 
 Write the program core, do not bother with the input/output.
@@ -144,7 +146,7 @@ The config variables needed by your program are kept in cozy dataclasses. Write
 Install with a single command from [PyPi](https://pypi.org/project/mininterface/).
 
 ```bash
-pip install mininterface[all]  # GPLv3 and compatible
+pip install "mininterface[all]<2"  # GPLv3 and compatible
 ```
 
 ## Bundles

{mininterface-1.0.4 → mininterface-1.1.1}/README.md

@@ -1,5 +1,5 @@
 # Mininterface – access to GUI, TUI, web, CLI and config files
-[![Build Status](https://github.com/CZ-NIC/mininterface/actions/workflows/run-unittest.yml/badge.svg)](https://github.com/CZ-NIC/mininterface/actions)
+[![Build Status](https://github.com/CZ-NIC/mininterface/actions/workflows/run-unittest.yml/badge.svg?branch=main)](https://github.com/CZ-NIC/mininterface/actions)
 [![Downloads](https://static.pepy.tech/badge/mininterface)](https://pepy.tech/project/mininterface)
 
 Write the program core, do not bother with the input/output.
@@ -106,7 +106,7 @@ The config variables needed by your program are kept in cozy dataclasses. Write
 Install with a single command from [PyPi](https://pypi.org/project/mininterface/).
 
 ```bash
-pip install mininterface[all]  # GPLv3 and compatible
+pip install "mininterface[all]<2"  # GPLv3 and compatible
 ```
 
 ## Bundles

mininterface-1.1.1/mininterface/__init__.py

@@ -0,0 +1,7 @@
+from ._lib.run import run
+from ._mininterface import Mininterface
+from .exceptions import Cancelled
+from .tag import Tag
+from .tag.alias import Options, Validation
+
+__all__ = ["run", "Mininterface", "Tag", "Cancelled", "Validation", "Options"]

{mininterface-1.0.4 → mininterface-1.1.1}/mininterface/__main__.py

@@ -12,7 +12,7 @@ except ImportError:
 
     raise DependencyRequired("basic").exit()
 
-from . import run
+from ._lib.run import run
 from .cli import Command
 from .tag.flag import File
 from .tag.path_tag import PathTag

{mininterface-1.0.4 → mininterface-1.1.1}/mininterface/_lib/argparse_support.py

@@ -1,35 +1,20 @@
-from argparse import (
-    SUPPRESS,
-    _AppendAction,
-    _AppendConstAction,
-    _CountAction,
-    _HelpAction,
-    _StoreConstAction,
-    _StoreFalseAction,
-    _StoreTrueAction,
-    _SubParsersAction,
-    _VersionAction,
-    Action,
-    ArgumentParser,
-)
+import re
+import sys
+from argparse import (SUPPRESS, Action, ArgumentParser, _AppendAction,
+                      _AppendConstAction, _CountAction, _HelpAction,
+                      _StoreConstAction, _StoreFalseAction, _StoreTrueAction,
+                      _SubParsersAction, _VersionAction)
 from collections import defaultdict
 from dataclasses import MISSING, Field, dataclass, field, make_dataclass
 from functools import cached_property
-import re
-import sys
-from typing import Annotated, Callable, Literal, Optional
+from typing import Annotated, Callable, Optional
 from warnings import warn
 
-from tyro.conf import OmitSubcommandPrefixes
-
-from .. import Options
-
+from ..tag.alias import Options
 from .form_dict import DataClass
 
-
 try:
-    from tyro.constructors import PrimitiveConstructorSpec
-    from tyro.conf import Positional, arg
+    from tyro.conf import DisallowNone, OmitSubcommandPrefixes, Positional
 except ImportError:
     from ..exceptions import DependencyRequired
 
@@ -80,11 +65,16 @@ class ArgparseField:
         return self.action.dest in self.properties
 
 
-def parser_to_dataclass(parser: ArgumentParser, name: str = "Args") -> DataClass | list[DataClass]:
+def parser_to_dataclass(parser: ArgumentParser, name: str = "Args") -> tuple[DataClass | list[DataClass], Optional[str]]:
     """
     Note: Ex. parser.add_argument("--time", type=time) -> does work at all in argparse, here it works.
+
+    Returns:
+        DataClass | list[DataClass]
+        Optional[str]: add_version flag
     """
     subparsers: list[_SubParsersAction] = []
+    add_version = None
 
     normal_actions: list[Action] = []
     has_positionals = False
@@ -98,6 +88,9 @@ def parser_to_dataclass(parser: ArgumentParser, name: str = "Args") -> DataClass
                         "This CLI parser have a subcommand placed after positional arguments. The order of arguments changes, see --help."
                     )
                 subparsers.append(action)
+            case _VersionAction():
+                # We do not want the version to be part of the dataclass (and appear in `m.form()`).
+                add_version = action.version
             case _:
                 if not action.option_strings:
                     has_positionals = True
@@ -113,9 +106,9 @@ def parser_to_dataclass(parser: ArgumentParser, name: str = "Args") -> DataClass
             )
             for subparser in subparsers
             for subname, subactions, help_ in _loop_SubParsersAction(subparser)
-        ]
+        ], add_version
     else:
-        return _make_dataclass_from_actions(normal_actions, name, None, parser.description)
+        return _make_dataclass_from_actions(normal_actions, name, None, parser.description), add_version
 
 
 def _loop_SubParsersAction(subparser: _SubParsersAction):
@@ -144,22 +137,6 @@ def _make_dataclass_from_actions(
         match action:
             case _HelpAction():
                 continue
-            case _VersionAction():
-                # NOTE Should be probably implemented in tyro. Here that way:
-                # run(add_version="1.2.3")
-                # run(add_version_package="intelmq") -> get pip version
-                arg_type = Annotated[
-                    None,
-                    PrimitiveConstructorSpec(
-                        nargs="*",
-                        metavar="",
-                        instance_from_str=lambda _, v=action.version: print(v) or sys.exit(0),
-                        is_instance=lambda _: True,
-                        # NOTE tyro might not diplay anything here,
-                        # but it displays `(default: )`
-                        str_from_instance=(lambda _, v=action.version: [str(v)]),
-                    ),
-                ]
             case _SubParsersAction():
                 # Note that there is only one _SubParsersAction in argparse
                 # but to be sure, we allow multiple of them
@@ -216,12 +193,17 @@ def _make_dataclass_from_actions(
                 else:
                     arg_type = str
 
-        metavar = None
         if "default" not in opt and "default_factory" not in opt:
             if action.choices:
-                # With the drop of Python 3.10, use:
+                # With the drop of Python 3.10, use mere:
                 # arg_type = Literal[*action.choices]
-                arg_type = Annotated[arg_type, Options(*action.choices)]
+                if sys.version_info >= (3,11):
+                    from .future_compatibility import literal
+                    arg_type = literal(action.choices)
+                else:
+                    # we do not prefer this option as tyro does not understand it
+                    # and won't display options in the help
+                    arg_type = Annotated[arg_type, Options(*action.choices)]
 
             if not action.option_strings and action.default is None and action.nargs != "?":
                 opt["default"] = MISSING
@@ -281,4 +263,4 @@ def _make_dataclass_from_actions(
         separator = ": " if needs_colon else ("\n" if trimmed else "")
         dc.__doc__ = trimmed + separator + (description or "")
 
-    return dc
+    return DisallowNone[dc]

{mininterface-1.0.4 → mininterface-1.1.1}/mininterface/_lib/auxiliary.py

@@ -1,12 +1,16 @@
-from typing import get_args, get_origin, Union
-from dataclasses import fields, is_dataclass
+import logging
 import os
 import re
 from argparse import ArgumentParser
+from dataclasses import fields, is_dataclass
+from functools import lru_cache
 from types import UnionType
-from typing import Callable, Iterable, Optional, TypeVar, Union, get_args, get_origin
+from typing import (Any, Callable, Iterable, Optional, TypeVar, Union, Literal,
+                    get_args, get_origin, get_type_hints)
+
+from annotated_types import Ge, Gt, Le, Len, Lt, MultipleOf
 
-from annotated_types import Gt, Ge, Lt, Le, MultipleOf, Len
+logger = logging.getLogger(__name__)
 
 try:
     from tyro.extras import get_parser
@@ -71,14 +75,28 @@ 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|required).*\)", "", action.help or "")
+        re.sub(r"\s\(positional\)$", "", 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:
+@lru_cache
+def _get_parser(obj):
     if get_parser:
-        return get_descriptions(get_parser(obj))[param]
+        return get_parser(obj)
+
+
+def get_description(obj, param: str) -> str:
+    if p := _get_parser(obj):
+        try:
+            d = get_descriptions(p)[param].strip()
+        except KeyError:  # either fetching failed or user added no description
+            return ""
+        else:
+            if d.replace("-", "_") == param:
+                # field `bot_id` is reported as `bot-id` in tyro
+                return ""
+            return d
     else:
         # We are missing mininterface[basic] requirement. Tyro is missing.
         # Without tyro, we are not able to evaluate the class: m.form(Env),
@@ -91,6 +109,78 @@ def yield_annotations(dataclass):
     yield from (cl.__annotations__ for cl in dataclass.__mro__ if is_dataclass(cl))
 
 
+def get_annotation(class_, dest: str, crawled: list):
+    """Get the attribute annotation according to the path in `dest` (dot means a nested subclass).
+    Works for dataclass, pydantic, attrs.
+
+    Ex: get_annotation(AppConfig, "bot.bot_id"))
+
+    Ex: get_annotation(AppConfig, "app.subcommand.bot_id"), "message")
+        class AppConfig:
+            subcommand: Message|Console
+
+        class Message:
+            bot_id: int
+    """
+    parts = dest.split(".")
+    current_cls = class_
+    for part, class_name in zip(parts, crawled):
+        if not isinstance(current_cls, type):  # `(Message | Console)`
+            for cl in get_args(current_cls):
+                if cl.__name__.casefold() == class_name:
+                    current_cls = cl
+                    break
+            else:
+                raise KeyError(f"Field {part!r} not accessible in {current_cls}")
+
+        hints = get_type_hints(current_cls)
+
+        if part not in hints:
+            raise KeyError(f"Field {part!r} not found in {current_cls}")
+        current_cls = hints[part]  # přejdi na typ dalšího levelu
+    return current_cls
+
+
+def get_or_create_parent_dict(d: dict, fname: str, ignore_last=False) -> dict:
+    """
+    Return the subdict for the path in `fname`, but ignore the last part.
+    If a subdict does not exist, create it.
+    If `fname` has only one part, return `d` directly.
+    """
+    parts = fname.split(".")
+    # if len(parts) == 1:
+    #     return d
+    if ignore_last:
+        parts = parts[:-1]
+
+    current = d
+    for part in parts:
+        if part not in current or not isinstance(current[part], dict):
+            current[part] = {}
+        current = current[part]
+    return current
+
+
+# NOTE Deprecated
+# def get_nested_class(class_: type, fname: str, ignore_last=False) -> type:
+#     """
+#     Traverse the class attributes according to the dot-separated path in `fname`
+#     and return the type of the most deeply nested attribute.
+#     Works for dataclasses, Pydantic models, and attrs classes.
+#     """
+#     parts = fname.split(".")
+#     if ignore_last:
+#         parts = parts[:-1]
+#     current = class_
+
+#     for part in parts:
+#         if not hasattr(current, part):
+#             raise AttributeError(f"{part} not found in {current}")
+#         current = getattr(current, part)
+
+#     return current
+
+
 def matches_annotation(value, annotation) -> bool:
     """Check whether the value type corresponds to the annotation.
     Because built-in isinstance is not enough, it cannot determine parametrized generics.
@@ -101,6 +191,8 @@ def matches_annotation(value, annotation) -> bool:
 
     # generics, ex. list, tuple
     origin = get_origin(annotation)
+    if origin is Literal:
+        return value in get_args(annotation)
     if origin:
         if not isinstance(value, origin):
             return False
@@ -109,6 +201,8 @@ def matches_annotation(value, annotation) -> bool:
         if origin is list:
             return all(matches_annotation(item, subtypes[0]) for item in value)
         elif origin is tuple:
+            if len(subtypes) == 2 and subtypes[1] is Ellipsis: # ex. tuple[int, ...]
+                return all(matches_annotation(v, subtypes[0]) for v in value)
             if len(subtypes) != len(value):
                 return False
             return all(matches_annotation(v, t) for v, t in zip(value, subtypes))
@@ -192,6 +286,17 @@ def merge_dicts(d1: dict, d2: dict):
             d1[key] = value
     return d1
 
+def dict_diff(a: dict, b: dict) -> dict:
+    """ Returns the B values where they differ. """
+    result = {}
+    for k in b:
+        if isinstance(a.get(k), dict) and isinstance(b.get(k), dict):
+            nested = dict_diff(a[k], b[k])
+            if nested:
+                result[k] = nested
+        elif a.get(k) != b.get(k):
+            result[k] = b[k]
+    return result
 
 def naturalsize(value: float | str, *args) -> str:
     """For a bare interface, humanize might not be installed."""
@@ -227,6 +332,7 @@ def validate_annotated_type(meta, value) -> bool:
         raise NotImplementedError(f"Unknown predicated {meta}")
     return True
 
+
 def allows_none(annotation) -> bool:
     """True, if annotation allows None: `int | None`, `Optional[int]`, `Union[int,None]`."""
     if annotation is None:
@@ -238,4 +344,33 @@ def allows_none(annotation) -> bool:
 
     if origin is Union or origin is UnionType:
         return any(arg is type(None) for arg in args)
-    return False
+    return False
+
+def strip_none(annotation):
+    """Return the same annotation but without NoneType inside a Union/Optional."""
+    origin = get_origin(annotation)
+
+    if origin is Union or origin is UnionType:
+        args = tuple(arg for arg in get_args(annotation) if arg is not type(None))
+        if len(args) == 1:
+            return args[0]
+        return Union[args]  # nebo origin[args], aby se zachoval typ
+
+    return annotation
+
+@lru_cache(maxsize=1024*10)
+def _get_origin(tp: Any):
+    """
+    Cached version of typing.get_origin.
+    Faster when called repeatedly on the same type hints.
+    """
+    return get_origin(tp)
+
+
+def remove_empty_dicts(d: dict):
+    """Recursively remove empty dicts from a nested dict, in place."""
+    for k in list(d):
+        if isinstance(d[k], dict):
+            remove_empty_dicts(d[k])
+            if not d[k]:
+                d.pop(k)

mininterface-1.1.1/mininterface/_lib/cli_flags.py

@@ -0,0 +1,107 @@
+from functools import lru_cache
+import logging
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+from .form_dict import EnvClass
+
+
+class CliFlags:
+
+    _add_verbose: bool = False
+    version: bool | str = False
+    _add_quiet: bool = False
+
+    default_verbosity: int = logging.WARNING
+    _verbosity_sequence: Optional[Sequence[int]] = None
+
+    def __init__(
+        self,
+        add_verbose: bool | int | Sequence[int] = False,
+        add_version: Optional[str] = None,
+        add_version_package: Optional[str] = None,
+        add_quiet: bool = False,
+    ):
+        self._enabled = {"verbose": True, "version": True, "quiet": True}
+        # verbosity
+        match add_verbose:
+            case bool():
+                self._add_verbose = add_verbose
+            case int():
+                self._add_verbose = True
+                self.default_verbosity = add_verbose
+                self._verbosity_sequence = list(range(add_verbose-10, -1, -10))
+            case list() | tuple():
+                self._add_verbose = True
+                self.default_verbosity = add_verbose[0]
+                self._verbosity_sequence = add_verbose[1:]
+        self._add_quiet = add_quiet
+
+        # version
+        if add_version:
+            self.version = add_version
+        elif add_version_package:
+            try:
+                from importlib.metadata import PackageNotFoundError, version
+            except ImportError:
+                self.version = f"cannot determine version"
+            try:
+                self.version = version(add_version_package)
+            except PackageNotFoundError:
+                self.version = f"package {add_version_package} not found"
+
+    def should_add(self, env_classes: list[EnvClass]) -> bool:
+        # Flags are added only if neither the env_class nor any of the subcommands have the same-name flag already
+        self._enabled["verbose"] = self._add_verbose and self._attr_not_present("verbose", env_classes)
+        self._enabled["quiet"] = self._add_quiet and self._attr_not_present("quiet", env_classes)
+        self._enabled["version"] = self.version and self._attr_not_present("version", env_classes)
+
+        return self.add_verbose or self.add_version or self.add_quiet
+
+    def _attr_not_present(self, flag, env_classes):
+        return all(flag not in cl.__annotations__ for cl in env_classes)
+
+    @property
+    def add_verbose(self):
+        return self._add_verbose and self._enabled["verbose"]
+
+    @property
+    def add_version(self):
+        return self.version and self._enabled["version"]
+
+    @property
+    def add_quiet(self):
+        return self._add_quiet and self._enabled["quiet"]
+
+    def get_log_level(self, count):
+        """
+        Ex.
+        * add_verbose = True ( default level = WARNING )
+            * -v -> logging.INFO
+            * -vv -> logging.DEBUG
+            * -vvv -> logging.NOTSET
+        * add_verbose = default level INFO
+            * -v -> logging.DEBUG
+            * -vv -> logging.NOTSET
+        * add_verbose = (40, 35, 30, 25)
+            * -v -> 35
+            * -vv -> logging.INFO
+            * -vvv -> 25
+            * -vvv -> logging.NOTSET
+
+        Args:
+            count: number of times `--verbose` flag is used. Negative count means the `--quiet` flag is used.
+
+        Returns:
+            int: log level
+        """
+        if count == -1: # quiet flag
+            return logging.ERROR
+        if not count:
+            return self.default_verbosity
+        if not self._verbosity_sequence:
+            seq = logging.INFO, logging.DEBUG
+        else:
+            seq = self._verbosity_sequence
+        log_level = {i + 1: level for i, level in enumerate(seq)}.get(count, logging.NOTSET)
+        return log_level