ruyi 0.39.0__py3-none-any.whl

ruyi/telemetry/telemetry_cli.py

@@ -0,0 +1,127 @@
+import argparse
+import datetime
+from typing import TYPE_CHECKING
+
+from ..cli.cmd import RootCommand
+
+if TYPE_CHECKING:
+    from ..cli.completion import ArgumentParser
+    from ..config import GlobalConfig
+
+
+# Telemetry preference commands
+class TelemetryCommand(
+    RootCommand,
+    cmd="telemetry",
+    has_subcommands=True,
+    help="Manage your telemetry preferences",
+):
+    @classmethod
+    def configure_args(cls, gc: "GlobalConfig", p: "ArgumentParser") -> None:
+        pass
+
+
+class TelemetryConsentCommand(
+    TelemetryCommand,
+    cmd="consent",
+    aliases=["on"],
+    help="Give consent to telemetry data uploads",
+):
+    @classmethod
+    def configure_args(cls, gc: "GlobalConfig", p: "ArgumentParser") -> None:
+        pass
+
+    @classmethod
+    def main(cls, cfg: "GlobalConfig", args: argparse.Namespace) -> int:
+        from .provider import set_telemetry_mode
+
+        now = datetime.datetime.now().astimezone()
+        set_telemetry_mode(cfg, "on", now)
+        return 0
+
+
+class TelemetryLocalCommand(
+    TelemetryCommand,
+    cmd="local",
+    help="Set telemetry mode to local collection only",
+):
+    @classmethod
+    def configure_args(cls, gc: "GlobalConfig", p: "ArgumentParser") -> None:
+        pass
+
+    @classmethod
+    def main(cls, cfg: "GlobalConfig", args: argparse.Namespace) -> int:
+        from .provider import set_telemetry_mode
+
+        set_telemetry_mode(cfg, "local")
+        return 0
+
+
+class TelemetryOptoutCommand(
+    TelemetryCommand,
+    cmd="optout",
+    aliases=["off"],
+    help="Opt out of telemetry data collection",
+):
+    @classmethod
+    def configure_args(cls, gc: "GlobalConfig", p: "ArgumentParser") -> None:
+        pass
+
+    @classmethod
+    def main(cls, cfg: "GlobalConfig", args: argparse.Namespace) -> int:
+        from .provider import set_telemetry_mode
+
+        set_telemetry_mode(cfg, "off")
+        return 0
+
+
+class TelemetryStatusCommand(
+    TelemetryCommand,
+    cmd="status",
+    help="Print the current telemetry mode",
+):
+    @classmethod
+    def configure_args(cls, gc: "GlobalConfig", p: "ArgumentParser") -> None:
+        p.add_argument(
+            "--verbose",
+            "-v",
+            action="store_true",
+            help="Enable verbose output",
+        )
+
+    @classmethod
+    def main(cls, cfg: "GlobalConfig", args: argparse.Namespace) -> int:
+        verbose: bool = args.verbose
+        if not verbose:
+            cfg.logger.stdout(cfg.telemetry_mode)
+            return 0
+
+        if cfg.telemetry is None:
+            cfg.logger.I(
+                "telemetry mode is [green]off[/]: no further data will be collected"
+            )
+            return 0
+
+        cfg.telemetry.print_telemetry_notice(for_cli_verbose_output=True)
+        return 0
+
+
+class TelemetryUploadCommand(
+    TelemetryCommand,
+    cmd="upload",
+    help="Upload collected telemetry data now",
+):
+    @classmethod
+    def configure_args(cls, gc: "GlobalConfig", p: "ArgumentParser") -> None:
+        pass
+
+    @classmethod
+    def main(cls, cfg: "GlobalConfig", args: argparse.Namespace) -> int:
+        if cfg.telemetry is None:
+            cfg.logger.W("telemetry is disabled, nothing to upload")
+            return 0
+
+        cfg.telemetry.flush(upload_now=True)
+        # disable the flush at program exit because we have just done that
+        cfg.telemetry.discard_events()
+        return 0

ruyi/utils/ar.py

