paramspecli 0.2.1__tar.gz → 0.2.2__tar.gz

{paramspecli-0.2.1 → paramspecli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramspecli
-Version: 0.2.1
+Version: 0.2.2
 Summary: Type-safe facade for the venerable argparse
 Author: jkmnt
 Requires-Python: >=3.12
@@ -78,7 +78,7 @@ pip install paramspecli
 - Commands match handler functions parameters with arguments and options.
 - Arguments are bound to the handler's positional parameters.
 - Options are bound to the handler's keyword parameters.
-- Groups organize the commands. Groups may be nested. They could act like like an intermediate commands, i.e. have own handlers, options and arguments.
+- Groups organize the commands. Groups may be nested. They could act like an intermediate commands, i.e. have own handlers, options and arguments.
 - CLI 'compiles' to the `argparse`, runs it, then outputs the parse result.
 - Parse result is a callable. Calling it invokes handlers along the route.
 

{paramspecli-0.2.1 → paramspecli-0.2.2}/README.md

@@ -64,7 +64,7 @@ pip install paramspecli
 - Commands match handler functions parameters with arguments and options.
 - Arguments are bound to the handler's positional parameters.
 - Options are bound to the handler's keyword parameters.
-- Groups organize the commands. Groups may be nested. They could act like like an intermediate commands, i.e. have own handlers, options and arguments.
+- Groups organize the commands. Groups may be nested. They could act like an intermediate commands, i.e. have own handlers, options and arguments.
 - CLI 'compiles' to the `argparse`, runs it, then outputs the parse result.
 - Parse result is a callable. Calling it invokes handlers along the route.
 

{paramspecli-0.2.1 → paramspecli-0.2.2}/src/paramspecli/__init__.py

@@ -1,15 +1,17 @@
 """Type-safe facade for the venerable argparse"""
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 
 
 from .args import argument as argument
+from .cli import MISSING as MISSING
 from .cli import Action as Action
 from .cli import CallableGroup as CallableGroup
 from .cli import Command as Command
 from .cli import Config as Config
 from .cli import Group as Group
 from .cli import Handler as Handler
+from .cli import Missing as Missing
 from .cli import Route as Route
 from .cli import help_action as help_action
 from .cli import version_action as version_action

{paramspecli-0.2.1 → paramspecli-0.2.2}/src/paramspecli/apstub.py

@@ -81,4 +81,4 @@ class ArgumentParserLike(
     def exit(self, status: int = ..., message: str | None = ...) -> NoReturn: ...
 
 
-class ArgumentGroupLike(SupportsAddArgument, SupportsAddOneofGroup, Protocol): ...
+class ArgumentGroupLike(SupportsAddArgument, SupportsAddOneofGroup, SupportsSetDefaults, Protocol): ...

{paramspecli-0.2.1 → paramspecli-0.2.2}/src/paramspecli/args.py

@@ -107,4 +107,4 @@ def argument(
     choices: Iterable[Any] | None = None,
 ) -> Argument[Any, Any]:
     """Positional argument. Always required, unless made optional via `nargs="?"`."""
-    return Argument(metavar, help=help, type=type, choices=choices, nargs=nargs, default=default)
+    return Argument(metavar, help=help, conv=type, choices=choices, nargs=nargs, default=default)

{paramspecli-0.2.1 → paramspecli-0.2.2}/src/paramspecli/cli.py

@@ -1,6 +1,7 @@
 import argparse
 import dataclasses
 import sys
+from types import EllipsisType
 from typing import (
     Any,
     Callable,
@@ -10,6 +11,7 @@ from typing import (
     Iterator,
     Literal,
     Mapping,
+    NamedTuple,
     Protocol,
     Self,
     Sequence,
@@ -28,14 +30,20 @@ from .apstub import (
     SupportsSetDefaults,
     TypeConverter,
 )
+from .conv import PathConv
 
 # TODO:
 # if section has a headline, it's not auto-purged from the help.
 # Ok for user sections, bad for the default options/arguments sections
 
-type ArgparseActionCls = type[argparse.Action]
+type Missing = EllipsisType
+MISSING: Final = ...
 
-type HandlerSpec = tuple[Callable[..., None] | None, list[Any], dict[str, Any]]
+
+class HandlerSpec(NamedTuple):
+    func: Callable[..., None] | None
+    args: list[str]  # [arg_key]
+    opts: dict[str, str]  # {opt_name: opt_key}
 
 
 class Markup(Protocol):
@@ -48,11 +56,16 @@ class DefaultFunc[**P](Protocol):
     def __call__(self, parser: ArgumentParserLike, /, *args: P.args, **kwargs: P.kwargs) -> None: ...
 
 
-def _make_spec(prefix: str, func: Callable[..., None] | None, nargs: int, options: Iterable[str]) -> HandlerSpec:
-    return (
-        func,
-        [f"{prefix}[{i}]" for i in range(nargs)],
-        {param: f"{prefix}.{param}" for param in options},
+def _make_spec(
+    level: int,
+    func: Callable[..., None] | None,
+    args: Sequence["Arg | Cnst | Ctx"],
+    options: Mapping[str, "Opt | MixedOpts | Cnst | Ctx"],
+) -> HandlerSpec:
+    return HandlerSpec(
+        func=func,
+        args=[f"{level}[{i}]" for i in range(len(args))],
+        opts={param: f"{level}.{param}" for param in options},
     )
 
 
@@ -94,11 +107,30 @@ def _as_plain(arg: str | Markup | None) -> str | None:
     return str(arg)
 
 
+def _may_raise_custom_exceptions(conv: TypeConverter[Any]) -> bool:
+    if conv is int:
+        return False
+    if conv is float:
+        return False
+    if conv is bool:
+        return False
+    if isinstance(conv, PathConv):
+        return False
+    return True
+
+
 def print_group_help(parser: ArgumentParserLike, /, *args: Any, **kwargs: Any) -> None:
     parser.print_help()
     parser.exit()
 
 
+# print some values in a nicer way. currently it's a lists w/o quotes
+def nice_str(val: Any) -> str:
+    if isinstance(val, list):
+        return f"[{ ", ".join([str(item) for item in val])}]"
+    return str(val)
+
+
 def _with_argparser_arg[**P](
     f: Callable[Concatenate[ArgumentParserLike, P], None], argparser: ArgumentParserLike
 ) -> Callable[P, None]:
@@ -126,6 +158,17 @@ class HelpFormatter(argparse.HelpFormatter):
             return text.splitlines()
         return super()._split_lines(text, width)
 
+    # interpolate lists manually to avoid extra quotes
+    def _get_help_string(self, action: argparse.Action) -> str | None:
+        help = action.help
+
+        if help is not None and "%(default)s" in help:
+            if isinstance(action.default, list):
+                s = nice_str(action.default)
+                help = help.replace("%(default)s", s)
+
+        return help
+
 
 @dataclasses.dataclass
 class Config:
@@ -152,6 +195,8 @@ class Config:
     parser_class: type[argparse.ArgumentParser] = argparse.ArgumentParser
     """Argparge parser class to use"""
     formatter_class: type[argparse.HelpFormatter] = HelpFormatter
+    """Silently ignore unknown args and place them into the Route.unknown_args"""
+    ignore_unknown_args: bool = False
     """Argparse help formatter class to use"""
     root_parser_extra_kwargs: Mapping[str, Any] = dataclasses.field(default_factory=dict)
     """Dict of extra kwargs for the root (CLI) argparse.ArgumentParser"""
@@ -165,7 +210,7 @@ class Arg:
 
     metavar: str
     _: dataclasses.KW_ONLY
-    type: TypeConverter[Any] | None = None
+    conv: TypeConverter[Any] | None = None
     help: str | Markup | bool | None = None
     choices: Iterable[Any] | None = None
     nargs: int | Literal["*", "+", "?"] | None = None
@@ -179,10 +224,10 @@ class Arg:
     def __hash__(self) -> int:
         return hash(self.metavar)
 
-    def _build(self, owner: SupportsAddArgument, config: Config, *, dest: str) -> None:
-        _type = self.type
-        if _type and config.catch_typeconv_exceptions:
-            _type = util.catch_all(_type)
+    def _build(self, owner: SupportsAddArgument, config: Config, *, dest: str, **_rest: Any) -> None:
+        conv = self.conv
+        if conv and config.catch_typeconv_exceptions and _may_raise_custom_exceptions(conv):
+            conv = util.catch_all(conv)
 
         help = self.help
 
@@ -194,17 +239,16 @@ class Arg:
         # most kwargs shouldn't be set at all if None
         kwargs: dict[str, Any] = {
             "choices": self.choices,
-            "default": self.default,
             "nargs": self.nargs,
             "metavar": self.metavar,
             # NOTE: if type is not specified, argparse's MetavarTypeHelpFormatter may fail!
-            "type": _type,
+            "type": conv,
         }
         kwargs = {k: v for k, v in kwargs.items() if v is not None}
         if self.extra:
             kwargs |= self.extra
 
-        owner.add_argument(dest=dest, help=_as_plain(help), **kwargs)
+        owner.add_argument(dest=dest, help=_as_plain(help), default=self.default, **kwargs)
 
 
 # Too many fields to manage: dataclass to the rescue
@@ -214,14 +258,14 @@ class Opt:
 
     names: tuple[str, ...]
     _: dataclasses.KW_ONLY
-    type: TypeConverter[Any] | None = None
+    conv: TypeConverter[Any] | None = None
     help: str | Markup | bool | None = None
     hard_show_default: bool | str | None = None
     soft_show_default: bool | str = False
     required: bool = False
     choices: Iterable[Any] | None = None
     metavar: str | tuple[str, ...] | None = None
-    action: str | ArgparseActionCls | None = None
+    action: str | type[argparse.Action] | None = None
     nargs: int | Literal["*", "+", "?"] | None = None
     default: Any = None
     const: Any = None
@@ -243,7 +287,7 @@ class Opt:
     def __hash__(self) -> int:
         return hash(self.names)
 
-    def _build(self, owner: SupportsAddArgument, config: Config, *, dest: str | Literal[False]) -> None:
+    def _build(self, owner: SupportsAddArgument, config: Config, *, dest: str | Literal[False], **_rest: Any) -> None:
         help = self.help
 
         if help is False:
@@ -268,19 +312,18 @@ class Opt:
             else:
                 help += f" (default: {show_default})"
 
-        _type = self.type
-        if _type and config.catch_typeconv_exceptions:
-            _type = util.catch_all(_type)
+        conv = self.conv
+        if conv and config.catch_typeconv_exceptions and _may_raise_custom_exceptions(conv):
+            conv = util.catch_all(conv)
 
         # most kwargs shouldn't be set at all if None
         kwargs: dict[str, Any] = {
             "action": self.action,
             "choices": self.choices,
-            "default": self.default,
             "nargs": self.nargs,
             "const": self.const,
             "metavar": self.metavar,
-            "type": _type,
+            "type": conv,
             "required": self.required or None,
             "deprecated": self.deprecated if sys.version_info >= (3, 13) else None,
         }
@@ -289,7 +332,7 @@ class Opt:
         if self.extra:
             kwargs |= self.extra
 
-        owner.add_argument(*self.names, dest=dest or argparse.SUPPRESS, help=help, **kwargs)
+        owner.add_argument(*self.names, dest=dest or argparse.SUPPRESS, default=self.default, help=help, **kwargs)
 
     @property
     def is_hidden(self) -> bool:
@@ -300,6 +343,34 @@ class Opt:
         return self
 
 
+
+class Cnst:
+    __slots__ = ("value",)
+
+    def __init__(self, value: Any):
+        self.value: Final = value
+
+    def __repr__(self) -> str:
+        return _repr_class(self, {"value": self.value}, skip_none=False)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Cnst):
+            return NotImplemented
+        return bool(self.value == other.value)
+
+    def _build(self, owner: SupportsSetDefaults, config: Config, *, dest: str, **_rest: Any) -> None:
+        owner.set_defaults(**{dest: self.value})
+
+
+class Ctx:
+    __slots__ = ()
+
+    def _build(self, owner: SupportsSetDefaults, config: Config, *, dest: str, context: Any) -> None:
+        if context is None:
+            raise ValueError("context can't be None")
+        owner.set_defaults(**{dest: context})
+
+
 class MixedOpts:
     """Abstract mix of options"""
 
@@ -322,44 +393,17 @@ class MixedOpts:
         return self
 
 
-class Cnst:
-    __slots__ = ("value",)
-
-    def __init__(self, value: Any):
-        self.value: Final = value
-
-    def __repr__(self) -> str:
-        return _repr_class(self, {"value": self.value}, skip_none=False)
-
-    def __eq__(self, other: object) -> bool:
-        if not isinstance(other, Cnst):
-            return NotImplemented
-        return bool(self.value == other.value)
-
-    def _build(self, owner: SupportsSetDefaults, config: Config, *, dest: str) -> None:
-        owner.set_defaults(**{dest: self.value})
-
-
 class Action(Opt):
     """Special kind of option with side effects"""
 
     __slots__ = ()
 
-    def _build(self, owner: SupportsAddArgument, config: Config, *, dest: str | Literal[False]) -> None:
+    def _build(self, owner: SupportsAddArgument, config: Config, *, dest: str | Literal[False], **_rest: Any) -> None:
         if dest is not False:
             raise TypeError(f"Action is used in place of Option {dest!r}")
         return super()._build(owner, config, dest=dest)
 
 
-class Ctx:
-    __slots__ = ()
-
-    def _build(self, owner: SupportsSetDefaults, config: Config, *, dest: str, context: Any) -> None:
-        if context is None:
-            raise ValueError("context can't be None")
-        owner.set_defaults(**{dest: context})
-
-
 class Section:
     """Shows its options in a separate block of a `--help` output"""
 
@@ -427,7 +471,7 @@ class ParserLike:
 
         self.arguments: list[Arg | Cnst | Ctx] | None = None
         self.actions: list[Action] = []
-        self.options: dict[str, Opt | MixedOpts | Cnst | Ctx] | None = {}
+        self.options: dict[str, Opt | MixedOpts | Cnst | Ctx] | None = None
         self.sections: list[Section] = []
         self.oneofs: list[Oneof] = []
 
@@ -452,7 +496,7 @@ class ParserLike:
         self.options = {**options}
 
     def _build_sections(
-        self, owner: ArgumentParserLike, config: Config, *, default_group: ArgumentGroupLike
+        self, parser: ArgumentParserLike, config: Config, *, default_group: ArgumentGroupLike
     ) -> dict[Opt, SupportsAddArgument]:
         sectmap: dict[Opt, ArgumentGroupLike] = {}
         oneofmap: dict[Opt, SupportsAddArgument] = {}
@@ -461,7 +505,7 @@ class ParserLike:
             if section_dupes := section.options.intersection(sectmap):
                 raise KeyError(f"options {section_dupes} are in several sections at once")
 
-            sectmap |= dict.fromkeys(section.options, section._build(owner, config))
+            sectmap |= dict.fromkeys(section.options, section._build(parser, config))
 
         for oneof in self.oneofs:
             if not oneof.options:
@@ -480,58 +524,51 @@ class ParserLike:
         return tgtmap
 
     def _build_params(
-        self, owner: ArgumentParserLike, config: Config, *, parents: Sequence["ParserLike"], context: Any
+        self, parser: ArgumentParserLike, config: Config, *, parents: Sequence["ParserLike"], context: Any
     ) -> None:
         if self._func:
             if self.arguments is None or self.options is None:
                 raise ValueError("bind() was not called")
 
-        key = str(len(parents))
+        level = len(parents)
 
-        spec = _make_spec(key, self._func, len(self.arguments or []), self.options or {})
-        owner.set_defaults(**{key: spec})
+        spec = _make_spec(level, self._func, self.arguments or [], self.options or {})
+        parser.set_defaults(**{str(level): spec})
 
         if self.arguments:
-            arguments_group = owner.add_argument_group(
+            arguments_group = parser.add_argument_group(
                 title=config.arguments_title, description=_as_plain(config.arguments_headline)
             )
 
             for i, argument in enumerate(self.arguments):
-                name = f"{key}[{i}]"
-                if isinstance(argument, Cnst):
-                    argument._build(owner, config, dest=name)
-                elif isinstance(argument, Ctx):
-                    argument._build(owner, config, dest=name, context=context)
-                else:
-                    argument._build(arguments_group, config, dest=name)
-
-        default_options_group = owner.add_argument_group(
+                dest = f"{level}[{i}]"
+                argument._build(arguments_group, config, dest=dest, context=context)
+
+        default_options_group = parser.add_argument_group(
             title=config.options_title, description=_as_plain(config.options_headline)
         )
 
-        tgtmap = self._build_sections(owner, config, default_group=default_options_group)
+        tgtmap = self._build_sections(parser, config, default_group=default_options_group)
 
         for action in self.actions:
             action._build(tgtmap.pop(action, default_options_group), config, dest=False)
 
         if self.options:
             for param, item in self.options.items():
-                name = f"{key}.{param}"
-                if isinstance(item, Cnst):
-                    item._build(owner, config, dest=name)
-                elif isinstance(item, Ctx):
-                    item._build(owner, config, dest=name, context=context)
-                else:
-                    seq = (item,) if isinstance(item, Opt) else item.options
-                    for opt in seq:
-                        opt._build(tgtmap.pop(opt, default_options_group), config, dest=name)
+                dest = f"{level}.{param}"
+                seq = (item,) if not isinstance(item, MixedOpts) else item.options
+                for opt in seq:
+                    if isinstance(opt, (Cnst, Ctx)):
+                        opt._build(parser, config, dest=dest, context=context)
+                    else:
+                        opt._build(tgtmap.pop(opt, default_options_group), config, dest=dest, context=context)
 
         if tgtmap:
             raise KeyError(f"unconsumed items in sections: {tgtmap.keys()}")
 
     def _build_subparser(
         self,
-        owner: SupportsAddParser,
+        parent: SupportsAddParser,
         config: Config,
         *,
         parents: Sequence["ParserLike"],
@@ -544,7 +581,7 @@ class ParserLike:
         if epilog is None and config.propagate_epilog and parents:
             epilog = parents[0].epilog
 
-        return owner.add_parser(
+        return parent.add_parser(
             basename,
             aliases=aliases,
             help=_as_plain(self.help),
@@ -635,12 +672,10 @@ class Handler:
     def from_ns(cls, ns: argparse.Namespace, spec: HandlerSpec) -> Self:
         vars = ns.__dict__
 
-        func, argnames, kwargnames = spec
-
-        args = [vars[name] for name in argnames]
-        kwargs = {k: vars[v] for k, v in kwargnames.items()}
+        args = [vars[name] for name in spec.args]
+        kwargs = {k: vars[v] for k, v in spec.opts.items()}
 
-        return cls(func, args, kwargs)
+        return cls(spec.func, args, kwargs)
 
     @classmethod
     def from_spec(cls, func: Callable[..., None] | None, /, *arguments: Any, **options: Any) -> Self:
@@ -651,9 +686,11 @@ class Route:
     """Represents sequence of handers, arguments and options.
     Calling it will invoke the handlers"""
 
-    def __init__(self, handlers: Sequence[Handler]):
+    def __init__(self, handlers: Sequence[Handler], unknown_args: Sequence[str] | None = None):
         self.handlers = handlers
+        self.unknown_args = unknown_args
 
+    # unrecognized args are ignored for the comparison
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, Route):
             return NotImplemented
@@ -680,7 +717,7 @@ class Route:
         return [h for h in self.handlers if h.func is not None]
 
     @classmethod
-    def from_ns(cls, ns: argparse.Namespace) -> Self:
+    def from_ns(cls, ns: argparse.Namespace, unknown_args: Sequence[str] | None = None) -> Self:
         specs: list[tuple[int, HandlerSpec]] = []
         for k, v in ns.__dict__.items():
             try:
@@ -692,7 +729,7 @@ class Route:
         specs.sort()
 
         handlers = [Handler.from_ns(ns, spec[1]) for spec in specs]
-        return cls(handlers)
+        return cls(handlers, unknown_args=unknown_args)
 
 
 ## More concrete
@@ -720,14 +757,14 @@ class Command[**P](ParserLike):
 
     def _build(
         self,
-        owner: ArgumentParserLike,
+        parser: ArgumentParserLike,
         config: Config,
         *,
         parents: Sequence["Group"],
         context: Any,
         **kwargs: Any,
     ) -> None:
-        self._build_params(owner, config, parents=parents, context=context)
+        self._build_params(parser, config, parents=parents, context=context)
 
     def bind(self, *arguments: P.args, **options: P.kwargs) -> Self:
         """Bind function parameters to arguments/options"""
@@ -741,6 +778,10 @@ class Command[**P](ParserLike):
         parser = self._build_root_parser(config)
         self._build(parser, config, parents=[], context=context)
 
+        if config.ignore_unknown_args:
+            ns, unknown_args = parser.parse_known_args(input)
+            return Route.from_ns(ns, unknown_args=unknown_args)
+
         ns = parser.parse_args(input)
         return Route.from_ns(ns)
 
@@ -773,31 +814,31 @@ class Group(ParserLike):
         if add_help:
             self.append_action(_help_action)
 
-    def _build(self, owner: ArgumentParserLike, config: Config, *, parents: Sequence["Group"], context: Any) -> None:
-        self._build_params(owner, config, parents=parents, context=context)
-        self._build_default_handler(owner, config, parents=parents)
-        self._build_nodes(owner, config, parents=parents, context=context)
+    def _build(self, parser: ArgumentParserLike, config: Config, *, parents: Sequence["Group"], context: Any) -> None:
+        self._build_params(parser, config, parents=parents, context=context)
+        self._build_default_handler(parser, config, parents=parents)
+        self._build_nodes(parser, config, parents=parents, context=context)
 
     def _build_default_handler(
-        self, owner: ArgumentParserLike, config: Config, *, parents: Sequence["ParserLike"]
+        self, parser: ArgumentParserLike, config: Config, *, parents: Sequence["ParserLike"]
     ) -> None:
         if not self.default_func:
             return
 
-        default_func = _with_argparser_arg(self.default_func, owner)
+        default_func = _with_argparser_arg(self.default_func, parser)
 
-        key = str(len(parents))
-        deeper_key = str(len(parents) + 1)
-        spec = _make_spec(key, default_func, len(self.arguments or []), self.options or {})
-        owner.set_defaults(**{deeper_key: spec})
+        level = len(parents)
+        next_level = level + 1
+        spec = _make_spec(level, default_func, self.arguments or [], self.options or {})
+        parser.set_defaults(**{str(next_level): spec})
 
     def _build_nodes(
-        self, owner: ArgumentParserLike, config: Config, *, parents: Sequence["Group"], context: Any
+        self, parent: ArgumentParserLike, config: Config, *, parents: Sequence["Group"], context: Any
     ) -> None:
         if not self.nodes:
             return
 
-        sub = owner.add_subparsers(
+        sub = parent.add_subparsers(
             title=self.title if self.title is not None else config.commands_title,
             description=_as_plain(self.headline),
             parser_class=config.parser_class,
@@ -824,6 +865,10 @@ class Group(ParserLike):
             e.add_note("- Cli")
             raise
 
+        if config.ignore_unknown_args:
+            ns, unknown_args = parser.parse_known_args(input)
+            return Route.from_ns(ns, unknown_args=unknown_args)
+
         ns = parser.parse_args(input)
         return Route.from_ns(ns)
 

{paramspecli-0.2.1 → paramspecli-0.2.2}/src/paramspecli/conv.py

@@ -6,11 +6,11 @@ from typing import Final, Literal
 class PathConv:
     __name__ = "PATH"
 
-    __slots__ = ("exists", "resolve", "type")
+    __slots__ = ("exists", "kind", "resolve")
 
-    def __init__(self, type: Literal["file", "dir", None] = None, *, exists: bool | None = None, resolve: bool = True):
+    def __init__(self, kind: Literal["file", "dir", None] = None, *, exists: bool | None = None, resolve: bool = True):
         self.exists: Final = exists
-        self.type: Final = type
+        self.kind: Final = kind
         self.resolve: Final = resolve
 
     # scenarios:
@@ -26,24 +26,24 @@ class PathConv:
         if self.resolve:
             path = path.resolve()
 
-        check_type = False
+        check_kind = False
 
         if self.exists is True:
             if not path.exists():
                 raise ArgumentTypeError(f"{path} does not exists")
-            check_type = True
+            check_kind = True
         elif self.exists is False:
             if path.exists():
                 raise ArgumentTypeError(f"{path} already exists")
         else:
-            if self.type and path.exists():
-                check_type = True
+            if self.kind and path.exists():
+                check_kind = True
 
-        if check_type:
-            if self.type == "file":
+        if check_kind:
+            if self.kind == "file":
                 if not path.is_file():
                     raise ArgumentTypeError(f"{path} is not a file")
-            elif self.type == "dir":
+            elif self.kind == "dir":
                 if not path.is_dir():
                     raise ArgumentTypeError(f"{path} is not a directory")
 

{paramspecli-0.2.1 → paramspecli-0.2.2}/src/paramspecli/doc.py

@@ -4,7 +4,7 @@ from typing import Any, Final, Iterable, Mapping, NamedTuple, Protocol, Sequence
 
 from paramspecli import md
 
-from .cli import Arg, Command, Group, Opt, Section, name_and_aliases
+from .cli import Arg, Command, Group, Opt, Section, name_and_aliases, nice_str
 
 
 class Renderer(Protocol):
@@ -65,6 +65,7 @@ class Settings:
     usage_title: str = "Usage"
     aliases_title: str = "Aliases"
     options_headline: str | None = None
+    choice_metavar: str = "CHOICE"
 
 
 class Doc:
@@ -121,8 +122,10 @@ class Doc:
         else:
             out += _join([r.code(name) for name in names], sep=", ")
 
-        if option.metavar is not None:
-            out += " " + r.i(r.e(self.r_metavar(option.metavar, option)))
+        metavar = self.r_metavar(option)
+
+        if metavar:
+            out += " " + r.i(r.e(metavar))
         return out
 
     def r_option_default(self, option: Opt) -> str:
@@ -134,12 +137,12 @@ class Doc:
             if isinstance(option.hard_show_default, str):
                 default = option.hard_show_default
             elif option.hard_show_default is True:
-                default = str(option.default)
+                default = nice_str(option.default)
         else:
             if isinstance(option.soft_show_default, str):
                 default = option.soft_show_default
             elif option.soft_show_default is True:
-                default = str(option.default)
+                default = nice_str(option.default)
 
         if default is None:
             return ""
@@ -164,10 +167,17 @@ class Doc:
 
         return out
 
-    def r_metavar(self, metavar: str | tuple[str, ...], item: Opt | Arg) -> str:
+    def r_metavar(self, item: Opt | Arg) -> str:
+        metavar = item.metavar
         if isinstance(metavar, tuple):
             return _join(metavar, sep=" ")
 
+        if metavar is None:
+            if item.choices:
+                metavar = self.config.choice_metavar
+            else:
+                return ""
+
         nargs = item.nargs
 
         if isinstance(nargs, int):
@@ -177,7 +187,7 @@ class Doc:
         if nargs == "+":
             return f"{metavar} [{metavar} ...]"
         if nargs == "?":
-            return f"[{metavar} ...]"
+            return f"[{metavar}]"
         return metavar
 
     def r_arguments(self, arguments: Sequence[Arg]) -> str:
@@ -231,7 +241,7 @@ class Doc:
     def _group_usage_partial(self, me: BoundGroup) -> str:
         return _join(
             me.name,
-            [self.r_metavar(arg.metavar, arg) for arg in self.get_arguments(me)],
+            [self.r_metavar(arg) for arg in self.get_arguments(me)],
             sep=" ",
         )
 
@@ -273,7 +283,7 @@ class Doc:
                 [self._group_usage_partial(p) for p in parents],
                 me.name,
                 [f"[{section.title.lower()}]" for section in options_sections],
-                [self.r_metavar(arg.metavar, arg) for arg in self.get_arguments(me)],
+                [self.r_metavar(arg) for arg in self.get_arguments(me)],
                 sep=" ",
             )
         )

{paramspecli-0.2.1 → paramspecli-0.2.2}/src/paramspecli/flags.py

@@ -1,6 +1,7 @@
 from argparse import BooleanOptionalAction
 from typing import Any, Literal, overload
 
+from .cli import MISSING
 from .fake import Option, RepeatedOption
 
 
@@ -54,7 +55,7 @@ def flag[D](
 def flag(
     *names: str,
     value: Any = True,
-    default: Any = ...,
+    default: Any = MISSING,
     help: str | bool | None = None,
     show_default: bool | str | None = None,
 ) -> Option[Any, Any]:
@@ -80,7 +81,7 @@ def flag(
 
 
     """
-    if default is ...:
+    if default is MISSING:
         soft_show_default = False
         if value is True:
             default = False
@@ -130,16 +131,6 @@ def switch(
     show_default: bool | str | None = None,
 ) -> Option[bool, Any]:
     """On/Off switch with complimentary flags: `--foo/--no-foo`. Default is `False`"""
-    longs = [name for name in names if name.startswith("--")]
-    if not longs:
-        raise ValueError("at least one name starting with '--' is required")
-
-    soft_show_default: bool | str
-
-    if default is True or default is False:
-        soft_show_default = longs[0] if default else f"--no-{longs[0][2:]}"
-    else:
-        soft_show_default = True
 
     return Option(
         names,
@@ -148,7 +139,7 @@ def switch(
         default=default,
         #
         hard_show_default=show_default,
-        soft_show_default=soft_show_default,
+        soft_show_default=True,
     )
 
 

{paramspecli-0.2.1 → paramspecli-0.2.2}/src/paramspecli/opts.py

@@ -1,7 +1,7 @@
-from types import EllipsisType
 from typing import Any, Iterable, Literal, overload
 
 from .apstub import TypeConverter
+from .cli import Missing
 from .fake import Option, RepeatedOption
 
 
@@ -49,7 +49,7 @@ def option(
     choices: Iterable[str] | None = None,
     metavar: str | tuple[str, ...] | None = None,
     show_default: bool | str | None = None,
-) -> Option[str | EllipsisType, None]: ...
+) -> Option[str | Missing, None]: ...
 
 
 ## nargs, default: D
@@ -75,7 +75,7 @@ def option[D](
     choices: Iterable[str] | None = None,
     metavar: str | tuple[str, ...] | None = None,
     show_default: bool | str | None = None,
-) -> Option[str | EllipsisType, D]: ...
+) -> Option[str | Missing, D]: ...
 
 
 ## type: T
@@ -127,7 +127,7 @@ def option[T](
     choices: Iterable[T] | None = None,
     metavar: str | tuple[str, ...] | None = None,
     show_default: bool | str | None = None,
-) -> Option[T | EllipsisType, None]: ...
+) -> Option[T | Missing, None]: ...
 
 
 ## type: T, default: str, nargs
@@ -156,7 +156,7 @@ def option[T](
     choices: Iterable[T] | None = None,
     metavar: str | tuple[str, ...] | None = None,
     show_default: bool | str | None = None,
-) -> Option[T | EllipsisType, T]: ...
+) -> Option[T | Missing, T]: ...
 
 
 ## type: T, default: D, nargs
@@ -184,7 +184,7 @@ def option[T, D](
     choices: Iterable[T] | None = None,
     metavar: str | tuple[str, ...] | None = None,
     show_default: bool | str | None = None,
-) -> Option[T | EllipsisType, D]: ...
+) -> Option[T | Missing, D]: ...
 
 
 def option(
@@ -198,15 +198,19 @@ def option(
     show_default: bool | str | None = None,
 ) -> Option[Any, Any]:
     """Just an option"""
+
+    if metavar is None and choices is None:
+        metavar = names[0].lstrip("-").upper()
+
     return Option(
         names,
         help=help,
-        type=type,
+        conv=type,
         nargs=nargs,
         default=default,
         const=... if nargs == "?" else None,
         choices=choices,
-        metavar=metavar if metavar is not None else names[0].lstrip("-").upper(),
+        metavar=metavar,
         action="store",
         #
         hard_show_default=show_default,
@@ -310,13 +314,17 @@ def repeated_option(
 ) -> RepeatedOption[Any]:
     """Option which could present multiple times on a command line.
     Result is collected into the list"""
+
+    if metavar is None and choices is None:
+        metavar = names[0].lstrip("-").upper()
+
     return RepeatedOption(
         names,
         help=help,
-        type=type,
+        conv=type,
         nargs=nargs,
         choices=choices,
-        metavar=metavar if metavar is not None else names[0].lstrip("-").upper(),
+        metavar=metavar,
         action="extend" if flatten else "append",
         default=[],
         #