compose-lazy 0.7.0__py3-none-any.whl

compose_lazy/__init__.py

@@ -0,0 +1,10 @@
+"""A smart CLI wrapper for docker compose with interactive selection support."""
+
+import logging
+from importlib.metadata import version
+
+__version__ = version("compose-lazy")
+
+logger = logging.getLogger("compose_lazy")
+logger.addHandler(logging.NullHandler())
+logger.propagate = False

compose_lazy/args.py

@@ -0,0 +1,155 @@
+import logging
+from argparse import ArgumentParser, Namespace
+from typing import Callable, Self
+
+from .process import DockerCmdProcessor
+
+logger = logging.getLogger(__name__)
+
+
+class ArgBuilder:
+    def __init__(self, parser: ArgumentParser):
+        self.parser = parser
+
+    def set_defaults(self, func: Callable[[Namespace], int] | None = None) -> Self:
+        func = func or DockerCmdProcessor()
+        self.parser.set_defaults(func=func)
+        return self
+
+    def add_common_compose_options(self) -> Self:
+        return self._add_file_args()._add_profile_args()._add_project_args()
+
+    def add_service_name_subcmd(self, multiple: bool = False) -> Self:
+        """Add positional argument of service name(s) to command definition.
+
+        multiple=True: accepts multiple service names, all optional (e.g. up, build, stop, etc.).
+        multiple=False: accepts single service name, required by docker compose (e.g. exec, run).
+        """
+        if multiple:
+            self.parser.add_argument(
+                "service_name",
+                nargs="*",
+                default=[],
+                help="(Optional) target service names",
+            )
+            # Add trigger option to start interactive selection explicitly.
+            self.parser.add_argument(
+                "-s",
+                "--service",
+                action="store_true",
+                help="show service name candidates, select interactively",
+            )
+        else:
+            # If no service_name given, interactive selection starts automatically.
+            self.parser.add_argument(
+                "service_name",
+                nargs="?",
+                type=lambda x: [x],
+                default=[],
+                help="(Required) target service name",
+            )
+        return self
+
+    def add_inner_bash_cmd_args(self) -> Self:
+        self.parser.add_argument(
+            "inner_bash_cmd",
+            nargs="*",
+            default=[],
+            help="command to run inside the service (default: bash)",
+        )
+        return self
+
+    def add_build_args(self) -> Self:
+        self.parser.add_argument(
+            "-b",
+            "--build",
+            action="store_true",
+            help="docker compose up `--build`",
+        )
+        return self
+
+    def add_detach_args(self) -> Self:
+        """add optional argument `-d` to `docker compose up` command."""
+        self.parser.add_argument(
+            "-d", "--detach", action="store_true", help="docker compose up `-d`"
+        )
+        return self
+
+    def add_follow_args(self) -> Self:
+        """add optional argument `-f` to `docker compose logs` command."""
+        self.parser.add_argument(
+            "-fo", "--follow", action="store_true", help="docker compose logs `-f`"
+        )
+        return self
+
+    def add_all_args(self) -> Self:
+        """add optional argument `--all(-a)` to `docker compose ps` command."""
+        self.parser.add_argument(
+            "-a",
+            "--all",
+            action="store_true",
+            help="docker compose ps `-a`",
+        )
+        return self
+
+    def add_status_args(self) -> Self:
+        self.parser.add_argument(
+            "-st",
+            "--status",
+            choices=[
+                "created",
+                "restarting",
+                "running",
+                "removing",
+                "paused",
+                "exited",
+                "dead",
+            ],
+            help="docker compose ps `--status` <STATUS>",
+        )
+        return self
+
+    def add_remove_orphans_args(self) -> Self:
+        self.parser.add_argument(
+            "-ro",
+            "--remove-orphans",
+            action="store_true",
+            help="docker compose down `--remove-orphans`",
+        )
+        return self
+
+    def add_wait_args(self) -> Self:
+        self.parser.add_argument(
+            "-w",
+            "--wait",
+            action="store_true",
+            help="docker compose up `--wait`",
+        )
+        return self
+
+    def _add_file_args(self) -> Self:
+        self.parser.add_argument(
+            "-f",
+            "--file",
+            nargs="*",
+            help="specify compose file(s). if omitted with -f, select interactively",
+        )
+        return self
+
+    def _add_project_args(self) -> Self:
+        self.parser.add_argument(
+            "-p",
+            "--project",
+            default="",
+            help="docker compose `-p PROJECT_NAME`",
+        )
+        return self
+
+    def _add_profile_args(self) -> Self:
+        self.parser.add_argument(
+            "-pf",
+            "--profile",
+            nargs="*",
+            help="specify profile(s). if omitted with -pf, select interactively",
+        )
+        return self

compose_lazy/cli_utils.py

@@ -0,0 +1,105 @@
+import logging
+import sys
+from typing import Iterable, Literal, overload
+
+logger = logging.getLogger(__name__)
+
+
+@overload
+def interactive_select(
+        candidates, flag=..., *, multiple=..., allow_zero: Literal[True]
+) -> None | list[str]: ...
+
+
+@overload
+def interactive_select(
+        candidates, flag=..., *, multiple=..., allow_zero: Literal[False] = ...
+) -> list[str]: ...
+
+
+def interactive_select(
+        candidates: Iterable[str],
+        flag: str | None = None,
+        *,
+        multiple: bool = True,
+        allow_zero: bool = False,
+) -> list[str] | None:
+    """Starts general interactive session.
+
+    When `allow_zero` is False, returns list[str].
+    Only when `allow_zero` is True, may return None (if the user inputs exactly `0`).
+    Despite `multiple` being True or False, the choice `0` cannot be included in multiple choices (the session continues).
+
+    Args:
+        candidates (Iterable[str]): list, set, dict, etc... and generator-like objects.
+        flag (str | None, optional): Specified when each candidate needs prefix tag in list. Defaults to None.
+        multiple (bool, optional): Enables multiple select. Defaults to True.
+        allow_zero (bool, optional): Enables the choice `0` make it return None. Defaults to False.
+
+    Raises:
+        SystemExit: Raised when user input `q` or `Q`.
+        KeyboardInterrupt: Raised when user stopped session by Ctrl+C.
+
+    Returns:
+        list[str] | None: The list of candidate name(s) user selected, or None when `0` inputed.
+    """
+    prompt = (
+        "\nEnter your choices (e.g., 1,3,4) or 'q' to quit: "
+        if multiple
+        else "\nEnter your choice or 'q' to quit: "
+    )
+    err_msg = (
+        "☓ Invalid selection. Please use valid numbers."
+        if multiple
+        else "☓ Invalid selection. Please use a valid number."
+    )
+
+    candidates = sorted(candidates)
+    # Show choices
+    for idx, candidate in enumerate(candidates, start=1):
+        print(f"{idx:>5}. {candidate}")
+
+    if allow_zero:
+        print("\nOr 0 to enter an alternative choice.", end="")
+
+    # User input
+    while True:
+        args = []
+
+        try:
+            if (choices_str := input(prompt)) in ["Q", "q"]:
+                print("\nCancelled.")
+                raise SystemExit
+
+            choices = list(
+                map(
+                    lambda i: int(i) - 1,
+                    (i.strip() for i in choices_str.split(",") if i.strip()),
+                )
+            )
+            if allow_zero:
+                if choices == [-1]:  # When input is "0"
+                    return None
+                if len(choices) > 1 and -1 in choices:  # When multiple input includes "0"
+                    raise ValueError
+            if not multiple and len(choices) != 1:
+                raise ValueError
+            if any((i < 0 for i in choices)):
+                raise IndexError
+
+            for idx in choices:
+                chosen = candidates[idx]
+                if flag is None:
+                    args += [chosen]
+                else:
+                    args += [flag, chosen]
+
+        except (ValueError, IndexError):
+            print(err_msg, file=sys.stderr)
+        except KeyboardInterrupt as e:
+            print("\nCancelled.")
+            raise e
+        else:
+            print()
+            break
+    return args