@@ -0,0 +1,74 @@
+from contextlib import AbstractContextManager
+from typing import BinaryIO, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+import arpy
+
+
+class ArpyArchiveWrapper(arpy.Archive, AbstractContextManager["arpy.Archive"]):
+    """Compatibility shim for arpy.Archive, for easy interop with both arpy 1.x
+    and 2.x."""
+
+    def __init__(
+        self,
+        filename: str | None = None,
+        fileobj: BinaryIO | None = None,
+    ) -> None:
+        super().__init__(filename=filename, fileobj=fileobj)
+
+    def __enter__(self) -> arpy.Archive:
+        if hasattr(super(), "__enter__"):
+            # in case we're working with a newer arpy version that has a
+            # non-trivial __enter__ implementation
+            return super().__enter__()
+
+        # backport of arpy 2.x __enter__ implementation
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: "TracebackType | None",
+    ) -> None:
+        if hasattr(super(), "__exit__"):
+            return super().__exit__(exc_type, exc_value, traceback)
+
+        # backport of arpy 2.x __exit__ implementation
+        self.close()
+
+    def infolist(self) -> list[arpy.ArchiveFileHeader]:
+        if hasattr(super(), "infolist"):
+            return super().infolist()
+
+        # backport of arpy 2.x infolist()
+        self.read_all_headers()
+        return [
+            header
+            for header in self.headers
+            if header.type
+            in (
+                arpy.HEADER_BSD,
+                arpy.HEADER_NORMAL,
+                arpy.HEADER_GNU,
+            )
+        ]
+
+    def open(self, name: bytes | arpy.ArchiveFileHeader) -> arpy.ArchiveFileData:
+        if hasattr(super(), "open"):
+            return super().open(name)
+
+        # backport of arpy 2.x open()
+        if isinstance(name, bytes):
+            ar_file = self.archived_files.get(name)
+            if ar_file is None:
+                raise KeyError("There is no item named %r in the archive" % (name,))
+
+            return ar_file
+
+        if name not in self.headers:
+            raise KeyError("Provided header does not match this archive")
+
+        return arpy.ArchiveFileData(ar_obj=self, header=name)

ruyi/utils/ci.py

@@ -0,0 +1,63 @@
+from typing import Mapping
+
+
+def is_running_in_ci(os_environ: Mapping[str, str]) -> bool:
+    """Simplified and quick CI check meant for basic judgement."""
+    if os_environ.get("CI", "") == "true":
+        return True
+    elif os_environ.get("TF_BUILD", "") == "True":
+        return True
+    return False
+
+
+def probe_for_ci(os_environ: Mapping[str, str]) -> str | None:
+    # https://www.appveyor.com/docs/environment-variables/
+    if os_environ.get("APPVEYOR", "").lower() == "true":
+        return "appveyor"
+    # https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#system-variables-devops-services
+    elif os_environ.get("TF_BUILD", "") == "True":
+        return "azure"
+    # https://circleci.com/docs/variables/#built-in-environment-variables
+    elif os_environ.get("CIRCLECI", "") == "true":
+        return "circleci"
+    # https://cirrus-ci.org/guide/writing-tasks/#environment-variables
+    elif os_environ.get("CIRRUS_CI", "") == "true":
+        return "cirrus"
+    # https://gitea.com/gitea/act_runner/pulls/113
+    # this should be checked before GHA because upstream maintains compatibility
+    # with GHA by also providing GHA-style preset variables
+    # TODO: also detect Forgejo
+    elif os_environ.get("GITEA_ACTIONS", "") == "true":
+        return "gitea"
+    # https://gitee.com/help/articles/4358#article-header8
+    elif "GITEE_PIPELINE_NAME" in os_environ:
+        return "gitee"
+    # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables
+    elif os_environ.get("GITHUB_ACTIONS", "") == "true":
+        return "github"
+    # https://docs.gitlab.com/ee/ci/variables/predefined_variables.html#predefined-variables
+    elif os_environ.get("GITLAB_CI", "") == "true":
+        return "gitlab"
+    # https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#using-environment-variables
+    # may have false-negatives but likely no false-positives
+    elif "JENKINS_URL" in os_environ:
+        return "jenkins"
+    # https://gitee.com/openeuler/mugen
+    # seems nothing except $OET_PATH is guaranteed
+    elif "OET_PATH" in os_environ:
+        return "mugen"
+    # there seems to be no designated marker for openQA, test a couple of
+    # hopefully ubiquitous variables to avoid going through the entire key set
+    elif "OPENQA_CONFIG" in os_environ or "OPENQA_URL" in os_environ:
+        return "openqa"
+    # https://docs.travis-ci.com/user/environment-variables/#default-environment-variables
+    elif os_environ.get("TRAVIS", "") == "true":
+        return "travis"
+    # https://docs.koderover.com/zadig/Zadig%20v3.1/project/build/
+    # https://github.com/koderover/zadig/blob/v3.1.0/pkg/microservice/jobexecutor/core/service/job.go#L117
+    elif os_environ.get("ZADIG", "") == "true":
+        return "zadig"
+    elif os_environ.get("CI", "") == "true":
+        return "unidentified"
+
+    return None

