fractal-server 2.2.0a1__py3-none-any.whl → 2.3.0__py3-none-any.whl

fractal_server/tasks/v2/background_operations_ssh.py

@@ -0,0 +1,317 @@
+import json
+import os
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from sqlalchemy.orm.attributes import flag_modified
+
+from ...app.models.v2 import CollectionStateV2
+from ._TaskCollectPip import _TaskCollectPip
+from .background_operations import _handle_failure
+from .background_operations import _insert_tasks
+from .background_operations import _prepare_tasks_metadata
+from .background_operations import _set_collection_state_data_status
+from fractal_server.app.db import get_sync_db
+from fractal_server.app.schemas.v2 import CollectionStatusV2
+from fractal_server.app.schemas.v2.manifest import ManifestV2
+from fractal_server.config import get_settings
+from fractal_server.logger import get_logger
+from fractal_server.logger import set_logger
+from fractal_server.ssh._fabric import FractalSSH
+from fractal_server.ssh._fabric import put_over_ssh
+from fractal_server.ssh._fabric import run_command_over_ssh
+from fractal_server.syringe import Inject
+from fractal_server.tasks.v2.utils import get_python_interpreter_v2
+
+TEMPLATES_DIR = Path(__file__).parent / "templates"
+
+
+def _parse_script_5_stdout(stdout: str) -> dict[str, str]:
+    searches = [
+        ("Python interpreter:", "python_bin"),
+        ("Package name:", "package_name"),
+        ("Package version:", "package_version"),
+        ("Package parent folder:", "package_root_parent_remote"),
+        ("Manifest absolute path:", "manifest_path_remote"),
+    ]
+    stdout_lines = stdout.splitlines()
+    attributes = dict()
+    for search, attribute_name in searches:
+        matching_lines = [_line for _line in stdout_lines if search in _line]
+        if len(matching_lines) == 0:
+            raise ValueError(f"String '{search}' not found in stdout.")
+        elif len(matching_lines) > 1:
+            raise ValueError(
+                f"String '{search}' found too many times "
+                f"({len(matching_lines)})."
+            )
+        else:
+            actual_line = matching_lines[0]
+            attribute_value = actual_line.split(search)[-1].strip(" ")
+            attributes[attribute_name] = attribute_value
+    return attributes
+
+
+def _customize_and_run_template(
+    script_filename: str,
+    templates_folder: Path,
+    replacements: list[tuple[str, str]],
+    tmpdir: str,
+    logger_name: str,
+    fractal_ssh: FractalSSH,
+) -> str:
+    """
+    Customize one of the template bash scripts, transfer it to the remote host
+    via SFTP and then run it via SSH.
+
+    Args:
+        script_filename:
+        templates_folder:
+        replacements:
+        tmpdir:
+        logger_name:
+        fractal_ssh:
+    """
+    logger = get_logger(logger_name)
+    logger.debug(f"_customize_and_run_template {script_filename} - START")
+    settings = Inject(get_settings)
+
+    # Read template
+    template_path = templates_folder / script_filename
+    with template_path.open("r") as f:
+        script_contents = f.read()
+    # Customize template
+    for old_new in replacements:
+        script_contents = script_contents.replace(old_new[0], old_new[1])
+    # Write script locally
+    script_path_local = (Path(tmpdir) / script_filename).as_posix()
+    with open(script_path_local, "w") as f:
+        f.write(script_contents)
+
+    # Transfer script to remote host
+    script_path_remote = os.path.join(
+        settings.FRACTAL_SLURM_SSH_WORKING_BASE_DIR,
+        f"script_{abs(hash(tmpdir))}{script_filename}",
+    )
+    logger.debug(f"Now transfer {script_path_local=} over SSH.")
+    put_over_ssh(
+        local=script_path_local,
+        remote=script_path_remote,
+        fractal_ssh=fractal_ssh,
+        logger_name=logger_name,
+    )
+
+    # Execute script remotely
+    cmd = f"bash {script_path_remote}"
+    logger.debug(f"Now run '{cmd}' over SSH.")
+    stdout = run_command_over_ssh(cmd=cmd, fractal_ssh=fractal_ssh)
+    logger.debug(f"Standard output of '{cmd}':\n{stdout}")
+
+    logger.debug(f"_customize_and_run_template {script_filename} - END")
+    return stdout
+
+
+def background_collect_pip_ssh(
+    state_id: int,
+    task_pkg: _TaskCollectPip,
+    fractal_ssh: FractalSSH,
+) -> None:
+    """
+    Collect a task package over SSH
+
+    This function is run as a background task, therefore exceptions must be
+    handled.
+
+    NOTE: by making this function sync, it will run within a thread - due to
+    starlette/fastapi handling of background tasks (see
+    https://github.com/encode/starlette/blob/master/starlette/background.py).
+    """
+    # Work within a temporary folder, where also logs will be placed
+    with TemporaryDirectory() as tmpdir:
+        LOGGER_NAME = "task_collection_ssh"
+        log_file_path = Path(tmpdir) / "log"
+        logger = set_logger(
+            logger_name=LOGGER_NAME,
+            log_file_path=log_file_path,
+        )
+
+        logger.debug("START")
+        for key, value in task_pkg.dict(exclude={"package_manifest"}).items():
+            logger.debug(f"task_pkg.{key}: {value}")
+
+        # Open a DB session soon, since it is needed for updating `state`
+        with next(get_sync_db()) as db:
+            try:
+                # Prepare replacements for task-collection scripts
+                settings = Inject(get_settings)
+                python_bin = get_python_interpreter_v2(
+                    python_version=task_pkg.python_version
+                )
+                package_version = (
+                    ""
+                    if task_pkg.package_version is None
+                    else task_pkg.package_version
+                )
+
+                install_string = task_pkg.package
+                if task_pkg.package_extras is not None:
+                    install_string = (
+                        f"{install_string}[{task_pkg.package_extras}]"
+                    )
+                if (
+                    task_pkg.package_version is not None
+                    and not task_pkg.is_local_package
+                ):
+                    install_string = (
+                        f"{install_string}=={task_pkg.package_version}"
+                    )
+                package_env_dir = (
+                    Path(settings.FRACTAL_SLURM_SSH_WORKING_BASE_DIR)
+                    / ".fractal"
+                    / f"{task_pkg.package_name}{package_version}"
+                ).as_posix()
+
+                replacements = [
+                    ("__PACKAGE_NAME__", task_pkg.package_name),
+                    ("__PACKAGE_ENV_DIR__", package_env_dir),
+                    ("__PACKAGE__", task_pkg.package),
+                    ("__PYTHON__", python_bin),
+                    ("__INSTALL_STRING__", install_string),
+                ]
+
+                common_args = dict(
+                    templates_folder=TEMPLATES_DIR,
+                    replacements=replacements,
+                    tmpdir=tmpdir,
+                    logger_name=LOGGER_NAME,
+                    fractal_ssh=fractal_ssh,
+                )
+
+                fractal_ssh.check_connection()
+
+                logger.debug("installing - START")
+                _set_collection_state_data_status(
+                    state_id=state_id,
+                    new_status=CollectionStatusV2.INSTALLING,
+                    logger_name=LOGGER_NAME,
+                    db=db,
+                )
+                # Avoid keeping the db session open as we start some possibly
+                # long operations that do not use the db
+                db.close()
+
+                stdout = _customize_and_run_template(
+                    script_filename="_1_create_venv.sh",
+                    **common_args,
+                )
+                stdout = _customize_and_run_template(
+                    script_filename="_2_upgrade_pip.sh",
+                    **common_args,
+                )
+                stdout = _customize_and_run_template(
+                    script_filename="_3_pip_install.sh",
+                    **common_args,
+                )
+                stdout_pip_freeze = _customize_and_run_template(
+                    script_filename="_4_pip_freeze.sh",
+                    **common_args,
+                )
+                logger.debug("installing - END")
+
+                logger.debug("collecting - START")
+                _set_collection_state_data_status(
+                    state_id=state_id,
+                    new_status=CollectionStatusV2.COLLECTING,
+                    logger_name=LOGGER_NAME,
+                    db=db,
+                )
+                # Avoid keeping the db session open as we start some possibly
+                # long operations that do not use the db
+                db.close()
+
+                stdout = _customize_and_run_template(
+                    script_filename="_5_pip_show.sh",
+                    **common_args,
+                )
+
+                pkg_attrs = _parse_script_5_stdout(stdout)
+                for key, value in pkg_attrs.items():
+                    logger.debug(
+                        f"collecting - parsed from pip-show: {key}={value}"
+                    )
+                # Check package_name match
+                # FIXME SSH: Does this work for non-canonical `package_name`?
+                package_name_pip_show = pkg_attrs.get("package_name")
+                package_name_task_pkg = task_pkg.package_name
+                if package_name_pip_show != package_name_task_pkg:
+                    error_msg = (
+                        f"`package_name` mismatch: "
+                        f"{package_name_task_pkg=} but "
+                        f"{package_name_pip_show=}"
+                    )
+                    logger.error(error_msg)
+                    raise ValueError(error_msg)
+                # Extract/drop parsed attributes
+                package_name = pkg_attrs.pop("package_name")
+                python_bin = pkg_attrs.pop("python_bin")
+                package_root_parent_remote = pkg_attrs.pop(
+                    "package_root_parent_remote"
+                )
+                manifest_path_remote = pkg_attrs.pop("manifest_path_remote")
+
+                # FIXME SSH: Use more robust logic to determine `package_root`,
+                # e.g. as in the custom task-collection endpoint (where we use
+                # `importlib.util.find_spec`)
+                package_name_underscore = package_name.replace("-", "_")
+                package_root_remote = (
+                    Path(package_root_parent_remote) / package_name_underscore
+                ).as_posix()
+
+                # Read and validate remote manifest file
+                with fractal_ssh.sftp().open(manifest_path_remote, "r") as f:
+                    manifest = json.load(f)
+                logger.info(f"collecting - loaded {manifest_path_remote=}")
+                ManifestV2(**manifest)
+                logger.info("collecting - manifest is a valid ManifestV2")
+
+                # Create new _TaskCollectPip object
+                new_pkg = _TaskCollectPip(
+                    **task_pkg.dict(
+                        exclude={"package_version", "package_name"},
+                        exclude_unset=True,
+                        exclude_none=True,
+                    ),
+                    package_manifest=manifest,
+                    **pkg_attrs,
+                )
+
+                task_list = _prepare_tasks_metadata(
+                    package_manifest=new_pkg.package_manifest,
+                    package_version=new_pkg.package_version,
+                    package_source=new_pkg.package_source,
+                    package_root=Path(package_root_remote),
+                    python_bin=Path(python_bin),
+                )
+                _insert_tasks(task_list=task_list, db=db)
+                logger.debug("collecting - END")
+
+                # Finalize (write metadata to DB)
+                logger.debug("finalising - START")
+                collection_state = db.get(CollectionStateV2, state_id)
+                collection_state.data["log"] = log_file_path.open("r").read()
+                collection_state.data["freeze"] = stdout_pip_freeze
+                collection_state.data["status"] = CollectionStatusV2.OK
+                flag_modified(collection_state, "data")
+                db.commit()
+                logger.debug("finalising - END")
+                logger.debug("END")
+
+            except Exception as e:
+                _handle_failure(
+                    state_id=state_id,
+                    log_file_path=log_file_path,
+                    logger_name=LOGGER_NAME,
+                    exception=e,
+                    db=db,
+                )
+                return

