paramspecli 0.2.1__py3-none-any.whl

paramspecli/flags.py

@@ -0,0 +1,226 @@
+from argparse import BooleanOptionalAction
+from typing import Any, Literal, overload
+
+from .fake import Option, RepeatedOption
+
+
+##
+# common use - set: True, unset: False
+@overload
+def flag(  # type: ignore[overload-overlap]
+    *names: str,
+    value: bool = True,
+    help: str | Literal[False] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[bool, bool]: ...
+
+
+## value: T
+# even less common use - set: T, unset: None
+@overload
+def flag[T](
+    *names: str,
+    value: T,
+    help: str | Literal[False] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[T, None]: ...
+
+
+## value: T, default: D
+# even even less common use - set: T, unset: D
+@overload
+def flag[T, D](
+    *names: str,
+    value: T,
+    default: D,
+    help: str | Literal[False] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[T, D]: ...
+
+
+## default: D
+# for completeness. shouldn't be really used
+@overload
+def flag[D](
+    *names: str,
+    default: D,
+    value: bool = True,
+    help: str | Literal[False] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[bool, D]: ...
+
+
+# NOTE: using singleton ellipsis here as the sentinel
+def flag(
+    *names: str,
+    value: Any = True,
+    default: Any = ...,
+    help: str | bool | None = None,
+    show_default: bool | str | None = None,
+) -> Option[Any, Any]:
+    """flag
+
+    In basic configuration it's boolean:
+    ```
+    flag() -> True if --foo else False
+    ```
+    Pass `value=False` to invert:
+    ```
+    flag(value=False) -> False if --foo else True
+    ```
+
+    Pass non-bool `value` to disable the boolean mode:
+    ```
+    flag(value=123) -> 123 if --foo else None
+    ```
+    Pass `default` to change default:
+    ```
+    flag(value=123, default=456) -> 123 if --foo else 456
+    ```
+
+
+    """
+    if default is ...:
+        soft_show_default = False
+        if value is True:
+            default = False
+        elif value is False:
+            default = True
+        else:
+            default = None
+    else:
+        soft_show_default = default is not None
+
+    return Option(
+        names,
+        help=help,
+        action="store_const",
+        const=value,
+        default=default,
+        #
+        hard_show_default=show_default,
+        soft_show_default=soft_show_default,
+    )
+
+
+## -> bool
+@overload
+def switch(
+    *names: str,
+    default: bool = False,
+    help: str | Literal[False] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[bool, bool]: ...
+
+
+## default: D
+@overload
+def switch[D](
+    *names: str,
+    default: D,
+    help: str | Literal[False] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[bool, D]: ...
+
+
+def switch(
+    *names: str,
+    default: Any = False,
+    help: str | bool | None = None,
+    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,
+        help=help,
+        action=BooleanOptionalAction,
+        default=default,
+        #
+        hard_show_default=show_default,
+        soft_show_default=soft_show_default,
+    )
+
+
+## -> int
+@overload
+def count(
+    *names: str,
+    default: int = 0,
+    help: str | Literal[False] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[int, int]: ...
+
+
+## default: None
+@overload
+def count(
+    *names: str,
+    default: None,
+    help: str | Literal[False] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[int, None]: ...
+
+
+def count(
+    *names: str,
+    default: int | None = 0,
+    help: str | bool | None = None,
+    show_default: bool | str | None = None,
+) -> Option[int, Any]:
+    """Counter: `-vvv`. Default is `0`"""
+    return Option(
+        names,
+        help=help,
+        action="count",
+        default=default,
+        #
+        hard_show_default=show_default,
+        soft_show_default=False,
+    )
+
+
+##
+@overload
+def repeated_flag(
+    *names: str,
+    value: bool = True,
+    help: str | Literal[False] | None = None,
+) -> RepeatedOption[bool]: ...
+
+
+# value: T
+@overload
+def repeated_flag[T](
+    *names: str,
+    value: T,
+    help: str | Literal[False] | None = None,
+) -> RepeatedOption[T]: ...
+
+
+def repeated_flag(
+    *names: str,
+    value: Any = True,
+    help: str | bool | None = None,
+) -> RepeatedOption[Any]:
+    """Flag which could be present multiple times on a command line.
+    Each appearance adds `value` to the list.
+    """
+    return RepeatedOption(
+        names,
+        help=help,
+        action="append_const",
+        default=[],
+        const=value,
+        soft_show_default=False,
+    )

paramspecli/md.py

@@ -0,0 +1,75 @@
+import re
+from typing import Iterable
+
+# NOTE: dots are not escaped
+_MD_ESCAPE = re.compile("[" + re.escape(r"\`*_{}[]<>()#+-!") + "]")
+
+
+class Md(str):
+    __slots__ = ()
+
+    def plain(self) -> str:
+        return self.replace("\\", "")
+
+
+class Renderer:
+    """Default markdown renderer"""
+
+    def p(self, text: str) -> str:
+        return text + "\n\n"
+
+    def h(self, level: int, text: str) -> str:
+        return f"{'#' * level} {text}\n\n"
+
+    def br(self) -> str:
+        return "<br />\n"
+
+    def b(self, text: str) -> str:
+        return f"**{text}**"
+
+    def i(self, text: str) -> str:
+        return f"*{text}*"
+
+    def blockquote(self, text: str) -> str:
+        return "\n".join([f"> {line}" for line in text.splitlines()]) + "\n\n"
+
+    def ul(self, lis: Iterable[str]) -> str:
+        elts: list[str] = []
+        for li in lis:
+            lines = li.splitlines()
+            if lines:
+                elts.append(f"- {lines[0]}")
+                elts.extend(f"    {line}" for line in lines[1:])
+        return "\n".join(elts) + "\n\n"
+
+    def dl(self, dtdds: Iterable[tuple[str, str]]) -> str:
+        return self.ul(self.p(dt) + self.p(dd) for dt, dd in dtdds)
+
+    def code(self, text: str) -> str:
+        return f"`{text}`"
+
+    def codeblock(self, text: str, lang: str | None = None) -> str:
+        return f"```{lang or ''}\n{text}\n```\n\n"
+
+    def strike(self, text: str) -> str:
+        return f"~~~{text}~~~"
+
+    def hr(self) -> str:
+        return "---\n\n"
+
+    def link(self, url: str, *, text: str | None) -> str:
+        if text:
+            return f"[{text}]({url})"
+        return f"({url})"
+
+    def e(self, text: str) -> str:
+        return _MD_ESCAPE.sub(r"\\\g<0>", text)
+
+    def body(self, text: str) -> str:
+        return text
+
+    # It's easier to post-process markdown than account for extra newlines while generating
+    def postprocess(self, text: str) -> str:
+        out = "\n".join(line.rstrip() for line in text.splitlines())
+        out = re.sub(r"\n{3,}", "\n\n", out)
+        return out

paramspecli/opts.py

@@ -0,0 +1,324 @@
+from types import EllipsisType
+from typing import Any, Iterable, Literal, overload
+
+from .apstub import TypeConverter
+from .fake import Option, RepeatedOption
+
+
+##
+@overload
+def option(
+    *names: str,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[str] | None = None,
+    metavar: str | None = None,
+    show_default: bool | str | None = None,
+) -> Option[str, None]: ...
+
+
+## default: D
+@overload
+def option[D](
+    *names: str,
+    default: D,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[str] | None = None,
+    metavar: str | None = None,
+    show_default: bool | str | None = None,
+) -> Option[str, D]: ...
+
+
+## nargs
+@overload
+def option(
+    *names: str,
+    nargs: int | Literal["+", "*"],
+    help: str | Literal[False] | None = None,
+    choices: Iterable[str] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[list[str], None]: ...
+
+
+## optional
+@overload
+def option(
+    *names: str,
+    nargs: Literal["?"],
+    help: str | Literal[False] | None = None,
+    choices: Iterable[str] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[str | EllipsisType, None]: ...
+
+
+## nargs, default: D
+@overload
+def option[D](
+    *names: str,
+    nargs: int | Literal["+", "*"],
+    default: D,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[str] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[list[str], D]: ...
+
+
+## optional, default: D
+@overload
+def option[D](
+    *names: str,
+    nargs: Literal["?"],
+    default: D,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[str] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[str | EllipsisType, D]: ...
+
+
+## type: T
+@overload
+def option[T](
+    *names: str,
+    type: TypeConverter[T],
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+    metavar: str | None = None,
+    show_default: bool | str | None = None,
+) -> Option[T, None]: ...
+
+
+## type: T, default: str | D
+# default is parsed if str, otherwise left as is
+@overload
+def option[T, D](
+    *names: str,
+    type: TypeConverter[T],
+    default: str | D,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+    metavar: str | None = None,
+    show_default: bool | str | None = None,
+) -> Option[T, T | D]: ...
+
+
+## type: T, nargs
+@overload
+def option[T](
+    *names: str,
+    type: TypeConverter[T],
+    nargs: int | Literal["+", "*"],
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[list[T], None]: ...
+
+
+## type: T, optional
+@overload
+def option[T](
+    *names: str,
+    type: TypeConverter[T],
+    nargs: Literal["?"],
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[T | EllipsisType, None]: ...
+
+
+## type: T, default: str, nargs
+# yes, this one is strange. default is parsed by T, but list is not formed
+@overload
+def option[T](
+    *names: str,
+    type: TypeConverter[T],
+    nargs: int | Literal["+", "*"],
+    default: str,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[list[T], T]: ...
+
+
+## type: T, default: str, optional
+@overload
+def option[T](
+    *names: str,
+    type: TypeConverter[T],
+    nargs: Literal["?"],
+    default: str,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[T | EllipsisType, T]: ...
+
+
+## type: T, default: D, nargs
+@overload
+def option[T, D](
+    *names: str,
+    type: TypeConverter[T],
+    nargs: int | Literal["+", "*"],
+    default: D,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[list[T], D]: ...
+
+
+## type: T, default: D, optional
+@overload
+def option[T, D](
+    *names: str,
+    type: TypeConverter[T],
+    nargs: Literal["?"],
+    default: D,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[T | EllipsisType, D]: ...
+
+
+def option(
+    *names: str,
+    type: TypeConverter[Any] | None = None,
+    default: Any = None,
+    nargs: int | Literal["+", "*", "?"] | None = None,
+    help: str | bool | None = None,
+    choices: Iterable[Any] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+    show_default: bool | str | None = None,
+) -> Option[Any, Any]:
+    """Just an option"""
+    return Option(
+        names,
+        help=help,
+        type=type,
+        nargs=nargs,
+        default=default,
+        const=... if nargs == "?" else None,
+        choices=choices,
+        metavar=metavar if metavar is not None else names[0].lstrip("-").upper(),
+        action="store",
+        #
+        hard_show_default=show_default,
+        soft_show_default=default is not None,
+    )
+
+
+##
+@overload
+def repeated_option(
+    *names: str,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[str] | None = None,
+    metavar: str | None = None,
+) -> RepeatedOption[str]: ...
+
+
+## nargs
+@overload
+def repeated_option(
+    *names: str,
+    nargs: int | Literal["+", "*"],
+    flatten: Literal[False] = False,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[str] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+) -> RepeatedOption[list[str]]: ...
+
+
+## nargs, flatten
+@overload
+def repeated_option(
+    *names: str,
+    nargs: int | Literal["+", "*"],
+    flatten: Literal[True],
+    help: str | Literal[False] | None = None,
+    choices: Iterable[str] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+) -> RepeatedOption[str]: ...
+
+
+## type: T
+@overload
+def repeated_option[T](
+    *names: str,
+    type: TypeConverter[T],
+    flatten: Literal[False] = False,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+    metavar: str | None = None,
+) -> RepeatedOption[T]: ...
+
+
+## type: T, flatten
+# gotcha: type converter should return iterable so it could extend running list
+@overload
+def repeated_option[T](
+    *names: str,
+    type: TypeConverter[Iterable[T]],
+    flatten: Literal[True],
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+    metavar: str | None = None,
+) -> RepeatedOption[T]: ...
+
+
+## type: T, nargs
+@overload
+def repeated_option[T](
+    *names: str,
+    type: TypeConverter[T],
+    nargs: int | Literal["+", "*"],
+    flatten: Literal[False] = False,
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+) -> RepeatedOption[list[T]]: ...
+
+
+## type: T, nargs, flatten
+@overload
+def repeated_option[T](
+    *names: str,
+    type: TypeConverter[T],
+    nargs: int | Literal["+", "*"],
+    flatten: Literal[True],
+    help: str | Literal[False] | None = None,
+    choices: Iterable[T] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+) -> RepeatedOption[T]: ...
+
+
+def repeated_option(
+    *names: str,
+    type: TypeConverter[Any] | None = None,
+    nargs: int | Literal["+", "*"] | None = None,
+    flatten: bool = False,
+    help: str | bool | None = None,
+    choices: Iterable[Any] | None = None,
+    metavar: str | tuple[str, ...] | None = None,
+) -> RepeatedOption[Any]:
+    """Option which could present multiple times on a command line.
+    Result is collected into the list"""
+    return RepeatedOption(
+        names,
+        help=help,
+        type=type,
+        nargs=nargs,
+        choices=choices,
+        metavar=metavar if metavar is not None else names[0].lstrip("-").upper(),
+        action="extend" if flatten else "append",
+        default=[],
+        #
+        soft_show_default=False,
+    )

paramspecli/util.py

@@ -0,0 +1,50 @@
+import sys
+from argparse import ArgumentTypeError
+from functools import wraps
+from typing import Callable, NoReturn, TextIO
+
+from .apstub import TypeConverter
+
+
+def echo(*strings: str, nl: bool = True, stream: TextIO | None = None) -> None:
+    """Should be used instead of the print() to make intention clear"""
+    out = stream or sys.stdout
+    for s in strings:
+        out.write(s)
+        if nl:
+            out.write("\n")
+    out.flush()
+
+
+def exit(status: int = 0, message: str | tuple[str, ...] | None = None) -> NoReturn:
+    """Print error message and exit"""
+    if message:
+        if isinstance(message, str):
+            message = (message,)
+        echo(*message, stream=sys.stderr)
+    sys.exit(status)
+
+
+def catch_all[T](f: TypeConverter[T]) -> TypeConverter[T]:
+    """Catch type converter exceptions and present them as the cli errors"""
+
+    @wraps(f)
+    def catcher(s: str) -> T:
+        try:
+            return f(s)
+        except ArgumentTypeError as e:
+            raise e
+        except Exception as e:
+            raise ArgumentTypeError(str(e)) from e
+
+    return catcher
+
+
+def resolve_later[**P](resolve: Callable[[], Callable[P, None]]) -> Callable[P, None]:
+    """Allows the handler to be resolved at the call time"""
+
+    @wraps(resolve)
+    def wrap(*args: P.args, **kwargs: P.kwargs) -> None:
+        resolve()(*args, **kwargs)
+
+    return wrap