pyproject-external 0.1.0__py3-none-any.whl

pyproject_external/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2023 Quansight Labs
+"""
+pyproject-external - Utilities to work with PEP 725 `[external]` metadata
+"""
+
+from ._config import Config  # noqa
+from ._external import External  # noqa
+from ._registry import Registry, Ecosystems, Mapping, default_ecosystems, remote_mapping  # noqa
+from ._system import (  # noqa
+    find_ecosystem_for_package_manager,
+    detect_ecosystem_and_package_manager,
+    activated_conda_env,
+)
+from ._url import DepURL  # noqa
+from ._version import __version__
+
+__all__ = [
+    "__version__",
+    "Config",
+    "DepURL",
+    "Ecosystems",
+    "External",
+    "Mapping",
+    "Registry",
+    "activated_conda_env",
+    "find_ecosystem_for_package_manager",
+    "detect_ecosystem_and_package_manager",
+    "default_ecosystems",
+    "remote_mapping",
+]
+
+
+def __dir__() -> list[str]:
+    return __all__

pyproject_external/__main__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025 Quansight Labs
+
+if __name__ == "__main__":
+    import sys
+
+    from ._cli import app
+
+    sys.exit(app())

pyproject_external/_cli/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025 Quansight Labs
+
+from .app import app as app

pyproject_external/_cli/_utils.py

@@ -0,0 +1,39 @@
+import tarfile
+from enum import Enum
+from pathlib import Path
+
+import typer
+
+
+def _read_pyproject_from_sdist(path: Path) -> str:
+    with tarfile.open(path) as tar:
+        for info in tar.getmembers():
+            name = info.name
+            if "/" in name and name.split("/")[-1] == "pyproject.toml":
+                return tar.extractfile(info).read().decode()
+    raise ValueError("Could not read pyproject.toml file from sdist")
+
+
+def _pyproject_text(package: Path) -> str:
+    if package.is_file():
+        if not package.name.lower().endswith(".tar.gz"):
+            raise typer.BadParameter(f"Given package '{package}' is a file, but not a sdist.")
+        return _read_pyproject_from_sdist(package)
+    if package.is_dir():
+        return (package / "pyproject.toml").read_text()
+    raise typer.BadParameter(f"Package {package} is not a valid path.")
+
+
+class _Installers(str, Enum):
+    pip = "pip"
+    uv = "uv"
+
+
+class NotOnCIError(RuntimeError):
+    def __init__(self):
+        super().__init__(
+            "This tool should only be used in CI or ephemeral environments!\n\n"
+            "It will likely install system packages as a side effect of providing the "
+            "external dependencies required to build the wheels.\n\n"
+            "If you understand the risks, set CI=1 to override."
+        )

pyproject_external/_cli/app.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025 Quansight Labs
+"""
+CLI to work with PEP 725 external metadata.
+"""
+
+import logging
+
+import typer
+from rich.console import Console
+from rich.logging import RichHandler
+
+from .build import app as _install
+from .install import app as _build
+from .prepare import app as _prepare
+from .show import app as _show
+
+app = typer.Typer(
+    help=__doc__,
+    no_args_is_help=True,
+    add_completion=False,
+)
+app.add_typer(_show)
+app.add_typer(_build)
+app.add_typer(_install)
+app.add_typer(_prepare)
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(message)s",
+    datefmt="[%X]",
+    handlers=[RichHandler(console=Console(stderr=True))],
+)
+
+if __name__ == "__main__":
+    app()

pyproject_external/_cli/build.py

