ruyi 0.39.0__py3-none-any.whl

ruyi/__init__.py

@@ -0,0 +1,21 @@
+import typing
+
+if typing.TYPE_CHECKING:
+
+    class NuitkaVersion(typing.NamedTuple):
+        major: int
+        minor: int
+        micro: int
+        releaselevel: str
+        containing_dir: str
+        standalone: bool
+        onefile: bool
+        macos_bundle_mode: bool
+        no_asserts: bool
+        no_docstrings: bool
+        no_annotations: bool
+        module: bool
+        main: str
+        original_argv0: str | None
+
+    __compiled__: NuitkaVersion

ruyi/__main__.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+
+import os
+import sys
+
+import ruyi
+from ruyi.utils.ci import is_running_in_ci
+from ruyi.utils.global_mode import (
+    EnvGlobalModeProvider,
+    ENV_FORCE_ALLOW_ROOT,
+    TRUTHY_ENV_VAR_VALUES,
+    is_env_var_truthy,
+)
+
+# NOTE: no imports that directly or indirectly pull in pygit2 should go here,
+# because import of pygit2 will fail if done before ssl_patch. Notably this
+# means no GlobalConfig here because it depends on ruyi.ruyipkg.repo.
+
+
+def _is_running_as_root() -> bool:
+    # this is way too simplistic but works on *nix systems which is all we
+    # support currently
+    if hasattr(os, "getuid"):
+        return os.getuid() == 0
+    return False
+
+
+def _is_allowed_to_run_as_root() -> bool:
+    if is_env_var_truthy(os.environ, ENV_FORCE_ALLOW_ROOT):
+        return True
+    if is_running_in_ci(os.environ):
+        # CI environments are usually considered to be controlled, and safe
+        # for root usage.
+        return True
+    return False
+
+
+def entrypoint() -> None:
+    gm = EnvGlobalModeProvider(os.environ, sys.argv)
+
+    # NOTE: import of `ruyi.log` takes ~90ms on my machine, so initialization
+    # of logging is deferred as late as possible
+
+    if _is_running_as_root() and not _is_allowed_to_run_as_root():
+        from ruyi.log import RuyiConsoleLogger
+
+        logger = RuyiConsoleLogger(gm)
+
+        logger.F("refusing to run as super user outside CI without explicit consent")
+
+        choices = ", ".join(f"'{x}'" for x in TRUTHY_ENV_VAR_VALUES)
+        logger.I(
+            f"re-run with environment variable [yellow]{ENV_FORCE_ALLOW_ROOT}[/] set to one of [yellow]{choices}[/] to signify consent"
+        )
+        sys.exit(1)
+
+    if not sys.argv:
+        from ruyi.log import RuyiConsoleLogger
+
+        logger = RuyiConsoleLogger(gm)
+
+        logger.F("no argv?")
+        sys.exit(1)
+
+    if gm.is_packaged and ruyi.__compiled__.standalone:
+        # If we're running from a bundle, our bundled libssl may remember a
+        # different path for loading certificates than appropriate for the
+        # current system, in which case the pygit2 import will fail. To avoid
+        # this we have to patch ssl.get_default_verify_paths with additional
+        # logic.
+        #
+        # this must happen before pygit2 is imported
+        from ruyi.utils import ssl_patch
+
+        del ssl_patch
+
+    from ruyi.utils.nuitka import get_nuitka_self_exe, get_argv0
+
+    # note down our own executable path, for identity-checking in mux, if not
+    # we're not already Nuitka-compiled
+    #
+    # we assume the one-file build if Nuitka is detected; sys.argv[0] does NOT
+    # work if it's just `ruyi` so we have to check our parent process in that case
+    self_exe = get_nuitka_self_exe() if gm.is_packaged else __file__
+    sys.argv[0] = get_argv0()
+    gm.record_self_exe(sys.argv[0], __file__, self_exe)
+
+    from ruyi.config import GlobalConfig
+    from ruyi.cli.main import main
+    from ruyi.log import RuyiConsoleLogger
+
+    logger = RuyiConsoleLogger(gm)
+    gc = GlobalConfig.load_from_config(gm, logger)
+    sys.exit(main(gm, gc, sys.argv))
+
+
+if __name__ == "__main__":
+    entrypoint()

ruyi/cli/__init__.py

@@ -0,0 +1,5 @@
+from typing import Final
+
+
+# Should be all-lower for is_called_as_ruyi to work
+RUYI_ENTRYPOINT_NAME: Final = "ruyi"

