abxpkg 1.10.1__py3-none-any.whl

abxpkg/__init__.py

@@ -0,0 +1,195 @@
+__package__ = "abxpkg"
+
+from .base_types import (
+    BinName,
+    InstallArgs,
+    PATHStr,
+    HostBinPath,
+    HostExistsPath,
+    BinDirPath,
+    BinProviderName,
+    bin_name,
+    bin_abspath,
+    bin_abspaths,
+    func_takes_args_or_kwargs,
+)
+from .semver import SemVer, bin_version
+from .shallowbinary import ShallowBinary
+from .logging import (
+    logger,
+    get_logger,
+    configure_logging,
+    configure_rich_logging,
+    RICH_INSTALLED,
+)
+from .exceptions import (
+    ABXPkgError,
+    BinaryOperationError,
+    BinaryInstallError,
+    BinaryLoadError,
+    BinaryUpdateError,
+    BinaryUninstallError,
+)
+from .binprovider import (
+    BinProvider,
+    EnvProvider,
+    OPERATING_SYSTEM,
+    DEFAULT_PATH,
+    DEFAULT_ENV_PATH,
+    PYTHON_BIN_DIR,
+    BinProviderOverrides,
+    BinaryOverrides,
+    ProviderFuncReturnValue,
+    HandlerType,
+    HandlerValue,
+    HandlerDict,
+    HandlerReturnValue,
+)
+from .binary import Binary
+
+from .binprovider_apt import AptProvider
+from .binprovider_brew import BrewProvider
+from .binprovider_cargo import CargoProvider
+from .binprovider_gem import GemProvider
+from .binprovider_goget import GoGetProvider
+from .binprovider_nix import NixProvider
+from .binprovider_docker import DockerProvider
+from .binprovider_pip import PipProvider
+from .binprovider_uv import UvProvider
+from .binprovider_npm import NpmProvider
+from .binprovider_pnpm import PnpmProvider
+from .binprovider_yarn import YarnProvider
+from .binprovider_bun import BunProvider
+from .binprovider_deno import DenoProvider
+from .binprovider_ansible import AnsibleProvider
+from .binprovider_pyinfra import PyinfraProvider
+from .binprovider_chromewebstore import ChromeWebstoreProvider
+from .binprovider_puppeteer import PuppeteerProvider
+from .binprovider_playwright import PlaywrightProvider
+from .binprovider_bash import BashProvider
+
+ALL_PROVIDERS = [
+    EnvProvider,
+    UvProvider,
+    PipProvider,
+    PnpmProvider,
+    NpmProvider,
+    YarnProvider,
+    BunProvider,
+    BrewProvider,
+    GemProvider,
+    GoGetProvider,
+    CargoProvider,
+    PlaywrightProvider,
+    PuppeteerProvider,
+    AptProvider,
+    NixProvider,
+    DockerProvider,
+    DenoProvider,
+    AnsibleProvider,
+    PyinfraProvider,
+    ChromeWebstoreProvider,
+    BashProvider,
+]
+
+
+def _provider_class(provider: type[BinProvider] | BinProvider) -> type[BinProvider]:
+    return provider if isinstance(provider, type) else type(provider)
+
+
+ALL_PROVIDER_NAMES = [
+    _provider_class(provider).model_fields["name"].default for provider in ALL_PROVIDERS
+]  # pip, apt, brew, etc.
+ALL_PROVIDER_CLASS_NAMES = [
+    _provider_class(provider).__name__ for provider in ALL_PROVIDERS
+]  # PipProvider, AptProvider, BrewProvider, etc.
+
+# Lazy provider singletons: maps provider name -> class
+# e.g. 'apt' -> AptProvider, 'pip' -> PipProvider, 'env' -> EnvProvider
+_PROVIDER_CLASS_BY_NAME = {
+    _provider_class(provider).model_fields["name"].default: _provider_class(provider)
+    for provider in ALL_PROVIDERS
+}
+_provider_singletons: dict = {}
+
+
+def __getattr__(name: str):
+    if name in _PROVIDER_CLASS_BY_NAME:
+        if name not in _provider_singletons:
+            _provider_singletons[name] = _PROVIDER_CLASS_BY_NAME[name]()
+        return _provider_singletons[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Main types
+    "BinProvider",
+    "Binary",
+    "SemVer",
+    "ShallowBinary",
+    "logger",
+    "get_logger",
+    "configure_logging",
+    "configure_rich_logging",
+    "RICH_INSTALLED",
+    # Exceptions
+    "ABXPkgError",
+    "BinaryOperationError",
+    "BinaryInstallError",
+    "BinaryLoadError",
+    "BinaryUpdateError",
+    "BinaryUninstallError",
+    # Helper Types
+    "BinName",
+    "InstallArgs",
+    "PATHStr",
+    "BinDirPath",
+    "HostBinPath",
+    "HostExistsPath",
+    "BinProviderName",
+    # Override types
+    "BinProviderOverrides",
+    "BinaryOverrides",
+    "ProviderFuncReturnValue",
+    "HandlerType",
+    "HandlerValue",
+    "HandlerDict",
+    "HandlerReturnValue",
+    # Validator Functions
+    "bin_version",
+    "bin_name",
+    "bin_abspath",
+    "bin_abspaths",
+    "func_takes_args_or_kwargs",
+    # Globals
+    "OPERATING_SYSTEM",
+    "DEFAULT_PATH",
+    "DEFAULT_ENV_PATH",
+    "PYTHON_BIN_DIR",
+    # BinProviders (classes)
+    "EnvProvider",
+    "AptProvider",
+    "BrewProvider",
+    "CargoProvider",
+    "GemProvider",
+    "GoGetProvider",
+    "NixProvider",
+    "DockerProvider",
+    "PipProvider",
+    "UvProvider",
+    "NpmProvider",
+    "PnpmProvider",
+    "YarnProvider",
+    "BunProvider",
+    "DenoProvider",
+    "AnsibleProvider",
+    "PyinfraProvider",
+    "ChromeWebstoreProvider",
+    "PuppeteerProvider",
+    "PlaywrightProvider",
+    "BashProvider",
+    # Note: provider singleton names (apt, pip, brew, etc.) are intentionally
+    # excluded from __all__ so that `from abxpkg import *` does not eagerly
+    # instantiate every provider. Use explicit imports instead:
+    #   from abxpkg import apt, pip, brew, npm, pnpm, yarn, bun, deno
+]

