ybox 0.9.8__py3-none-any.whl

ybox/pkg/list.py

@@ -0,0 +1,191 @@
+"""
+List packages or package files on an active ybox container.
+"""
+
+import argparse
+import re
+import sys
+from configparser import SectionProxy
+from typing import Callable
+
+from ybox.cmd import PkgMgr, page_command
+from ybox.config import Consts, StaticConfiguration
+from ybox.print import fgcolor as fg
+from ybox.print import print_warn
+from ybox.state import RuntimeConfiguration, YboxStateManagement
+from ybox.util import FormatTable
+
+
+def list_packages(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
+                  conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
+                  state: YboxStateManagement) -> int:
+    """
+    List packages installed in a container including those not managed by `ybox-pkg`, if required.
+    Some package details can also be listed like the version and whether a package has been
+    installed as a dependency or is a top-level package.
+
+    When multiple containers share the same root directory, then listing all packages will include
+    those installed from other containers, if any.
+
+    :param args: arguments having all attributes passed by the user
+    :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
+    :param docker_cmd: the podman/docker executable to use
+    :param conf: the :class:`StaticConfiguration` for the container
+    :param runtime_conf: the `RuntimeConfiguration` of the container
+    :param state: instance of `YboxStateManagement` having the state of all ybox containers
+    :return: integer exit status of list packages command where 0 represents success
+    """
+    plain_sep: str = args.plain_separator
+    separator = plain_sep or Consts.default_field_separator()
+    if args.os_pkgs:
+        # package list and details will all be fetched using distribution's package manager
+        if args.verbose:
+            list_cmd = pkgmgr[PkgMgr.LIST_ALL_LONG.value] if args.all else pkgmgr[
+                PkgMgr.LIST_LONG.value]
+        else:
+            list_cmd = pkgmgr[PkgMgr.LIST_ALL.value] if args.all else pkgmgr[PkgMgr.LIST.value]
+        list_cmd = list_cmd.format(packages="", separator=separator)
+        if shared_containers := state.get_other_shared_containers(conf.box_name,
+                                                                  runtime_conf.shared_root):
+            print_warn("Package listing will include packages from other containers sharing the "
+                       f"same root directory: {', '.join(shared_containers)}", file=sys.stderr)
+    else:
+        # package list will be fetched from the state database while the details, if required,
+        # will be fetched using the distribution's package manager
+        dependency_type = ".*" if args.all else ""
+        packages = " ".join(state.get_packages(conf.box_name, dependency_type=dependency_type))
+        if not packages:
+            return 0
+        # TODO: optional dependencies from state database should also be shown since those
+        # can be different from the package manager
+        list_cmd = pkgmgr[PkgMgr.LIST_ALL_LONG.value] if args.verbose else pkgmgr[
+            PkgMgr.LIST_ALL.value]
+        list_cmd = list_cmd.format(packages=packages, separator=separator)
+
+    docker_args = [docker_cmd, "exec"]
+    if sys.stdout.isatty():  # don't act as a terminal if it is being redirected
+        docker_args.append("-it")
+    docker_args.extend([conf.box_name, "/bin/bash", "-c", list_cmd])
+    # empty pager argument is a valid one and indicates no pagination, hence the `is None` check
+    pager: str = (args.pager or "") if args.pager is not None or plain_sep else conf.pager
+    headers = ["Name", "Version", "Dependency Of (req,opt)",
+               "Description"] if args.verbose else ["Name", "Version"]
+    transform = None if plain_sep else _build_table_transform(args, separator, headers)
+    header = plain_sep.join(headers) + "\n" if plain_sep else ""
+    return page_command(docker_args, pager, "listing packages", transform, header)
+
+
+def _build_table_transform(args: argparse.Namespace, separator: str,
+                           headers: list[str]) -> Callable[[str], str]:
+    """
+    Return a transformation function that takes the output of the underlying package manager
+    (invoked using podman/docker exec) and returns a string of table format layout appropriate
+    for display on a terminal.
+
+    :param args: the parsed arguments passed to the invoking script
+    :param separator: the separator used between the fields
+    :param headers: list of header strings to use for the columns
+    :return: a transformation function that takes input string having the output from package
+             manager and returns a string where the fields are formatted as a table appropriate
+             for display in a terminal
+    """
+    def as_table(s: str) -> str:
+        """
+        Format output from the package manager having <name> and <version> fields as a table
+        string for display in a terminal.
+        """
+        table = (line.split(separator, maxsplit=1) for line in s.splitlines())
+        colors = (fg.lightgray, fg.orange)
+        # outline formats like 'rounded_outline' would be preferable, but unfortunately they
+        # are broken for multiline values, hence using the relatively better looking format
+        # from the non-broken ones
+        return FormatTable(table, headers, colors, "psql", (1.0, 1.0)).show()
+
+    def as_long_table(s: str) -> str:
+        """
+        Format output from the package manager having <name>, <version>, <dependency of>
+        and <description> fields as a table string for display in a terminal.
+        """
+        dep_of_idx = 2
+        # add color to "Dependency Of" header to indicate the color scheme used in values
+        headers[dep_of_idx] = f"Dependency Of ({fg.purple}req {fg.cyan}opt{fg.reset})"
+        colors = (fg.lightgray, fg.orange, fg.reset, fg.blue)
+        table_fmt = FormatTable((), headers, colors, "rounded_grid", (2.0, 2.0, 3.0, 3.0))
+        # build the table data which uses the "Dependency Of" column width to decide on how
+        # to truncate the various "req" and "opt" dependency lists
+        table_fmt.table = (_format_long_line(line, separator, table_fmt.max_col_widths[dep_of_idx],
+                                             args.no_trunc) for line in s.splitlines())
+        return table_fmt.show()
+
+    return as_long_table if args.verbose else as_table
+
+
+# regex that matches the values in the "Dependency Of" column
+_DEP_OF_RE = re.compile(r"(req\((?P<req>[^)]+)\))?,?(opt\((?P<opt>.+)\))?")
+
+
+def _format_long_line(line: str, separator: str, dep_of_width: int,
+                      no_trunc: bool) -> tuple[str, str, str, str]:
+    """
+    Format the `Dependency Of` column to include the required and optional dependencies while the
+    other three fields are returned as is after extraction from the given `line`.
+
+    :param line: a line of output from the package manager which is expected to be of the form:
+                 <name>{separator}<version>{separator}<dependency of>{separator}<description>
+    :param separator: the separator used between the fields
+    :param dep_of_width: the final calculated display width of the "Dependency Of" column
+    :param no_trunc: if True then do not truncate the 'Dependency Of' column value
+    :return: tuple of formatted (<name>, <version>, <dependency of>, <description>) fields
+    """
+    name, version, dep_of, description = line.split(separator, maxsplit=3)
+    # replace literal "\n" with newline
+    description = description.replace(r"\n", "\n")
+    if dep_of and (dep_of_match := _DEP_OF_RE.fullmatch(dep_of)):
+        dep_of_dict = dep_of_match.groupdict()
+        req_by = dep_of_dict.get("req") or ""
+        opt_for = dep_of_dict.get("opt") or ""
+        # description is not trimmed and is shown multi-line, so use its size as an upper limit
+        if not no_trunc and len(dep_of) > (max_width := max(dep_of_width, len(description))):
+            trim_factor = (len(dep_of) - max_width) / float(len(req_by) + len(opt_for))
+            if req_by:
+                trim_size = int(trim_factor * len(req_by) + 0.5)  # floor to nearest int
+                req_by = req_by[:max(0, len(req_by) - trim_size - 3)] + "..."
+            if opt_for:
+                trim_size = int(trim_factor * len(opt_for) + 0.5)  # floor to nearest int
+                opt_for = opt_for[:max(0, len(opt_for) - trim_size - 3)] + "..."
+        dep_of_parts: list[str] = []
+        if req_by:
+            dep_of_parts.extend((fg.purple, "req(", req_by, ")", fg.reset))
+        if opt_for:
+            if req_by:
+                dep_of_parts.append(" ")
+            dep_of_parts.extend((fg.cyan, "opt(", opt_for, ")", fg.reset))
+        return name, version, "".join(dep_of_parts), description
+    return name, version, dep_of, description
+
+
+# noinspection PyUnusedLocal
+def list_files(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
+               conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
+               state: YboxStateManagement) -> int:
+    # pylint: disable=unused-argument
+    """
+    List the files of a package installed in a container including those not managed by `ybox-pkg`.
+
+    :param args: arguments having `package` and all other attributes passed by the user
+    :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
+    :param docker_cmd: the podman/docker executable to use
+    :param conf: the :class:`StaticConfiguration` for the container
+    :param runtime_conf: the `RuntimeConfiguration` of the container
+    :param state: instance of `YboxStateManagement` having the state of all ybox containers
+    :return: integer exit status of list package files command where 0 represents success
+    """
+    package: str = args.package
+    list_cmd = pkgmgr[PkgMgr.LIST_FILES.value]
+    docker_args = [docker_cmd, "exec"]
+    if sys.stdout.isatty():  # don't act as a terminal if it is being redirected
+        docker_args.append("-it")
+    docker_args.extend([conf.box_name, "/bin/bash", "-c", list_cmd.format(package=package)])
+    # empty pager argument is a valid one and indicates no pagination, hence the `is None` check
+    pager: str = args.pager if args.pager is not None else conf.pager
+    return page_command(docker_args, pager, error_msg=f"listing files of '{package}'")