ruyi/utils/frontmatter.py

@@ -0,0 +1,38 @@
+# Minimal frontmatter support for Markdown, because [python-frontmatter] is
+# not packaged in major Linux distributions, complicating packaging work.
+#
+# Only the YAML frontmatter is supported here, unlike python-frontmatter
+# which supports additionally JSON and TOML frontmatter formats.
+#
+# [python-frontmatter]: https://github.com/eyeseast/python-frontmatter
+
+import re
+from typing import Final
+import yaml
+
+
+FRONTMATTER_BOUNDARY_RE: Final = re.compile(r"(?m)^-{3,}\s*$")
+
+
+class Post:
+    def __init__(self, metadata: dict[str, object] | None, content: str) -> None:
+        self._md = metadata
+        self.content = content
+
+    def get(self, key: str) -> object | None:
+        return None if self._md is None else self._md.get(key)
+
+
+def loads(s: str) -> Post:
+    m = FRONTMATTER_BOUNDARY_RE.match(s)
+    if m is None:
+        return Post(None, s)
+
+    x = FRONTMATTER_BOUNDARY_RE.split(s, 2)
+    if len(x) != 3:
+        return Post(None, s)
+
+    fm, content = x[1], x[2]
+
+    metadata = yaml.safe_load(fm)
+    return Post(metadata, content)

ruyi/utils/git.py