compose_lazy/config.py

@@ -0,0 +1,38 @@
+import logging
+import os
+
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+
+except ImportError:
+    pass
+
+DEBUG = os.environ.get("COMPOSE_LAZY_DEBUG", "False").lower() in ["true", "t"]
+
+LOG_LEVEL = "DEBUG" if DEBUG else "INFO"
+
+
+def setup_logger(name: str) -> None:
+    """Add console handler only when "DEBUG" is active.
+
+    :param name: the name of this package
+    :return: None
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.DEBUG)
+    logger.propagate = False
+
+    if any(isinstance(h, logging.StreamHandler) for h in logger.handlers):
+        return
+
+    ch = logging.StreamHandler()
+    ch.setLevel(getattr(logging, LOG_LEVEL, logging.INFO))
+    ch_formatter = logging.Formatter(
+        "%(asctime)s | %(levelname)s | %(filename)s %(message)s", "%H:%M:%S"
+    )
+    ch.setFormatter(ch_formatter)
+
+    if DEBUG:
+        logger.addHandler(ch)

compose_lazy/main.py

@@ -0,0 +1,330 @@
+import logging
+import sys
+from argparse import ArgumentParser
+from importlib.metadata import version
+
+from . import config
+from .args import ArgBuilder
+from .process import DockerCmdProcessor
+from .workspace import WorkspaceProcessor, WorkspaceRegistrar
+
+VERSION = version("compose_lazy")
+
+logger = logging.getLogger(__name__)
+
+processor = DockerCmdProcessor()
+ws_registrar = WorkspaceRegistrar()
+ws_processor = WorkspaceProcessor()
+
+
+def main() -> None:
+    config.setup_logger("compose_lazy")
+
+    base_parser = ArgumentParser(
+        allow_abbrev=False,
+        usage="dcp <SUBCOMMAND> [options]",
+        description="Shorthand aliases for docker compose commands.",
+        epilog="See also: `dcpu -h`, `dcpe -h`, `dcp ws -h`",
+    )
+    base_parser.suggest_on_error = True
+    base_parser.add_argument("--version", action="version", version=f"compose-lazy {VERSION}")
+
+    root_subparsers = base_parser.add_subparsers(dest="subcmd")
+
+    # dcp up(u) command
+    _up = root_subparsers.add_parser(
+        "up",
+        aliases=["u"],
+        allow_abbrev=False,
+        usage="dcp up(u) [SERVICE_NAME ...] [options]",
+        description="Shorthand for `docker compose up`.",
+        help="docker compose `up`, also available as: dcpu",
+    )
+    (
+        ArgBuilder(_up)
+        .add_service_name_subcmd(multiple=True)
+        .add_detach_args()
+        .add_build_args()
+        .add_wait_args()
+        .add_common_compose_options()
+        .set_defaults(func=processor)
+    )
+
+    # dcp build(b) command
+    _build = root_subparsers.add_parser(
+        "build",
+        aliases=["b"],
+        allow_abbrev=False,
+        usage="dcp build(b) [SERVICE_NAME ...] [options]",
+        description="Shorthand for `docker compose build`.",
+        help="docker compose `build`",
+    )
+    (
+        ArgBuilder(_build)
+        .add_service_name_subcmd(multiple=True)
+        .add_common_compose_options()
+        .set_defaults(func=processor)
+    )
+
+    # dcp exec(e) command
+    _exec = root_subparsers.add_parser(
+        "exec",
+        aliases=["e"],
+        allow_abbrev=False,
+        usage="dcp exec(e) <SERVICE_NAME> [BASH|commands] [options]",
+        description="Shorthand for `docker compose exec`.",
+        help="docker compose `exec`, also available as: dcpe",
+    )
+    (
+        ArgBuilder(_exec)
+        .add_service_name_subcmd(multiple=False)
+        .add_inner_bash_cmd_args()
+        .add_common_compose_options()
+        .set_defaults(func=processor)
+    )
+
+    # dcp run command
+    _run = root_subparsers.add_parser(
+        "run",
+        allow_abbrev=False,
+        usage="dcp run <SERVICE_NAME> [BASH|commands]",
+        description="Shorthand for `docker compose run`.",
+        help="docker compose `run`",
+    )
+    (
+        ArgBuilder(_run)
+        .add_service_name_subcmd(multiple=False)
+        .add_inner_bash_cmd_args()
+        .add_common_compose_options()
+        .set_defaults(func=processor)
+    )
+
+    # dcp restart(re) command
+    _restart = root_subparsers.add_parser(
+        "restart",
+        aliases=["re"],
+        allow_abbrev=False,
+        usage="dcp restart(re) [SERVICE_NAME ...]",
+        description="Shorthand for `docker compose restart`.",
+        help="docker compose `restart`",
+    )
+    (
+        ArgBuilder(_restart)
+        .add_service_name_subcmd(multiple=True)
+        .add_common_compose_options()
+        .set_defaults(func=processor)
+    )
+
+    # dcp ps command
+    _ps = root_subparsers.add_parser(
+        "ps",
+        allow_abbrev=False,
+        usage="dcp ps [SERVICE_NAME ...] [-a] [-st STATUS]",
+        description="Shorthand for `docker compose ps`.",
+        help="docker compose `ps`",
+    )
+    (
+        ArgBuilder(_ps)
+        .add_service_name_subcmd(multiple=True)
+        .add_all_args()
+        .add_status_args()
+        .add_common_compose_options()
+        .set_defaults(func=processor)
+    )
+
+    # dcp logs(l) command
+    _logs = root_subparsers.add_parser(
+        "logs",
+        aliases=["l"],
+        allow_abbrev=False,
+        usage="dcp logs(l) [SERVICE_NAME ...] [-f]",
+        description="Shorthand for `docker compose logs`.",
+        help="docker compose `logs`",
+    )
+    (
+        ArgBuilder(_logs)
+        .add_service_name_subcmd(multiple=True)
+        .add_follow_args()
+        .add_common_compose_options()
+        .set_defaults(func=processor)
+    )
+
+    # dcp stop(s) command
+    _stop = root_subparsers.add_parser(
+        "stop",
+        aliases=["s"],
+        allow_abbrev=False,
+        usage="dcp stop(s) [SERVICE_NAME ...]",
+        description="Shorthand for `docker compose stop`.",
+        help="docker compose `stop`",
+    )
+    (
+        ArgBuilder(_stop)
+        .add_service_name_subcmd(multiple=True)
+        .add_common_compose_options()
+        .set_defaults(func=processor)
+    )
+
+    # dcp down command
+    _down = root_subparsers.add_parser(
+        "down",
+        allow_abbrev=False,
+        usage="dcp down [-f FILE_NAME ...] [-p PROJECT_NAME] [-ro]",
+        description="Shorthand for `docker compose down`.",
+        help="docker compose `down`",
+    )
+    (
+        ArgBuilder(_down)
+        .add_remove_orphans_args()
+        .add_common_compose_options()
+        .set_defaults(func=processor)
+    )
+
+    # dcp workspace(ws) command
+    _workspace = root_subparsers.add_parser(
+        "workspace",
+        aliases=["ws"],
+        allow_abbrev=False,
+        usage="dcp workspace(ws) [SUBCOMMAND] [options]",
+        description="Operate all repos in a user-defined workspace (a named group of repositories).",
+        help="Original command, operate multiple repos at once. See also `dcp ws -h`.",
+    )
+    ws_subparsers = _workspace.add_subparsers(dest="ws_subcmd")
+
+    # dcp ws register command
+    ws_subparsers.add_parser(
+        "register",
+        aliases=["reg"],
+        allow_abbrev=False,
+        usage="dcp ws register(reg)",
+        description="Register a new repository to a workspace interactively.",
+        help="Register a new repo to a workspace.",
+    ).set_defaults(func=ws_registrar)
+
+    # dcp ws delete command
+    ws_subparsers.add_parser(
+        "delete",
+        aliases=["del"],
+        allow_abbrev=False,
+        usage="dcp ws delete(del)",
+        description="Delete a repository from a workspace interactively.",
+        help="Delete a repo from a workspace.",
+    ).set_defaults(func=ws_registrar)
+
+    # dcp ws list command
+    ws_subparsers.add_parser(
+        "list",
+        aliases=["li"],
+        allow_abbrev=False,
+        usage="dcp ws list(li)",
+        description="Show all registered workspaces and their repositories.",
+        help="List all registered workspaces.",
+    ).set_defaults(func=ws_registrar)
+
+    # dcp ws up command
+    ws_subparsers.add_parser(
+        "up",
+        aliases=["u"],
+        allow_abbrev=False,
+        usage="dcp ws up(u)",
+        description="Run `docker compose up` for all repos in a selected workspace.",
+        help="docker compose `up` for each repo.",
+    ).set_defaults(func=ws_processor)
+
+    # dcp ws restart command
+    ws_subparsers.add_parser(
+        "restart",
+        aliases=["re"],
+        allow_abbrev=False,
+        usage="dcp ws restart(re)",
+        description="Run `docker compose restart` for all repos in a selected workspace.",
+        help="docker compose `restart` for each repo.",
+    ).set_defaults(func=ws_processor)
+
+    # dcp ws stop command
+    ws_subparsers.add_parser(
+        "stop",
+        aliases=["s"],
+        allow_abbrev=False,
+        usage="dcp ws stop(s)",
+        description="Run `docker compose stop` for all repos in a selected workspace.",
+        help="docker compose `stop` for each repo.",
+    ).set_defaults(func=ws_processor)
+
+    # dcp ws down command
+    ws_subparsers.add_parser(
+        "down",
+        allow_abbrev=False,
+        usage="dcp ws down",
+        description="Run `docker compose down` for all repos in a selected workspace.",
+        help="docker compose `down` for each repo.",
+    ).set_defaults(func=ws_processor)
+
+    args = base_parser.parse_args()
+    if args.subcmd is None:
+        base_parser.print_help()
+        sys.exit(0)
+    if args.subcmd in ("workspace", "ws") and args.ws_subcmd is None:
+        _workspace.print_help()
+        sys.exit(0)
+
+    code = args.func(args)
+    sys.exit(code)
+
+
+def dcpu_main() -> None:
+    config.setup_logger("compose_lazy")
+
+    parser = ArgumentParser(
+        allow_abbrev=False,
+        usage="dcpu [SERVICE_NAME] [options]",
+        description="Shorthand for `docker compose up`.",
+        epilog="See also: `dcp -h`, `dcpe -h`",
+    )
+
+    # dcpu command
+    (
+        ArgBuilder(parser)
+        .add_service_name_subcmd(multiple=True)
+        .add_detach_args()
+        .add_build_args()
+        .add_wait_args()
+        .add_common_compose_options()
+        .set_defaults(func=processor.call_dcpu)
+    )
+
+    parser.add_argument(
+        "-v", "--version", action="version", version=f"compose-lazy {VERSION}"
+    )
+
+    args = parser.parse_args()
+    code = args.func(args)
+    sys.exit(code)
+
+
+def dcpe_main() -> None:
+    config.setup_logger("compose_lazy")
+
+    parser = ArgumentParser(
+        allow_abbrev=False,
+        usage="dcpe <SERVICE_NAME> [BASH|commands] [options]",
+        description="Shorthand for `docker compose exec`.",
+        epilog="See also: `dcp -h`, `dcpu -h`",
+    )
+
+    # dcpe command
+    (
+        ArgBuilder(parser)
+        .add_service_name_subcmd(multiple=False)
+        .add_inner_bash_cmd_args()
+        .add_common_compose_options()
+        .set_defaults(func=processor.call_dcpe)
+    )
+
+    parser.add_argument(
+        "-v", "--version", action="version", version=f"compose-lazy {VERSION}"
+    )
+
+    args = parser.parse_args()
+    code = args.func(args)
+    sys.exit(code)