ruyi/cli/builtin_commands.py

@@ -0,0 +1,14 @@
+from ..device import provision_cli as provision_cli
+from ..mux.venv import venv_cli as venv_cli
+from ..pluginhost import plugin_cli as plugin_cli
+from ..ruyipkg import admin_cli as admin_cli
+from ..ruyipkg import entity_cli as entity_cli
+from ..ruyipkg import install_cli as install_cli
+from ..ruyipkg import list_cli as list_cli
+from ..ruyipkg import news_cli as news_cli
+from ..ruyipkg import profile_cli as profile_cli
+from ..ruyipkg import update_cli as update_cli
+from ..telemetry import telemetry_cli as telemetry_cli
+from . import self_cli as self_cli
+from . import config_cli as config_cli
+from . import version_cli as version_cli

ruyi/cli/cmd.py

@@ -0,0 +1,224 @@
+import argparse
+from typing import Callable, IO, Protocol, TYPE_CHECKING
+
+from . import RUYI_ENTRYPOINT_NAME
+
+if TYPE_CHECKING:
+    from ..config import GlobalConfig
+    from .completion import ArgumentParser
+
+    CLIEntrypoint = Callable[["GlobalConfig", argparse.Namespace], int]
+
+
+class _PrintHelp(Protocol):
+    def print_help(self, file: IO[str] | None = None) -> None: ...
+
+
+def _wrap_help(x: _PrintHelp) -> "CLIEntrypoint":
+    def _wrapped_(gc: "GlobalConfig", args: argparse.Namespace) -> int:
+        x.print_help()
+        return 0
+
+    return _wrapped_
+
+
+class BaseCommand:
+    parsers: "list[type[BaseCommand]]" = []
+
+    cmd: str | None
+    _tele_key: str | None
+    has_subcommands: bool
+    is_experimental: bool
+    is_subcommand_required: bool
+    has_main: bool
+    aliases: list[str]
+    description: str | None
+    prog: str | None
+    help: str | None
+
+    def __init_subclass__(
+        cls,
+        cmd: str | None,
+        has_subcommands: bool = False,
+        is_subcommand_required: bool = False,
+        is_experimental: bool = False,
+        has_main: bool | None = None,
+        aliases: list[str] | None = None,
+        description: str | None = None,
+        prog: str | None = None,
+        help: str | None = None,
+        **kwargs: object,
+    ) -> None:
+        cls.cmd = cmd
+
+        if cmd is None:
+            cls._tele_key = None
+        else:
+            parent_cls = cls.mro()[1]
+            parent_raw_tele_key = getattr(parent_cls, "_tele_key", None)
+            if parent_raw_tele_key is None:
+                cls._tele_key = cmd
+            else:
+                cls._tele_key = f"{parent_raw_tele_key} {cmd}"
+
+        cls.has_subcommands = has_subcommands
+        cls.is_subcommand_required = is_subcommand_required
+        cls.is_experimental = is_experimental
+        cls.has_main = has_main if has_main is not None else not has_subcommands
+
+        # argparse params
+        cls.aliases = aliases or []
+        cls.description = description
+        cls.prog = prog
+        cls.help = help
+
+        cls.parsers.append(cls)
+
+        super().__init_subclass__(**kwargs)
+
+    @classmethod
+    def configure_args(cls, gc: "GlobalConfig", p: "ArgumentParser") -> None:
+        """Configure arguments for this parser."""
+        pass
+
+    @classmethod
+    def main(cls, cfg: "GlobalConfig", args: argparse.Namespace) -> int:
+        """Entrypoint of this command."""
+        raise NotImplementedError
+
+    @classmethod
+    def is_root(cls) -> bool:
+        return cls.cmd is None
+
+    @classmethod
+    def _build_tele_key(cls) -> str:
+        return "<bare>" if cls._tele_key is None else cls._tele_key
+
+    @classmethod
+    def build_argparse(cls, gc: "GlobalConfig") -> "ArgumentParser":
+        from .completion import ArgumentParser
+
+        p = ArgumentParser(prog=cls.prog, description=cls.description)
+        cls.configure_args(gc, p)
+        cls._populate_defaults(p)
+        cls._maybe_build_subcommands(gc, p)
+        return p
+
+    @classmethod
+    def _maybe_build_subcommands(
+        cls,
+        gc: "GlobalConfig",
+        p: "ArgumentParser",
+    ) -> None:
+        if not cls.has_subcommands:
+            return
+
+        sp = p.add_subparsers(
+            title="subcommands",
+            required=cls.is_subcommand_required,
+        )
+        for subcmd_cls in cls.parsers:
+            if subcmd_cls.mro()[1] is not cls:
+                # do not recurse onto self or non-direct subclasses
+                continue
+            if subcmd_cls.is_experimental and not gc.is_experimental:
+                # skip configuring experimental commands if not enabled in
+                # the environment
+                continue
+            subcmd_cls._configure_subcommand(gc, sp)
+
+    @classmethod
+    def _configure_subcommand(
+        cls,
+        gc: "GlobalConfig",
+        sp: "argparse._SubParsersAction[ArgumentParser]",
+    ) -> argparse.ArgumentParser:
+        assert cls.cmd is not None
+        p = sp.add_parser(
+            cls.cmd,
+            aliases=cls.aliases,
+            help=cls.help,
+        )
+        cls.configure_args(gc, p)
+        cls._populate_defaults(p)
+        cls._maybe_build_subcommands(gc, p)
+        return p
+
+    @classmethod
+    def _populate_defaults(cls, p: "ArgumentParser") -> None:
+        if cls.has_main:
+            p.set_defaults(func=cls.main, tele_key=cls._build_tele_key())
+        else:
+            p.set_defaults(func=_wrap_help(p), tele_key=cls._build_tele_key())
+
+
+class RootCommand(
+    BaseCommand,
+    cmd=None,
+    has_subcommands=True,
+    has_main=True,
+    prog=RUYI_ENTRYPOINT_NAME,
+    description="RuyiSDK Package Manager",
+):
+    @classmethod
+    def configure_args(cls, gc: "GlobalConfig", p: "ArgumentParser") -> None:
+        from .version_cli import cli_version
+
+        p.add_argument(
+            "-V",
+            "--version",
+            action="store_const",
+            dest="func",
+            const=cli_version,
+            help="Print version information",
+        )
+        p.add_argument(
+            "--porcelain",
+            action="store_true",
+            help="Give the output in a machine-friendly format if applicable",
+        )
+
+        # https://github.com/python/cpython/issues/67037 prevents the registration
+        # of undocumented subcommands, so a preferred usage of
+        # "ruyi completion-script --shell=bash" is not possible right now.
+        p.add_argument(
+            "--output-completion-script",
+            action="store",
+            type=str,
+            dest="completion_script",
+            default=None,
+            help=argparse.SUPPRESS,
+        )
+
+    @classmethod
+    def main(cls, cfg: "GlobalConfig", args: argparse.Namespace) -> int:
+        sh: str | None = args.completion_script
+        if not sh:
+            args._parser.print_help()  # pylint: disable=protected-access
+            return 0
+        # the rest are implementation of "--output-completion-script"
+
+        if sh not in {"bash", "zsh"}:
+            raise ValueError(f"Unsupported shell: {sh}")
+
+        import sys
+        from ..resource_bundle import get_resource_str
+
+        script = get_resource_str("_ruyi_completion")
+        assert script is not None, "should never happen; completion script not found"
+        sys.stdout.write(script)
+        return 0
+
+
+# Repo admin commands
+class AdminCommand(
+    RootCommand,
+    cmd="admin",
+    has_subcommands=True,
+    # https://github.com/python/cpython/issues/67037
+    # help=argparse.SUPPRESS,
+    help="(NOT FOR REGULAR USERS) Subcommands for managing Ruyi repos",
+):
+    @classmethod
+    def configure_args(cls, gc: "GlobalConfig", p: "ArgumentParser") -> None:
+        pass

