first working version

.devcontainer/devcontainer.json

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

.github/workflows/test.yml

@@ -0,0 +1,51 @@
+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 typeguard -r requirements/requirements.python.test.txt
+
+            - name: Run tests.
+              run : |
+                python -m pytest tests -s --log-cli-level=info
+
+    install-as-package-and-test:
+        runs-on: [ubuntu-latest]
+        container:
+            image: python:${{ matrix.version }}
+        strategy:
+            matrix:
+                version: ['3.10', '3.12']
+        steps:
+            - name: Install as package.
+              run : |
+                  pip install git+https://github.com/uliegecsm/system-helpers.git@${{ github.sha }}
+
+            - name: Test 'apt' helpers as CLI directly.
+              run : |
+                  apt-helpers install-packages --update --clean --upgrade --packages jq
+
+            - name: Test 'update-alternatives' helpers as CLI directly.
+              run : |
+                  update-alternatives-helpers --help
+
+            - name: Check that we can import packages in Python.
+              run : |
+                  python -c "import apt_helpers"
+                  python -c "import update_alternatives_helpers"

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,11 @@
-# apt-helpers
-This repository contains useful standalone helper scripts for `apt`.
+# System helpers
+
+This repository contains useful standalone helper scripts for `Linux` systems.
+
+## `apt`
+
+Useful for dealing with `apt` related tasks.
+
+## `update-alternatives`
+
+Useful for dealing with `update-alternatives` tasks.

apt/helpers.py

@@ -0,0 +1,60 @@
+import argparse
+import logging
+import pathlib
+
+import typeguard
+
+from apt.install import install_packages
+
+@typeguard.typechecked
+def parse_args() -> argparse.Namespace:
+    """
+    Parse CLI arguments.
+    """
+    parser = argparse.ArgumentParser()
+
+    subparsers = parser.add_subparsers(required = True)
+
+    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 = 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/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 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 install_packages(*,
+    packages : typing.Optional[typing.List[str]] = None,
+    requirements : typing.Optional[typing.List[pathlib.Path]] = None,
+    update : bool = False,
+    upgrade : bool = False,
+    clean: bool = False,
+) -> 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 = 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"))

requirements/requirements.python.test.txt

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

setup.py

@@ -0,0 +1,25 @@
+from setuptools import setup
+
+setup(
+    name             = 'system-helpers',
+    version          = '0.1',
+    license          = 'MIT',
+    url              = 'https://github.com/uliegecsm/system-helpers',
+    install_requires = [
+        'typeguard',
+    ],
+    packages = [
+        'system_helpers.apt',
+        'system_helpers.update_alternatives',
+    ],
+    package_dir = {
+        'system_helpers.apt' : 'apt',
+        'system_helpers.update_alternatives' : 'update-alternatives',
+    },
+    entry_points = {
+        'console_scripts': [
+            'apt-helpers = system_helpers.apt.helpers:main',
+            'update-alternatives-helpers = system_helpers.update_alternatives.helpers:main',
+        ],
+    },
+)

tests/apt/test_install.py

@@ -0,0 +1,93 @@
+import itertools
+import pathlib
+import tempfile
+import typing
+import unittest.mock
+
+import pytest
+import pytest_console_scripts
+import typeguard
+
+from apt import install
+
+@pytest.fixture
+@typeguard.typechecked
+def requirements() -> typing.Generator[typing.Tuple[typing.List[pathlib.Path], typing.List[str]], None, None]:
+    """
+    Get requirements files *à la* `pip`.
+    """
+    with tempfile.NamedTemporaryFile(mode = 'w+') as req_1, \
+         tempfile.NamedTemporaryFile(mode = 'w+') as req_2:
+        req_1.write("# Let's start this first requirement file with a comment. Then, add some packages.\n")
+        req_1.write("git\n")
+        req_1.write("and\n")
+        req_1.write("\n")
+        req_1.write("# Some other useless comments here.\n")
+        req_1.write("whatnot\n")
+        req_1.flush()
+
+        req_2.write("# Let's start this other requirement file with a comment. Then, add some packages.\n")
+        req_2.write("cmake\n")
+        req_2.write("is\n")
+        req_2.write("nice even with many whatever\n")
+        req_2.flush()
+
+        packages = ['git', 'and', 'whatnot', 'cmake', 'is', 'nice', 'even', 'with', 'many', 'whatever']
+
+        yield ([pathlib.Path(req_1.name), pathlib.Path(req_2.name)], packages)
+
+class TestAptInstall:
+    """
+    Test :py:class:`apt_helpers.install.apt_install_packages`.
+    """
+    @staticmethod
+    @typeguard.typechecked
+    def get_script():
+        """
+        Retrieve script path.
+        """
+        return pathlib.Path(__file__).parent.parent.parent / 'apt' / 'helpers.py'
+
+    def test_list_of_package_names(self):
+        """
+        Test for a provided list of package names.
+        """
+        packages = ['git', 'and', 'whatnot']
+
+        with unittest.mock.patch(target = 'subprocess.check_call', side_effect = [None, None, None]) as mocker:
+            install.install_packages(packages = packages, update = False, upgrade = True, clean = False)
+
+            mocker.assert_has_calls(calls = [
+                unittest.mock.call(['apt', '--yes', 'upgrade']),
+                unittest.mock.call(['apt', '--yes', '--no-install-recommends', 'install'] + packages),
+            ])
+
+    def test_list_of_requirement_files(self, requirements):
+        """
+        Test for a provided list of requirement files, *à la* `pip`.
+        """
+        with unittest.mock.patch(target = 'subprocess.check_call', side_effect = [None]) as mocker:
+            install.install_packages(requirements = requirements[0], update = False, upgrade = False, clean = False)
+
+            mocker.assert_has_calls(calls = [
+                unittest.mock.call(['apt', '--yes', '--no-install-recommends', 'install'] + requirements[1]),
+            ])
+
+    @unittest.mock.patch(target = 'subprocess.check_call', side_effect = [None])
+    @pytest.mark.script_launch_mode('inprocess')
+    def test_install_packages_from_cli(self, mocker, script_runner : pytest_console_scripts.ScriptRunner, requirements):
+        """
+        Install many `APT` through requirement-like files and package names given to the CLI.
+        """
+        result = script_runner.run([
+            str(self.get_script()),
+            'install-packages',
+            '--packages', 'one', 'two',
+            *list(itertools.chain.from_iterable([['--requirement', str(x)] for x in requirements[0]]))
+        ], print_result = True)
+
+        assert result.returncode == 0
+
+        mocker.assert_has_calls(calls = [
+            unittest.mock.call(['apt', '--yes', '--no-install-recommends', 'install', 'one', 'two'] + requirements[1]),
+        ])