fractal_server/tasks/v2/endpoint_operations.py

@@ -0,0 +1,136 @@
+import json
+from pathlib import Path
+from typing import Literal
+from typing import Optional
+from typing import Union
+from zipfile import ZipFile
+
+from ._TaskCollectPip import _TaskCollectPip
+from .utils import _parse_wheel_filename
+from .utils import get_python_interpreter_v2
+from fractal_server.app.schemas.v2 import ManifestV2
+from fractal_server.config import get_settings
+from fractal_server.logger import get_logger
+from fractal_server.syringe import Inject
+from fractal_server.utils import execute_command
+
+
+FRACTAL_PUBLIC_TASK_SUBDIR = ".fractal"
+
+
+async def download_package(
+    *,
+    task_pkg: _TaskCollectPip,
+    dest: Union[str, Path],
+) -> Path:
+    """
+    Download package to destination and return wheel-file path.
+    """
+    interpreter = get_python_interpreter_v2(
+        python_version=task_pkg.python_version
+    )
+    pip = f"{interpreter} -m pip"
+    if task_pkg.package_version is None:
+        package_and_version = f"{task_pkg.package_name}"
+    else:
+        package_and_version = (
+            f"{task_pkg.package_name}=={task_pkg.package_version}"
+        )
+    cmd = f"{pip} download --no-deps {package_and_version} -d {dest}"
+    stdout = await execute_command(command=cmd, cwd=Path("."))
+    pkg_file = next(
+        line.split()[-1] for line in stdout.split("\n") if "Saved" in line
+    )
+    return Path(pkg_file)
+
+
+def _load_manifest_from_wheel(
+    path: Path, wheel: ZipFile, logger_name: Optional[str] = None
+) -> ManifestV2:
+    logger = get_logger(logger_name)
+    namelist = wheel.namelist()
+    try:
+        manifest = next(
+            name for name in namelist if "__FRACTAL_MANIFEST__.json" in name
+        )
+    except StopIteration:
+        msg = f"{path.as_posix()} does not include __FRACTAL_MANIFEST__.json"
+        logger.error(msg)
+        raise ValueError(msg)
+    with wheel.open(manifest) as manifest_fd:
+        manifest_dict = json.load(manifest_fd)
+    manifest_version = str(manifest_dict["manifest_version"])
+    if manifest_version == "2":
+        pkg_manifest = ManifestV2(**manifest_dict)
+        return pkg_manifest
+    else:
+        msg = f"Manifest version {manifest_version=} not supported"
+        logger.error(msg)
+        raise ValueError(msg)
+
+
+def inspect_package(
+    path: Path, logger_name: Optional[str] = None
+) -> dict[Literal["pkg_version", "pkg_manifest"], str]:
+    """
+    Inspect task package to extract version and manifest
+
+    Note that this only works with wheel files, which have a well-defined
+    dist-info section. If we need to generalize to to tar.gz archives, we would
+    need to go and look for `PKG-INFO`.
+
+    Args:
+        path: Path of the package wheel file.
+        logger_name:
+
+    Returns:
+        A dictionary with keys `pkg_version` and `pkg_manifest`.
+    """
+
+    logger = get_logger(logger_name)
+
+    if not path.as_posix().endswith(".whl"):
+        raise ValueError(
+            "Only wheel packages are supported in Fractal "
+            f"(given {path.name})."
+        )
+
+    # Extract package name and version from wheel filename
+    _info = _parse_wheel_filename(wheel_filename=path.name)
+    pkg_version = _info["version"]
+
+    # Read and validate task manifest
+    logger.debug(f"Now reading manifest for {path.as_posix()}")
+    with ZipFile(path) as wheel:
+        pkg_manifest = _load_manifest_from_wheel(
+            path, wheel, logger_name=logger_name
+        )
+    logger.debug("Manifest read correctly.")
+
+    info = dict(
+        pkg_version=pkg_version,
+        pkg_manifest=pkg_manifest,
+    )
+    return info
+
+
+def create_package_dir_pip(
+    *,
+    task_pkg: _TaskCollectPip,
+    create: bool = True,
+) -> Path:
+    """
+    Create venv folder for a task package and return corresponding Path object
+    """
+    settings = Inject(get_settings)
+    user = FRACTAL_PUBLIC_TASK_SUBDIR
+    if task_pkg.package_version is None:
+        raise ValueError(
+            f"Cannot create venv folder for package `{task_pkg.package}` "
+            "with `version=None`."
+        )
+    package_dir = f"{task_pkg.package_name}{task_pkg.package_version}"
+    venv_path = settings.FRACTAL_TASKS_DIR / user / package_dir
+    if create:
+        venv_path.mkdir(exist_ok=False, parents=True)
+    return venv_path