@@ -0,0 +1,169 @@
+from contextlib import AbstractContextManager
+import pathlib
+from typing import Any, TYPE_CHECKING
+
+from pygit2 import GitError, Oid
+from pygit2.callbacks import RemoteCallbacks
+from pygit2.repository import Repository
+
+try:
+    from pygit2.remotes import TransferProgress
+except ModuleNotFoundError:
+    # pygit2 < 1.14.0
+    # see https://github.com/libgit2/pygit2/commit/a8b2421bea550292
+    #
+    # import-untyped: the current pygit2 type stubs were written after the
+    # `remote` -> `remotes` rename, so no stubs for it
+    from pygit2.remote import TransferProgress  # type: ignore[import-not-found,import-untyped,no-redef,unused-ignore]
+
+# for compatibility with <1.14.0, cannot `from pygit2.enums import MergeAnalysis`
+# see https://github.com/libgit2/pygit2/pull/1251
+from pygit2 import (
+    GIT_MERGE_ANALYSIS_UNBORN,
+    GIT_MERGE_ANALYSIS_FASTFORWARD,
+    GIT_MERGE_ANALYSIS_UP_TO_DATE,
+)
+
+from rich.progress import Progress, TaskID
+from rich.text import Text
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+from ..log import RuyiLogger
+
+
+def human_readable_path_of_repo(repo: Repository) -> pathlib.Path:
+    """
+    Returns a human-readable path of the repository.
+    If the repository is a submodule, returns the path to the parent module.
+    """
+    repo_path = pathlib.Path(repo.path)
+    return repo_path.parent if repo_path.name == ".git" else repo_path
+
+
+class RemoteGitProgressIndicator(
+    RemoteCallbacks,
+    AbstractContextManager["RemoteGitProgressIndicator"],
+):
+    def __init__(self) -> None:
+        super().__init__()
+        self.p = Progress()
+        self.task: TaskID | None = None
+        self._last_stats: TransferProgress | None = None
+        self._task_name: str = ""
+
+    def __enter__(self) -> "Self":
+        self.p.__enter__()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_value: Any, tb: Any) -> None:
+        return self.p.__exit__(exc_type, exc_value, tb)
+
+    # Compatibility with pygit2 < 1.8.0.
+    def progress(self, string: str) -> None:
+        return self.sideband_progress(string)
+
+    def sideband_progress(self, string: str) -> None:
+        self.p.console.print("\r", Text(string), sep="", end="")
+
+    def transfer_progress(self, stats: TransferProgress) -> None:
+        new_phase = False
+        task_name: str = self._task_name
+        total: int = 0
+        completed: int = 0
+
+        if (
+            self._last_stats is None
+            or self._last_stats.received_objects != stats.received_objects
+        ):
+            task_name = "transferring objects"
+            total = stats.total_objects
+            completed = stats.received_objects
+        elif self._last_stats.indexed_deltas != stats.indexed_deltas:
+            task_name = "processing deltas"
+            total = stats.total_deltas
+            completed = stats.indexed_deltas
+        elif self._last_stats.received_bytes != stats.received_bytes:
+            # we don't render the received size at the moment
+            pass
+
+        new_phase = self._task_name != task_name
+        if new_phase:
+            self.task = self.p.add_task(task_name, total=total, completed=completed)
+            self._task_name = task_name
+        else:
+            if self.task is not None:
+                self.p.update(self.task, total=total, completed=completed)
+
+        self._last_stats = stats
+
+
+# based on https://stackoverflow.com/questions/27749418/implementing-pull-with-pygit2
+def pull_ff_or_die(
+    logger: RuyiLogger,
+    repo: Repository,
+    remote_name: str,
+    remote_url: str,
+    branch_name: str,
+    *,
+    allow_auto_management: bool,
+) -> None:
+    remote = repo.remotes[remote_name]
+    if remote.url != remote_url:
+        if not allow_auto_management:
+            logger.F(
+                f"URL of remote '[yellow]{remote_name}[/]' does not match expected URL"
+            )
+            repo_path = human_readable_path_of_repo(repo)
+            logger.I(f"repository:          [yellow]{repo_path}[/]")
+            logger.I(f"expected remote URL: [yellow]{remote_url}[/]")
+            logger.I(f"actual remote URL:   [yellow]{remote.url}[/]")
+            logger.I("please fix the repo settings manually")
+            raise SystemExit(1)
+
+        logger.D(
+            f"updating url of remote {remote_name} from {remote.url} to {remote_url}"
+        )
+        repo.remotes.set_url("origin", remote_url)
+
+    logger.D("fetching")
+    try:
+        with RemoteGitProgressIndicator() as pr:
+            remote.fetch(callbacks=pr)
+    except GitError as e:
+        logger.F(f"failed to fetch from remote URL {remote_url}: {e}")
+        raise SystemExit(1) from e
+
+    remote_head_ref = repo.lookup_reference(f"refs/remotes/{remote_name}/{branch_name}")
+    remote_head: Oid
+    if isinstance(remote_head_ref.target, Oid):
+        remote_head = remote_head_ref.target
+    else:
+        assert isinstance(remote_head_ref.target, str)
+        remote_head = Oid(hex=remote_head_ref.target)
+
+    merge_analysis, _ = repo.merge_analysis(remote_head)
+
+    if merge_analysis & GIT_MERGE_ANALYSIS_UP_TO_DATE:
+        # nothing to do
+        logger.D("repo state already up-to-date")
+        return
+
+    if merge_analysis & (GIT_MERGE_ANALYSIS_UNBORN | GIT_MERGE_ANALYSIS_FASTFORWARD):
+        # simple fast-forwarding is enough in both cases
+        logger.D(f"fast-forwarding repo to {remote_head}")
+        tgt = repo.get(remote_head)
+        assert tgt is not None
+        repo.checkout_tree(tgt)
+
+        logger.D(f"updating branch {branch_name} HEAD")
+        local_branch_ref = repo.lookup_reference(f"refs/heads/{branch_name}")
+        local_branch_ref.set_target(remote_head)
+        repo.head.set_target(remote_head)
+        return
+
+    # cannot handle these cases
+    logger.F("cannot fast-forward repo to newly fetched state")
+    logger.I("manual intervention is required to avoid data loss")
+    raise SystemExit(1)

ruyi/utils/global_mode.py