ybox/pkg/mark.py

@@ -0,0 +1,68 @@
+"""
+Mark a package as a dependency or as explicitly installed.
+"""
+
+import argparse
+from configparser import SectionProxy
+
+from ybox.cmd import PkgMgr, build_shell_command, run_command
+from ybox.config import StaticConfiguration
+from ybox.print import print_error, print_info
+from ybox.state import (CopyType, DependencyType, RuntimeConfiguration,
+                        YboxStateManagement)
+from ybox.util import check_package
+
+
+def mark_package(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
+                 conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
+                 state: YboxStateManagement) -> int:
+    """
+    Mark a package as a dependency of another package or an explicitly installed one.
+
+    :param args: arguments having `package` and all other attributes passed by the user
+    :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
+    :param docker_cmd: the podman/docker executable to use
+    :param conf: the :class:`StaticConfiguration` for the container
+    :param runtime_conf: the `RuntimeConfiguration` of the container
+    :param state: instance of `YboxStateManagement` having the state of all ybox containers
+    :return: integer exit status of mark package command where 0 represents success
+    """
+    mark_explicit: bool = args.explicit
+    mark_dependency_of: str = args.dependency_of or ""
+    if not mark_explicit ^ bool(mark_dependency_of):
+        print_error("ybox-pkg mark: exactly one of -e or -D option must be specified "
+                    f"(explicit={mark_explicit}, dependency-of={mark_dependency_of})")
+        return 1
+    # check that the package(s) are installed and replace with actual installed name
+    check_cmd = pkgmgr[PkgMgr.CHECK_INSTALL.value]
+    all_packages = [str(args.package)]
+    if mark_dependency_of:
+        all_packages.insert(0, mark_dependency_of)  # keep the non-dependent package at the front
+    for idx, package in enumerate(all_packages):
+        code, inst_pkgs = check_package(docker_cmd, check_cmd, package, conf.box_name)
+        if code != 0:
+            print_error(f"Package '{package}' is not installed in container '{conf.box_name}'")
+            return 1
+        all_packages[idx] = inst_pkgs[0]
+    # make entries in the state database if the packages are not present
+    package = all_packages[0]
+    state.register_package(conf.box_name, package, [], CopyType(0), {},
+                           runtime_conf.shared_root, None, "", skip_if_exists=True)
+    if mark_dependency_of:
+        # currently "optional" is the only supported dependency type
+        print_info(f"Marking '{all_packages[1]}' as an optional dependency of '{package}'")
+        state.register_package(conf.box_name, all_packages[1], [], CopyType(0), {},
+                               runtime_conf.shared_root, dep_type=DependencyType.OPTIONAL,
+                               dep_of=package, skip_if_exists=True)
+        # the package may or may not be a dependency in the underlying packaging, so don't mark
+        # at the package manager level which may cause the package to be orphaned and auto-removed
+    else:
+        print_info(f"Marking '{package}' as explicitly installed")
+        # remove any dependency entries for this package to mark it as explicitly installed
+        state.unregister_dependency(conf.box_name, "%", package)
+        # also mark as explicitly installed using the underlying package manager
+        mark_cmd = pkgmgr[PkgMgr.MARK_EXPLICIT.value]
+        return int(run_command(build_shell_command(
+            docker_cmd, conf.box_name, mark_cmd.format(package=package)), exit_on_error=False,
+            error_msg=f"marking '{package}' as explicitly installed"))
+    return 0

