first working version

.devcontainer/devcontainer.json

@@ -0,0 +1,12 @@
+{
+    "image": "python:3.10",
+    "extensions" : [
+        "eamodio.gitlens",
+        "mhutchie.git-graph",
+        "ms-azuretools.vscode-docker"
+    ],
+    "runArgs": [
+        "--privileged",
+    ],
+    "onCreateCommand": "apt update && apt --yes install git && pip install -r requirements/requirements.python.txt -r requirements/requirements.python.test.txt && git config --global --add safe.directory $PWD"
+}

.github/workflows/test.yml

@@ -0,0 +1,46 @@
+name: Test
+
+on:
+    push:
+        branches:
+            - main
+    pull_request:
+        branches:
+            - main
+
+jobs:
+
+    test:
+        runs-on: ubuntu-latest
+        container:
+            image: python:3.10
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Install dependencies.
+              run : |
+                python -m pip install -r requirements/requirements.python.txt -r requirements/requirements.python.test.txt
+
+            - name: Run tests.
+              run : |
+                python -m pytest tests
+
+    install-as-package-and-test:
+        runs-on: [ubuntu-latest]
+        container:
+            image: python:3.10
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  path: package-sources
+
+            - name: Install as package.
+              run : |
+                  # If this repository becomes public, be sure to use the following instead:
+                  # pip install git+https://github.com/uliegecsm/apt-helpers.git@${{ github.sha }}
+                  pip install package-sources
+                  rm -rf package-sources
+
+            - name: Test as CLI directly.
+              run : |
+                  apt-helpers install-packages --update --clean --upgrade --packages jq

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ULiege CSM
+
+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.

README.md

@@ -1,2 +1,3 @@
-# apt-helpers
+# `apt` helpers
+
 This repository contains useful standalone helper scripts for `apt`.

apt_helpers/alternatives.py

@@ -0,0 +1,25 @@
+import pathlib
+import subprocess
+import typing
+
+import typeguard
+
+@typeguard.typechecked
+def update_alternatives(*,
+    for_each_of : typing.Dict,
+    prefix : pathlib.Path,
+    level : int,
+    display : bool,
+) -> None:
+    """
+    Update alternatives for a list of 'apps'.
+    """
+    for link, command in for_each_of.items():
+        subprocess.check_call([
+            'update-alternatives',
+            '--install', prefix / link, link, prefix / command,
+            str(level),
+        ])
+
+        if display:
+            subprocess.check_call(['update-alternatives', '--display', link])

apt_helpers/helpers.py

@@ -0,0 +1,92 @@
+import argparse
+import logging
+import pathlib
+
+import typeguard
+
+from apt_helpers.alternatives import update_alternatives
+from apt_helpers.install      import apt_install_packages
+from apt_helpers.utils        import AppendKVPairsAction
+
+@typeguard.typechecked
+def parse_args() -> argparse.Namespace:
+    """
+    Parse CLI arguments.
+    """
+    parser = argparse.ArgumentParser()
+
+    subparsers = parser.add_subparsers(required = True)
+
+    parser_ua = subparsers.add_parser('update-alternatives')
+
+    parser_ua.add_argument(
+        '--prefix',
+        help = "Directory where alternatives are created.",
+        required = False, type = pathlib.Path, default = pathlib.Path("/usr/bin")
+    )
+
+    parser_ua.add_argument(
+        '--for-each-of',
+        help = "List of link-command pairs.",
+        nargs='*',
+        required = True, action = AppendKVPairsAction,
+    )
+
+    parser_ua.add_argument(
+        '--level',
+        help = "Priority level.",
+        required = False, type = int, default = 10
+    )
+
+    parser_ua.add_argument(
+        '--display',
+        help = "Whether to display information.",
+        required = False, action = 'store_true', default = True
+    )
+
+    parser_ua.set_defaults(func = update_alternatives)
+
+    parser_ip = subparsers.add_parser('install-packages')
+
+    parser_ip.add_argument('--clean',   action = 'store_true')
+    parser_ip.add_argument('--update',  action = 'store_true')
+    parser_ip.add_argument('--upgrade', action = 'store_true')
+
+    parser_ip.add_argument(
+        '--packages',
+        help = "List of packages to install.",
+        nargs = '*',
+        required = False,
+        dest = 'packages',
+    )
+
+    parser_ip.add_argument(
+        '--requirement',
+        help = 'Requirement file à la pip.',
+        dest = 'requirements',
+        action = 'append',
+        type = pathlib.Path,
+        required = False,
+    )
+
+    parser_ip.set_defaults(func = apt_install_packages)
+
+    return parser.parse_args()
+
+
+@typeguard.typechecked
+def main() -> None:
+
+    logging.basicConfig(level=logging.INFO)
+
+    args = parse_args()
+
+    kwargs = vars(args)
+
+    func = kwargs.pop('func')
+
+    func(**kwargs)
+
+if __name__ == "__main__":
+
+    main()