@@ -0,0 +1,204 @@
+import abc
+import os
+from typing import Final, Mapping, Protocol, runtime_checkable
+
+import ruyi
+
+ENV_DEBUG: Final = "RUYI_DEBUG"
+ENV_EXPERIMENTAL: Final = "RUYI_EXPERIMENTAL"
+ENV_FORCE_ALLOW_ROOT: Final = "RUYI_FORCE_ALLOW_ROOT"
+ENV_TELEMETRY_OPTOUT_KEY: Final = "RUYI_TELEMETRY_OPTOUT"
+ENV_VENV_ROOT_KEY: Final = "RUYI_VENV"
+
+TRUTHY_ENV_VAR_VALUES: Final = {"1", "true", "x", "y", "yes"}
+
+
+def is_env_var_truthy(env: Mapping[str, str], var: str) -> bool:
+    if v := env.get(var):
+        return v.lower() in TRUTHY_ENV_VAR_VALUES
+    return False
+
+
+@runtime_checkable
+class ProvidesGlobalMode(Protocol):
+    @property
+    def argv0(self) -> str: ...
+
+    @property
+    def main_file(self) -> str: ...
+
+    @property
+    def self_exe(self) -> str: ...
+
+    @property
+    def is_debug(self) -> bool: ...
+
+    @property
+    def is_experimental(self) -> bool: ...
+
+    @property
+    def is_packaged(self) -> bool: ...
+
+    @property
+    def is_porcelain(self) -> bool: ...
+
+    @property
+    def is_telemetry_optout(self) -> bool: ...
+
+    @property
+    def is_cli_autocomplete(self) -> bool: ...
+
+    @property
+    def venv_root(self) -> str | None: ...
+
+
+class GlobalModeProvider(metaclass=abc.ABCMeta):
+    """
+    Abstract base class for global mode providers.
+    """
+
+    @property
+    @abc.abstractmethod
+    def argv0(self) -> str:
+        return ""
+
+    @property
+    @abc.abstractmethod
+    def main_file(self) -> str:
+        return ""
+
+    @property
+    @abc.abstractmethod
+    def self_exe(self) -> str:
+        return ""
+
+    def record_self_exe(self, argv0: str, main_file: str, self_exe: str) -> None:
+        pass
+
+    @property
+    @abc.abstractmethod
+    def is_debug(self) -> bool:
+        return False
+
+    @property
+    @abc.abstractmethod
+    def is_experimental(self) -> bool:
+        return False
+
+    @property
+    @abc.abstractmethod
+    def is_packaged(self) -> bool:
+        return False
+
+    @property
+    @abc.abstractmethod
+    def is_porcelain(self) -> bool:
+        return False
+
+    @is_porcelain.setter
+    @abc.abstractmethod
+    def is_porcelain(self, v: bool) -> None:
+        pass
+
+    @property
+    @abc.abstractmethod
+    def is_telemetry_optout(self) -> bool:
+        return False
+
+    @property
+    @abc.abstractmethod
+    def is_cli_autocomplete(self) -> bool:
+        return False
+
+    @property
+    @abc.abstractmethod
+    def venv_root(self) -> str | None:
+        return None
+
+
+def _guess_porcelain_from_argv(argv: list[str]) -> bool:
+    """
+    Guess if the current invocation is a "porcelain" command based on the
+    arguments passed, without requiring the ``argparse`` machinery to be
+    completely initialized.
+    """
+    # If the first argument is `--porcelain`, we assume it's a porcelain command.
+    # This is currently accurate as the porcelain flag is only possible at this
+    # position right now.
+    return len(argv) > 1 and argv[1] == "--porcelain"
+
+
+class EnvGlobalModeProvider(GlobalModeProvider):
+    def __init__(
+        self,
+        env: Mapping[str, str] | None = None,
+        argv: list[str] | None = None,
+    ) -> None:
+        if env is None:
+            env = os.environ
+        if argv is None:
+            argv = []
+
+        self._argv0 = ""
+        self._main_file = ""
+        self._self_exe = ""
+
+        self._is_debug = is_env_var_truthy(env, ENV_DEBUG)
+        self._is_experimental = is_env_var_truthy(env, ENV_EXPERIMENTAL)
+        self._is_porcelain = _guess_porcelain_from_argv(argv)
+        self._is_telemetry_optout = is_env_var_truthy(env, ENV_TELEMETRY_OPTOUT_KEY)
+
+        # We have to lift this piece of implementation detail out of argcomplete,
+        # as the argcomplete import is very costly in terms of startup time.
+        self._is_cli_autocomplete = "_ARGCOMPLETE" in os.environ
+
+        self._venv_root = env.get(ENV_VENV_ROOT_KEY)
+
+    @property
+    def argv0(self) -> str:
+        return self._argv0
+
+    @property
+    def main_file(self) -> str:
+        return self._main_file
+
+    @property
+    def self_exe(self) -> str:
+        return self._self_exe
+
+    def record_self_exe(self, argv0: str, main_file: str, self_exe: str) -> None:
+        self._argv0 = argv0
+        self._main_file = main_file
+        self._self_exe = self_exe
+
+    @property
+    def is_debug(self) -> bool:
+        return self._is_debug
+
+    @property
+    def is_experimental(self) -> bool:
+        return self._is_experimental
+
+    @property
+    def is_packaged(self) -> bool:
+        return hasattr(ruyi, "__compiled__")
+
+    @property
+    def is_porcelain(self) -> bool:
+        return self._is_porcelain
+
+    @is_porcelain.setter
+    def is_porcelain(self, v: bool) -> None:
+        self._is_porcelain = v
+
+    @property
+    def is_telemetry_optout(self) -> bool:
+        return self._is_telemetry_optout
+
+    @property
+    def is_cli_autocomplete(self) -> bool:
+        return self._is_cli_autocomplete
+
+    @property
+    def venv_root(self) -> str | None:
+        return self._venv_root