ybox 0.9.8__py3-none-any.whl

ybox/pkg/search.py

@@ -0,0 +1,52 @@
+"""
+Methods for searching packages in the repositories matching given search terms.
+"""
+
+import argparse
+import sys
+from configparser import SectionProxy
+
+from ybox.cmd import PkgMgr, page_command
+from ybox.config import StaticConfiguration
+from ybox.state import RuntimeConfiguration, YboxStateManagement
+
+
+# noinspection PyUnusedLocal
+def search_packages(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
+                    conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
+                    state: YboxStateManagement) -> int:
+    # pylint: disable=unused-argument
+    """
+    Uninstall package specified by `args.package` on a ybox container with given podman/docker
+    command. Additional flags honored are `args.quiet` to bypass user confirmation during
+    uninstall, `args.keep_config_files` to keep the system configuration and/or data files
+    of the package, `args.skip_deps` to skip removal of all orphaned dependencies of the package
+    (including required and optional dependencies).
+
+    :param args: arguments having `search` 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 search command where 0 represents success
+    """
+    quiet_flag = pkgmgr[PkgMgr.QUIET_DETAILS_FLAG.value] if args.quiet else ""
+    official = pkgmgr[PkgMgr.SEARCH_OFFICIAL_FLAG.value] if args.official else ""
+    word_start = word_end = ""
+    if args.word:
+        word_start = pkgmgr[PkgMgr.SEARCH_WORD_START_FLAG.value]
+        word_end = pkgmgr[PkgMgr.SEARCH_WORD_END_FLAG.value]
+    search_terms: list[str] = args.search  # there will be at least one search term in the list
+    search = pkgmgr[PkgMgr.SEARCH_ALL.value] if args.all else pkgmgr[PkgMgr.SEARCH.value]
+    # quote the search terms for bash to properly see the full arguments if they contain spaces
+    # or other special characters
+    search_cmd = search.format(quiet=quiet_flag, official=official, word_start=word_start,
+                               word_end=word_end, search="'" + "' '".join(search_terms) + "'")
+    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", search_cmd])
+    # 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="searching repositories")

ybox/pkg/uninst.py

@@ -0,0 +1,92 @@
+"""
+Methods for uninstalling package uninstallation on an active ybox container.
+"""
+
+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, print_notice
+from ybox.state import RuntimeConfiguration, YboxStateManagement
+from ybox.util import check_package, select_item_from_menu
+
+
+def uninstall_package(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
+                      conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
+                      state: YboxStateManagement) -> int:
+    """
+    Uninstall package specified by `args.package` on a ybox container with given podman/docker
+    command. Additional flags honored are `args.quiet` to bypass user confirmation during
+    uninstall, `args.keep_config_files` to keep the system configuration and/or data files
+    of the package, `args.skip_deps` to skip removal of all orphaned dependencies of the package
+    (including required and optional dependencies).
+
+    :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 uninstall command where 0 represents success
+    """
+    package: str = args.package
+    quiet_flag = pkgmgr[PkgMgr.QUIET_FLAG.value] if args.quiet else ""
+    purge_flag = "" if args.keep_config_files else pkgmgr[PkgMgr.PURGE_FLAG.value]
+    remove_deps_flag = "" if args.skip_deps else pkgmgr[PkgMgr.REMOVE_DEPS_FLAG.value]
+    uninstall_cmd = pkgmgr[PkgMgr.UNINSTALL.value].format(
+        quiet=quiet_flag, purge=purge_flag, remove_deps=remove_deps_flag, package="{package}")
+    check_cmd = pkgmgr[PkgMgr.CHECK_INSTALL.value]
+    return _uninstall_package(package, args.skip_deps, uninstall_cmd, check_cmd, docker_cmd, conf,
+                              runtime_conf, state)
+
+
+def _uninstall_package(package: str, skip_deps: bool, uninstall_cmd: str, check_cmd: str,
+                       docker_cmd: str, conf: StaticConfiguration,
+                       runtime_conf: RuntimeConfiguration, state: YboxStateManagement,
+                       dep_msg: str = "") -> int:
+    """
+    Real workhorse of :func:`uninstall_package` that uninstalls given package on a ybox container
+    with given podman/docker command.
+
+    :param package: the package to be uninstalled
+    :param skip_deps: true if orphaned dependencies of the package should not be uninstalled
+    :param uninstall_cmd: fully formed uninstallation command from the distribution's `distro.ini`
+    :param check_cmd: command to check for existence of the package returning the resolved name
+                      as read from distribution's `distro.ini`; this should have {package}
+                      placeholder in the string which will be resolved before execution
+    :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
+    :param dep_msg: if this is invoked for uninstalling a dependency then the string "dependency "
+                    to display in messages, defaults to ""
+    :return: exit code of the underlying package manager command run using podman/docker
+    """
+    installed = False
+    code, inst_packages = check_package(docker_cmd, check_cmd, package, conf.box_name)
+    if code == 0:
+        installed = True
+        if len(inst_packages) > 1:
+            print_notice(f"Multiple packages found for '{package}', select one to uninstall")
+            if selected_pkg := select_item_from_menu(inst_packages):
+                package = selected_pkg
+            else:
+                return 1
+        else:
+            package = inst_packages[0]
+        print_info(f"Uninstalling {dep_msg}'{package}' from '{conf.box_name}'")
+        code = int(run_command(build_shell_command(
+            docker_cmd, conf.box_name, uninstall_cmd.format(package=package)),
+            exit_on_error=False, error_msg=f"uninstalling '{package}'"))
+    elif not dep_msg:  # dependency may have been uninstalled in original package uninstallation
+        print_error(f"Package '{package}' is not installed in container '{conf.box_name}'")
+    # go ahead with removal from local state and wrappers, even if package was not installed
+    if code == 0 or not installed:
+        orphans = state.unregister_package(conf.box_name, package, runtime_conf.shared_root)
+        if not skip_deps and orphans:
+            print_info(f"Uninstalling orphaned dependencies of '{package}' {list(orphans.keys())}")
+            for opt_dep in orphans:
+                _uninstall_package(opt_dep, skip_deps, uninstall_cmd, check_cmd, docker_cmd, conf,
+                                   runtime_conf, state, dep_msg="dependency ")
+    return code

