ruyi 0.41.0b20250926__py3-none-any.whl → 0.42.0__py3-none-any.whl

ruyi/config/schema.py

@@ -1,6 +1,6 @@
 import datetime
 import sys
-from typing import Final, Sequence
+from typing import Final, Sequence, TypeGuard
 
 from .errors import (
     InvalidConfigKeyError,
@@ -43,7 +43,7 @@ def validate_section(section: str) -> None:
         raise InvalidConfigSectionError(section)
 
 
-def get_expected_type_for_config_key(key: str | Sequence[str]) -> type:
+def get_expected_type_for_config_key(key: str | Sequence[str]) -> type | Sequence[type]:
     parsed_key = parse_config_key(key)
     if len(parsed_key) != 2:
         # for now there's no nested config option
@@ -87,17 +87,29 @@ def _get_expected_type_for_section_repo(sel: str) -> type:
         raise InvalidConfigKeyError(sel)
 
 
-def _get_expected_type_for_section_telemetry(sel: str) -> type:
+def _get_expected_type_for_section_telemetry(sel: str) -> type | tuple[type, ...]:
     if sel == KEY_TELEMETRY_MODE:
         return str
     elif sel == KEY_TELEMETRY_PM_TELEMETRY_URL:
         return str
     elif sel == KEY_TELEMETRY_UPLOAD_CONSENT:
-        return datetime.datetime
+        return (type(None), datetime.datetime)
     else:
         raise InvalidConfigKeyError(sel)
 
 
+def _is_all_str(obj: object) -> TypeGuard[Sequence[str]]:
+    if not isinstance(obj, Sequence):
+        return False
+    return all(isinstance(i, str) for i in obj)
+
+
+def _is_all_type(obj: object) -> TypeGuard[Sequence[type]]:
+    if not isinstance(obj, Sequence):
+        return False
+    return all(isinstance(i, type) for i in obj)
+
+
 def ensure_valid_config_kv(
     key: str | Sequence[str],
     check_val: bool = False,
@@ -108,9 +120,9 @@ def ensure_valid_config_kv(
         # for now there's no nested config option
         raise InvalidConfigKeyError(key)
 
-    expected_type = get_expected_type_for_config_key(parsed_key)
+    expected_types = get_expected_type_for_config_key(parsed_key)
     # validity of config key is already checked by get_expected_type_for_config_key
-    _ensure_value_type(key, check_val, val, expected_type)
+    ensure_value_type(key, check_val, val, expected_types)
 
     if not check_val:
         return
@@ -120,14 +132,26 @@ def ensure_valid_config_kv(
         return _extra_validate_section_telemetry_kv(key, sel, val)
 
 
-def _ensure_value_type(
+def ensure_value_type(
     key: str | Sequence[str],
     check_val: bool,
     val: object | None,
-    expected: type,
+    expected: type | Sequence[type],
 ) -> None:
-    if check_val and not isinstance(val, expected):
-        raise InvalidConfigValueTypeError(key, val, expected)
+    if not check_val:
+        return
+
+    expected_types: tuple[type, ...]
+    if isinstance(expected, type):
+        expected_types = (expected,)
+    else:
+        expected_types = tuple(expected)
+
+    for ty in expected_types:
+        if isinstance(val, ty):
+            return
+
+    raise InvalidConfigValueTypeError(key, val, expected)
 
 
 def _extra_validate_section_telemetry_kv(
@@ -138,13 +162,18 @@ def _extra_validate_section_telemetry_kv(
     if sel == KEY_TELEMETRY_MODE:
         # value type is already ensured earlier
         if val not in ("local", "off", "on"):
-            raise InvalidConfigValueError(key, val)
+            raise InvalidConfigValueError(key, val, str)
 
 
 def encode_value(v: object) -> str:
     """Encodes the given config value into a string representation suitable for
     display or storage into TOML config files."""
 
+    if v is None:
+        from ..utils.toml import NoneValue
+
+        raise NoneValue()
+
     if isinstance(v, bool):
         return "true" if v else "false"
     elif isinstance(v, int):
@@ -164,24 +193,50 @@ def encode_value(v: object) -> str:
 
 
 def decode_value(
-    key: str | Sequence[str] | type,
+    key: str | Sequence[str],
     val: str,
 ) -> object:
     """Decodes the given string representation of a config value into a Python
     value, directed by type information implied by the config key."""
 
     if isinstance(key, type):
-        expected_type = key
-    else:
-        expected_type = get_expected_type_for_config_key(key)
+        return _decode_single_type_value(None, val, key)
+    elif _is_all_type(key):
+        return _decode_typed_value(None, val, key)
+
+    assert isinstance(key, str) or _is_all_str(key)
+    expected_types = get_expected_type_for_config_key(key)
 
+    if isinstance(expected_types, type):
+        return _decode_single_type_value(key, val, expected_types)
+    return _decode_typed_value(key, val, expected_types)
+
+
+def _decode_typed_value(
+    key: str | Sequence[str] | None,
+    val: str,
+    expected_types: Sequence[type],
+) -> object:
+    for ty in expected_types:
+        try:
+            return _decode_single_type_value(key, val, ty)
+        except (RuntimeError, TypeError, ValueError):
+            continue
+    raise InvalidConfigValueError(key, val, expected_types)
+
+
+def _decode_single_type_value(
+    key: str | Sequence[str] | None,
+    val: str,
+    expected_type: type,
+) -> object:
     if expected_type is bool:
         if val in ("true", "yes", "1"):
             return True
         elif val in ("false", "no", "0"):
             return False
         else:
-            raise InvalidConfigValueError(key, val)
+            raise InvalidConfigValueError(key, val, expected_type)
     elif expected_type is int:
         return int(val, 10)
     elif expected_type is str:
@@ -194,4 +249,4 @@ def decode_value(
         v = datetime.datetime.fromisoformat(val)
         return v.astimezone() if v.tzinfo is None else v
     else:
-        raise NotImplementedError(f"invalid type for config value: {expected_type}")
+        raise NotImplementedError(f"unhandled type for config value: {expected_type}")

ruyi/device/provision.py

@@ -276,7 +276,7 @@ We are about to:
                 """
 Some flashing steps require the use of fastboot, in which case you should
 ensure the target device is showing up in [yellow]fastboot devices[/] output.
-Please confirm it yourself before the flashing begins.
+Please [bold red]confirm it yourself before continuing[/].
 """
             )
             if not user_input.ask_for_yesno_confirmation(

ruyi/pluginhost/api.py

@@ -44,7 +44,7 @@ class RuyiHostAPI:
 
     @property
     def ruyi_version(self) -> str:
-        return str(RUYI_SEMVER)
+        return RUYI_SEMVER
 
     @property
     def ruyi_plugin_api_rev(self) -> int:

ruyi/ruyipkg/distfile.py

@@ -1,10 +1,10 @@
 from functools import cached_property
 import os
-from typing import Final
+from typing import Any, Final
 
 from ..log import RuyiLogger
 from .checksum import Checksummer
-from .fetch import BaseFetcher
+from .fetcher import BaseFetcher
 from .pkg_manifest import DistfileDecl
 from .repo import MetadataRepo
 from .unpack import do_unpack, do_unpack_or_symlink
@@ -187,7 +187,11 @@ class Distfile:
                 f"failed to fetch distfile: {self.dest} failed integrity checks"
             )
 
-    def unpack(self, root: str | None, logger: RuyiLogger) -> None:
+    def unpack(
+        self,
+        root: str | os.PathLike[Any] | None,
+        logger: RuyiLogger,
+    ) -> None:
         return do_unpack(
             logger,
             self.dest,
@@ -197,7 +201,11 @@ class Distfile:
             prefixes_to_unpack=self.prefixes_to_unpack,
         )
 
-    def unpack_or_symlink(self, root: str | None, logger: RuyiLogger) -> None:
+    def unpack_or_symlink(
+        self,
+        root: str | os.PathLike[Any] | None,
+        logger: RuyiLogger,
+    ) -> None:
         return do_unpack_or_symlink(
             logger,
             self.dest,

ruyi/ruyipkg/install.py

@@ -1,7 +1,8 @@
-import os.path
+import os
 import pathlib
 import shutil
 import tempfile
+from typing import Any
 
 from ruyi.ruyipkg.state import BoundInstallationStateStore
 
@@ -29,6 +30,9 @@ def do_extract_atoms(
     atom_strs: set[str],
     *,
     canonicalized_host: str | RuyiHost,
+    dest_dir: os.PathLike[Any] | None,  # None for CWD
+    extract_without_subdir: bool,
+    fetch_only: bool,
 ) -> int:
     logger = cfg.logger
     logger.D(f"about to extract for host {canonicalized_host}: {atom_strs}")
@@ -41,7 +45,6 @@ def do_extract_atoms(
         if pm is None:
             logger.F(f"atom {a_str} matches no package in the repository")
             return 1
-        pkg_name = pm.name_for_installation
 
         sv = pm.service_level
         if sv.has_known_issues:
@@ -49,43 +52,92 @@ def do_extract_atoms(
             for s in sv.render_known_issues(pm.repo.messages, cfg.lang_code):
                 logger.I(s)
 
-        bm = pm.binary_metadata
-        sm = pm.source_metadata
-        if bm is None and sm is None:
-            logger.F(f"don't know how to extract package [green]{pkg_name}[/]")
-            return 2
+        ret = _do_extract_pkg(
+            cfg,
+            pm,
+            canonicalized_host=canonicalized_host,
+            fetch_only=fetch_only,
+            dest_dir=dest_dir,
+            extract_without_subdir=extract_without_subdir,
+        )
+        if ret != 0:
+            return ret
 
-        if bm is not None and sm is not None:
-            logger.F(
-                f"cannot handle package [green]{pkg_name}[/]: package is both binary and source"
-            )
-            return 2
+    return 0
 
-        distfiles_for_host: list[str] | None = None
-        if bm is not None:
-            distfiles_for_host = bm.get_distfile_names_for_host(canonicalized_host)
-        elif sm is not None:
-            distfiles_for_host = sm.get_distfile_names_for_host(canonicalized_host)
 
-        if not distfiles_for_host:
-            logger.F(
-                f"package [green]{pkg_name}[/] declares no distfile for host {canonicalized_host}"
-            )
-            return 2
+def _do_extract_pkg(
+    cfg: GlobalConfig,
+    pm: BoundPackageManifest,
+    *,
+    canonicalized_host: str | RuyiHost,
+    dest_dir: os.PathLike[Any] | None,  # None for CWD
+    extract_without_subdir: bool,
+    fetch_only: bool,
+) -> int:
+    logger = cfg.logger
 
-        dfs = pm.distfiles
+    pkg_name = pm.name_for_installation
 
-        for df_name in distfiles_for_host:
-            df_decl = dfs[df_name]
-            ensure_unpack_cmd_for_method(logger, df_decl.unpack_method)
-            df = Distfile(df_decl, mr)
-            df.ensure(logger)
+    if not extract_without_subdir:
+        # extract into a subdirectory named <pkg_name>-<version>
+        subdir_name = pm.name_for_installation
+        if dest_dir is None:
+            dest_dir = pathlib.Path(subdir_name)
+        else:
+            dest_dir = pathlib.Path(dest_dir) / subdir_name
 
-            logger.I(f"extracting [green]{df_name}[/] for package [green]{pkg_name}[/]")
-            # unpack into CWD
-            df.unpack(None, logger)
+    logger.D(f"about to extract {pm} to {dest_dir}")
 
-        logger.I(f"package [green]{pkg_name}[/] extracted to current working directory")
+    # Make sure destination directory exists
+    if dest_dir is not None:
+        dest_dir = pathlib.Path(dest_dir)
+        dest_dir.mkdir(parents=True, exist_ok=True)
+
+    bm = pm.binary_metadata
+    sm = pm.source_metadata
+    if bm is None and sm is None:
+        logger.F(f"don't know how to extract package [green]{pkg_name}[/]")
+        return 2
+
+    if bm is not None and sm is not None:
+        logger.F(
+            f"cannot handle package [green]{pkg_name}[/]: package is both binary and source"
+        )
+        return 2
+
+    distfiles_for_host: list[str] | None = None
+    if bm is not None:
+        distfiles_for_host = bm.get_distfile_names_for_host(canonicalized_host)
+    elif sm is not None:
+        distfiles_for_host = sm.get_distfile_names_for_host(canonicalized_host)
+
+    if not distfiles_for_host:
+        logger.F(
+            f"package [green]{pkg_name}[/] declares no distfile for host {canonicalized_host}"
+        )
+        return 2
+
+    dfs = pm.distfiles
+
+    for df_name in distfiles_for_host:
+        df_decl = dfs[df_name]
+        ensure_unpack_cmd_for_method(logger, df_decl.unpack_method)
+        df = Distfile(df_decl, pm.repo)
+        df.ensure(logger)
+
+        if fetch_only:
+            logger.D("skipping extraction because [yellow]--fetch-only[/] is given")
+            continue
+
+        logger.I(f"extracting [green]{df_name}[/] for package [green]{pkg_name}[/]")
+        # unpack into destination
+        df.unpack(dest_dir, logger)
+
+    if not fetch_only:
+        logger.I(
+            f"package [green]{pkg_name}[/] has been extracted to {dest_dir}",
+        )
 
     return 0
 
@@ -147,6 +199,21 @@ def do_install_atoms(
                 return ret
             continue
 
+        # the user may be trying to fetch a source-only package with `ruyi install --fetch-only`,
+        # so try that too for better UX
+        if fetch_only and pm.source_metadata is not None:
+            ret = _do_extract_pkg(
+                config,
+                pm,
+                canonicalized_host=canonicalized_host,
+                dest_dir=None,  # unused in this case
+                extract_without_subdir=False,  # unused in this case
+                fetch_only=fetch_only,
+            )
+            if ret != 0:
+                return ret
+            continue
+
         logger.F(f"don't know how to handle non-binary package [green]{pkg_name}[/]")
         return 2
 

ruyi/ruyipkg/install_cli.py

@@ -1,4 +1,5 @@
 import argparse
+import pathlib
 from typing import TYPE_CHECKING
 
 from ..cli.cmd import RootCommand
@@ -26,6 +27,25 @@ class ExtractCommand(
         if gc.is_cli_autocomplete:
             a.completer = package_completer_builder(gc)
 
+        p.add_argument(
+            "-d",
+            "--dest-dir",
+            type=str,
+            metavar="DESTDIR",
+            default=".",
+            help="Destination directory to extract to (default: current directory)",
+        )
+        p.add_argument(
+            "--extract-without-subdir",
+            action="store_true",
+            help="Extract files directly into DESTDIR instead of package-named subdirectories",
+        )
+        p.add_argument(
+            "-f",
+            "--fetch-only",
+            action="store_true",
+            help="Fetch distribution files only without installing",
+        )
         p.add_argument(
             "--host",
             type=str,
@@ -38,14 +58,22 @@ class ExtractCommand(
         from .host import canonicalize_host_str
         from .install import do_extract_atoms
 
-        host: str = args.host
         atom_strs: set[str] = set(args.atom)
+        dest_dir_arg: str = args.dest_dir
+        extract_without_subdir: bool = args.extract_without_subdir
+        host: str = args.host
+        fetch_only: bool = args.fetch_only
+
+        dest_dir = None if dest_dir_arg == "." else pathlib.Path(dest_dir_arg)
 
         return do_extract_atoms(
             cfg,
             cfg.repo,
             atom_strs,
             canonicalized_host=canonicalize_host_str(host),
+            dest_dir=dest_dir,
+            extract_without_subdir=extract_without_subdir,
+            fetch_only=fetch_only,
         )
 
 

ruyi/ruyipkg/profile.py

@@ -1,7 +1,21 @@
 from os import PathLike
-from typing import Any, Iterable, TypeGuard, cast
+from typing import (
+    Any,
+    Iterable,
+    Mapping,
+    Protocol,
+    Sequence,
+    TypedDict,
+    TypeGuard,
+    TYPE_CHECKING,
+    cast,
+)
+
+if TYPE_CHECKING:
+    from typing_extensions import NotRequired
 
 from ..pluginhost.ctx import PluginHostContext, SupportsEvalFunction
+from .entity_provider import BaseEntityProvider
 from .pkg_manifest import EmulatorFlavor
 
 
@@ -206,3 +220,136 @@ class ProfileProxy:
         sysroot: PathLike[Any] | None,
     ) -> dict[str, str] | None:
         return self._provider.get_env_config_for_emu_flavor(self._id, flavor, sysroot)
+
+
+#
+# Protocols
+#
+
+
+# MetadataRepo is defined in repo.py, but we don't want to import repo.py here
+# to avoid circular import. Instead, we just describe the methods and properties
+# that we need from MetadataRepo with a Protocol.
+class ProvidesProfiles(Protocol):
+    def get_supported_arches(self) -> list[str]: ...
+    def get_profile_for_arch(self, arch: str, name: str) -> ProfileProxy | None: ...
+    def iter_profiles_for_arch(self, arch: str) -> Iterable[ProfileProxy]: ...
+
+
+#
+# Entity type and schema for profile entities
+#
+
+PROFILE_V1_ENTITY_TYPE = "profile-v1"
+PROFILE_V1_ENTITY_TYPE_SCHEMA = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "required": ["profile-v1"],
+    "properties": {
+        "profile-v1": {
+            "type": "object",
+            "properties": {
+                "id": {"type": "string"},
+                "display_name": {"type": "string"},
+                "name": {"type": "string"},
+                "arch": {"type": "string"},
+                "needed_toolchain_quirks": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                },
+                "toolchain_common_flags_str": {"type": "string"},
+            },
+            "required": [
+                "id",
+                "display_name",
+                "name",
+                "arch",
+                "needed_toolchain_quirks",
+                "toolchain_common_flags_str",
+            ],
+        },
+        "related": {
+            "type": "array",
+            "description": "List of related entity references",
+            "items": {"type": "string", "pattern": "^.+:.+"},
+        },
+        "unique_among_type_during_traversal": {
+            "type": "boolean",
+            "description": "Whether this entity should be unique among all entities of the same type during traversal",
+        },
+    },
+}
+
+
+class ProfileV1EntityData(TypedDict):
+    id: str
+    display_name: str
+    name: str
+    arch: str
+    needed_toolchain_quirks: list[str]
+    toolchain_common_flags_str: str
+
+
+ProfileV1Entity = TypedDict(
+    "ProfileV1Entity",
+    {
+        "profile-v1": ProfileV1EntityData,
+        "related": "NotRequired[list[str]]",
+        "unique_among_type_during_traversal": "NotRequired[bool]",
+    },
+    total=False,
+)
+
+
+class ProfileEntityProvider(BaseEntityProvider):
+    def __init__(self, provider: ProvidesProfiles) -> None:
+        super().__init__()
+        self._provider = provider
+
+    def discover_schemas(self) -> dict[str, object]:
+        return {
+            PROFILE_V1_ENTITY_TYPE: PROFILE_V1_ENTITY_TYPE_SCHEMA,
+        }
+
+    def load_entities(
+        self,
+        entity_types: Sequence[str],
+    ) -> Mapping[str, Mapping[str, Mapping[str, Any]]]:
+        result: dict[str, Mapping[str, Mapping[str, Any]]] = {}
+        for ty in entity_types:
+            if ty == PROFILE_V1_ENTITY_TYPE:
+                result[ty] = _load_profile_v1_entities(self._provider)
+        return result
+
+
+def _load_profile_v1_entities(provider: ProvidesProfiles) -> dict[str, ProfileV1Entity]:
+    result: dict[str, ProfileV1Entity] = {}
+    for arch in provider.get_supported_arches():
+        result.update(_load_profile_v1_entities_for_arch(provider, arch))
+    return result
+
+
+def _load_profile_v1_entities_for_arch(
+    provider: ProvidesProfiles,
+    arch: str,
+) -> dict[str, ProfileV1Entity]:
+    result: dict[str, ProfileV1Entity] = {}
+    for profile in provider.iter_profiles_for_arch(arch):
+        full_name = profile.id
+        relations = [f"arch:{arch}"]
+
+        needed_toolchain_quirks = sorted(profile.need_quirks)
+
+        result[profile.id] = {
+            "profile-v1": {
+                "id": profile.id,
+                "display_name": full_name,
+                "name": profile.id,
+                "arch": profile.arch,
+                "needed_toolchain_quirks": needed_toolchain_quirks,
+                "toolchain_common_flags_str": profile.get_common_flags(
+                    needed_toolchain_quirks,
+                ),
+            },
+            "related": relations,
+        }
+    return result

ruyi/ruyipkg/repo.py

@@ -34,7 +34,7 @@ from .pkg_manifest import (
     InputPackageManifestType,
     is_prerelease,
 )
-from .profile import PluginProfileProvider, ProfileProxy
+from .profile import PluginProfileProvider, ProfileEntityProvider, ProfileProxy
 from .protocols import ProvidesPackageManifests
 
 if sys.version_info >= (3, 11):
@@ -234,6 +234,7 @@ class MetadataRepo(ProvidesPackageManifests):
             gc.logger,
             FSEntityProvider(gc.logger, pathlib.Path(self.root) / "entities"),
             MetadataRepoEntityProvider(self),
+            ProfileEntityProvider(self),
         )
         self._plugin_host_ctx = PluginHostContext.new(gc.logger, self.plugin_root)
         self._plugin_fn_evaluator = self._plugin_host_ctx.make_evaluator()
@@ -284,7 +285,9 @@ class MetadataRepo(ProvidesPackageManifests):
             self.repo = Repository(self.root)
             return self.repo
 
-        self.logger.I(f"the package repository does not exist at [yellow]{self.root}[/]")
+        self.logger.I(
+            f"the package repository does not exist at [yellow]{self.root}[/]"
+        )
         self.logger.I(f"cloning from [cyan link={self.remote}]{self.remote}[/]")
 
         with RemoteGitProgressIndicator() as pr:
@@ -313,7 +316,7 @@ class MetadataRepo(ProvidesPackageManifests):
 
         # only manage the repo settings on the user's behalf if the user
         # has not overridden the repo directory themselves
-        allow_auto_management = self._gc.override_repo_dir is None
+        allow_auto_management = not self._gc.have_overridden_repo_dir
 
         pull_ff_or_die(
             self.logger,

ruyi/ruyipkg/state.py

@@ -76,6 +76,16 @@ class RuyipkgGlobalStateStore:
         """Ensure the state directory exists."""
         self.root.mkdir(parents=True, exist_ok=True)
 
+    def purge_installation_info(self) -> None:
+        """Purge installation records."""
+        self._installs_file.unlink(missing_ok=True)
+        self._installs_cache = None
+        # if the state dir is empty, remove it
+        try:
+            self.root.rmdir()
+        except OSError:
+            pass
+
     def _load_installs(self) -> dict[str, PackageInstallationInfo]:
         """Load installation records from disk."""
         if self._installs_cache is not None: