freyacli 0.1.0__py3-none-any.whl

freyacli/__init__.py

@@ -0,0 +1,18 @@
+from ._misc.freya_syntax_error import FreyaSyntaxError
+from ._misc.arg_dtype_error import ArgDTypeError
+from ._misc.help_str import HelpStr
+
+from ._utils.color import Color
+from ._utils.path_assertion import PathAssertion
+
+from ._arguments.arg_count import ArgCount
+from ._arguments.arg_dtype import ArgDType
+from ._arguments.argument_rule import ArgumentRule
+from ._arguments.subcommand import Subcommand
+
+from ._parsers.freya_parser import FreyaParser
+from ._parsers.args_parser import ArgsParser
+
+from ._core.app import App
+
+WIDTH_TERMINAL: int = 1 # automatically set to the current terminal width when App is initialized

freyacli/_arguments/arg_count.py

@@ -0,0 +1,118 @@
+import freyacli as fy
+
+# //////////////////////////////////////////////////////////////////////////////
+class ArgCount:
+    """
+    `FYR` syntax follows a similarity to regex conventions for specifying amount of expected arguments.
+
+    - `n` -> exactly n
+        - `min_nvalues = n`, `val_optional = False`, `unlimited = False`
+        - `FYR` example: `~sphere[s,sphere]4.FLOAT`
+            - this means that `-s` must be passed with exactly `4` float values.
+        - Automatic help string:
+            - n = 1: `<value>`
+            - n > 1: `<value(n)>`
+
+    - `n?` -> 0 or n
+        - `min_nvalues = n`, `val_optional = True`, `unlimited = False`
+        - `FYR` example: `~out_mrc[m,mrc]1?.PATH`
+            - this means `-m` can be passed with exactly `1` value or without a value.
+        - Automatic help string:
+            - n = 1: `[<value>]`
+            - n > 1: `[<value(n)>]`
+
+    - `*` -> 0 or more
+        - `min_nvalues = 0`, `val_optional = True`, `unlimited = True`
+        - `FYR` example: `~configs[c,config]*.STR`
+            - this means that `-c` can be passed with or without values. Amount of values is arbitrary.
+        - Automatic help string: `[<value...>]`
+
+    - `n+` -> n or more
+        - `min_nvalues = n`, `val_optional = False`, `unlimited = True`
+        - `FYR` example: `~resids[i,resids]1+.STR`
+            - this means that `-i` must be passed with *at least* `1` value.
+        - Automatic help string:
+            - n = 1: `<value...>`
+            - n > 1: `<value(n)[...]>`
+    """
+
+    # --------------------------------------------------------------------------
+    def __init__(self, min_nvalues: int = 0, val_optional: bool = False, unlimited: bool = False):
+        self.min_nvalues  = min_nvalues  # 0 for *, n otherwise
+        self.val_optional = val_optional # True for n? and *, False for n and n+
+        self.unlimited    = unlimited    # True for * and n+, False for n and n?
+
+
+    # --------------------------------------------------------------------------
+    @classmethod
+    def from_str(cls, string: str) -> "ArgCount":
+        def _safe_substr(s: str) -> str:
+            substr = s[:-1]
+            if not substr: raise fy.FreyaSyntaxError(
+                f"Invalid argument count specification: '{s}'."+\
+                "Expected format examples: '3', '3?', '*', '3+'."+\
+                "Number is mandatory for all formats except '*', which always means '0 or more'."
+            )
+            return substr
+
+        def _safe_int(s: str) -> int:
+            try: return int(s)
+            except ValueError: raise fy.FreyaSyntaxError(
+                f"Invalid number in argument count specification: '{s}'."+\
+                "Expected format examples: '3', '3?', '*', '3+'."+\
+                "Number is mandatory for all formats except '*', which always means '0 or more'."
+            )
+
+        if string.endswith("?"): return cls(
+            min_nvalues = _safe_int(_safe_substr(string)),
+            unlimited = False,
+            val_optional = True
+        )
+        if string.endswith("*"): return cls(
+            min_nvalues = 0,
+            unlimited = True,
+            val_optional = True
+        )
+        if string.endswith("+"): return cls(
+            min_nvalues = _safe_int(_safe_substr(string)),
+            unlimited = True,
+            val_optional = False
+        )
+        return cls(
+            min_nvalues = _safe_int(string),
+            unlimited = False,
+            val_optional = False
+        )
+
+
+    # --------------------------------------------------------------------------
+    def get_help_str(self, buffer: str) -> str:
+        if self.val_optional:
+            if self.unlimited: return f"[<{buffer}...>]"     # * case
+            if self.min_nvalues == 1: return f"[<{buffer}>]" # n? case with n=1
+            return f"[<{buffer}({self.min_nvalues})>]"       # n? case with n>1
+
+        if self.unlimited:
+            if self.min_nvalues == 1: return f"<{buffer}...>" # n+ case with n=1
+            return f"<{buffer}({self.min_nvalues})[...]>"     # n+ case with n>1
+
+        if self.min_nvalues == 1: return f"<{buffer}>" # n case with n=1
+        return f"<{buffer}({self.min_nvalues})>"       # n case with n>1
+
+
+    # --------------------------------------------------------------------------
+    def is_full(self, nvalues: int) -> bool:
+        """Returns `True` for an argument that shouldn't take more values."""
+        if self.unlimited: return False
+        return nvalues >= self.min_nvalues
+
+
+    # --------------------------------------------------------------------------
+    def has_enough_values(self, nvalues: int) -> bool:
+        """Returns `True` for an argument that has already received enough values."""
+        if self.val_optional: return True
+        if self.unlimited: return nvalues >= self.min_nvalues
+        return nvalues == self.min_nvalues
+
+
+# //////////////////////////////////////////////////////////////////////////////