ruyi/cli/completer.py

@@ -0,0 +1,50 @@
+"""
+helper functions for CLI completions
+"""
+
+import argparse
+from typing import Protocol, Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # A "lie" for type checking purposes. This is a known and wont fix issue for mypy.
+    # Mypy would think the fallback import needs to be the same type as the first import.
+    # See: https://github.com/python/mypy/issues/1153
+    from argcomplete.completers import BaseCompleter
+else:
+    try:
+        from argcomplete.completers import BaseCompleter
+    except ImportError:
+        # Fallback for environments where argcomplete is less than 2.0.0
+        class BaseCompleter(object):
+            def __call__(
+                self,
+                *,
+                prefix: str,
+                action: argparse.Action,
+                parser: argparse.ArgumentParser,
+                parsed_args: argparse.Namespace,
+            ) -> None:
+                raise NotImplementedError(
+                    "This method should be implemented by a subclass."
+                )
+
+
+class NoneCompleter(BaseCompleter):
+    def __call__(
+        self,
+        *,
+        prefix: str,
+        action: argparse.Action,
+        parser: argparse.ArgumentParser,
+        parsed_args: argparse.Namespace,
+    ) -> None:
+        return None
+
+
+class DynamicCompleter(Protocol):
+    def __call__(
+        self,
+        prefix: str,
+        parsed_args: object,
+        **kwargs: Any,
+    ) -> list[str]: ...