ybox/pkg/repair.py

@@ -0,0 +1,150 @@
+"""
+Try to repair packages and state after a failed package operation or an interrupt/kill.
+"""
+
+import argparse
+import subprocess
+import time
+from configparser import SectionProxy
+
+from ybox.cmd import (PkgMgr, build_shell_command, check_active_ybox,
+                      run_command)
+from ybox.config import StaticConfiguration
+from ybox.print import (fgcolor, print_color, print_error, print_info,
+                        print_warn)
+from ybox.state import RuntimeConfiguration, YboxStateManagement
+
+
+def repair_package_state(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
+                         conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
+                         state: YboxStateManagement) -> int:
+    """
+    Try to repair packages and state after a failed package operation or an interrupt/kill
+    or dangling package manager processes and/or locks.
+
+    :param args: arguments having all attributes passed by the user
+    :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
+    :param docker_cmd: the podman/docker executable to use
+    :param conf: the :class:`StaticConfiguration` for the container
+    :param runtime_conf: the `RuntimeConfiguration` of the container
+    :param state: instance of `YboxStateManagement` having the state of all ybox containers
+    :return: integer exit status of repair command where 0 represents success
+    """
+    quiet: bool = args.quiet
+    quiet_flag = pkgmgr[PkgMgr.QUIET_FLAG.value] if quiet else ""
+    # find all the containers sharing the same shared root
+    if runtime_conf.shared_root:
+        containers = [c for c in state.get_containers(shared_root=runtime_conf.shared_root)
+                      if check_active_ybox(docker_cmd, c)]
+    else:
+        containers = [conf.box_name]
+    # first check for active package operations across all containers on the same shared root
+    # and kill them
+    if not _kill_processes(pkgmgr, docker_cmd, containers, quiet):
+        return 1
+    # remove any package manager related dangling locks
+    _remove_locks(pkgmgr, docker_cmd, containers, quiet)
+
+    # run package manager to repair any failed package operations
+    repair_cmd = pkgmgr[PkgMgr.REPAIR.value]
+    if args.extensive:
+        resp = "y" if quiet else input("Repair thoroughly by reinstalling packages? (y/N) ")
+        if resp.strip().lower() == "y":
+            repair_cmd = pkgmgr[PkgMgr.REPAIR_ALL.value]
+    if (code := int(run_command(build_shell_command(
+            docker_cmd, conf.box_name, repair_cmd.format(quiet=quiet_flag)), exit_on_error=False,
+            error_msg="repairing packages"))) != 0:
+        return code
+
+    # finally restart containers after user confirmation
+    resp = "y" if quiet else input(f"Restart container(s) {containers}? (y/N) ")
+    if resp.strip().lower() == "y":
+        for container in containers:
+            print_color(f"Restarting ybox container '{container}'", fg=fgcolor.cyan)
+            if run_command([docker_cmd, "container", "stop", container],
+                           exit_on_error=False, error_msg="container stop") == 0:
+                time.sleep(2)
+                run_command([docker_cmd, "container", "start", container],
+                            exit_on_error=False, error_msg="container start")
+    return 0
+
+
+def _kill_processes(pkgmgr: SectionProxy, docker_cmd: str, containers: list[str],
+                    quiet: bool) -> bool:
+    """
+    Kill any package manager related processes after user confirmation (if required).
+
+    :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
+    :param docker_cmd: the podman/docker executable to use
+    :param containers: list of affected containers having the same shared root
+    :param quiet: if True then skip user confirmation before removing any lock files
+    :return: true for success, else false in case of failure to kill one or more processes
+    """
+    processes_pattern = pkgmgr[PkgMgr.PROCESSES_PATTERN.value]
+    for container in containers:
+        print_info(
+            f"Checking for active package manager related processes in container '{container}'")
+        ps_result = run_command([docker_cmd, "exec", container, "/usr/bin/pgrep", "-fa",
+                                 processes_pattern], capture_output=True, exit_on_error=False,
+                                error_msg="SKIP")
+        if isinstance(ps_result, int) or not (processes := ps_result.splitlines()):
+            continue
+        # confirm with user before killing those processes
+        print_color("Following active package manager related processes were found in "
+                    f"container '{container}':", fgcolor.cyan)
+        for process in processes:
+            pid, _, cmd = process.partition(" ")
+            print(f"    [PID={pid}] {cmd}")
+        resp = "y" if quiet else input("Kill the above processes? (y/N/space separated PIDs) ")
+        resp = resp.strip().lower()
+        if (not resp) or resp == "n":
+            continue
+        if resp == "y":
+            pids = [process.partition(" ")[0] for process in processes]
+        else:
+            pids = resp.split()
+        for sig in ("-INT", "-TERM", "-KILL"):
+            print_warn(f"Sending {sig} signal to {' '.join(pids)} in container '{container}'")
+            docker_args = [docker_cmd, "exec", container, "/usr/bin/sudo", "/bin/kill", sig]
+            docker_args.extend(pids)
+            subprocess.run(docker_args, check=False, stderr=subprocess.DEVNULL)
+            time.sleep(2)
+            # filter out only the processes that are still active
+            check_res = run_command([docker_cmd, "exec", "/usr/bin/ps", "-o", "pid=", "-p",
+                                     ",".join(pids)], capture_output=True, exit_on_error=False,
+                                    error_msg="SKIP")
+            if isinstance(check_res, int) or not (pids := check_res.split()):
+                break
+        if pids:
+            print_error(f"Unable to kill {' '.join(pids)} in container '{container}'. You may "
+                        "need to manually check inside with 'ybox-cmd' or restart the container")
+            return False
+    return True
+
+
+def _remove_locks(pkgmgr: SectionProxy, docker_cmd: str, containers: list[str],
+                  quiet: bool) -> None:
+    """
+    Remove any package manager related lock files after user confirmation (if required).
+
+    :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
+    :param docker_cmd: the podman/docker executable to use
+    :param containers: list of affected containers having the same shared root
+    :param quiet: if True then skip user confirmation before removing any lock files
+    """
+    locks_pattern = pkgmgr[PkgMgr.LOCKS_PATTERN.value]
+    ls_cmd = f"/bin/ls {locks_pattern.replace(',', ' ')} 2>/dev/null"
+    for container in containers:
+        print_info(f"Checking for lock files in container '{container}'")
+        ls_result = subprocess.run(build_shell_command(docker_cmd, container, ls_cmd),
+                                   check=False, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
+        # confirm with user before removing locks
+        if not (locks := ls_result.stdout.decode("utf-8").split()):
+            continue
+        print_color(f"Found existing lock file(s) {locks} in container '{container}'",
+                    fgcolor.cyan)
+        resp = "y" if quiet else input("Remove the above lock file(s)? (y/N) ")
+        if resp.strip().lower() == "y":
+            docker_args = [docker_cmd, "exec", container, "/usr/bin/sudo", "/bin/rm"]
+            docker_args.extend(locks)
+            run_command(docker_args, exit_on_error=False, error_msg="removing lock files")

ybox/pkg/repo.py

@@ -0,0 +1,251 @@
+"""
+Methods for repository management including adding, removing and listing repositories.
+"""
+
+import argparse
+import re
+import subprocess
+import sys
+from configparser import SectionProxy
+from typing import Iterable, Sequence
+
+from ybox.cmd import (PkgMgr, RepoCmd, build_shell_command, page_output,
+                      run_command)
+from ybox.config import Consts, StaticConfiguration
+from ybox.print import fgcolor as fg
+from ybox.print import print_error, print_info, print_warn
+from ybox.state import RuntimeConfiguration, YboxStateManagement
+from ybox.util import FormatTable
+
+
+def repo_add(args: argparse.Namespace, pkgmgr: SectionProxy, repo: SectionProxy,
+             docker_cmd: str, conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
+             state: YboxStateManagement) -> int:
+    """
+    Add a new named repository given server URL(s) and optionally a verification key
+    (usually a GPG/PGP key) to the underlying distribution's package manager.
+    This method will also update the package metadata cache to reflect the change.
+
+    :param args: arguments having `name`, `urls` and all other attributes passed by the user
+    :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
+    :param repo: the `[repo]` section from `distro.ini` configuration file of the distribution
+    :param docker_cmd: the podman/docker executable to use
+    :param conf: the :class:`StaticConfiguration` for the container
+    :param runtime_conf: the `RuntimeConfiguration` of the container
+    :param state: instance of `YboxStateManagement` having the state of all ybox containers
+    :return: integer exit status of repo-add command where 0 represents success
+    """
+    name: str = args.name
+    urls = ",".join(args.urls)
+    # register_repository expects a valid string hence replace with empty string if `None`
+    key: str = args.key or ""
+    options: str = args.options or ""
+    with_source_repo: bool = args.add_source_repo
+    # register in the state database to check if there is no existing entry (the changes
+    #   will be rolled back in case of failure later)
+    shared_root = runtime_conf.shared_root
+    container_or_shared_root = shared_root or conf.box_name
+    if not state.register_repository(name, container_or_shared_root, urls, key, options,
+                                     with_source_repo, update=False):
+        shared_root_msg = f" (on shared root {shared_root})" if shared_root else ""
+        print_error(f"Repository with name '{name}' already registered for the container "
+                    f"'{conf.box_name}'{shared_root_msg}")
+        return 1
+
+    exists_cmd = repo[RepoCmd.EXISTS.value].format(name=name)
+    if (code := int(run_command(build_shell_command(docker_cmd, conf.box_name, exists_cmd),
+                    exit_on_error=False, error_msg="SKIP"))) == 0:
+        print_error(f"Repository with name '{name}' already present in the package manager "
+                    f"for the container '{conf.box_name}' [distribution: {conf.distribution}]")
+        return 1
+
+    # first fetch and register the key if specified
+    if key:
+        print_info(f"Fetching and registering key '{key}'")
+        key_server = str(args.key_server or repo.get(RepoCmd.DEFAULT_GPG_KEY_SERVER.value,
+                                                     fallback=Consts.default_key_server()))
+        if re.match(r"^\S*?://", key):
+            add_key_cmd = repo[RepoCmd.ADD_KEY.value].format(url=key, name=name)
+            print_info(f"Registering key from URL '{key}'")
+            with subprocess.Popen(build_shell_command(docker_cmd, conf.box_name, add_key_cmd),
+                                  stdout=subprocess.PIPE) as key_result:
+                # fetch the key ID from the output to register it
+                keyid_tag = "KEYID="
+                assert key_result.stdout is not None
+                while line := key_result.stdout.readline():
+                    key_out = line.decode("utf-8").strip()
+                    if key_out.startswith(keyid_tag):
+                        if (keyid := key_out[len(keyid_tag):]) != key:
+                            key = keyid
+                            print_info(f"Registered key '{key}'")
+                            state.register_repository(name, container_or_shared_root, urls, key,
+                                                      options, with_source_repo, update=True)
+                    else:
+                        sys.stdout.buffer.write(line)
+                        sys.stdout.flush()
+                if (code := key_result.wait(60)) != 0:
+                    print_error(f"FAILED to register key '{key}' for repository '{name}' -- "
+                                "see the output above for details.")
+                    return code
+        else:
+            add_key_cmd = repo[RepoCmd.ADD_KEY_ID.value].format(key=key, server=key_server,
+                                                                name=name)
+            print_info(f"Registering key '{key}'")
+            if (code := int(run_command(build_shell_command(
+                    docker_cmd, conf.box_name, add_key_cmd), exit_on_error=False,
+                    error_msg="registering repository key"))) != 0:
+                return code
+
+    # in case of failures, unregister key and/or repository at the end
+    add_cmd = repo[RepoCmd.ADD.value].format(name=name, urls=urls, options=options)
+    success = False
+    repo_added = False
+    src_added = False
+    try:
+        # next add the repository
+        print_info(f"Registering repository '{name}'")
+        if (code := int(run_command(build_shell_command(docker_cmd, conf.box_name, add_cmd),
+                                    exit_on_error=False, error_msg="adding repository"))) != 0:
+            return code
+        repo_added = True
+        # add the source code repository if specified
+        if with_source_repo and (add_src_cmd := repo.get(RepoCmd.ADD_SOURCE.value, fallback="")):
+            print_info(f"Registering source code repository '{name}'")
+            add_src_cmd = add_src_cmd.format(name=name, urls=urls, options=options)
+            if (code := int(run_command(build_shell_command(
+                    docker_cmd, conf.box_name, add_src_cmd), exit_on_error=False,
+                    error_msg="adding source repository"))) != 0:
+                return code
+            src_added = True
+
+        # finally update the package metadata for the change in repositories
+        code = _refresh_package_metadata(pkgmgr, docker_cmd, conf)
+        success = code == 0
+        return code
+    finally:
+        # remove the added key and/or repository in case of failure
+        if not success:
+            if repo_added:
+                print_info(f"Trying to unregister failed repository '{name}'")
+                remove_cmd = repo[RepoCmd.REMOVE.value].format(name=name, remove_source=src_added)
+                run_command(build_shell_command(docker_cmd, conf.box_name, remove_cmd),
+                            exit_on_error=False, error_msg=f"unregistering repository '{name}'")
+            if key:
+                print_info(f"Trying to unregister key for failed repository '{name}'")
+                remove_key_cmd = repo[RepoCmd.REMOVE_KEY.value].format(key=key, name=name)
+                run_command(build_shell_command(docker_cmd, conf.box_name, remove_key_cmd),
+                            exit_on_error=False, error_msg=f"unregistering key '{key}'")
+
+
+def repo_remove(args: argparse.Namespace, pkgmgr: SectionProxy, repo: SectionProxy,
+                docker_cmd: str, conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
+                state: YboxStateManagement) -> int:
+    """
+    Remove an existing named repository from the underlying distribution's package manager.
+    This method will also update the package metadata cache to reflect the change.
+
+    :param args: arguments having `name` and all other attributes passed by the user
+    :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
+    :param repo: the `[repo]` section from `distro.ini` configuration file of the distribution
+    :param docker_cmd: the podman/docker executable to use
+    :param conf: the :class:`StaticConfiguration` for the container
+    :param runtime_conf: the `RuntimeConfiguration` of the container
+    :param state: instance of `YboxStateManagement` having the state of all ybox containers
+    :return: integer exit status of repo-remove command where 0 represents success
+    """
+    # unregister from the state database to check if there is no existing entry (the changes
+    #   will be rolled back in case of failure later)
+    name: str = args.name
+    shared_root = runtime_conf.shared_root
+    container_or_shared_root = shared_root or conf.box_name
+    if not (result := state.unregister_repository(name, container_or_shared_root)):
+        shared_root_msg = f" (on shared root {shared_root})" if shared_root else ""
+        print_error(f"No such repository with name '{name}' registered for the container "
+                    f"'{conf.box_name}'{shared_root_msg}")
+        return 1
+    key, with_source_repo = result
+    # first unregister the repository key, if any
+    if key:
+        print_info(f"Unregistering repository key '{key}'")
+        remove_key_cmd = repo[RepoCmd.REMOVE_KEY.value].format(key=key, name=name)
+        if (code := int(run_command(build_shell_command(
+                docker_cmd, conf.box_name, remove_key_cmd), exit_on_error=False,
+                error_msg=f"unregistering key '{key}'"))) != 0 and not args.force:
+            return code
+    # next remove the repository
+    print_info(f"Unregistering repository '{name}'")
+    remove_cmd = repo[RepoCmd.REMOVE.value].format(name=name, remove_source=with_source_repo)
+    if (code := int(run_command(build_shell_command(
+            docker_cmd, conf.box_name, remove_cmd), exit_on_error=False,
+            error_msg=f"unregistering repository '{name}'"))) != 0 and not args.force:
+        return code
+    # finally update package metadata
+    code = _refresh_package_metadata(pkgmgr, docker_cmd, conf)
+    return 0 if args.force else code
+
+
+def _refresh_package_metadata(pkgmgr: SectionProxy, docker_cmd: str,
+                              conf: StaticConfiguration) -> int:
+    """
+    Refresh package metadata cache to reflect the change in the registered repositories.
+
+    :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
+    :param docker_cmd: the podman/docker executable to use
+    :param conf: the :class:`StaticConfiguration` for the container
+    :return: integer exit status of package refresh command where 0 represents success
+    """
+    print_info("Refreshing package metadata")
+    update_meta_cmd = pkgmgr[PkgMgr.UPDATE_META.value]
+    return int(run_command(build_shell_command(docker_cmd, conf.box_name, update_meta_cmd),
+                           exit_on_error=False, error_msg="updating package metadata"))
+
+
+# noinspection PyUnusedLocal
+def repo_list(args: argparse.Namespace, pkgmgr: SectionProxy, repo: SectionProxy,
+              docker_cmd: str, conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
+              state: YboxStateManagement) -> int:
+    # pylint: disable=unused-argument
+    """
+    List the repositories registered using :func:`repo-add`.
+
+    :param args: arguments having all attributes passed by the user
+    :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
+    :param repo: the `[repo]` section from `distro.ini` configuration file of the distribution
+    :param docker_cmd: the podman/docker executable to use
+    :param conf: the :class:`StaticConfiguration` for the container
+    :param runtime_conf: the `RuntimeConfiguration` of the container
+    :param state: instance of `YboxStateManagement` having the state of all ybox containers
+    :return: integer exit status of repo-list command where 0 represents success
+    """
+    separator: str = args.plain_separator or ""
+
+    def plain_output(tbl: Iterable[Iterable[str]], hdr: Sequence[str]) -> str:
+        return "\n".join((separator.join(hdr), *(separator.join(line) for line in tbl)))
+
+    repos = state.get_repositories(runtime_conf.shared_root or conf.box_name)
+    if not repos:
+        print_warn(f"No external repositories have been registered in container '{conf.box_name}'")
+        return 1
+    fg_name = fg.lightgray
+    fg_urls = fg.orange
+    if args.verbose:
+        table = ((name, urls, key, options, "true" if with_source_repo else "false")
+                 for name, urls, key, options, with_source_repo in repos)
+        headers = ("Name", "Servers", "Key", "Options", "Source")
+        if separator:
+            out = plain_output(table, headers)
+        else:
+            # using ratio of 4:16:11:6:3 (out of 40) for the widths of the five columns
+            out = FormatTable(table, headers, (fg_name, fg_urls, fg.cyan, fg.green, fg.blue),
+                              "rounded_grid", (4.0, 16.0, 11.0, 6.0, 3.0)).show()
+    else:
+        table = ((name, urls) for name, urls, _, _, _ in repos)
+        headers = ("Name", "Servers")
+        if separator:
+            out = plain_output(table, headers)
+        else:
+            out = FormatTable(table, headers, (fg_name, fg_urls),
+                              "rounded_grid", (2.0, 8.0)).show()
+    # empty pager argument is a valid one and indicates no pagination, hence the `is None` check
+    pager: str = (args.pager or "") if args.pager is not None or separator else conf.pager
+    return page_output((out.encode("utf-8"),), pager)