abxpkg/admin.py

@@ -0,0 +1,45 @@
+from types import MethodType
+
+from django.contrib import admin
+
+
+def register_admin_views(admin_site: admin.AdminSite):
+    """register the django-admin-data-views defined in settings.ADMIN_DATA_VIEWS"""
+
+    from admin_data_views.admin import (
+        get_app_list,
+        admin_data_index_view,
+        get_admin_data_urls,
+        get_urls,
+    )
+
+    setattr(admin_site, "get_app_list", MethodType(get_app_list, admin_site))
+    setattr(
+        admin_site,
+        "admin_data_index_view",
+        MethodType(admin_data_index_view, admin_site),
+    )
+    setattr(
+        admin_site,
+        "get_admin_data_urls",
+        MethodType(get_admin_data_urls, admin_site),
+    )
+    setattr(
+        admin_site,
+        "get_urls",
+        MethodType(get_urls(admin_site.get_urls), admin_site),
+    )
+
+    return admin_site
+
+
+register_admin_views(admin.site)
+
+# if you've implemented a custom admin site, you should call this function on your site
+
+# class YourSiteAdmin(admin.AdminSite):
+#     ...
+#
+# custom_site = YourSiteAdmin()
+#
+# register_admin_views(custom_site)

abxpkg/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class AbxPkgConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "abxpkg"