apt_helpers/install.py

@@ -0,0 +1,82 @@
+import logging
+import pathlib
+import shutil
+import subprocess
+import typing
+
+import typeguard
+
+@typeguard.typechecked
+def get_list_of_packages_from_requirements_file(*, file : pathlib.Path) -> typing.List[str]:
+    """
+    Get list of packages from a requirements file.
+
+    Note that this function only supports skipping empty lines and comment lines, *i.e.*,
+    not all features from https://pip.pypa.io/en/stable/reference/requirements-file-format/
+    are supported.
+    """
+    packages = []
+    with file.open(mode = "r") as file:
+        for line in file:
+            line = line.strip()
+            if line and not line.startswith('#'):
+                packages.extend(line.strip().split())
+    return packages
+
+@typeguard.typechecked
+def apt_install_command(*, yes : bool = True, no_install_recommends : bool = True) -> typing.List[str]:
+    """
+    Get the `apt` command to install packages.
+    """
+    cmd = ['apt']
+
+    if yes:
+        cmd.append('--yes')
+
+    if no_install_recommends:
+        cmd.append('--no-install-recommends')
+
+    cmd.append('install')
+    return cmd
+
+@typeguard.typechecked
+def apt_install_packages(*,
+    packages : typing.Optional[typing.List[str]] = None,
+    requirements : typing.Optional[typing.List[pathlib.Path]] = None,
+    update : bool = True,
+    upgrade : bool = False,
+    clean: bool = True,
+) -> None:
+    """
+    Install list of packages by using apt.
+
+    Optionally:
+        * update
+        * upgrade
+        * clean
+    """
+    to_be_installed = []
+
+    if packages:
+        to_be_installed += packages
+
+    if requirements:
+        for file in requirements:
+            to_be_installed += get_list_of_packages_from_requirements_file(file = file)
+
+    logging.info(f"Installing 'apt' packages {to_be_installed} (update={update}, upgrade={upgrade}, clean={clean})")
+
+    if update:
+        subprocess.check_call(["apt", "update"])
+
+    if upgrade:
+        subprocess.check_call(['apt', '--yes', 'upgrade'])
+
+    args = apt_install_command(yes = True, no_install_recommends = True)
+    args += to_be_installed
+
+    subprocess.check_call(args)
+
+    if clean:
+        subprocess.check_call(["apt", "clean"])
+        shutil.rmtree(pathlib.Path("/var/lib/apt/lists"))

apt_helpers/utils.py

@@ -0,0 +1,25 @@
+import argparse
+import typing
+
+import typeguard
+
+@typeguard.typechecked
+def dict_to_list(dic : dict, key_prefix : str = '', sep : str = "=", join : typing.Optional[str] = None) -> list | str:
+    """
+    Transform a dictionary to a list.
+    """
+    res = [
+        key_prefix + k + sep + v
+        for k, v in dic.items()
+    ]
+    return res if not join else join.join(res)
+
+class AppendKVPairsAction(argparse.Action):
+    """
+    Action to parse a list of key-value pairs and append to a dictionary.
+    """
+    @typeguard.typechecked
+    def __call__(self, parser : argparse.ArgumentParser, args : argparse.Namespace, values : typing.List[str], option_string : typing.Optional[str] = None, **kwargs):
+        kvpairs = getattr(args, self.dest) or {}
+        kvpairs.update(dict(map(lambda x: x.split("=", 2), values)))
+        setattr(args, self.dest, kvpairs)

requirements/requirements.python.test.txt

@@ -0,0 +1,2 @@
+pytest
+pytest_console_scripts

requirements/requirements.python.txt

@@ -0,0 +1,2 @@
+# This forwards 'pip' to the 'setup.py' install requirements.
+.

setup.py

@@ -0,0 +1,17 @@
+from setuptools import setup, find_packages
+
+setup(
+    name             = 'apt-helpers',
+    version          = '0.1',
+    install_requires = [
+        'typeguard',
+    ],
+    packages         = find_packages(),
+    license          = 'MIT',
+    url              = 'https://github.com/uliegecsm/apt-helpers',
+    entry_points = {
+        'console_scripts': [
+            'apt-helpers = apt_helpers.helpers:main',
+        ],
+    },
+)