fractal_server/tasks/v2/templates/_1_create_venv.sh

@@ -0,0 +1,46 @@
+set -e
+
+write_log(){
+    TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    echo "[collect-task, $TIMESTAMP] $1"
+}
+
+
+# Variables to be filled within fractal-server
+PACKAGE_ENV_DIR=__PACKAGE_ENV_DIR__
+PYTHON=__PYTHON__
+
+TIME_START=$(date +%s)
+
+
+# Create main folder
+if [ -d "$PACKAGE_ENV_DIR" ]; then
+    write_log "ERROR: Folder $PACKAGE_ENV_DIR already exists. Exit."
+    exit 1
+fi
+write_log "START mkdir -p $PACKAGE_ENV_DIR"
+mkdir -p $PACKAGE_ENV_DIR
+write_log "END   mkdir -p $PACKAGE_ENV_DIR"
+echo
+
+
+# Create venv
+write_log "START create venv in ${PACKAGE_ENV_DIR}"
+"$PYTHON" -m venv "$PACKAGE_ENV_DIR" --copies
+write_log "END   create venv in ${PACKAGE_ENV_DIR}"
+echo
+VENVPYTHON=${PACKAGE_ENV_DIR}/bin/python
+if [ -f "$VENVPYTHON" ]; then
+    write_log "OK: $VENVPYTHON exists."
+    echo
+else
+    write_log "ERROR: $VENVPYTHON not found"
+    exit 2
+fi
+
+# End
+TIME_END=$(date +%s)
+write_log "All good up to here."
+write_log "Elapsed: $((TIME_END - TIME_START)) seconds"
+write_log "Exit."
+echo

fractal_server/tasks/v2/templates/_2_upgrade_pip.sh

@@ -0,0 +1,30 @@
+set -e
+
+write_log(){
+    TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    echo "[collect-task, $TIMESTAMP] $1"
+}
+
+# Variables to be filled within fractal-server
+PACKAGE_ENV_DIR=__PACKAGE_ENV_DIR__
+PACKAGE_NAME=__PACKAGE_NAME__
+PACKAGE=__PACKAGE__
+PYTHON=__PYTHON__
+INSTALL_STRING=__INSTALL_STRING__
+
+TIME_START=$(date +%s)
+
+VENVPYTHON=${PACKAGE_ENV_DIR}/bin/python
+
+# Upgrade pip
+write_log "START upgrade pip"
+"$VENVPYTHON" -m pip install pip --upgrade
+write_log "END   upgrade pip"
+echo
+
+# End
+TIME_END=$(date +%s)
+write_log "All good up to here."
+write_log "Elapsed: $((TIME_END - TIME_START)) seconds"
+write_log "Exit."
+echo

fractal_server/tasks/v2/templates/_3_pip_install.sh

@@ -0,0 +1,32 @@
+set -e
+
+write_log(){
+    TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    echo "[collect-task, $TIMESTAMP] $1"
+}
+
+
+# Variables to be filled within fractal-server
+PACKAGE_ENV_DIR=__PACKAGE_ENV_DIR__
+PACKAGE_NAME=__PACKAGE_NAME__
+PACKAGE=__PACKAGE__
+PYTHON=__PYTHON__
+INSTALL_STRING=__INSTALL_STRING__
+
+
+TIME_START=$(date +%s)
+
+VENVPYTHON=${PACKAGE_ENV_DIR}/bin/python
+
+# Install package
+write_log "START install ${INSTALL_STRING}"
+"$VENVPYTHON" -m pip install "$INSTALL_STRING"
+write_log "END   install ${INSTALL_STRING}"
+echo
+
+# End
+TIME_END=$(date +%s)
+write_log "All good up to here."
+write_log "Elapsed: $((TIME_END - TIME_START)) seconds"
+write_log "Exit."
+echo