freyacli/_arguments/arg_dtype.py

@@ -0,0 +1,61 @@
+from enum import Enum, auto
+from pathlib import Path
+
+import freyacli as fy
+
+# //////////////////////////////////////////////////////////////////////////////
+class ArgDType(Enum):
+    NONE   = auto()
+    TOGGLE = auto()
+    STR    = auto()
+    PATH   = auto()
+    INT    = auto()
+    FLOAT  = auto()
+
+    # --------------------------------------------------------------------------
+    @classmethod
+    def from_str(cls, s: str | None) -> "ArgDType":
+        if s is None: return cls.NONE
+        s = s.lower()
+        if not s:        return cls.TOGGLE
+        if s == "str":   return cls.STR
+        if s == "path":  return cls.PATH
+        if s == "float": return cls.FLOAT
+        if s == "int":   return cls.INT
+        raise fy.FreyaSyntaxError(f"Invalid flag type specified: '{s}'")
+
+
+    # --------------------------------------------------------------------------
+    def stores_data(self) -> bool:
+        return self != ArgDType.NONE and self != ArgDType.TOGGLE
+
+    # --------------------------------------------------------------------------
+    def parse_value(self, arg_name: str, raw_value: str) -> fy.ArgDTypeError |\
+        bool|str|Path|int|float:
+
+        if self == ArgDType.NONE:
+            raise fy.FreyaSyntaxError(f"Argument doesn't accept any values, but somehow got '{raw_value}'.")
+
+        if self == ArgDType.TOGGLE:
+            raise fy.FreyaSyntaxError(f"Argument is a flag of type TOGGLE and doesn't accept any values, but somehow got '{raw_value}'.")
+
+        if self == ArgDType.STR:
+            return raw_value.strip('"').strip("'")
+
+        if self == ArgDType.PATH:
+            return Path(raw_value)
+
+        if self == ArgDType.INT:
+            try: return int(raw_value)
+            except ValueError: return fy.ArgDTypeError(
+                f"Argument '{arg_name}' expected an integer value, but got '{raw_value}'."
+            )
+
+        if self == ArgDType.FLOAT:
+            try: return float(raw_value)
+            except ValueError: return fy.ArgDTypeError(
+                f"Argument '{arg_name}' expected a float value, but got '{raw_value}'."
+            )
+
+
+# //////////////////////////////////////////////////////////////////////////////