ruyi/cli/completion.py

@@ -0,0 +1,26 @@
+"""
+helper functions for CLI completions
+
+see https://github.com/kislyuk/argcomplete/issues/443 for why this is needed
+"""
+
+import argparse
+from typing import Any, Callable, Optional, Sequence, cast
+
+
+class ArgcompleteAction(argparse.Action):
+    completer: Optional[Callable[[str, object], list[str]]]
+
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: str | Sequence[Any] | None,
+        option_string: str | None = None,
+    ) -> None:
+        raise NotImplementedError(".__call__() not defined")
+
+
+class ArgumentParser(argparse.ArgumentParser):
+    def add_argument(self, *args: Any, **kwargs: Any) -> ArgcompleteAction:
+        return cast(ArgcompleteAction, super().add_argument(*args, **kwargs))

ruyi/cli/config_cli.py

@@ -0,0 +1,153 @@
+import argparse
+from typing import TYPE_CHECKING
+
+from .cmd import RootCommand
+
+if TYPE_CHECKING:
+    from .completion import ArgumentParser
+    from .. import config
+
+
+# Config management commands
+class ConfigCommand(
+    RootCommand,
+    cmd="config",
+    has_subcommands=True,
+    help="Manage Ruyi's config options",
+):
+    @classmethod
+    def configure_args(
+        cls,
+        gc: "config.GlobalConfig",
+        p: "ArgumentParser",
+    ) -> None:
+        pass
+
+
+class ConfigGetCommand(
+    ConfigCommand,
+    cmd="get",
+    help="Query the value of a Ruyi config option",
+):
+    @classmethod
+    def configure_args(
+        cls,
+        gc: "config.GlobalConfig",
+        p: "ArgumentParser",
+    ) -> None:
+        p.add_argument(
+            "key",
+            type=str,
+            help="The Ruyi config option to query",
+        )
+
+    @classmethod
+    def main(cls, cfg: "config.GlobalConfig", args: argparse.Namespace) -> int:
+        from ..config.schema import encode_value
+
+        key: str = args.key
+
+        val = cfg.get_by_key(key)
+        if val is None:
+            return 1
+
+        cfg.logger.stdout(encode_value(val))
+        return 0
+
+
+class ConfigSetCommand(
+    ConfigCommand,
+    cmd="set",
+    help="Set the value of a Ruyi config option",
+):
+    @classmethod
+    def configure_args(
+        cls,
+        gc: "config.GlobalConfig",
+        p: "ArgumentParser",
+    ) -> None:
+        p.add_argument(
+            "key",
+            type=str,
+            help="The Ruyi config option to set",
+        )
+        p.add_argument(
+            "value",
+            type=str,
+            help="The value to set the option to",
+        )
+
+    @classmethod
+    def main(cls, cfg: "config.GlobalConfig", args: argparse.Namespace) -> int:
+        from ..config.editor import ConfigEditor
+        from ..config.schema import decode_value
+
+        key: str = args.key
+        val: str = args.value
+
+        pyval = decode_value(key, val)
+        with ConfigEditor.work_on_user_local_config(cfg) as ed:
+            ed.set_value(key, pyval)
+            ed.stage()
+
+        return 0
+
+
+class ConfigUnsetCommand(
+    ConfigCommand,
+    cmd="unset",
+    help="Unset a Ruyi config option",
+):
+    @classmethod
+    def configure_args(
+        cls,
+        gc: "config.GlobalConfig",
+        p: "ArgumentParser",
+    ) -> None:
+        p.add_argument(
+            "key",
+            type=str,
+            help="The Ruyi config option to unset",
+        )
+
+    @classmethod
+    def main(cls, cfg: "config.GlobalConfig", args: argparse.Namespace) -> int:
+        from ..config.editor import ConfigEditor
+
+        key: str = args.key
+
+        with ConfigEditor.work_on_user_local_config(cfg) as ed:
+            ed.unset_value(key)
+            ed.stage()
+
+        return 0
+
+
+class ConfigRemoveSectionCommand(
+    ConfigCommand,
+    cmd="remove-section",
+    help="Remove a section from the Ruyi config",
+):
+    @classmethod
+    def configure_args(
+        cls,
+        gc: "config.GlobalConfig",
+        p: "ArgumentParser",
+    ) -> None:
+        p.add_argument(
+            "section",
+            type=str,
+            help="The section to remove",
+        )
+
+    @classmethod
+    def main(cls, cfg: "config.GlobalConfig", args: argparse.Namespace) -> int:
+        from ..config.editor import ConfigEditor
+
+        section: str = args.section
+
+        with ConfigEditor.work_on_user_local_config(cfg) as ed:
+            ed.remove_section(section)
+            ed.stage()
+
+        return 0

