gitbolt 0.0.0.dev1__py3-none-any.whl

gitbolt/git_subprocess/runner/simple_impl.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+A simple and straight-forward git command subprocess runner implementation.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from subprocess import CompletedProcess
+from typing import overload, override, Any, Literal
+
+from gitbolt.git_subprocess.constants import GIT_CMD
+from gitbolt.git_subprocess.exceptions import GitCmdException
+from gitbolt.git_subprocess.runner import GitCommandRunner
+
+
+class SimpleGitCR(GitCommandRunner):
+    """
+    Simple git command runner that simply runs everything `as-is` in a subprocess.
+    """
+
+    @overload
+    @override
+    def run_git_command(
+        self,
+        main_cmd_args: list[str],
+        subcommand_args: list[str],
+        *subprocess_run_args: Any,
+        _input: str,
+        text: Literal[True],
+        **subprocess_run_kwargs: Any,
+    ) -> CompletedProcess[str]: ...
+
+    @overload
+    @override
+    def run_git_command(
+        self,
+        main_cmd_args: list[str],
+        subcommand_args: list[str],
+        *subprocess_run_args: Any,
+        _input: bytes,
+        text: Literal[False],
+        **subprocess_run_kwargs: Any,
+    ) -> CompletedProcess[bytes]: ...
+
+    @overload
+    @override
+    def run_git_command(
+        self,
+        main_cmd_args: list[str],
+        subcommand_args: list[str],
+        *subprocess_run_args: Any,
+        text: Literal[True],
+        **subprocess_run_kwargs: Any,
+    ) -> CompletedProcess[str]: ...
+
+    @overload
+    @override
+    def run_git_command(
+        self,
+        main_cmd_args: list[str],
+        subcommand_args: list[str],
+        *subprocess_run_args: Any,
+        text: Literal[False] = ...,
+        **subprocess_run_kwargs: Any,
+    ) -> CompletedProcess[bytes]: ...
+
+    @override
+    def run_git_command(
+        self,
+        main_cmd_args: list[str],
+        subcommand_args: list[str],
+        *subprocess_run_args: Any,
+        _input: str | bytes | None = None,
+        text: Literal[True, False] = False,
+        **subprocess_run_kwargs: Any,
+    ) -> CompletedProcess[str] | CompletedProcess[bytes]:
+        try:
+            return subprocess.run(
+                [GIT_CMD, *main_cmd_args, *subcommand_args],
+                *subprocess_run_args,
+                input=_input,
+                text=text,
+                **subprocess_run_kwargs,
+            )
+        except subprocess.CalledProcessError as e:
+            raise GitCmdException(called_process_error=e, exit_code=e.returncode) from e

gitbolt/git_subprocess/utils.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Utility functions related to processors specific to git commands using subprocess.
+"""
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from vt.utils.commons.commons.core_py import is_unset, not_none_not_unset, Unset
+
+
+def git_main_cmd_repeating_flag_args(
+    val: Sequence[Path] | Unset | None, cmd_flag: str
+) -> list[str]:
+    """
+    Returns a flattened list of repeating flags and values.
+
+    Used for flags like `-C` which may be repeated with multiple values.
+
+    Args:
+        val: A list of values to apply with the flag.
+        cmd_flag: The flag to apply to each value.
+
+    Returns:
+        A flattened list like ['-C', 'repo1', '-C', 'repo2']
+
+    Examples:
+        >>> git_main_cmd_repeating_flag_args([Path("repo1"), Path("repo2")], "-C")
+        ['-C', 'repo1', '-C', 'repo2']
+
+        >>> git_main_cmd_repeating_flag_args([], "-C")
+        []
+
+        >>> from vt.utils.commons.commons.core_py import UNSET
+        >>> git_main_cmd_repeating_flag_args([Path("repo1"), UNSET, Path("repo2")], "-C")
+        ['-C', 'repo1', '-C', 'repo2']
+
+        >>> git_main_cmd_repeating_flag_args(None, "-C")
+        []
+
+        >>> git_main_cmd_repeating_flag_args(UNSET, "-C")
+        []
+    """
+    if not_none_not_unset(val):
+        return [
+            item
+            for entry in val
+            if not is_unset(entry)
+            for item in [cmd_flag, str(entry)]
+        ]
+    return []
+
+
+def git_main_cmd_dict_flag_args(
+    val: dict[str, str | bool | None | Unset] | None | Unset, cmd_flag: str
+) -> list[str]:
+    """
+    Converts a dictionary into flag pairs used by commands like `-c key=value`.
+
+    - `True` or `None` => `-c key`
+    - `False` => `-c key=`
+    - `UNSET` keys are skipped
+
+    Args:
+        val: Dictionary of key-value pairs.
+        cmd_flag: The flag to apply.
+
+    Returns:
+        A list of CLI arguments.
+
+    Examples:
+        >>> git_main_cmd_dict_flag_args({"foo.bar": "baz"}, "-c")
+        ['-c', 'foo.bar=baz']
+
+        >>> git_main_cmd_dict_flag_args({"foo.bar": ""}, "-c")
+        ['-c', 'foo.bar=']
+
+        >>> git_main_cmd_dict_flag_args({"foo.bar": True}, "-c")
+        ['-c', 'foo.bar']
+
+        >>> git_main_cmd_dict_flag_args({"foo.bar": False}, "-c")
+        ['-c', 'foo.bar=']
+
+        >>> git_main_cmd_dict_flag_args({"foo.bar": None}, "-c")
+        ['-c', 'foo.bar']
+
+        >>> from vt.utils.commons.commons.core_py import UNSET
+        >>> git_main_cmd_dict_flag_args({"foo.bar": UNSET}, "-c")
+        []
+
+        >>> git_main_cmd_dict_flag_args({
+        ...     "a.b": "x", "c.d": "", "e.f": True, "g.h": False, "i.j": None
+        ... }, "-c")
+        ['-c', 'a.b=x', '-c', 'c.d=', '-c', 'e.f', '-c', 'g.h=', '-c', 'i.j']
+
+        >>> git_main_cmd_dict_flag_args(None, "-c")
+        []
+
+        >>> git_main_cmd_dict_flag_args(UNSET, "-c")
+        []
+
+        >>> git_main_cmd_dict_flag_args({}, "-c")
+        []
+    """
+    if not_none_not_unset(val):
+        args = []
+        for k, v in val.items():
+            if is_unset(v):
+                continue
+            if v is True or v is None:
+                args += [cmd_flag, k]
+            elif v is False:
+                args += [cmd_flag, f"{k}="]
+            else:
+                args += [cmd_flag, f"{k}={v}"]
+        return args
+    return []
+
+
+def git_main_cmd_simple_flag_args(val: bool | Unset | None, cmd_flag: str) -> list[str]:
+    """
+    Returns a single flag if the value is set and truthy.
+
+    Args:
+        val: A boolean-like value.
+        cmd_flag: The flag to apply.
+
+    Returns:
+        A list with just the flag, or empty.
+
+    Examples:
+        >>> git_main_cmd_simple_flag_args(True, "--no-pager")
+        ['--no-pager']
+
+        >>> git_main_cmd_simple_flag_args(False, "--no-pager")
+        []
+
+        >>> git_main_cmd_simple_flag_args(None, "--no-pager")
+        []
+
+        >>> from vt.utils.commons.commons.core_py import UNSET
+        >>> git_main_cmd_simple_flag_args(UNSET, "--no-pager")
+        []
+    """
+    if not_none_not_unset(val):
+        return [cmd_flag] if val else []
+    else:
+        return []
+
+
+def git_main_cmd_pair_flag_args(val: Any, cmd_flag: str) -> list[str]:
+    """
+    Returns a flag and value pair, or nothing if not set.
+
+    Args:
+        val: The value to attach to the flag.
+        cmd_flag: The flag name.
+
+    Returns:
+        A list like ['--exec-path', 'tmp'] or []
+
+    Examples:
+        >>> git_main_cmd_pair_flag_args("foo", "--namespace")
+        ['--namespace', 'foo']
+
+        >>> git_main_cmd_pair_flag_args(Path("repo"), "--namespace")
+        ['--namespace', 'repo']
+
+        >>> git_main_cmd_pair_flag_args(None, "--namespace")
+        []
+
+        >>> from vt.utils.commons.commons.core_py import UNSET
+        >>> git_main_cmd_pair_flag_args(UNSET, "--namespace")
+        []
+    """
+    return [cmd_flag, str(val)] if not_none_not_unset(val) else []

gitbolt/ls_tree.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Helper interfaces specific to ``git ls-tree`` subcommand.
+"""
+
+from abc import abstractmethod
+from typing import Protocol, Unpack, override, Literal
+
+from vt.utils.errors.error_specs import ERR_INVALID_USAGE
+from vt.utils.errors.error_specs.utils import require_type, require_iterable
+
+from gitbolt.exceptions import GitExitingException
+from gitbolt.models import GitLsTreeOpts
+
+
+class LsTreeArgsValidator(Protocol):
+    """
+    The argument validator for ``git ls-tree`` subcommand.
+    """
+
+    @abstractmethod
+    def validate(self, tree_ish: str, **ls_tree_opts: Unpack[GitLsTreeOpts]) -> None:
+        """
+        Validate arguments passed to the ls-tree() method.
+
+        :param tree_ish: A tree-ish identifier (commit SHA, branch name, etc.).
+        :param ls_tree_opts: Keyword arguments mapping to supported options for ``git ls-tree``.
+        """
+        ...
+
+
+class UtilLsTreeArgsValidator(LsTreeArgsValidator):
+    """
+    Independent utility function sort of interface to perform ``ls_tree()`` arguments validation.
+    """
+
+    @override
+    def validate(self, tree_ish: str, **ls_tree_opts: Unpack[GitLsTreeOpts]) -> None:
+        """
+        Validate the inputs provided to the ``git ls-tree`` command.
+
+        This utility ensures type safety and logical correctness of arguments
+        passed to the ``git ls-tree`` subcommand.
+
+        This includes:
+        * Enforcing that ``tree_ish`` is a string.
+        * Checking that each supported boolean flag (like ``d``, ``r``, ``z``, etc.)
+          is a valid boolean if provided.
+        * Validating that ``abbrev`` is an integer between 0 and 40 (inclusive).
+        * Ensuring ``format_`` is a string if specified.
+        * Checking that ``path`` is a list of strings if specified.
+
+        All validations will raise a ``GitExitingException`` with a specific
+        exit code depending on the nature of the failure:
+
+        * ``TypeError`` leads to ``ERR_DATA_FORMAT_ERR``.
+        * ``ValueError`` leads to ``ERR_INVALID_USAGE``.
+
+        See: `git ls-tree documentation <https://git-scm.com/docs/git-ls-tree>`_.
+
+        :param tree_ish: A valid Git tree-ish identifier (e.g., branch name, commit hash).
+        :param ls_tree_opts: Keyword arguments that map to valid ls-tree options.
+        :raises GitExitingException: When validation fails.
+
+        Examples::
+
+            >>> UtilLsTreeArgsValidator().validate("HEAD", d=True, abbrev=10)
+            >>> UtilLsTreeArgsValidator().validate("abc123", format_="%(objectname)", path=["src/", "README.md"])
+            >>> UtilLsTreeArgsValidator().validate("main", name_only=False, z=True)
+
+
+        Invalid Examples (will raise GitExitingException), printing these just for doctesting::
+
+            >>> UtilLsTreeArgsValidator().validate(42) # type: ignore[arg-type] # tree_ish expects str and int is provided
+            Traceback (most recent call last):
+            gitbolt.exceptions.GitExitingException: TypeError: 'tree_ish' must be a string
+
+            >>> UtilLsTreeArgsValidator().validate("HEAD", abbrev="abc") # type: ignore[arg-type] # abbrev expects int and str is provided
+            Traceback (most recent call last):
+            gitbolt.exceptions.GitExitingException: TypeError: 'abbrev' must be an int
+
+            >>> UtilLsTreeArgsValidator().validate("HEAD", abbrev=True) # type: ignore[arg-type] # abbrev expects int and bool is provided
+            Traceback (most recent call last):
+            gitbolt.exceptions.GitExitingException: TypeError: 'abbrev' must be an int
+
+            >>> UtilLsTreeArgsValidator().validate("HEAD", abbrev=100)
+            Traceback (most recent call last):
+            gitbolt.exceptions.GitExitingException: ValueError: abbrev must be between 0 and 40.
+
+            >>> UtilLsTreeArgsValidator().validate("HEAD",
+            ...                       path="src/")  # type: ignore[arg-type] as path expects list[str] and str is provided.
+            Traceback (most recent call last):
+            gitbolt.exceptions.GitExitingException: TypeError: 'path' must be a non-str iterable
+
+            >>> UtilLsTreeArgsValidator().validate("HEAD",
+            ...                       path=1)  # type: ignore[arg-type] as path expects list[str] and str is provided.
+            Traceback (most recent call last):
+            gitbolt.exceptions.GitExitingException: TypeError: 'path' must be a non-str iterable
+
+            >>> UtilLsTreeArgsValidator().validate("HEAD",
+            ...                         z="yes")  # type: ignore[arg-type] as z expects bool and str is provided.
+            Traceback (most recent call last):
+            gitbolt.exceptions.GitExitingException: TypeError: 'z' must be a boolean
+        """
+        require_type(tree_ish, "tree_ish", str, GitExitingException)
+
+        bool_keys: list[
+            Literal[
+                "d",
+                "r",
+                "t",
+                "long",
+                "z",
+                "name_only",
+                "object_only",
+                "full_name",
+                "full_tree",
+                "name_status",
+            ]
+        ] = [
+            "d",
+            "r",
+            "t",
+            "long",
+            "z",
+            "name_only",
+            "object_only",
+            "full_name",
+            "full_tree",
+            "name_status",
+        ]
+
+        for key in bool_keys:
+            if key in ls_tree_opts:
+                the_key = ls_tree_opts[key]
+                require_type(the_key, key, bool, GitExitingException)
+
+        if "abbrev" in ls_tree_opts:
+            abbrev = ls_tree_opts["abbrev"]
+            require_type(abbrev, "abbrev", int, GitExitingException)
+            if not (0 <= abbrev <= 40):
+                errmsg = "abbrev must be between 0 and 40."
+                raise GitExitingException(
+                    errmsg, exit_code=ERR_INVALID_USAGE
+                ) from ValueError(errmsg)
+
+        if "format_" in ls_tree_opts:
+            format_ = ls_tree_opts["format_"]
+            require_type(format_, "format_", str, GitExitingException)
+
+        if "path" in ls_tree_opts:
+            path = ls_tree_opts["path"]
+            require_iterable(path, "path", str, list, GitExitingException)