akebi 0.1.0__py3-none-any.whl

akebi/__init__.py

@@ -0,0 +1 @@
+from akebi.bun import Bun

akebi/bun.py

@@ -0,0 +1,217 @@
+import contextlib
+import hashlib
+import os
+import platform
+import shutil
+import stat
+import subprocess
+import typing as t
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from zipfile import ZipFile
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    TypeAdapter,
+    ValidationInfo,
+    field_validator,
+    validate_call,
+)
+from pydantic_extra_types.semantic_version import SemanticVersion
+from rich.status import Status
+
+from akebi import utils
+
+
+class Bun(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    app_name: str = None
+    """
+    An identifier under which Bun installations created by this object are to be isolated.
+    """
+
+    # In practice, this will always be a `SemanticVersion` object.
+    version: SemanticVersion | t.Literal["latest"] = Field(None, validate_default=True)
+    """
+    The version of Bun to use. Leave empty to use the latest version locally available. Pass "latest" to use the
+    latest version, period.
+    """
+
+    @field_validator("version", mode="before")
+    @classmethod
+    def validate_version(cls, v, info: ValidationInfo) -> SemanticVersion | str:
+        if v is None:
+            installed_versions = []
+
+            for directory in utils.get_bun_dir(info.data.get("app_name")).glob("*/"):
+                try:
+                    installed_versions.append(
+                        TypeAdapter(SemanticVersion).validate_python(directory.name)
+                    )
+                except ValueError:
+                    pass
+
+            if installed_versions:
+                return max(installed_versions)
+            else:
+                v = "latest"
+
+        if isinstance(v, str) and v == "latest":
+            with utils.github_client(api=True) as gh:
+                releases = (
+                    gh.get("/repos/oven-sh/bun/releases").raise_for_status().json()
+                )
+
+            return releases[0]["tag_name"].split("-v")[-1]
+
+        return v
+
+    @property
+    def bin_path(self) -> Path:
+        """
+        The absolute path to the Bun executable.
+
+        This only returns where the executable *should* be; it does not guarantee that it exists.
+        """
+        return utils.get_bun_dir(self.app_name) / str(self.version) / "bin" / "bun"
+
+    @property
+    def checksum(self) -> str | None:
+        """
+        The checksum of the file at the intended location of the Bun executable.
+        """
+        if self.bin_path.is_file():
+            return hashlib.sha256(self.bin_path.read_bytes()).hexdigest()
+
+    @property
+    def stored_checksum(self) -> str | None:
+        """
+        The checksum of the Bun executable at the time it was downloaded.
+        """
+        with utils.state(table="bun") as bun_db:
+            return bun_db.get(str(self.bin_path))
+
+    @property
+    def is_installed(self) -> bool:
+        """
+        Whether this Bun is installed.
+        """
+        return self.bin_path.is_file() and self.checksum == self.stored_checksum
+
+    def setup(self, *, force: bool = False) -> t.Self:
+        """
+        Install this Bun if it isn't installed already.
+
+        Parameters
+        ----------
+        force: bool, default=False
+            Install this Bun even if it's already installed.
+
+        Returns
+        -------
+        Bun
+            This object.
+        """
+        if self.is_installed and not force:
+            return self
+
+        with Status(f"Installing Bun v{self.version}..."):
+            target = {"host": platform.system().casefold()}
+
+            architecture = platform.machine().casefold()
+
+            match architecture:
+                case "x86_64" | "amd64":
+                    target["architecture"] = "x64"
+                case "arm64":
+                    target["architecture"] = "aarch64"
+                case _:
+                    target["architecture"] = architecture
+
+            if target["host"] == "linux":
+                libc = utils.guess_libc()
+
+                if libc == "musl":
+                    target["libc"] = libc
+
+            if utils.needs_baseline_build():
+                target["build"] = "baseline"
+
+            asset = f"bun-{'-'.join(target.values())}.zip"
+
+            with utils.github_client() as gh:
+                asset_resp = gh.get(
+                    f"/oven-sh/bun/releases/download/bun-v{self.version}/{asset}",
+                    follow_redirects=True,
+                )
+
+            if asset_resp.status_code == 404:
+                # noinspection PyArgumentList
+                raise Exception(
+                    f"No Bun {self.version} release with name {asset} could be found"
+                )
+
+            asset_resp.raise_for_status()
+
+            with TemporaryDirectory() as tmpdir:
+                with contextlib.chdir(tmpdir):
+                    bun_zip = Path("bun.zip")
+                    bun_zip.write_bytes(asset_resp.content)
+
+                    ZipFile(bun_zip).extractall()
+
+                    bun_bin = next(Path.cwd().glob("**/bun"))
+                    bun_bin.chmod(bun_bin.stat().st_mode | stat.S_IEXEC)
+
+                    self.bin_path.parent.mkdir(parents=True, exist_ok=True)
+
+                    shutil.move(bun_bin, self.bin_path)
+
+            with utils.state(table="bun") as bun_db:
+                bun_db[str(self.bin_path)] = self.checksum
+
+            return self
+
+    @validate_call()
+    def __call__(
+        self,
+        args: t.Annotated[list | str, Field(default_factory=list)],
+        /,
+        **kwargs,
+    ) -> subprocess.CompletedProcess:
+        """
+        Invoke this Bun.
+
+        Parameters
+        ----------
+        args: list or str, optional, default=[]
+            Command-line arguments to pass to the invocation.
+
+        kwargs: dict, default={}
+            Arbitrary keyword arguments to pass to ``subprocess.run``.
+
+        Returns
+        -------
+        subprocess.CompletedProcess
+            The associated ``subprocess.CompletedProcess`` object.
+        """
+        self.setup()
+
+        if isinstance(args, list):
+            args = [self.bin_path] + args
+        elif isinstance(args, str):
+            args = f"{self.bin_path} {args}"
+
+        env = kwargs.get("env", os.environ)
+
+        # If the Bun binary isn't on PATH then things like create-next-app will be displeased.
+        if isinstance(env, t.MutableMapping):
+            kwargs["env"] = {
+                **env,
+                "PATH": str(self.bin_path.parent) + os.pathsep + env.get("PATH", ""),
+            }
+
+        return subprocess.run(args, **kwargs)

akebi/utils.py

@@ -0,0 +1,182 @@
+import ctypes
+import platform
+import subprocess
+import typing as t
+from contextlib import contextmanager
+from pathlib import Path
+
+import httpx2 as httpx
+import kokomikke
+import platformdirs
+from sqlitedict import SqliteDict
+
+
+def github_client(*, api: bool = False, **kwargs) -> httpx.Client:
+    """
+    Return an ``httpx.Client`` for GitHub.
+
+    Parameters
+    ----------
+    api: bool, default=False
+        If True, return an `httpx.Client` for the GitHub API.
+
+    kwargs: dict, default={}
+        Arbitrary keyword arguments to pass to ``httpx.Client``.
+    """
+    return httpx.Client(
+        base_url="https://api.github.com" if api else "https://github.com",
+        event_hooks={
+            "request": [_github_client_request_token_hook],
+            "response": [_github_client_rate_limit_hook],
+        },
+        **kwargs,
+    )
+
+
+def get_cache_dir() -> Path:
+    """
+    Return Akebi's cache directory.
+    """
+    path = platformdirs.user_cache_path("akebi", appauthor=False)
+    path.mkdir(exist_ok=True, parents=True)
+
+    return path
+
+
+def get_data_dir() -> Path:
+    """
+    Return Akebi's data directory.
+    """
+    path = platformdirs.user_data_path("akebi", appauthor=False)
+    path.mkdir(parents=True, exist_ok=True)
+
+    return path
+
+
+def get_bun_dir(app_name: str = None) -> Path:
+    """
+    Return the directory where Akebi-managed Bun installs are located.
+    """
+    if app_name:
+        path = get_cache_dir() / "isolated" / app_name / "bun"
+    else:
+        path = get_cache_dir() / "shared" / "bun"
+
+    path.mkdir(parents=True, exist_ok=True)
+
+    return path
+
+
+def guess_libc() -> t.Literal["gnu", "musl"] | None:
+    """
+    Make a best-effort attempt at determining the C standard library implementation on a Linux system.
+    """
+    if platform.system().lower() != "linux":
+        return None
+
+    # Check os-release for known musl distributions
+    try:
+        os_release = platform.freedesktop_os_release()
+    except OSError:
+        pass
+    else:
+        identities = {os_release.get("ID")}.union(os_release.get("ID_LIKE", "").split())
+
+        if identities.intersection({"alpine", "postmarketos", "chimera"}):
+            return "musl"
+
+    # Read the output of `ldd --version`
+    try:
+        ldd_command = subprocess.run(
+            ["ldd", "--version"], capture_output=True, text=True
+        )
+    except FileNotFoundError:
+        pass
+    else:
+        # `ldd --version` on musl systems exits nonzero and writes to stderr. why? you tell me
+        ldd_info = ldd_command.stdout + ldd_command.stderr
+
+        if "gnu" in ldd_info.casefold():
+            return "gnu"
+        elif "musl" in ldd_info.casefold():
+            return "musl"
+
+    # Check which libc the Python interpreter is linked against
+    match platform.libc_ver()[0]:
+        case "glibc":
+            return "gnu"
+        case "musl":
+            return "musl"
+
+    # Check /lib and /lib64 for files beginning with ld-linux- or ld-musl-
+    for directory in ["/lib", "/lib64"]:
+        for prefix, libc in zip(["ld-linux-", "ld-musl-"], ["gnu", "musl"]):
+            if next(Path(directory).glob(f"{prefix}*"), None):
+                return libc
+
+    # If all else fails, assume glibc and hope for the best
+    return "gnu"
+
+
+def needs_baseline_build() -> bool:
+    """
+    Determine whether the host machine requires a baseline build of Bun.
+    """
+
+    if platform.machine() in ["arm64", "aarch64"]:
+        return False
+
+    match platform.system().lower():
+        case "darwin":
+            try:
+                sysctl = subprocess.check_output(["sysctl", "-a"], text=True)
+            except FileNotFoundError, subprocess.CalledProcessError:
+                return True
+            else:
+                return "avx2" not in sysctl.casefold()
+
+        case "linux":
+            cpu_info = Path("/proc/cpuinfo")
+            return not (
+                cpu_info.is_file() and "avx2" in cpu_info.read_text().casefold()
+            )
+
+        case "windows":
+            return not bool(ctypes.windll.kernel32.IsProcessorFeaturePresent(40))
+
+    return True
+
+
+@contextmanager
+def state(table: str = "unnamed") -> SqliteDict:
+    """
+    Context manager for accessing Akebi's key-value store.
+
+    Parameters
+    ----------
+    table: str, default="unnamed"
+        The table to access.
+    """
+    with SqliteDict(get_data_dir() / "akebi.db", tablename=table) as db:
+        yield db
+        db.commit()
+
+
+def _github_client_request_token_hook(request: httpx.Request) -> None:
+    """
+    HTTPX event hook to attach a GitHub access token, if one can be found, to requests to GitHub.
+    """
+    if token := kokomikke.search():
+        request.headers["Authorization"] = f"Bearer {token}"
+
+
+def _github_client_rate_limit_hook(response: httpx.Response) -> None:
+    """
+    HTTPX event hook to handle HTTP 429 errors in responses from GitHub.
+    """
+    if response.status_code == 429:
+        raise Exception(
+            "GitHub is rate limiting you. You can probably fix this by setting the "
+            "GITHUB_TOKEN environment variable or logging into the GitHub CLI (https://cli.github.com); your "
+            "credentials will automatically be attached to future GitHub requests."
+        )

akebi-0.1.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: akebi
+Version: 0.1.0
+Summary: Manage Bun installations from Python
+Author-email: celsius narhwal <hello@celsiusnarhwal.dev>
+License-File: LICENSE.md
+Requires-Python: >=3.14
+Requires-Dist: httpx2>=2.4.0
+Requires-Dist: kokomikke>=0.1.4
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: platformdirs>=4.10.0
+Requires-Dist: pydantic-extra-types>=2.11.1
+Requires-Dist: pydantic-settings>=2.14.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: rich>=15.0.0
+Requires-Dist: semver>=3.0.4
+Requires-Dist: sqlitedict>=2.1.0
+Description-Content-Type: text/markdown
+
+# Akebi
+
+Akebi allows Python programs to manage [Bun](https://bun.com) installations. It is intended for programs that need
+to install or run Node.js packages but do not wish to depend on the end user having an appropriate runtime or package
+manager installed.
+
+## Installation
+
+```shell
+pip install akebi
+```
+
+## Usage
+
+First, create an `akebi.Bun` object:
+
+```python
+from akebi import Bun
+
+bun = Bun()
+bun = Bun(version="1.3.14")  # use a specific version of Bun
+bun = Bun(version="latest")  # use the latest version of Bun
+```
+
+You can then invoke Bun by calling the `Bun` object you just created. A `Bun` object takes a `subprocess.run`-esque list or string
+containing command-line arguments.
+
+```python
+from akebi import Bun
+
+bun = Bun()
+
+bun(["run", "./my-script.ts"])
+bun(["add", "next"])
+bun(["create", "docusaurus"])
+```
+
+Akebi will automatically install Bun as necessary, but you can also install it manually with `Bun.setup`:
+
+```python
+bun.setup()
+
+# or, to forcibly overwrite existing installations of the same version:
+
+bun.setup(force=True)  
+```
+
+Under the hood, Akebi uses `subprocess.run` to invoke Bun. Keyword arguments passed to `Bun` objects will be passed 
+through to `subprocess.run`, e.g.:
+
+```python
+bun("update tailwindcss", shell=True, capture_output=True, text=True)
+```
+
+### Isolated installations
+
+If you want to ensure the Bun installations used by your program aren't touched by anything else that uses
+Akebi, you can set `Bun.app_name`:
+
+```python
+bun = Bun(app_name="com.example.myapp")
+```
+
+Bun installations created by your program will be located under an `app_name` subdirectory. You should choose
+an app name that's consistent within your program and not likely be taken by other programs that use
+Akebi.

akebi-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+akebi/__init__.py,sha256=FPE54glVDeEhp5nhkb4xhDdIx1vkWqXM-ZMtq6rdWnY,26
+akebi/bun.py,sha256=1o1osEUof_s4Ha5dEfaUPnTmHuv0Yaj3mf7dNplAS0U,6538
+akebi/utils.py,sha256=NgvTk3ThJzg2Zrf7KLtBdYosyCaA5Xw8YAlOXMrsllY,5235
+akebi-0.1.0.dist-info/METADATA,sha256=_ryY2Ex7IsgHb-IG8OHFT40ysaQRQOK9jG369TBAzZQ,2319
+akebi-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+akebi-0.1.0.dist-info/entry_points.txt,sha256=CYzeoyViLwn_s_HxQTTNzLyyxULPY1DMn-_99Lf-Tsc,37
+akebi-0.1.0.dist-info/licenses/LICENSE.md,sha256=hA4i2yCQXys8petYmompsCotSkMDAtoJ5WDiDAsuoGA,1100
+akebi-0.1.0.dist-info/RECORD,,

akebi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

akebi-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+akebi = akebi:main

akebi-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,25 @@
+# The MIT License (MIT)
+
+Copyright © 2026-present celsius narhwal
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+