fractal_server/tasks/v2/templates/_4_pip_freeze.sh

@@ -0,0 +1,21 @@
+set -e
+
+write_log(){
+    TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    echo "[collect-task, $TIMESTAMP] $1"
+}
+
+
+
+# Variables to be filled within fractal-server
+PACKAGE_ENV_DIR=__PACKAGE_ENV_DIR__
+PACKAGE_NAME=__PACKAGE_NAME__
+PACKAGE=__PACKAGE__
+PYTHON=__PYTHON__
+INSTALL_STRING=__INSTALL_STRING__
+
+
+
+VENVPYTHON=${PACKAGE_ENV_DIR}/bin/python
+
+"$VENVPYTHON" -m pip freeze

fractal_server/tasks/v2/templates/_5_pip_show.sh

@@ -0,0 +1,59 @@
+set -e
+
+write_log(){
+    TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    echo "[collect-task, $TIMESTAMP] $1"
+}
+
+
+# Variables to be filled within fractal-server
+PACKAGE_ENV_DIR=__PACKAGE_ENV_DIR__
+PACKAGE_NAME=__PACKAGE_NAME__
+PACKAGE=__PACKAGE__
+PYTHON=__PYTHON__
+INSTALL_STRING=__INSTALL_STRING__
+
+
+TIME_START=$(date +%s)
+
+VENVPYTHON=${PACKAGE_ENV_DIR}/bin/python
+write_log "Python interpreter: $VENVPYTHON"
+echo
+
+# FIXME: only run pip-show once!
+
+# Extract information about paths
+# WARNING: this block will fail for paths which inlcude whitespace characters
+write_log "START pip show"
+$VENVPYTHON -m pip show ${PACKAGE_NAME}
+write_log "END   pip show"
+echo
+PACKAGE_NAME=$($VENVPYTHON -m pip show ${PACKAGE_NAME} | grep "Name:" | cut -d ":" -f 2 | tr -d "[:space:]")
+write_log "Package name: $PACKAGE_NAME"
+echo
+PACKAGE_VERSION=$($VENVPYTHON -m pip show ${PACKAGE_NAME} | grep "Version:" | cut -d ":" -f 2 | tr -d "[:space:]")
+write_log "Package version: $PACKAGE_VERSION"
+echo
+PACKAGE_PARENT_FOLDER=$($VENVPYTHON -m pip show ${PACKAGE_NAME} | grep "Location:" | cut -d ":" -f 2 | tr -d "[:space:]")
+write_log "Package parent folder: $PACKAGE_PARENT_FOLDER"
+echo
+MANIFEST_RELATIVE_PATH=$($VENVPYTHON -m pip show ${PACKAGE_NAME} --files | grep "__FRACTAL_MANIFEST__.json" | tr -d "[:space:]")
+write_log "Manifest relative path: $MANIFEST_RELATIVE_PATH"
+echo
+MANIFEST_ABSOLUTE_PATH="${PACKAGE_PARENT_FOLDER}/${MANIFEST_RELATIVE_PATH}"
+write_log "Manifest absolute path: $MANIFEST_ABSOLUTE_PATH"
+echo
+if [ -f "$MANIFEST_ABSOLUTE_PATH" ]; then
+    write_log "OK: manifest path exists"
+    echo
+else
+    write_log "ERROR: manifest path not found at $MANIFEST_ABSOLUTE_PATH"
+    exit 3
+fi
+
+# End
+TIME_END=$(date +%s)
+write_log "All good up to here."
+write_log "Elapsed: $((TIME_END - TIME_START)) seconds"
+write_log "Exit."
+echo

