Add commands module to run external commands

repo_management/commands.py:
Add `run_command()` which allows for running an external command with
the help of subprocess-tee.
Add the private method `_print_env()` which is used to print the
optional environment variables given to `run_command()`.

tests/test_commands.py:
Add tests for `_print_env()` and `run_command()`.

repo_management/commands.py

+from pathlib import Path
+from subprocess import PIPE, STDOUT, CalledProcessError
+from typing import Dict, List, Optional, Union
+
+from subprocess_tee import CompletedProcess, run
+
+
+def _print_env(env: Optional[Dict[str, str]]) -> None:
+    """Print the environment variables from a dict
+
+    Parameters
+    ----------
+    env: Optional[Dict[str, str]]
+        An optional dict with environment variables and their values
+    """
+
+    if env:
+        for (key, value) in sorted(env.items()):
+            print(f"{key}: {value}")
+
+
+def run_command(
+    cmd: Union[str, List[str]],
+    env: Optional[Dict[str, str]] = None,
+    debug: bool = False,
+    echo: bool = False,
+    quiet: bool = False,
+    check: bool = False,
+    cwd: Union[Optional[str], Optional[Path]] = None,
+) -> CompletedProcess:
+    """Run a command
+
+    Parameters
+    ----------
+    cmd: Union[str, List[str]]
+        A string or list of strings that will be passed to subprocess.run()
+    env: Optional[Dict[str, str]]
+        A dict of environment variables and their respective values (defaults to None)
+    debug: bool
+        Whether to run in debug mode, which prints environment variables and command output (defaults to False)
+    echo: bool
+        Whether to print the command before running it (defaults to False)
+    quiet: bool
+        Whether to print the output of command while running it (defaults to False)
+    check: bool
+        Whether to check the return code of the command, which implies raising CallecProcessError (defaults to False)
+    cwd: Union[Optional[str], Optional[Path]]
+        In which directory to run the command (defaults to None, which means current working directory)
+
+    Raises
+    ------
+    CalledProcessError
+        If check is True and the commands return code is not 0
+
+    Returns
+    -------
+    CompletedProcess
+        The result of the command
+    """
+
+    if debug:
+        _print_env(env)
+
+    result = run(
+        cmd,
+        env=env,
+        stdout=PIPE,
+        stderr=STDOUT,
+        echo=echo or debug,
+        quiet=quiet,
+        cwd=cwd,
+    )
+    if result.returncode != 0 and check:
+        raise CalledProcessError(
+            returncode=result.returncode,
+            cmd=result.args,
+            output=result.stdout,
+            stderr=result.stderr,
+        )
+    return result

tests/test_commands.py

+from contextlib import nullcontext as does_not_raise
+from pathlib import Path
+from subprocess import CalledProcessError
+from typing import ContextManager, Dict, List, Optional, Union
+
+from pytest import mark, raises
+
+from repo_management import commands
+
+
+@mark.parametrize("env", [(None), ({"FOO": "BAR"})])
+def test__print_env(env: Optional[Dict[str, str]]) -> None:
+    commands._print_env(env)
+
+
+@mark.parametrize(
+    "cmd, env, debug, echo, quiet, check, cwd, expectation",
+    [
+        (["ls", "-lah"], {"FOO": "BAR"}, False, False, False, False, None, does_not_raise()),
+        (["ls", "-lah"], {"FOO": "BAR"}, True, False, False, False, None, does_not_raise()),
+        (["cd", "-f"], {"FOO": "BAR"}, True, False, False, True, None, raises(CalledProcessError)),
+    ],
+)
+def test_run_command(
+    cmd: Union[str, List[str]],
+    env: Optional[Dict[str, str]],
+    debug: bool,
+    echo: bool,
+    quiet: bool,
+    check: bool,
+    cwd: Union[Optional[str], Optional[Path]],
+    expectation: ContextManager[str],
+) -> None:
+    with expectation:
+        commands.run_command(cmd=cmd, env=env, debug=debug, echo=echo, quiet=quiet, check=check, cwd=cwd)