ruyi/cli/main.py

@@ -0,0 +1,111 @@
+import atexit
+import os
+import sys
+from typing import Final, TYPE_CHECKING
+
+from ..config import GlobalConfig
+from ..telemetry.scope import TelemetryScope
+from ..utils.global_mode import GlobalModeProvider
+from . import RUYI_ENTRYPOINT_NAME
+
+ALLOWED_RUYI_ENTRYPOINT_NAMES: Final = (
+    RUYI_ENTRYPOINT_NAME,
+    f"{RUYI_ENTRYPOINT_NAME}.exe",
+    f"{RUYI_ENTRYPOINT_NAME}.bin",  # Nuitka one-file program cache
+    "__main__.py",
+)
+
+
+def is_called_as_ruyi(argv0: str) -> bool:
+    return os.path.basename(argv0).lower() in ALLOWED_RUYI_ENTRYPOINT_NAMES
+
+
+def main(gm: GlobalModeProvider, gc: GlobalConfig, argv: list[str]) -> int:
+    if tm := gc.telemetry:
+        tm.check_first_run_status()
+        tm.init_installation(False)
+        atexit.register(tm.flush)
+        tm.maybe_prompt_for_first_run_upload()
+
+    if not is_called_as_ruyi(gm.argv0):
+        from ..mux.runtime import mux_main
+
+        # record an invocation and the command name being proxied to
+        if tm := gc.telemetry:
+            tm.record(
+                TelemetryScope(None),
+                "cli:mux-invocation-v1",
+                target=os.path.basename(gm.argv0),
+            )
+
+        return mux_main(gm, gc, argv)
+
+    import ruyi
+    from .cmd import RootCommand
+    from . import builtin_commands
+
+    del builtin_commands
+
+    if TYPE_CHECKING:
+        from .cmd import CLIEntrypoint
+
+    logger = gc.logger
+    p = RootCommand.build_argparse(gc)
+
+    # We have to ensure argcomplete is only requested when it's supposed to,
+    # as the argcomplete import is very costly in terms of startup time, and
+    # that the package name completer requires the whole repo to be synced
+    # (which may not be the case for an out-of-the-box experience).
+    if gm.is_cli_autocomplete:
+        import argcomplete
+        from .completer import NoneCompleter
+
+        argcomplete.autocomplete(
+            p,
+            always_complete_options=True,
+            default_completer=NoneCompleter(),
+        )
+
+    args = p.parse_args(argv[1:])
+    # for getting access to the argparse parser in the CLI entrypoint
+    args._parser = p  # pylint: disable=protected-access
+
+    gm.is_porcelain = args.porcelain
+
+    nuitka_info = "not compiled"
+    if hasattr(ruyi, "__compiled__"):
+        nuitka_info = f"__compiled__ = {ruyi.__compiled__}"
+
+    logger.D(
+        f"__main__.__file__ = {gm.main_file}, sys.executable = {sys.executable}, {nuitka_info}"
+    )
+    logger.D(f"argv[0] = {gm.argv0}, self_exe = {gm.self_exe}")
+    logger.D(f"args={args}")
+
+    func: "CLIEntrypoint" = args.func
+
+    # record every invocation's subcommand for better insight into usage
+    # frequencies
+    try:
+        telemetry_key: str = args.tele_key
+    except AttributeError:
+        logger.F("internal error: CLI entrypoint was added without a telemetry key")
+        return 1
+
+    # Special-case the `--output-completion-script` argument; treat it as if
+    # "ruyi completion-script" were called.
+    try:
+        if args.completion_script:
+            telemetry_key = "completion-script"
+    except AttributeError:
+        pass
+
+    if tm := gc.telemetry:
+        tm.print_telemetry_notice()
+        tm.record(
+            TelemetryScope(None),
+            "cli:invocation-v1",
+            key=telemetry_key,
+        )
+
+    return func(gc, args)