fractal_server/tasks/v2/utils.py

@@ -0,0 +1,54 @@
+from typing import Literal
+
+from fractal_server.config import get_settings
+from fractal_server.syringe import Inject
+
+
+def get_python_interpreter_v2(
+    python_version: Literal["3.9", "3.10", "3.11", "3.12"]
+) -> str:
+    """
+    Return the path to the python interpreter
+
+    Args:
+        version: Python version
+
+    Raises:
+        ValueError: If the python version requested is not available on the
+                    host.
+
+    Returns:
+        interpreter: string representing the python executable or its path
+    """
+
+    if python_version not in ["3.9", "3.10", "3.11", "3.12"]:
+        raise ValueError(f"Invalid {python_version=}.")
+
+    settings = Inject(get_settings)
+    version_underscore = python_version.replace(".", "_")
+    key = f"FRACTAL_TASKS_PYTHON_{version_underscore}"
+    value = getattr(settings, key)
+    if value is None:
+        raise ValueError(f"Requested {python_version=}, but {key}={value}.")
+    return value
+
+
+def _parse_wheel_filename(wheel_filename: str) -> dict[str, str]:
+    """
+    Extract distribution and version from a wheel filename.
+
+    The structure of a wheel filename is fixed, and it must start with
+    `{distribution}-{version}` (see
+    https://packaging.python.org/en/latest/specifications/binary-distribution-format
+    ).
+
+    Note that we transform exceptions in `ValueError`s, since this function is
+    also used within Pydantic validators.
+    """
+    try:
+        parts = wheel_filename.split("-")
+        return dict(distribution=parts[0], version=parts[1])
+    except Exception as e:
+        raise ValueError(
+            f"Invalid {wheel_filename=}. Original error: {str(e)}."
+        )