dotlocalslashbin 0.0.6__tar.gz → 0.0.8__tar.gz

dotlocalslashbin-0.0.8/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.1
+Name: dotlocalslashbin
+Version: 0.0.8
+Summary: Download and extract files to `~/.local/bin/`.
+Author-email: Keith Maxwell <keith.maxwell@gmail.com>
+Description-Content-Type: text/markdown
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
+Requires-Dist: black ; extra == "test"
+Requires-Dist: codespell ; extra == "test"
+Requires-Dist: flit ; extra == "test"
+Requires-Dist: mypy ; extra == "test"
+Requires-Dist: nox ; extra == "test"
+Requires-Dist: ruff ; extra == "test"
+Requires-Dist: usort ; extra == "test"
+Project-URL: Home, https://github.com/maxwell-k/dotlocalslashbin/
+Provides-Extra: test
+
+`dotlocalslashbin` → Download to `~/.local/bin/`
+
+## Features
+
+Uses a [TOML] configuration file, by default `bin.toml` and has no dependencies
+beyond the Python standard library. Supports the following actions after
+downloading the URL\* to a cache:
+
+- extract to the output directory — from zip or tar files — or
+- create a symbolic link in the output directory or
+- run a command for example to correct the shebang line in a zipapp or
+- copy the downloaded file
+
+Guesses the correct action if none is specified. By default caches downloads to
+`~/.cache/dotlocalslashbin/`.
+
+Optionally can:
+
+- run a command after download for example to correct a shebang line
+- confirm a SHA256 or SHA512 hex-digest of the downloaded file
+- invoke the target with an argument, for example `--version`
+- strip a prefix while extracting
+- ignore certain files while extracting
+
+\* if the URL is an absolute path on the local file system; it is not downloaded
+to the cache.
+
+[TOML]: https://en.wikipedia.org/wiki/TOML
+
+## Examples
+
+For example to download `yq` to the current working directory, first save the
+following as `yq.toml`, then run the command below:
+
+```
+[yq]
+expected = "cfbbb9ba72c9402ef4ab9d8f843439693dfb380927921740e51706d90869c7e1"
+url = "https://github.com/mikefarah/yq/releases/download/v4.43.1/yq_linux_amd64"
+version = "--version"
+```
+
+Command:
+
+    dotlocalslashbin --input=yq.toml --output=.
+
+Further examples are available in
+[`bin.toml` in maxwell-k/dotfiles](https://github.com/maxwell-k/dotfiles/blob/main/bin.toml).
+
+## See also
+
+<https://github.com/buildinspace/peru>
+
+<!--
+README.md
+SPDX-FileCopyrightText: 2024 Keith Maxwell <keith.maxwell@gmail.com>
+SPDX-License-Identifier: CC0-1.0
+-->
+<!-- vim: set filetype=markdown.htmlCommentNoSpell  : -->
+

dotlocalslashbin-0.0.8/README.md

@@ -0,0 +1,58 @@
+`dotlocalslashbin` → Download to `~/.local/bin/`
+
+## Features
+
+Uses a [TOML] configuration file, by default `bin.toml` and has no dependencies
+beyond the Python standard library. Supports the following actions after
+downloading the URL\* to a cache:
+
+- extract to the output directory — from zip or tar files — or
+- create a symbolic link in the output directory or
+- run a command for example to correct the shebang line in a zipapp or
+- copy the downloaded file
+
+Guesses the correct action if none is specified. By default caches downloads to
+`~/.cache/dotlocalslashbin/`.
+
+Optionally can:
+
+- run a command after download for example to correct a shebang line
+- confirm a SHA256 or SHA512 hex-digest of the downloaded file
+- invoke the target with an argument, for example `--version`
+- strip a prefix while extracting
+- ignore certain files while extracting
+
+\* if the URL is an absolute path on the local file system; it is not downloaded
+to the cache.
+
+[TOML]: https://en.wikipedia.org/wiki/TOML
+
+## Examples
+
+For example to download `yq` to the current working directory, first save the
+following as `yq.toml`, then run the command below:
+
+```
+[yq]
+expected = "cfbbb9ba72c9402ef4ab9d8f843439693dfb380927921740e51706d90869c7e1"
+url = "https://github.com/mikefarah/yq/releases/download/v4.43.1/yq_linux_amd64"
+version = "--version"
+```
+
+Command:
+
+    dotlocalslashbin --input=yq.toml --output=.
+
+Further examples are available in
+[`bin.toml` in maxwell-k/dotfiles](https://github.com/maxwell-k/dotfiles/blob/main/bin.toml).
+
+## See also
+
+<https://github.com/buildinspace/peru>
+
+<!--
+README.md
+SPDX-FileCopyrightText: 2024 Keith Maxwell <keith.maxwell@gmail.com>
+SPDX-License-Identifier: CC0-1.0
+-->
+<!-- vim: set filetype=markdown.htmlCommentNoSpell  : -->

{dotlocalslashbin-0.0.6 → dotlocalslashbin-0.0.8}/pyproject.toml

@@ -23,12 +23,34 @@ dotlocalslashbin = "dotlocalslashbin:main"
 test = [
   "black",
   "codespell",
-  "flake8",
   "flit",
+  "mypy",
   "nox",
+  "ruff",
   "usort",
 ]
 
+[tool.ruff]
+line-length = 88
+indent-width = 4
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  # "C901", # TODO
+  "D203", # incompatible with D211
+  "D213", # incompatible with D212
+  "I", # prefer usort to ruff isort implementation
+  # "PLR0912", # TODO
+  # "PLR0913", # TODO
+  # "PLR0915", # TODO
+  "S310", # the rule errors on the "use instead" code from `ruff rule S310`
+  "S602", # assume arguments to subprocess.run are validated
+  "S603", # assume trusted input  to subprocess.run
+  "T201", # print is used for output in command line scripts
+]
+
 # pyproject.toml
 # SPDX-FileCopyrightText: 2024 Keith Maxwell <keith.maxwell@gmail.com>
 # SPDX-License-Identifier: CC0-1.0

dotlocalslashbin-0.0.8/src/dotlocalslashbin.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+# src/dotlocalslashbin.py
+# Copyright 2022 Keith Maxwell
+# SPDX-License-Identifier: MPL-2.0
+"""Download and extract files to `~/.local/bin/`."""
+import tarfile
+from argparse import ArgumentDefaultsHelpFormatter, ArgumentParser, Namespace
+from dataclasses import dataclass
+from enum import Enum
+from hashlib import file_digest
+from pathlib import Path
+from shlex import split
+from shutil import copy
+from stat import S_IEXEC
+from subprocess import run
+from tomllib import load
+from urllib.error import HTTPError
+from urllib.request import urlopen
+from zipfile import ZipFile
+
+
+__version__ = "0.0.8"
+
+DEFAULT_OUTPUT = Path("~/.local/bin/")
+_SHA512_LENGTH = 128
+
+
+class _CustomNamespace(Namespace):
+    output: Path
+    input: Path
+    downloaded: Path
+
+
+Action = Enum("Action", ["command", "copy", "symlink", "untar", "unzip"])
+
+
+@dataclass(init=False)
+class Item:
+    """Class for an application."""
+
+    name: str
+    url: str
+    target: Path
+    action: Action
+    downloaded: Path
+    expected: str | None
+    version: str | None
+    prefix: str
+    command: str | None
+    ignore: set
+
+
+def main() -> int:
+    """Parse command line arguments and download each file."""
+    args = _parse_args()
+
+    with args.input.expanduser().open("rb") as file:
+        data = load(file)
+
+    for name, record in data.items():
+        item = Item()
+        item.name = name
+        item.url = record["url"]
+        default = args.output.joinpath(name)
+        item.target = Path(record.get("target", default)).expanduser()
+        item.ignore = record.get("ignore", set())
+        item.expected = record.get("expected", None)
+        item.version = record.get("version", None)
+        item.prefix = record.get("prefix", "")
+        item.command = record.get("command", None)
+
+        if "action" in record:
+            item.action = getattr(Action, record["action"])
+        else:
+            item.action = _guess_action(item)
+
+        if item.url.startswith("https://"):
+            item.downloaded = args.downloaded.expanduser() / item.url.rsplit("/", 1)[1]
+        else:
+            item.downloaded = Path(item.url)
+        try:
+            _process(item)
+        except HTTPError as e:
+            print(f"Error {e.code} downloading {e.url}")
+            return 1
+
+        arg0 = item.name if args.output == DEFAULT_OUTPUT else str(item.target)
+        print(" ".join(("#" if item.version else "$", arg0, item.version or "")))
+        if item.version:
+            run([arg0, item.version], check=True)
+        print()
+
+    return 0
+
+
+def _process(item: Item) -> None:
+    """Context manager to download and install a program."""
+    if not item.downloaded.is_file() and item.url.startswith("https://"):
+        _download(item)
+
+    if item.expected:
+        with item.downloaded.open("rb") as f:
+            _digest = "sha512" if len(item.expected) == _SHA512_LENGTH else "sha256"
+            digest = file_digest(f, _digest)
+
+        if (actual := digest.hexdigest()) != item.expected:
+            msg = f"Unexpected digest for {item.downloaded}: {actual=} {item.expected=}"
+            raise RuntimeError(msg)
+
+    item.target.parent.mkdir(parents=True, exist_ok=True)
+    item.target.unlink(missing_ok=True)
+    if item.action == Action.copy:
+        copy(item.downloaded, item.target)
+    elif item.action == Action.symlink:
+        item.target.symlink_to(item.downloaded)
+    elif item.action == Action.unzip:
+        with ZipFile(item.downloaded, "r") as file:
+            file.extract(item.target.name, path=item.target.parent)
+    elif item.action == Action.untar:
+        _untar(item)
+    elif item.action == Action.command and item.command is not None:
+        kwargs = {"target": item.target, "downloaded": item.downloaded}
+        run(split(item.command.format(**kwargs)), check=True)
+
+    if not item.target.is_symlink():
+        item.target.chmod(item.target.stat().st_mode | S_IEXEC)
+
+
+def _parse_args() -> _CustomNamespace:
+    parser = ArgumentParser(
+        prog=Path(__file__).name,
+        formatter_class=ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    help_ = "TOML specification"
+    parser.add_argument("--input", default="bin.toml", help=help_, type=Path)
+    help_ = "Target directory"
+    parser.add_argument("--output", default=DEFAULT_OUTPUT, help=help_, type=Path)
+    help_ = "Output directory"
+    default = "~/.cache/dotlocalslashbin/"
+    parser.add_argument("--downloaded", default=default, help=help_, type=Path)
+    return parser.parse_args(namespace=_CustomNamespace())
+
+
+def _download(item: Item) -> None:
+    item.downloaded.parent.mkdir(parents=True, exist_ok=True)
+    with urlopen(item.url) as fp, item.downloaded.open("wb") as dp:
+        size = int(fp.headers.get("Content-Length", -1))
+        print(f"Downloading {item.name}…")
+        written = dp.write(fp.read())
+
+    if size >= 0 and written != size:
+        msg = "Wrong content length"
+        raise RuntimeError(msg)
+
+
+def _untar(item: Item) -> None:
+    with tarfile.open(item.downloaded, "r") as file:
+        for member in file.getmembers():
+            if member.path in item.ignore:
+                continue
+            member.path = member.path.removeprefix(item.prefix)
+            try:
+                file.extract(member, path=item.target.parent, filter="tar")
+            except TypeError:  # before 3.11.4 e.g. Debian 12
+                file.extract(member, path=item.target.parent)
+
+
+def _guess_action(item: Item) -> Action:
+    if item.url.endswith((".tar.gz", ".tar")):
+        guess = Action.untar
+    elif item.url.endswith(".zip"):
+        guess = Action.unzip
+    elif item.url.startswith("/"):
+        guess = Action.symlink
+    elif item.command:
+        guess = Action.command
+    else:
+        guess = Action.copy
+    return guess
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dotlocalslashbin-0.0.6/PKG-INFO

@@ -1,26 +0,0 @@
-Metadata-Version: 2.1
-Name: dotlocalslashbin
-Version: 0.0.6
-Summary: Download and extract files to ~/.local/bin/
-Author-email: Keith Maxwell <keith.maxwell@gmail.com>
-Description-Content-Type: text/markdown
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
-Requires-Dist: black ; extra == "test"
-Requires-Dist: codespell ; extra == "test"
-Requires-Dist: flake8 ; extra == "test"
-Requires-Dist: flit ; extra == "test"
-Requires-Dist: nox ; extra == "test"
-Requires-Dist: usort ; extra == "test"
-Project-URL: Home, https://github.com/maxwell-k/dotlocalslashbin/
-Provides-Extra: test
-
-Download and extract files to ~/.local/bin/
-
-<!--
-README.md
-SPDX-FileCopyrightText: 2024 Keith Maxwell <keith.maxwell@gmail.com>
-SPDX-License-Identifier: CC0-1.0
--->
-<!-- vim: set filetype=markdown.htmlCommentNoSpell  : -->
-

dotlocalslashbin-0.0.6/README.md

@@ -1,8 +0,0 @@
-Download and extract files to ~/.local/bin/
-
-<!--
-README.md
-SPDX-FileCopyrightText: 2024 Keith Maxwell <keith.maxwell@gmail.com>
-SPDX-License-Identifier: CC0-1.0
--->
-<!-- vim: set filetype=markdown.htmlCommentNoSpell  : -->

dotlocalslashbin-0.0.6/src/dotlocalslashbin.py

@@ -1,192 +0,0 @@
-#!/usr/bin/env python3
-# src/dotlocalslashbin.py
-# Copyright 2022 Keith Maxwell
-# SPDX-License-Identifier: MPL-2.0
-"""Download and extract files to ~/.local/bin/"""
-import tarfile
-from argparse import (
-    ArgumentDefaultsHelpFormatter as formatter_class,
-    ArgumentParser,
-    Namespace,
-)
-from collections.abc import Generator
-from contextlib import contextmanager
-from hashlib import file_digest
-from pathlib import Path
-from shlex import split
-from shutil import copy
-from stat import S_IEXEC
-from subprocess import run
-from tomllib import load
-from urllib.error import HTTPError
-from urllib.request import urlopen
-from zipfile import ZipFile
-
-
-__version__ = "0.0.6"
-
-
-class CustomNamespace(Namespace):
-    output: Path
-    input: Path
-    downloaded: Path
-    completions: Path
-
-
-def parse_args():
-    parser = ArgumentParser(prog=Path(__file__).name, formatter_class=formatter_class)
-    parser.add_argument("--version", action="version", version=__version__)
-    help_ = "TOML specification"
-    parser.add_argument("--input", default="bin.toml", help=help_, type=Path)
-    help_ = "Target directory"
-    parser.add_argument("--output", default="~/.local/bin/", help=help_, type=Path)
-    help_ = "Download directory"
-    default = "~/.cache/dotlocalslashbin/"
-    parser.add_argument("--downloaded", default=default, help=help_, type=Path)
-    help_ = "Directory for ZSH completions"
-    default = "~/.local/share/zsh/site-functions/"
-    parser.add_argument("--completions", default=default, help=help_, type=Path)
-    return parser.parse_args(namespace=CustomNamespace)
-
-
-@contextmanager
-def _download(
-    args: type[CustomNamespace],
-    *,
-    name: str,
-    url: str,
-    target: Path | None = None,
-    action: str | None = None,
-    expected: str | None = None,
-    version: str | None = None,
-    prefix: str | None = None,
-    completions: str | None = None,
-    command: str | None = None,
-    ignore: set = set(),
-) -> Generator[tuple[Path, Path], None, None]:
-    """Context manager to download and install a program
-
-    Arguments:
-        url: the URL to download
-        action: action to take to install for example copy
-        target: the destination
-        expected: the SHA256 or SHA512 hex-digest of the file at URL
-        version: an argument to display the version for example --version
-        prefix: to remove when untarring
-        completions: whether to generate ZSH completions
-        command: command to run to install after download
-    """
-    if target is None:
-        target = args.output.joinpath(name)
-    assert target is not None
-
-    if url.startswith("https://"):
-        downloaded = args.downloaded.expanduser() / url.rsplit("/", 1)[1]
-        downloaded.parent.mkdir(parents=True, exist_ok=True)
-        if not downloaded.is_file():
-            with urlopen(url) as fp, downloaded.open("wb") as dp:
-                if "content-length" in fp.headers:
-                    size = int(fp.headers["Content-Length"])
-                else:
-                    size = -1
-
-                print(f"Downloading {name}…")
-                written = dp.write(fp.read())
-
-            if size >= 0 and written != size:
-                raise RuntimeError("Wrong content length")
-
-        if expected:
-            digest = "sha256"
-            if len(expected) == 128:
-                digest = "sha512"
-            with downloaded.open("rb") as f:
-                digest = file_digest(f, digest)
-
-            if (actual := digest.hexdigest()) != expected:
-                raise RuntimeError(
-                    f"Unexpected digest for {downloaded}: {actual=} {expected=}"
-                )
-    else:
-        downloaded = Path(url)
-
-    if action is None:
-        if url.endswith(".tar.gz"):
-            action = "untar"
-        elif url.endswith(".zip"):
-            action = "unzip"
-        elif url.startswith("/"):
-            action = "symlink"
-        elif command:
-            action = "command"
-        else:
-            action = "copy"
-
-    message = ("#" if version else "$") + f" {target} " + (version or "")
-    target = target.expanduser()
-    target.parent.mkdir(parents=True, exist_ok=True)
-    target.unlink(missing_ok=True)
-    if action == "copy":
-        copy(downloaded, target)
-    elif action == "symlink":
-        target.symlink_to(downloaded)
-    elif action == "unzip":
-        with ZipFile(downloaded, "r") as file:
-            file.extract(target.name, path=target.parent)
-    elif action == "untar":
-        with tarfile.open(downloaded, "r") as file:
-            for member in file.getmembers():
-                if prefix:
-                    member.path = member.path.removeprefix(prefix)
-                if member.path in ignore:
-                    continue
-                try:
-                    file.extract(member, path=target.parent, filter="tar")
-                except TypeError:  # before 3.11.4 e.g. Debian 12
-                    file.extract(member, path=target.parent)
-
-    elif action == "command" and command is not None:
-        kwargs = dict(target=target, downloaded=downloaded)
-        run(split(command.format(**kwargs)), check=True)
-
-    yield downloaded, target
-
-    if not target.is_symlink():
-        target.chmod(target.stat().st_mode | S_IEXEC)
-
-    if completions:
-        output = args.completions.expanduser() / f"_{target.name}"
-        output.parent.mkdir(parents=True, exist_ok=True)
-        kwargs = dict(target=target)  # target may not be on PATH
-        with output.open("w") as file:
-            run(split(completions.format(**kwargs)), check=True, stdout=file)
-
-    print(message)
-    if version:
-        run([target, version], check=True)
-
-    print()
-
-
-def main() -> int:
-    args = parse_args()
-
-    with args.input.expanduser().open("rb") as file:
-        data = load(file)
-
-    for name, kwargs in data.items():
-        kwargs["name"] = name
-        if "target" in kwargs:
-            kwargs["target"] = Path(kwargs["target"])
-        try:
-            with _download(args, **kwargs) as (downloaded, target):
-                pass
-        except HTTPError as e:
-            print(f"Error {e.code} downloading {e.url}")
-            return 1
-
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())