abxpkg/base_types.py

@@ -0,0 +1,312 @@
+__package__ = "abxpkg"
+
+import inspect
+import os
+import shutil
+
+from pathlib import Path
+from typing import Any, Annotated
+from collections.abc import Callable
+
+from platformdirs import user_config_path
+
+from pydantic import TypeAdapter, AfterValidator, BeforeValidator, ValidationError
+
+
+# Read once at import time. When set, providers that opt into
+# ``abxpkg_install_root_default("<provider>")`` default their
+# ``install_root`` to ``ABXPKG_LIB_DIR / <provider name>`` (e.g.
+# ``<lib>/npm``, ``<lib>/pip``, ``<lib>/gem``). Per-provider
+# ``ABXPKG_<NAME>_ROOT`` env vars override this for their own
+# provider; explicit constructor kwargs override both.
+DEFAULT_LIB_DIR: Path = user_config_path("abx") / "lib"
+
+
+def abxpkg_install_root_default(provider_name: str) -> Path | None:
+    """Resolve a provider's default install root from env vars.
+
+    Precedence (most specific wins):
+    1. ``ABXPKG_<PROVIDER>_ROOT`` (e.g. ``ABXPKG_NPM_ROOT``)
+    2. ``ABXPKG_LIB_DIR / <provider_name>``
+    3. ``None`` — caller's built-in default applies.
+
+    Explicit constructor kwargs (``install_root=`` or the
+    provider-specific alias) always override whatever this function
+    returns.
+    """
+    specific = os.environ.get(f"ABXPKG_{provider_name.upper()}_ROOT", "").strip()
+    if specific:
+        return Path(specific).expanduser().resolve()
+    # Read from os.environ directly (not the cached module-level
+    # ABXPKG_LIB_DIR) because the CLI sets it at runtime via --lib.
+    lib_dir = os.environ.get("ABXPKG_LIB_DIR", "").strip()
+    if lib_dir:
+        return Path(lib_dir).expanduser().resolve() / provider_name
+    return None
+
+
+def validate_binprovider_name(name: str) -> str:
+    assert 1 < len(name) < 16, (
+        "BinProvider names must be between 1 and 16 characters long"
+    )
+    assert name.replace("_", "").isalnum(), (
+        "BinProvider names can only contain a-Z0-9 and underscores"
+    )
+    assert name[0].isalpha(), "BinProvider names must start with a letter"
+    return name
+
+
+BinProviderName = Annotated[str, AfterValidator(validate_binprovider_name)]
+# in practice this is essentially BinProviderName: Literal['env', 'pip', 'apt', 'brew', 'npm', 'vendor']
+# but because users can create their own BinProviders we can't restrict it to a preset list of literal names
+
+
+def validate_bin_dir(path: Path) -> Path:
+    path = path.expanduser().absolute()
+    assert path.resolve()
+    assert os.path.isdir(path) and os.access(path, os.R_OK), (
+        f"path entries to add to $PATH must be absolute paths to directories {dir}"
+    )
+    return path
+
+
+BinDirPath = Annotated[Path, AfterValidator(validate_bin_dir)]
+
+
+def validate_PATH(PATH: str | list[str]) -> str:
+    paths = PATH.split(":") if isinstance(PATH, str) else list(PATH)
+    assert all(Path(bin_dir) for bin_dir in paths)
+    return ":".join(paths).strip(":")
+
+
+PATHStr = Annotated[str, BeforeValidator(validate_PATH)]
+
+
+def func_takes_args_or_kwargs(lambda_func: Callable[..., Any]) -> bool:
+    """returns True if a lambda func takes args/kwargs of any kind, otherwise false if it's pure/argless"""
+    signature = inspect.signature(lambda_func)
+    return any(
+        parameter.kind
+        in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        )
+        for parameter in signature.parameters.values()
+    )
+
+
+# @validate_call
+def bin_name(bin_path_or_name: str | Path) -> str:
+    """
+    - wget -> wget
+    - /usr/bin/wget -> wget
+    - ~/bin/wget -> wget
+    - ~/.local/bin/wget -> wget
+    - @postlight/parser -> @postlight/parser
+    - @postlight/parser@2.2.3 -> @postlight/parser
+    - yt-dlp==2024.05.09 -> yt-dlp
+    - postlight/parser^2.2.3 -> postlight/parser
+    - @postlight/parser@^2.2.3 -> @postlight/parser
+    """
+    str_bin_name = (
+        str(bin_path_or_name)
+        .split("^", 1)[0]
+        .split("=", 1)[0]
+        .split(">", 1)[0]
+        .split("<", 1)[0]
+    )
+    if str_bin_name.startswith("@"):
+        # @postlight/parser@^2.2.3 -> @postlight/parser
+        str_bin_name = "@" + str_bin_name[1:].split("@", 1)[0]
+    else:
+        str_bin_name = str_bin_name.split("@", 1)[0]
+
+    assert len(str_bin_name) > 0, "Binary names must be non-empty"
+    name = (
+        Path(str_bin_name).name if str_bin_name[0] in (".", "/", "~") else str_bin_name
+    )
+    assert 1 <= len(name) < 64, "Binary names must be between 1 and 63 characters long"
+    assert (
+        name.replace("-", "")
+        .replace("_", "")
+        .replace(".", "")
+        .replace(" ", "")
+        .replace("@", "")
+        .replace("/", "")
+        .isalnum()
+    ), f"Binary name can only contain a-Z0-9-_.@/ and spaces: {name}"
+    assert name.replace("@", "")[0].isalpha(), (
+        "Binary names must start with a letter or @"
+    )
+    # print('PARSING BIN NAME', bin_path_or_name, '->', name)
+    return name
+
+
+BinName = Annotated[str, AfterValidator(bin_name)]
+
+
+# @validate_call
+def path_is_file(path: Path | str) -> Path:
+    path = Path(path) if isinstance(path, str) else path
+    assert os.path.isfile(path) and os.access(path, os.R_OK), (
+        f"Path is not a file or we dont have permission to read it: {path}"
+    )
+    return path
+
+
+HostExistsPath = Annotated[Path, AfterValidator(path_is_file)]
+
+
+# @validate_call
+def path_is_executable(path: HostExistsPath) -> HostExistsPath:
+    assert os.path.isfile(path) and os.access(path, os.X_OK), (
+        f"Path is not executable (fix by running chmod +x {path})"
+    )
+    return path
+
+
+# @validate_call
+def path_is_script(path: HostExistsPath) -> HostExistsPath:
+    SCRIPT_EXTENSIONS = (".py", ".js", ".sh")
+    assert path.suffix.lower() in SCRIPT_EXTENSIONS, (
+        "Path is not a script (does not end in {})".format(", ".join(SCRIPT_EXTENSIONS))
+    )
+    return path
+
+
+HostExecutablePath = Annotated[HostExistsPath, AfterValidator(path_is_executable)]
+
+
+# @validate_call
+def path_is_abspath(path: Path) -> Path:
+    path = path.expanduser().absolute()  # resolve ~/ -> /home/<username/ and ../../
+    assert (
+        path.resolve()
+    )  # make sure symlinks can be resolved, but dont return resolved link
+    return path
+
+
+HostAbsPath = Annotated[HostExistsPath, AfterValidator(path_is_abspath)]
+HostBinPath = Annotated[
+    HostExistsPath,
+    AfterValidator(path_is_abspath),
+]  # removed: AfterValidator(path_is_executable)
+# not all bins need to be executable to be bins, some are scripts
+
+
+# @validate_call
+def bin_abspath(
+    bin_path_or_name: str | BinName | Path,
+    PATH: PATHStr | None = None,
+) -> HostBinPath | None:
+    assert bin_path_or_name
+    if PATH is None:
+        PATH = os.environ.get("PATH", "/bin")
+    if PATH:
+        PATH = str(PATH)
+    else:
+        return None
+
+    if str(bin_path_or_name).startswith("/"):
+        # already a path, get its absolute form
+        abspath = Path(bin_path_or_name).expanduser().absolute()
+    else:
+        # not a path yet, get path using shutil.which
+        binpath = shutil.which(bin_path_or_name, mode=os.X_OK, path=PATH)
+        # print(bin_path_or_name, PATH.split(':'), binpath, 'GOPINGNGN')
+        if not binpath:
+            # some bins dont show up with shutil.which (e.g. django-admin.py)
+            for path in PATH.split(":"):
+                bin_dir = Path(path)
+                # print('BIN_DIR', bin_dir, bin_dir.is_dir())
+                if not (os.path.isdir(bin_dir) and os.access(bin_dir, os.R_OK)):
+                    # raise Exception(f'Found invalid dir in $PATH: {bin_dir}')
+                    continue
+                bin_file = bin_dir / bin_path_or_name
+                # print(bin_file, path, bin_file.exists(), bin_file.is_file(), bin_file.is_symlink())
+                if os.path.isfile(bin_file) and os.access(bin_file, os.R_OK):
+                    return bin_file
+
+            return None
+        # print(binpath, PATH)
+        if str(Path(binpath).parent) not in PATH:
+            # print('WARNING, found bin but not in PATH', binpath, PATH)
+            # found bin but it was outside our search $PATH
+            return None
+        abspath = Path(binpath).expanduser().absolute()
+
+    try:
+        return TypeAdapter(HostBinPath).validate_python(abspath)
+    except ValidationError:
+        return None
+
+
+# @validate_call
+def bin_abspaths(
+    bin_path_or_name: BinName | Path,
+    PATH: PATHStr | None = None,
+) -> list[HostBinPath]:
+    assert bin_path_or_name
+
+    PATH = PATH or os.environ.get("PATH", "/bin")
+    abspaths = []
+
+    if str(bin_path_or_name).startswith("/"):
+        # already a path, get its absolute form
+        abspaths.append(Path(bin_path_or_name).expanduser().absolute())
+    else:
+        # not a path yet, get path using shutil.which
+        for path in PATH.split(":"):
+            binpath = shutil.which(bin_path_or_name, mode=os.X_OK, path=path)
+            if binpath and str(Path(binpath).parent) in PATH:
+                abspaths.append(binpath)
+
+    try:
+        return TypeAdapter(list[HostBinPath]).validate_python(abspaths)
+    except ValidationError:
+        return []
+
+
+################## Types ##############################################
+
+UNKNOWN_SHA256 = "unknown"
+
+
+def is_valid_sha256(sha256: str) -> str:
+    if sha256 == UNKNOWN_SHA256:
+        return sha256
+    assert len(sha256) == 64
+    assert sha256.isalnum()
+    return sha256
+
+
+Sha256 = Annotated[str, AfterValidator(is_valid_sha256)]
+
+
+def is_valid_install_args(
+    install_args: list[str] | tuple[str, ...] | str,
+) -> tuple[str, ...]:
+    """Make sure a string is a valid install string for a package manager, e.g. ['yt-dlp', 'ffmpeg']"""
+    if isinstance(install_args, str):
+        install_args = [install_args]
+    assert install_args
+    assert all(len(arg) for arg in install_args)
+    return tuple(install_args)
+
+
+def is_name_of_method_on_self(method_name: str) -> str:
+    assert (
+        method_name.startswith("self.")
+        and method_name.replace(".", "").replace("_", "").isalnum()
+    )
+    return method_name
+
+
+InstallArgs = Annotated[
+    tuple[str, ...] | list[str],
+    AfterValidator(is_valid_install_args),
+]
+
+SelfMethodName = Annotated[str, AfterValidator(is_name_of_method_on_self)]