freyacli/_arguments/argument_rule.py

@@ -0,0 +1,217 @@
+from pathlib import Path
+
+import freyacli as fy
+
+# //////////////////////////////////////////////////////////////////////////////
+class ArgumentRule:
+    _INDENT_LONG_DESC = 8
+
+    # --------------------------------------------------------------------------
+    def __init__(self, raw_rule: str | None):
+        self._raw_rule = raw_rule
+        self.help_str: fy.HelpStr = fy.HelpStr()
+
+        self._raw_user_values: list[str] = [] # raw string values provided by the user
+        self._n_user_values: int = 0 # amount of values provided by the user so far
+        self._was_used: bool = False # True when the flag of this argument was used at least once.
+
+        self.name: str = ""               # name that will be displayed between <> (e.g. "<value>") in the help string, and used to fetch any given values
+        self.is_positional: bool = False  # True when the argument doesn't need a preceding "flag" (e.g. just "<value>" instead of "--flag <value>")
+        self.is_optional: bool = False    # display with surrounding [] in the help string (e.g. "[<value>]")
+        self.flag_short: str = ""         # must be 1 character long. It's always used with a single preceding dash (e.g. "-f")
+        self.flag_long: str = ""          # used with a double preceding dash (e.g. "--flag")
+        self.default_value: str = ""      # when a default value is present, it's placed at the beginning of the respective help string, right after the flag type (e.g. "INT (default: 0)").
+        self.arg_dtype = fy.ArgDType.NONE # placed at the beginning of the help string. TOGGLE type is used for flags with no arguments, and the respective type (e.g. STR, INT) is used for flags with arguments.
+        self.arg_count = fy.ArgCount()    # contains information about the expected number of passed values and whether they are optional.
+
+        if raw_rule is None: return
+
+        self.is_optional = raw_rule.startswith('~')
+
+        (buffer,
+            self.default_value
+        ) = self._parse_default_value(raw_rule)
+
+        (buffer,
+            self.name
+        ) = self._parse_name(buffer)
+
+        (buffer,
+            self.is_positional,
+            self.flag_short,
+            self.flag_long
+        ) = self._parse_flags(buffer)
+
+        (buffer,
+            self.arg_count
+        ) = self._parse_arg_count(buffer)
+
+        self.arg_dtype = fy.ArgDType.from_str(buffer)
+
+
+    # --------------------------------------------------------------------------
+    def register_user_value(self, value: str) -> bool:
+        """Returns `True` when the argument is "full" (i.e. won't accept any more user values)"""
+        self._raw_user_values.append(value)
+        self._n_user_values += 1
+        self.touch()
+        return self.arg_count.is_full(self._n_user_values)
+
+
+    # --------------------------------------------------------------------------
+    def touch(self):
+        """
+        Marks the argument as used even if it doesn't receive any user values.
+        Useful when dealing with flags with optional keyword arguments
+        """
+        self._was_used = True
+
+
+    # --------------------------------------------------------------------------
+    def parse_user_values(self) -> None | fy.ArgDTypeError |\
+        bool|str|Path|int|float |\
+        list[bool]|list[str]|list[Path]|list[int]|list[float]:
+        """
+        Parses the raw user values according to the argument type (e.g. `INT`, `STR`, etc.) and returns the parsed values in the respective types.
+        When the argument accepts only 1 value, the value is returned directly instead of a `list`.
+        A boolean is returned for flags of `TOGGLE` type. Alternatively, `True` can be returned when a flag is passed but its optional keyword argument isn't.
+        An `ArgDTypeError` instance is returned when parsing fails due to invalid user input.
+        `None` is returned for non-used optional arguments, be it positional or non-toggle flags (i.e. those that should receive values).
+        """
+        if self._was_used and not self.arg_count.has_enough_values(self._n_user_values):
+            s = 's' if self.arg_count.min_nvalues > 1 else ''
+            return fy.ArgDTypeError(f"Expected {self.arg_count.min_nvalues} value{s} for argument '{self.name}', but got {len(self._raw_user_values)}.")
+
+        if self.arg_dtype in (fy.ArgDType.INT, fy.ArgDType.FLOAT):
+            ### for numeric types, split the raw user values, just in case they are received as a single space-separated string
+            self._raw_user_values = [
+                v for lst in self._raw_user_values for v in lst.split()
+            ]
+
+        parsed_values = [
+            self.arg_dtype.parse_value(self.name, raw_value)
+            for raw_value in self._raw_user_values
+        ]
+
+        if not parsed_values:
+            if self._was_used: return True # used flag has value of "True"
+            if self.is_positional: return None # unused optional positional argument has value of "None"
+            if self.arg_dtype is fy.ArgDType.TOGGLE: return False # unused toggle flag has value of "False"
+            return None # unused optional flag with arguments has value of "None"
+
+        if self.arg_count.min_nvalues == 1: return parsed_values[0]
+        return parsed_values
+
+
+    # --------------------------------------------------------------------------
+    def get_usage_str_positional(self) -> str:
+        """
+        Usage string is only relevant for positionals.
+        Flag arguments are summarized as [options...] in the usage string.
+        A more detailed description of them is provided in the longer help string.
+        """
+        if not self.is_positional:
+            raise fy.FreyaSyntaxError(f"Usage string can only be generated for positional arguments, but got a flag argument ('{self._raw_rule}').")
+
+        buffer = self.arg_count.get_help_str(self.name)
+        return fy.Color.blue(buffer)
+
+
+    # --------------------------------------------------------------------------
+    def get_help_string_description(self) -> str:
+        preffix = ""
+        if self.is_optional: preffix += "[optional] "
+        if self.arg_dtype.stores_data():
+            preffix += self.arg_dtype.name
+            if self.default_value: preffix += f" (default: {self.default_value})"
+            preffix += ". "
+
+        arg_desc = self._get_arg_description()
+        long_desc = self.help_str.wrapped_text(
+            indent = self._INDENT_LONG_DESC,
+            width = fy.WIDTH_TERMINAL - self._INDENT_LONG_DESC,
+            preffix = fy.Color.yellow(preffix)
+        )
+        return f"{arg_desc}\n{self._INDENT_LONG_DESC*' '}{long_desc}"
+
+
+    # --------------------------------------------------------------------------
+    def _parse_default_value(self, buffer: str) -> tuple[str, str]:
+        idx = buffer.find('=')
+        if idx == -1: return buffer, ''
+        return buffer[:idx], buffer[idx+1:]
+
+
+    # --------------------------------------------------------------------------
+    def _parse_name(self, buffer: str) -> tuple[str, str]:
+        name, buffer = self._safe_split_into_2(buffer, '[')
+        return buffer, name[int(self.is_optional):]
+
+
+    # --------------------------------------------------------------------------
+    def _parse_flags(self, buffer: str) -> tuple[str, bool, str, str]:
+        flags, buffer = self._safe_split_into_2(buffer, ']')
+        if not flags: return buffer, True, '', ''
+
+        flag_short, flag_long = self._safe_split_into_2(flags, ',')
+        if len(flag_short) > 1:
+            raise fy.FreyaSyntaxError(f"Short flags should be 1 character long, but got '{self.flag_short}'.")
+
+        return buffer, False, flag_short, flag_long
+
+
+    # --------------------------------------------------------------------------
+    def _parse_arg_count(self, buffer: str) -> fy.ArgCount:
+        if not buffer:
+            if self.default_value:
+                raise fy.FreyaSyntaxError(f"Flags with no arguments can't have a default value ('{self._raw_rule}')")
+            if self.is_positional:
+                raise fy.FreyaSyntaxError(f"Positional arguments must specify type and number of arguments ('{self._raw_rule}')")
+
+            return "", fy.ArgCount()
+
+        min_nvalues, buffer = self._safe_split_into_2(buffer, '.')
+        arg_count = fy.ArgCount.from_str(min_nvalues)
+        if self.is_positional:
+            ### having a distinction between self.is_optional (e.g. "passing -x" is optional)
+            ### vs arg_count.val_optional (e.g. "passing a value for -x" is optional)
+            ### is only relevant for flags, not for positionals
+            arg_count.val_optional = self.is_optional
+
+        return buffer, arg_count
+
+
+    # --------------------------------------------------------------------------
+    def _safe_split_into_2(self, buffer: str, char_split: str) -> tuple[str, str]:
+        splitted = buffer.split(char_split)
+        if len(splitted) == 2: return splitted
+        raise fy.FreyaSyntaxError(f"Invalid substring found inside argument rule: '{self._raw_rule}'")
+
+
+    # --------------------------------------------------------------------------
+    def _get_arg_description(self) -> str:
+        buffer = self.arg_count.get_help_str(self.name)
+        if self.is_positional: return fy.Color.blue("    " + buffer)
+
+        buffer = f" {buffer}" if self.arg_dtype.stores_data() else ""
+
+        if self.is_optional:
+            str_flags_0 = "["
+            str_flags_1 = "]"
+        else:
+            str_flags_0 = ""
+            str_flags_1 = ""
+
+        flag_short = f"-{self.flag_short}" if self.flag_short else ""
+        flag_long  = f"--{self.flag_long}" if self.flag_long  else ""
+
+        str_flags_0 += (
+            f"{flag_short}, {flag_long}" if self.flag_long else flag_short
+        ) if self.flag_short else flag_long
+
+        buffer = f"    {fy.Color.green(str_flags_0)}{fy.Color.blue(buffer)}"
+        if str_flags_1: buffer += fy.Color.green(str_flags_1)
+        return buffer
+
+
+# //////////////////////////////////////////////////////////////////////////////

