Source code for datalab.plugins.resources
# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
"""Package resources declared by plugins with the ``package:path`` syntax."""
from __future__ import annotations
import re
import sys
from importlib import resources
from pathlib import PurePosixPath
from typing import TYPE_CHECKING
if TYPE_CHECKING:
if sys.version_info >= (3, 11):
from importlib.resources.abc import Traversable
else:
from importlib.abc import Traversable
__all__ = ["LOCAL_ID_PATTERN", "resolve_package_resource", "split_package_resource"]
#: Plugin-local identifier syntax (examples, welcome page tiles)
LOCAL_ID_PATTERN = re.compile(r"^[a-z0-9]+(?:[._-][a-z0-9]+)*$")
_PACKAGE_PATTERN = re.compile(
r"^[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*$",
flags=re.ASCII,
)
[docs]
def split_package_resource(
resource: str, label: str = "Plugin resource"
) -> tuple[str, str]:
"""Validate a ``package:path`` resource and return its two parts
Args:
resource: resource declaration, e.g. ``"my_plugin:icons/logo.svg"``
label: resource description used in error messages
Returns:
Importable package name and POSIX path relative to this package
Raises:
ValueError: if the declaration is malformed
"""
if not isinstance(resource, str) or resource.count(":") != 1:
raise ValueError(f"{label} must use 'package:path' syntax")
package, path = resource.split(":")
if not _PACKAGE_PATTERN.fullmatch(package):
raise ValueError(f"{label} package is invalid")
posix_path = PurePosixPath(path)
if not path or "\\" in path or posix_path.is_absolute() or ".." in posix_path.parts:
raise ValueError(f"{label} path must be relative")
return package, path
[docs]
def resolve_package_resource(
resource: str, label: str = "Plugin resource"
) -> Traversable:
"""Resolve a ``package:path`` resource without requiring a filesystem path
Args:
resource: resource declaration, e.g. ``"my_plugin:icons/logo.svg"``
label: resource description used in error messages
Returns:
``importlib.resources`` traversable, also valid for zipped packages
Raises:
ValueError: if the declaration is malformed
FileNotFoundError: if the package does not contain the resource
"""
package, path = split_package_resource(resource, label)
traversable = resources.files(package)
for part in PurePosixPath(path).parts:
traversable = traversable.joinpath(part)
if not traversable.is_file():
raise FileNotFoundError(f"{label} not found: {resource}")
return traversable