feat: SelectTag None value

Author: e3rd

docs/Changelog.md

@@ -7,9 +7,10 @@
 * feat: add utility for generating unit tests
 * feat: [annotated types][mininterface.tag.tag.ValidationCallback] for collections
 * feat: [`Blank`][mininterface.tag.flag.Blank] flag marker default value
+* feat: None value in [SelectTag][mininterface.tag.SelectTag]
+* enh: custom validation is done at dataclass built, not later on the form call
 * fix: SelectTag preset value
 * fix: ArgumentParser parameters (like allow_abbrev)
-* enh: custom validation is done at dataclass built, not later on the form call
 
 ## 1.0.4 (2025-08-18)
 * enh: better argparse support (const support, store_false matching, subcommands)

docs/index.md

@@ -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]~=1.1  # GPLv3 and compatible
+pip install "mininterface[all]<2"  # GPLv3 and compatible
 ```
 
 ## Bundles

mininterface/_lib/argparse_support.py

@@ -1,34 +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, Optional
 from warnings import warn
 
-from tyro.conf import OmitSubcommandPrefixes
-
 from ..tag.alias import Options
-
 from .form_dict import DataClass
 
-
 try:
-    from tyro.conf import Positional
+    from tyro.conf import DisallowNone, OmitSubcommandPrefixes, Positional
 except ImportError:
     from ..exceptions import DependencyRequired
 
@@ -277,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/_lib/auxiliary.py

@@ -343,6 +343,17 @@ def allows_none(annotation) -> bool:
         return any(arg is type(None) for arg in args)
     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):

mininterface/_lib/cli_parser.py

@@ -345,7 +345,7 @@ def _fetch_currently_failed(requireds) -> TagDict:
             # Here, we pick the field unknown to the CLI parser too.
             # As whole subparser was unknown here, we safely consider all its fields wrong fields.
             if fname:
-                missing_req[fname_raw] = get_or_create_parent_dict(requireds, fname)
+                get_or_create_parent_dict(missing_req, fname, True)[fname_raw] = get_or_create_parent_dict(requireds, fname)
             else:
                 # This is the default subparser, without a field name:
                 # ex. `run([List, Run])`

mininterface/_lib/dataclass_creation.py

@@ -232,7 +232,7 @@ def _process_field(fname, ftype, disk_value, wf, m, default_value=MISSING):
     # the subcommand has been already chosen by CLI parser
     if isinstance(disk_value, ChosenSubcommand):  # `(class Message | class Console)`
         for _subcomm in get_args(_unwrap_annotated(ftype)):
-            if disk_value.name == getattr(_subcomm, "__name__", "").casefold():
+            if disk_value.name == to_kebab_case(_subcomm.__name__):
                 ftype = _subcomm  # `class Message` only
                 disk_value = disk_value.subdict
                 break

mininterface/_lib/tyro_patches.py

@@ -329,11 +329,13 @@ def _(self: TyroArgumentParser, *args, **kwargs):
         if cf.add_version:
             self.add_argument(
                 default_prefix * 2 + "version",
-                # I would use this native version, but it insert a blank line
-                # action="version",
-                # version=add_version,
-                action="store_const",
-                const=cf.version,
+                # NOTE We use the native version, but it inserts a blank line
+                action="version",
+                version=cf.version,
+                # Our custom version works bad with subcommands, we have to first resolve subcommands,
+                # than it comes to the version
+                # action="store_const",
+                # const=cf.version,
                 help=f"show program's version number ({cf.version}) and exit",
             )
 
@@ -360,11 +362,12 @@ def _(self: TyroArgumentParser, args=None, namespace=None):
                 logging.basicConfig(level=cf.default_verbosity, format="%(message)s", force=True)
             delattr(namespace, "verbose")
 
-        if cf.add_verbose and hasattr(namespace, "version"):
-            if namespace.version:
-                print(namespace.version)
-                raise SystemExit(0)
-            delattr(namespace, "version")
+        # This code is now not used, see `custom_init`
+        # if cf.add_verbose and hasattr(namespace, "version"):
+        #     if namespace.version:
+        #         print(namespace.version)
+        #         raise SystemExit(0)
+        #     delattr(namespace, "version")
 
         if cf.add_quiet and hasattr(namespace, "quiet"):
             if namespace.quiet:

mininterface/tag/select_tag.py

@@ -3,12 +3,15 @@
 from typing import Iterable, Literal, Optional, Type, get_args, get_origin
 from warnings import warn
 
+
+from .._lib.auxiliary import allows_none, strip_none
+
 from .tag import Tag, TagValue
 
 OptionsReturnType = list[tuple[str, TagValue, bool, tuple[str]]]
 """ label, choice value, is-tip, tupled-label """
 OptionLabel = str
-RichOptionLabel = OptionLabel | tuple[OptionLabel]
+RichOptionLabel = OptionLabel | tuple[OptionLabel, ...]
 OptionsType = (
     list[TagValue]
     | tuple[TagValue, ...]
@@ -171,8 +174,9 @@ def __post_init__(self):
 
         # Determine options from annotation
         if not self.options:
-            if get_origin(self.annotation) is Literal:
-                self.options = get_args(self.annotation)
+            pt = self._get_possible_types()
+            if len(pt) == 1 and pt[0][0] is Literal:
+                self.options = pt[0][1]
             elif self.annotation is not Enum:
                 # We take whatever is in the annotation, hoping there are some values.
                 # However, the symbol Enum itself (injected in Tag.__post_init__) will not bring us any benefit.
@@ -181,10 +185,14 @@ def __post_init__(self):
                 #
                 # @dataclass
                 # class dc:
-                #   field: Color -> Tag(annotation=enum.Color)
-                self.options = self.annotation
+                #   field: Color | None -> Tag(annotation=enum.Color)
+                #
+                # Why strip_none? The `| None` type will be readded later, we now clean it to pure Enum
+                # for detection purposes.
+                self.options = strip_none(self.annotation)
 
         # Disabling annotation is not a nice workaround, but it is needed for the `super().update` to be processed
+        orig_ann = self.annotation
         self.annotation = type(self)
         reset_name = not self.label
         super().__post_init__()
@@ -207,6 +215,24 @@ def __post_init__(self):
                 self.options = self.val
                 self.val = None
 
+        if (self.options and orig_ann is not None and allows_none(orig_ann)) or (
+            not self.options and orig_ann is None
+        ):
+            # None is among the options, like
+            # * `Options("one", None, "two")`
+            # * `Optional[Literal["one", "two"]]`
+            # * `SelectTag()`
+            # But ignore the case when the annotation is whole None with some options: `SelectTag(options=...)`.
+            opt = self._build_options()
+            if None not in opt.values():
+                for char in ("∅", "-", "None"):
+                    if char not in opt:
+                        # Put the None option to the first place
+                        self.options = {char: None, **{k: v for k, v in opt.items()}}
+                        break
+                else:
+                    raise ValueError("Cannot demark a None option.")
+
     def __hash__(self):  # every Tag child must have its own hash method to be used in Annotated
         return super().__hash__()
 
@@ -231,7 +257,7 @@ def _get_selected_keys(self):
         return [k for k, val, *_ in self._get_options() if val in self.val]
 
     @classmethod
-    def _repr_val(cls, v):
+    def _repr_val(cls, v) -> str:
         if cls._is_a_callable_val(v):
             return v.__name__
         if isinstance(v, Tag):
@@ -240,23 +266,28 @@ def _repr_val(cls, v):
             return str(v.value)
         return str(v)
 
-    def _build_options(self) -> dict[OptionLabel, TagValue]:
-        """Whereas self.options might have different format, this returns a canonic dict."""
+    def _build_options(self) -> dict[RichOptionLabel, TagValue]:
+        """Whereas self.options might have different format,
+        this returns a canonic dict.
+        The keys are all strs or all tuples.
+        """
 
         if self.options is None:
             return {}
         if isinstance(self.options, dict):
-            # assure the key is a str or their tuple
-            return {
-                (tuple(str(k) for k in key) if isinstance(key, tuple) else str(key)): self._get_tag_val(v)
-                for key, v in self.options.items()
-            }
+            # assure the keys are either strs or tuple of strs
+            keys = self.options.keys()
+            if any(isinstance(k, tuple) for k in keys):
+                keys = ((tuple(str(k) for k in key) if isinstance(key, tuple) else (str(key),)) for key in keys)
+            else:
+                keys = (str(key) for key in keys)
+            return {key: self._get_tag_val(v) for key, v in zip(keys, self.options.values())}
         if isinstance(self.options, Iterable):
             return {self._repr_val(v): self._get_tag_val(v) for v in self.options}
         if isinstance(self.options, type) and issubclass(self.options, Enum):  # Enum type, ex: options=ColorEnum
             return {str(v.value): self._get_tag_val(v) for v in list(self.options)}
 
-        warn(f"Not implemented options: {self.options}")
+        raise ValueError(f"Not implemented options: {self.options}")
 
     def _get_options(self, delim=" - ") -> OptionsReturnType:
         """Return a list of tuples (label, choice value, is tip, tupled-label).
@@ -281,10 +312,12 @@ def _get_options(self, delim=" - ") -> OptionsReturnType:
         options = self._build_options()
 
         keys = options.keys()
-        labels: Iterable[tuple[str, tuple[str]]]
+        labels: Iterable[tuple[str, tuple[str, ...]]]
         """ First is the str-label, second is guaranteed to be a tupled label"""
 
         if len(options) and isinstance(next(iter(options)), tuple):
+            # As options come from the _build_options, we are sure that if the first is a tuple,
+            # the others are tuples too.
             labels = self._span_to_lengths(keys, delim)
         else:
             labels = ((key, (key,)) for key in keys)

mininterface/tag/tag.py

@@ -641,6 +641,9 @@ def _is_subclass(self, class_type: type | tuple[type]):
                     return True
             elif subclass_matches_annotation(class_type, subtype):  # tuple
                 return True
+            elif origin is None and subclass_matches_annotation(subtype, class_type):
+                # ex. `ColorEnum | None` _is_subclass(Enum)
+                return True
         return False
 
     def _get_possible_types(self) -> list[tuple[type | None, type | list[type]]]:
@@ -666,11 +669,8 @@ def _(annot):
                     return [_(subt) for subt in subtype]
                 if origin is tuple:
                     return origin, list(subtype)
-                # elif origin is Literal:
-                #     ss=set(type(t) for t in subtype)
-                #     if len(ss) == 1:
-                #         return origin, ss.pop()
-                #     warn(f"This parametrized Literal generic not implemented: {annot}")
+                elif origin is Literal:
+                    return origin, subtype
                 elif len(subtype) == 1:
                     return origin, subtype[0]
                 else:

mininterface/tag/tag_factory.py

@@ -32,7 +32,8 @@ def _get_tag_type(tag: Tag) -> Type[Tag]:
     """Return the most specific Tag child that a tag value can be expressed with.
     Ex. Return PathTag for a Tag having a Path as a value.
     """
-    if get_origin(tag.annotation) is Literal:
+    pt = tag._get_possible_types()
+    if len(pt) == 1 and pt[0][0] is Literal:
         return SelectTag
     if tag._is_subclass(Path):
         return PathTag