@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025 Quansight Labs
+"""
+Build a wheel for the given sdist or project.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+import sys
+import tarfile
+from contextlib import nullcontext
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import Annotated
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
+
+import typer
+
+from .. import (
+    Config,
+    External,
+    activated_conda_env,
+    detect_ecosystem_and_package_manager,
+    find_ecosystem_for_package_manager,
+)
+from ._utils import NotOnCIError, _Installers, _pyproject_text
+
+log = logging.getLogger(__name__)
+app = typer.Typer()
+
+
+@app.command(
+    help=__doc__,
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def build(
+    package: Annotated[
+        str,
+        typer.Argument(
+            help="Package to build wheel for."
+            "It can be a path to a pyproject.toml-containing directory, "
+            "or a source distribution."
+        ),
+    ],
+    package_manager: Annotated[
+        str,
+        typer.Option(
+            help="If given, use this package manager to install the external dependencies "
+            "rather than the auto-detected one."
+        ),
+    ] = Config.load_user_config().preferred_package_manager or "",
+    outdir: Annotated[
+        str | None,
+        typer.Option(help="Output directory for the wheel. Defaults to working directory"),
+    ] = None,
+    build_installer: Annotated[
+        _Installers,
+        typer.Option(
+            help="Which installer tool should be used to provide the isolated 'build' venv"
+        ),
+    ] = _Installers.pip,
+    unknown_args: typer.Context = typer.Option(()),
+) -> None:
+    if not os.environ.get("CI"):
+        raise NotOnCIError()
+
+    package = Path(package)
+    pyproject_text = _pyproject_text(package)
+    pyproject = tomllib.loads(pyproject_text)
+    external = External.from_pyproject_data(pyproject)
+    external.validate()
+
+    if package_manager:
+        ecosystem = find_ecosystem_for_package_manager(package_manager)
+    else:
+        ecosystem, package_manager = detect_ecosystem_and_package_manager()
+    log.info("Detected ecosystem '%s' for package manager '%s'", ecosystem, package_manager)
+
+    install_external_cmd = external.install_command(ecosystem, package_manager=package_manager)
+    build_cmd = [
+        sys.executable,
+        "-m",
+        "build",
+        "--wheel",
+        "--outdir",
+        outdir or os.getcwd(),
+        "--installer",
+        build_installer,
+        *unknown_args.args,
+    ]
+    try:
+        # 1. Install external dependencies
+        subprocess.run(install_external_cmd, check=True)
+        # 2. Build wheel
+        with (
+            activated_conda_env(package_manager=package_manager)
+            if ecosystem == "conda-forge"
+            else nullcontext(os.environ) as env
+        ):
+            if package.is_file():
+                with TemporaryDirectory() as tmp:
+                    with tarfile.open(package) as tar:
+                        tar.extractall(tmp, filter="data")
+                        tmp = Path(tmp)
+                        if (tmp / "pyproject.toml").is_file():
+                            extracted_package = tmp
+                        else:
+                            extracted_package = next(tmp.glob("*"))
+                        subprocess.run([*build_cmd, extracted_package], check=True, env=env)
+            else:
+                subprocess.run([*build_cmd, package], check=True, env=env)
+    except subprocess.CalledProcessError as exc:
+        sys.exit(exc.returncode)  # avoid unnecessary typer pretty traceback

pyproject_external/_cli/install.py

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025 Quansight Labs
+"""
+Install a project in the given location. Wheels will be built as needed.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+import sys
+from contextlib import nullcontext
+from pathlib import Path
+from typing import Annotated
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
+
+import typer
+
+from .. import (
+    Config,
+    External,
+    activated_conda_env,
+    detect_ecosystem_and_package_manager,
+    find_ecosystem_for_package_manager,
+)
+from ._utils import NotOnCIError, _Installers, _pyproject_text
+
+log = logging.getLogger(__name__)
+app = typer.Typer()
+
+
+@app.command(
+    help=__doc__,
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def install(
+    package: Annotated[
+        str,
+        typer.Argument(
+            help="Package to build wheel for."
+            "It can be a path to a pyproject.toml-containing directory, "
+            "or a source distribution."
+        ),
+    ],
+    package_manager: Annotated[
+        str,
+        typer.Option(
+            help="If given, use this package manager to install the external dependencies "
+            "rather than the auto-detected one."
+        ),
+    ] = Config.load_user_config().preferred_package_manager or "",
+    installer: Annotated[
+        _Installers,
+        typer.Option(help="Which tool should be used to install the package"),
+    ] = _Installers.pip,
+    unknown_args: typer.Context = typer.Option(()),
+) -> None:
+    if not os.environ.get("CI"):
+        raise NotOnCIError()
+
+    package = Path(package)
+    pyproject_text = _pyproject_text(package)
+    pyproject = tomllib.loads(pyproject_text)
+    external = External.from_pyproject_data(pyproject)
+    external.validate()
+
+    if package_manager:
+        ecosystem = find_ecosystem_for_package_manager(package_manager)
+    else:
+        ecosystem, package_manager = detect_ecosystem_and_package_manager()
+    log.info("Detected ecosystem '%s' for package manager '%s'", ecosystem, package_manager)
+
+    install_external_cmd = external.install_command(ecosystem, package_manager=package_manager)
+    if installer == _Installers.pip:
+        install_cmd = [sys.executable, "-m", "pip", "install"]
+    elif installer == _Installers.uv:
+        install_cmd = ["uv", "pip", "install", "--python", sys.executable]
+    else:
+        raise ValueError(f"Unrecognized 'installer': {installer}")
+
+    try:
+        # 1. Install external dependencies
+        subprocess.run(install_external_cmd, check=True)
+        # 2. Build wheel
+        with (
+            activated_conda_env(package_manager=package_manager)
+            if ecosystem == "conda-forge"
+            else nullcontext(os.environ) as env
+        ):
+            subprocess.run([*install_cmd, *unknown_args.args, package], check=True, env=env)
+    except subprocess.CalledProcessError as exc:
+        sys.exit(exc.returncode)  # avoid unnecessary typer pretty traceback

pyproject_external/_cli/prepare.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025 Quansight Labs
+"""
+Prepare a package for building with [external] metadata
+by downloading and patching its most recent sdist.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import Annotated
+
+import typer
+
+from .._sdist import (
+    append_external_metadata,
+    apply_patches,
+    create_new_sdist,
+    download_sdist,
+    untar_sdist,
+)
+
+log = logging.getLogger(__name__)
+app = typer.Typer()
+
+
+@app.command(help=__doc__)
+def prepare(
+    package_name: Annotated[
+        str,
+        typer.Argument(help="PyPI package name to download and patch."),
+    ],
+    external_metadata_dir: Annotated[
+        str,
+        typer.Option(
+            help="Search this directory to find a '<package_name>.toml' "
+            "file that contains an '[external]' table.",
+        ),
+    ] = "external_metadata",
+    patches_dir: Annotated[
+        str,
+        typer.Option(
+            help="Search this directory to find a '<package_name>.py' "
+            "script that will run additional patches on the sdist contents.",
+        ),
+    ] = "patches",
+    out_dir: Annotated[
+        str,
+        typer.Option(help="Directory where the patched sdist will be written to."),
+    ] = "sdist",
+) -> None:
+    with TemporaryDirectory() as tmp:
+        tmp = Path(tmp)
+        fname_sdist = download_sdist(package_name, tmp)
+        fname_pyproject_toml = untar_sdist(fname_sdist, tmp)
+        append_external_metadata(
+            fname_pyproject_toml,
+            package_name,
+            patches_dir=external_metadata_dir,
+        )
+        apply_patches(package_name, fname_pyproject_toml.parent, patches_dir=patches_dir)
+        Path(out_dir).mkdir(parents=True, exist_ok=True)
+        create_new_sdist(fname_sdist, tmp, out_dir or os.getcwd())

pyproject_external/_cli/show.py

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2023 Quansight Labs
+"""
+Query PEP 725 [external] metadata from pyproject.toml or source distributions.
+"""
+
+import logging
+import shlex
+from enum import Enum
+from pathlib import Path
+from typing import Annotated
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
+
+import tomli_w
+import typer
+from rich import print as rprint
+from rich.markup import escape
+
+# Only import from __init__ to make sure the only uses the public interface
+from .. import (
+    Config,
+    External,
+    detect_ecosystem_and_package_manager,
+    find_ecosystem_for_package_manager,
+)
+from ._utils import _pyproject_text
+
+log = logging.getLogger(__name__)
+app = typer.Typer()
+
+
+class _OutputChoices(Enum):
+    RAW = "raw"
+    NORMALIZED = "normalized"
+    MAPPED_TABLE = "mapped"
+    MAPPED_LIST = "mapped-list"
+    COMMAND = "command"
+
+
+@app.command(help=__doc__)
+def show(
+    package: Annotated[
+        str,
+        typer.Argument(
+            help="Package to analyze. It can be a path to a pyproject.toml-containing directory,"
+            " or a source distribution."
+        ),
+    ],
+    validate: Annotated[
+        bool,
+        typer.Option(help="Validate external dependencies against central registry."),
+    ] = False,
+    output: Annotated[
+        _OutputChoices,
+        typer.Option(
+            help="Choose output format. 'raw' prints the TOML table as is. "
+            "'normalized' processes the 'dep:' URLs before printing them. "
+            "'mapped' prints the dependencies mapped to the given ecosystem. "
+            "'command' prints the install command for the given package manager."
+        ),
+    ] = _OutputChoices.RAW.value,
+    package_manager: Annotated[
+        str,
+        typer.Option(help="If given, use this package manager rather than the auto-detected one."),
+    ] = Config.load_user_config().preferred_package_manager or "",
+) -> None:
+    package = Path(package)
+    pyproject_text = _pyproject_text(package)
+    pyproject = tomllib.loads(pyproject_text)
+    raw_external = pyproject.get("external")
+    if not raw_external:
+        raise typer.BadParameter("Package's pyproject.toml does not contain an 'external' table.")
+
+    external = External.from_pyproject_data(pyproject)
+    if validate:
+        external.validate()
+
+    if output == _OutputChoices.RAW:
+        rprint(escape(tomli_w.dumps({"external": raw_external}).rstrip()))
+        return
+
+    if output == _OutputChoices.NORMALIZED:
+        rprint(escape(tomli_w.dumps(external.to_dict())))
+        return
+
+    if package_manager:
+        ecosystem = find_ecosystem_for_package_manager(package_manager)
+    else:
+        ecosystem, package_manager = detect_ecosystem_and_package_manager()
+    log.info("Detected ecosystem '%s' for package manager '%s'", ecosystem, package_manager)
+    if output == _OutputChoices.MAPPED_TABLE:
+        mapped_dict = external.to_dict(mapped_for=ecosystem, package_manager=package_manager)
+        rprint(escape(tomli_w.dumps(mapped_dict)))
+    # The following outputs might be used in shell substitutions like $(), so use print()
+    # directly. rich's print will hard-wrap the line and break the output.
+    elif output == _OutputChoices.COMMAND:
+        print(shlex.join(external.install_command(ecosystem, package_manager=package_manager)))
+    elif output == _OutputChoices.MAPPED_LIST:
+        print(shlex.join(external.map_dependencies(ecosystem, package_manager=package_manager)))
+    else:
+        raise typer.BadParameter(f"Unknown value for --output: {output}")

pyproject_external/_config.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025 Quansight Labs
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
+
+from platformdirs import user_config_dir
+
+from ._constants import APP_AUTHOR, APP_CONFIG_FILENAME, APP_NAME
+
+
+def _get_config_directory() -> Path:
+    if pyproject_external_config := os.environ.get("PYPROJECT_EXTERNAL_CONFIG"):
+        return Path(pyproject_external_config)
+    return Path(user_config_dir(appname=APP_NAME, appauthor=APP_AUTHOR))
+
+
+def _get_config_file() -> Path:
+    return _get_config_directory() / APP_CONFIG_FILENAME
+
+
+@dataclass(frozen=True, kw_only=True)
+class Config:
+    preferred_package_manager: str | None = None
+
+    @classmethod
+    def load_user_config(cls) -> "Config":
+        config_file = _get_config_file()
+        if config_file.is_file():
+            return cls(**tomllib.loads(_get_config_file().read_text()))
+        return cls()

pyproject_external/_constants.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025 Quansight Labs
+from typing import Final
+
+APP_NAME: Final[str] = "pyproject-external"
+APP_AUTHOR: Final[str] = "pyproject-external"
+APP_CONFIG_FILENAME: Final[str] = "config.toml"
+DEFAULT_ECOSYSTEMS_SCHEMA_URL: Final[str] = (
+    "https://raw.githubusercontent.com/jaimergp/external-metadata-mappings/main/"
+    "schemas/known-ecosystems.schema.json"
+)
+DEFAULT_ECOSYSTEMS_URL: Final[str] = (
+    "https://raw.githubusercontent.com/jaimergp/external-metadata-mappings/main/"
+    "data/known-ecosystems.json"
+)
+DEFAULT_MAPPING_SCHEMA_URL: Final[str] = (
+    "https://raw.githubusercontent.com/jaimergp/external-metadata-mappings/main/"
+    "schemas/external-mapping.schema.json"
+)
+DEFAULT_MAPPING_URL_TEMPLATE: Final[str] = (
+    "https://raw.githubusercontent.com/jaimergp/external-metadata-mappings/main/"
+    "data/{}.mapping.json"
+)
+DEFAULT_REGISTRY_SCHEMA_URL: Final[str] = (
+    "https://raw.githubusercontent.com/jaimergp/external-metadata-mappings/main/"
+    "schemas/central-registry.schema.json"
+)
+DEFAULT_REGISTRY_URL: Final[str] = (
+    "https://raw.githubusercontent.com/jaimergp/external-metadata-mappings/main/data/registry.json"
+)