ybox/pkg/update.py

@@ -0,0 +1,56 @@
+"""
+Update some or all packages on an active ybox container.
+"""
+
+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_warn
+from ybox.state import RuntimeConfiguration, YboxStateManagement
+
+# TODO: updating packages can lead to system libraries among others getting updated. At the very
+#       least, the container may need to be restarted thereafter. All other containers on the same
+#       shared root should also be restarted which can be an issue for the user. This is also
+#       a problem when creating a new container on the same shared root since that too does update.
+#       The biggest problem can be that even a new package install can end up updating shared libs.
+
+
+def update_packages(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
+                    conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
+                    state: YboxStateManagement) -> int:
+    """
+    Update the mentioned package installed in a container which can include packages not managed
+    by `ybox-pkg`, as well as those installed by other containers if the container shares the
+    same root directory with other containers.
+
+    When no package name is provided, then the entire installation is updated. Like above, it will
+    end up updating all the containers sharing the same root directory, if any. Note that
+    some rolling distributions like Arch Linux recommend always doing a full installation upgrade
+    rather than individual packages.
+
+    :param args: arguments having `packages` 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 update command where 0 represents success
+    """
+    quiet_flag = pkgmgr[PkgMgr.QUIET_FLAG.value] if args.quiet else ""
+    packages: list[str] = args.packages
+    if packages:
+        update_meta_cmd = pkgmgr[PkgMgr.UPDATE_META.value]
+        update_pkgs_cmd = pkgmgr[PkgMgr.UPDATE.value].format(quiet=quiet_flag,
+                                                             packages=' '.join(packages))
+        update_cmd = f"{{ {update_meta_cmd}; }} && {{ {update_pkgs_cmd}; }}"
+    else:
+        update_cmd = pkgmgr[PkgMgr.UPDATE_ALL.value].format(quiet=quiet_flag)
+    if shared_containers := state.get_other_shared_containers(conf.box_name,
+                                                              runtime_conf.shared_root):
+        # show all the containers sharing the same shared root
+        print_warn("The operation will also update packages in other containers having the same "
+                   f"shared root directory: {', '.join(shared_containers)}")
+    return int(run_command(build_shell_command(docker_cmd, conf.box_name, update_cmd),
+                           exit_on_error=False, error_msg="updating packages"))

ybox/print.py

@@ -0,0 +1,121 @@
+"""
+Utility classes and methods to print in color on terminal/console.
+"""
+
+import os
+import shutil
+import sys
+from dataclasses import dataclass
+from typing import IO, Optional
+
+
+# define color names for printing in terminal
+@dataclass(frozen=True)
+class TermColors:
+    """basic ASCII color strings for terminals"""
+    black: str
+    red: str
+    green: str
+    orange: str
+    blue: str
+    purple: str
+    cyan: str
+    lightgray: str
+    reset: str
+    bold: str
+    disable: str
+
+
+# foreground colors in the terminal
+fgcolor = TermColors(
+    "\033[30m", "\033[31m", "\033[32m", "\033[33m", "\033[34m", "\033[35m", "\033[36m",
+    "\033[37m", "\033[00m", "\033[01m", "\033[02m")
+# background colors in the terminal
+bgcolor = TermColors(
+    "\033[40m", "\033[41m", "\033[42m", "\033[43m", "\033[44m", "\033[45m", "\033[46m",
+    "\033[47m", "\033[00m", "\033[01m", "\033[02m")
+
+
+def get_terminal_width() -> int:
+    """
+    Get the best estimate of the width of the current terminal.
+    This may not work well if the output is piped, for example.
+    """
+    # Use stderr for the terminal width since stdout can be piped to pager.
+    try:
+        return os.get_terminal_size(sys.stderr.fileno()).columns
+    except OSError:
+        return shutil.get_terminal_size().columns
+
+
+def print_color(msg: str, fg: Optional[str] = None,
+                bg: Optional[str] = None, end: str = "\n", file: Optional[IO[str]] = None) -> None:
+    """
+    Display given string to standard output with foreground and background colors, if provided.
+    The colors will show up as expected on most known Linux terminals and console though
+    some colors may look different on different terminal implementation
+    (e.g. orange could be more like yellow).
+
+    :param msg: the string to be displayed
+    :param fg: the foreground color of the string
+    :param bg: the background color of the string
+    :param end: the terminating string which is newline by default (or can be empty for example)
+    :param file: the text-mode file object to use for writing (defaults to `sys.stdout`)
+    """
+    if fg:
+        if bg:
+            full_msg = f"{fg}{bg}{msg}{bgcolor.reset}{fgcolor.reset}"
+        else:
+            full_msg = f"{fg}{msg}{fgcolor.reset}"
+    elif bg:
+        full_msg = f"{bg}{msg}{bgcolor.reset}"
+    else:
+        full_msg = msg
+    # force flush the output if it doesn't end in a newline
+    print(full_msg, end=end, file=file, flush=end != "\n")
+
+
+def print_error(msg: str, end: str = "\n", file: Optional[IO[str]] = None) -> None:
+    """
+    Display an error string in red foreground (and no background change).
+
+    :param msg: the string to be displayed
+    :param end: the terminating string which is newline by default (or can be empty for example)
+    :param file: the text-mode file object to use for writing (defaults to `sys.stderr`)
+    """
+    if not file:
+        file = sys.stderr
+    print_color(msg, fg=fgcolor.red, end=end, file=file)
+
+
+def print_warn(msg: str, end: str = "\n", file: Optional[IO[str]] = None):
+    """
+    Display a warning string in purple foreground (and no background change).
+
+    :param msg: the string to be displayed
+    :param end: the terminating string which is newline by default (or can be empty for example)
+    :param file: the text-mode file object to use for writing (defaults to `sys.stdout`)
+    """
+    print_color(msg, fg=fgcolor.purple, end=end, file=file)
+
+
+def print_notice(msg: str, end: str = "\n", file: Optional[IO[str]] = None):
+    """
+    Display a string in orange foreground (and no background change).
+
+    :param msg: the string to be displayed
+    :param end: the terminating string which is newline by default (or can be empty for example)
+    :param file: the text-mode file object to use for writing (defaults to `sys.stdout`)
+    """
+    print_color(msg, fg=fgcolor.orange, end=end, file=file)
+
+
+def print_info(msg: str, end: str = "\n", file: Optional[IO[str]] = None):
+    """
+    Display an informational string in blue foreground (and no background change).
+
+    :param msg: the string to be displayed
+    :param end: the terminating string which is newline by default (or can be empty for example)
+    :param file: the text-mode file object to use for writing (defaults to `sys.stdout`)
+    """
+    print_color(msg, fg=fgcolor.blue, end=end, file=file)

ybox/run/cmd.py

@@ -0,0 +1,54 @@
+"""
+Code for the `ybox-cmd` script that is used to execute programs in an active ybox container.
+"""
+
+import argparse
+import sys
+
+from ybox.cmd import run_command
+from ybox.env import get_docker_command
+
+
+def main() -> None:
+    """main function for `ybox-cmd` script"""
+    main_argv(sys.argv[1:])
+
+
+def main_argv(argv: list[str]) -> None:
+    """
+    Main entrypoint of `ybox-cmd` that takes a list of arguments which are usually the
+    command-line arguments of the `main()` function. Pass ["-h"]/["--help"] to see all the
+    available arguments with help message for each.
+
+    :param argv: arguments to the function (main function passes `sys.argv[1:]`)
+    """
+    args = parse_args(argv)
+    docker_cmd = get_docker_command()
+    container_name = args.container_name
+
+    docker_args = [docker_cmd, "exec"]
+    if not args.skip_terminal:
+        docker_args.append("-it")
+    docker_args.append(container_name)
+    if isinstance(args.command, str):
+        docker_args.append(args.command)
+    else:
+        docker_args.extend(args.command)
+    run_command(docker_args, error_msg=f"{args.command} execution on '{container_name}'")
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    """
+    Parse command-line arguments for the program and return the result :class:`argparse.Namespace`.
+
+    :param argv: the list of arguments to be parsed
+    :return: the result of parsing using the `argparse` library as a :class:`argparse.Namespace`
+    """
+    parser = argparse.ArgumentParser(description="Run a command on an active ybox container")
+    parser.add_argument("-s", "--skip-terminal", action="store_true",
+                        help="skip interactive pseudo-terminal for the command "
+                             "(i.e. skip -it options to podman/docker)")
+    parser.add_argument("container_name", type=str, help="name of the active ybox")
+    parser.add_argument("command", nargs="*", default="/bin/bash",
+                        help="run the given command (default is /bin/bash)")
+    return parser.parse_args(argv)

ybox/run/control.py

@@ -0,0 +1,102 @@
+"""
+Code for the `ybox-control` script that is used to start/stop/restart a ybox container.
+"""
+
+import argparse
+import sys
+import time
+
+from ybox.cmd import check_active_ybox, get_ybox_state, run_command
+from ybox.config import StaticConfiguration
+from ybox.env import Environ, get_docker_command
+from ybox.print import fgcolor, print_color, print_error
+from ybox.util import wait_for_ybox_container
+
+
+def main() -> None:
+    """main function for `ybox-control` script"""
+    main_argv(sys.argv[1:])
+
+
+def start_container(docker_cmd: str, container_name: str):
+    """
+    Start an existing ybox container.
+
+    :param docker_cmd: the podman/docker executable to use
+    :param container_name: name of the container
+    """
+    if status := get_ybox_state(docker_cmd, container_name, (), exit_on_error=False):
+        if status[0] == "running":
+            print_color(f"Ybox container '{container_name}' already active", fg=fgcolor.cyan)
+        else:
+            print_color(f"Starting ybox container '{container_name}'", fg=fgcolor.cyan)
+            run_command([docker_cmd, "container", "start", container_name],
+                        error_msg="container start")
+            conf = StaticConfiguration(Environ(docker_cmd), status[1], container_name)
+            wait_for_ybox_container(docker_cmd, conf)
+    else:
+        print_error(f"No ybox container '{container_name}' found")
+        sys.exit(1)
+
+
+def stop_container(docker_cmd: str, container_name: str, fail_on_error: bool):
+    """
+    Stop a ybox container.
+
+    :param docker_cmd: the podman/docker executable to use
+    :param container_name: name of the container
+    :param fail_on_error: if True then show error message on failure to stop else ignore
+    """
+    if check_active_ybox(docker_cmd, container_name):
+        print_color(f"Stopping ybox container '{container_name}'", fg=fgcolor.cyan)
+        run_command([docker_cmd, "container", "stop", container_name], error_msg="container stop")
+        for _ in range(120):
+            time.sleep(0.5)
+            if get_ybox_state(docker_cmd, container_name, ("exited", "stopped"),
+                              exit_on_error=False, state_msg=" stopped"):
+                return
+        print_error(f"Failed to stop ybox container '{container_name}'")
+    elif fail_on_error:
+        print_error(f"No active ybox container '{container_name}' found")
+        sys.exit(1)
+    else:
+        print_color(f"No active ybox container '{container_name}' found", fg=fgcolor.cyan)
+
+
+def main_argv(argv: list[str]) -> None:
+    """
+    Main entrypoint of `ybox-control` that takes a list of arguments which are usually the
+    command-line arguments of the `main()` function. Pass ["-h"]/["--help"] to see all the
+    available arguments with help message for each.
+
+    :param argv: arguments to the function (main function passes `sys.argv[1:]`)
+    """
+    args = parse_args(argv)
+    docker_cmd = get_docker_command()
+    container_name = args.container_name
+    if args.action == "start":
+        start_container(docker_cmd, container_name)
+    elif args.action == "stop":
+        stop_container(docker_cmd, container_name, fail_on_error=True)
+    elif args.action == "restart":
+        stop_container(docker_cmd, container_name, fail_on_error=False)
+        start_container(docker_cmd, container_name)
+    elif args.action == "status":
+        if status := get_ybox_state(docker_cmd, container_name, (), exit_on_error=False):
+            print(status[0])
+        else:
+            print_error(f"No ybox container '{container_name}' found")
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    """
+    Parse command-line arguments for the program and return the result :class:`argparse.Namespace`.
+
+    :param argv: the list of arguments to be parsed
+    :return: the result of parsing using the `argparse` library as a :class:`argparse.Namespace`
+    """
+    parser = argparse.ArgumentParser(description="control ybox containers")
+    parser.add_argument("action", choices=["start", "stop", "restart", "status"],
+                        help="action to perform")
+    parser.add_argument("container_name", help="name of the ybox")
+    return parser.parse_args(argv)