freyacli/_arguments/subcommand.py

@@ -0,0 +1,170 @@
+import freyacli as fy
+
+# //////////////////////////////////////////////////////////////////////////////
+class Subcommand:
+    def __init__(self, name: str, parent: "Subcommand|None"):
+        self.name = name
+        self.parent: "Subcommand|None" = parent
+        self.children: dict[str, "Subcommand"] = {}
+        self.depth = 0 if self.is_root() else parent.depth + 1
+        self.help_str: fy.HelpStr = fy.HelpStr()
+
+        self.rules: dict[str, fy.ArgumentRule] = {}
+        self.rules_posit: list[fy.ArgumentRule] = []
+        self.rules_flags: list[fy.ArgumentRule] = []
+
+
+    # --------------------------------------------------------------------------
+    def __repr__(self):
+        values = ','.join('' if v is None else str(v) for v in self.children.values())
+        return f"Subcommand({self.depth}:{self.name}){{{values if values else ''}}}"
+
+
+    # --------------------------------------------------------------------------
+    def __getitem__(self, name: str) -> "Subcommand":
+        return self.get_child(name)
+
+
+    # --------------------------------------------------------------------------
+    def add_child(self, name: str) -> "Subcommand":
+        self._assert_unique_child(name)
+        child = Subcommand(name, self)
+        self.children[name] = child
+        return child
+
+
+    # --------------------------------------------------------------------------
+    def get_child(self, name: str) -> "Subcommand":
+        if name not in self.children:
+            raise fy.FreyaSyntaxError(f"Branch '{name}' is not defined in the CLI rules.")
+        return self.children[name]
+
+
+    # --------------------------------------------------------------------------
+    def add_rule(self, rule: fy.ArgumentRule):
+        if rule.name in self.rules:
+            raise fy.FreyaSyntaxError(f"Duplicate definition of '{rule}'.")
+
+        self.rules[rule.name] = rule
+        lst = self.rules_posit if rule.is_positional else self.rules_flags
+        lst.append(rule)
+
+
+    # --------------------------------------------------------------------------
+    def is_root(self) -> bool: return self.parent is None
+    def is_leaf(self) -> bool: return not self.children
+
+
+    # --------------------------------------------------------------------------
+    def get_args_with_flag(self, flag: str, short_name: bool) -> list[fy.ArgumentRule]:
+        """List of rules returned is ensured to contain between 0 and 1 elements."""
+        matches = list(filter(
+            lambda rule: flag == rule.flag_short if short_name else flag == rule.flag_long,
+            self.rules_flags
+        ))
+        if len(matches) > 1:
+            raise fy.FreyaSyntaxError(f"Multiple rules with the same flag: '{flag}'.")
+        return matches
+
+
+    # --------------------------------------------------------------------------
+    def get_path_to_root(self) -> list[str]:
+        path = []
+        node = self
+        while node:
+            if node.parent is None: break
+            path.append(node.name)
+            node = node.parent
+        return path[::-1]
+
+
+    # --------------------------------------------------------------------------
+    def str_help_long(self, py_name: str) -> str:
+        return '\n'.join((
+            self._get_usage_str(py_name),
+            self.help_str.nl_surround(),
+            self._get_str_leaf_arguments() if self.is_leaf() \
+                else self._get_str_subcommands(),
+        ))
+
+
+    # --------------------------------------------------------------------------
+    def _get_usage_str(self, py_name: str) -> str:
+        path_to_root = [py_name] + self.get_path_to_root()
+        preffix = "    " + ' '.join(path_to_root)
+
+        usage_posits = ' '.join(
+            rule.get_usage_str_positional() for rule in self.rules_posit
+        )
+        if usage_posits: usage_posits += ' '
+
+        if self.is_leaf():
+            ### [NOTE] options isn't currently supported for non-leaf nodes
+            return f"{preffix} {usage_posits}{fy.Color.green('[options...]')}"
+
+        return f"{preffix} {fy.Color.magenta('COMMAND')} ..."
+
+
+    # --------------------------------------------------------------------------
+    def _get_str_subcommands(self) -> str:
+        max_name_len = max(map(len, self.children.keys()))
+        width_name = len(fy.HelpStr.pad_name("", max_name_len))
+        width_desc = max(1, fy.WIDTH_TERMINAL - width_name)
+
+        rows_commands = '\n'.join((
+            fy.Color.magenta(fy.HelpStr.pad_name(name, max_name_len)) +\
+                child.help_str.wrapped_text(width_name, width_desc)
+            for name, child in self.children.items()
+        ))
+
+        return '\n'.join((
+            fy.Color.magenta("commands:", bright = False),
+            "    The following subcommands are available:",
+            "",
+            rows_commands,
+        ))
+
+
+    # --------------------------------------------------------------------------
+    def _get_str_leaf_arguments(self) -> str:
+        return '\n'.join((
+            self._get_str_leaf_posits(),
+            self._get_str_leaf_flags(),
+        ))
+
+
+    # --------------------------------------------------------------------------
+    def _get_str_leaf_posits(self) -> str:
+        if not self.rules_posit: return ""
+
+        rows_posits = '\n'.join((
+            rule.get_help_string_description()
+            for rule in self.rules_posit
+        ))
+        return '\n'.join((
+            fy.Color.blue("positional arguments:", bright = False),
+            rows_posits, "",
+        ))
+
+
+    # --------------------------------------------------------------------------
+    def _get_str_leaf_flags(self) -> str:
+        if not self.rules_flags: return ""
+
+        rows_flags = '\n'.join((
+            rule.get_help_string_description()
+            for rule in self.rules_flags
+        ))
+        return '\n'.join((
+            fy.Color.green("options:", bright = False),
+            rows_flags, "",
+        ))
+
+
+    # --------------------------------------------------------------------------
+    def _assert_unique_child(self, name: str):
+        if name in self.children:
+            raise fy.FreyaSyntaxError(f"Duplicate child branch '{name}' specified inside the same branch.")
+
+
+# //////////////////////////////////////////////////////////////////////////////