modpkgbuild 0.1.0__py3-none-any.whl

modpkgbuild-0.1.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: modpkgbuild
+Version: 0.1.0
+Summary: Creates a new PKGBUILD by modifying another
+Author-email: Russell Wright Helder <rwh@russellhelder.net>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: System :: Archiving :: Packaging
+Classifier: Topic :: System :: Software Distribution
+Classifier: Topic :: Text Processing :: Filters
+License-File: LICENSE
+Requires-Dist: pyyaml
+Project-URL: Homepage, https://github.com/rhelder/modpkgbuild
+Project-URL: Issues, https://github.com/rhelder/modpkgbuild/issues
+Import-Name: modpkgbuild
+
+# modpkgbuild
+
+## Description
+
+Creates one PKGBUILD from another PKGBUILD by applying a series of changes
+specified in a YAML file. Designed to automatically generate alternative
+versions of Arch Linux packages (e.g., enabling SELinux support, applying
+security-related patches, etc.). This makes it possible to e.g. implement a
+CI/CD pipeline that checks for updates to the relevant Arch package,
+automatically generates an alternative PKGBUILD when there has been an update,
+builds the alternative package in a clean container, and deploys it to a
+custom Pacman repo.
+
+The PKGBUILD is written to the current working directory. A diff between the
+old PKGBUILD and the new PKGBUILD is written to stderr on success.
+
+## Installation
+
+This script is available on PyPI as `modpkgbuild`:
+
+```
+pip install modpkgbuild
+```
+
+## modpkgbuild.yml
+
+`modpkgbuild` must be run in the same directory as a `modpkgbuild.yml`. The
+`modpkgbuild.yml` must contain the following two fields:
+
+| Key          | Value                         |
+| ------------ | -------------------------------
+| repo         | The URL to the git repository that contains the PKGBUILD you want to modify |
+| replacements | A list of replacement objects |
+
+A replacement object must contain three fields:
+
+| Key         | Value                                                   |
+| ----------- | ---------------------------------------------------------
+| description | A description of the purpose of the replacement         |
+| old         | A literal string you want to replace (may be multiline) |
+| new         | A literal string you want to replace `old` with (may be multiline) |
+
+Or, if the optional field `regex` is set to true, the fields mean the
+following:
+
+| Key         | Value                                                   |
+| ----------- | ---------------------------------------------------------
+| description | A description of the purpose of the replacement         |
+| old         | A regular expression matching text you want to replace (may be multiline, and may contain captures) |
+| new         | A replacement string (may be multiline, may contain backreferences) |
+
+All replacements must be specified **in order**. Any failure to match is
+considered an error. `modpkgbuild` is intentionally conservative in these ways
+so that it can be relied on in an automated packaging pipeline to not produce
+an incorrect PKGBUILD without an error.
+
+Accordingly, the user should use literal strings in `modpkgbuild.yml` whenever
+possible. Setting `regex` to true is to be discouraged unless there is a good
+reason – for example, you may need to capture part of the match and reference
+it in the replacement text.
+
+## Project Status
+
+This package should be considered to be alpha software. Until `modpkgbuild`
+has been more extensively tested, the user should manually review generated
+PKGBUILDs before building or deploying packages.
+

modpkgbuild-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+modpkgbuild.py,sha256=sKTwCw2012XkQe0TzPT4I7SnhtGn55BlMGWjkwBzNek,8955
+modpkgbuild-0.1.0.dist-info/entry_points.txt,sha256=ie8ZfD45Kz0Q8HuYHpJVlyU89sEl0XtZn_HAJrAsFzA,48
+modpkgbuild-0.1.0.dist-info/licenses/LICENSE,sha256=EQJaGGeBeSD0jhbWKGQp1bCxUr5M5Ty_FlNpaf_RIDw,1078
+modpkgbuild-0.1.0.dist-info/WHEEL,sha256=rLJE8OLPBZbz7tqxs1yD-wA-ADa1Ec5PuYU-Y_PNWDI,81
+modpkgbuild-0.1.0.dist-info/METADATA,sha256=Gr0dm5NwO8rOav5TmNe0AVKeYWbCOSSi9oSSlufXptU,3823
+modpkgbuild-0.1.0.dist-info/RECORD,,

modpkgbuild-0.1.0.dist-info/WHEEL

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

modpkgbuild-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+modpkgbuild=modpkgbuild:main
+

modpkgbuild-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Russell Wright Helder
+
+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.

modpkgbuild.py

@@ -0,0 +1,293 @@
+"""Creates one PKGBUILD from another by applying changes specified in a YAML file.
+
+Designed to automatically generate alternative versions of Arch Linux packages
+(e.g., enabling SELinux support, applying security-related patches, etc.).
+Must be run in the same directory as a modpkgbuild.yml. The PKGBUILD is
+written to the current working directory. A diff between the old PKGBUILD and
+the new PKGBUILD is written to stderr on success.
+"""
+
+import argparse
+import difflib
+from pathlib import Path
+import re
+import subprocess
+import sys
+import tempfile
+
+import yaml
+
+try:
+    from yaml import CSafeLoader as SafeLoader
+except ImportError:
+    from yaml import SafeLoader
+
+
+class ReplacementError(Exception):
+    """An error in applying a replacement."""
+
+
+class SpecError(Exception):
+    """An error in modpkgbuild.yml."""
+
+
+def write_new(new: str):
+    """Writes the new PKGBUILD to `./PKGBUILD`.
+
+    Args:
+        new (string):
+            The content of the new PKGBUILD.
+    """
+    tmpdir = tempfile.TemporaryDirectory(dir='.')
+    pkgbuild_path = Path(tmpdir.name) / 'PKGBUILD'
+
+    pkgbuild_path.write_text(new)
+
+    target_path = Path('PKGBUILD')
+
+    if target_path.is_file():
+        message('warning: PKGBUILD exists. Saving as PKGBUILD.orig...')
+
+        orig_path = Path('PKGBUILD.orig')
+
+        if orig_path.is_file():
+            raise FileExistsError('PKGBUILD.orig also exists. Aborting.')
+        else:
+            target_path.rename(orig_path)
+
+    pkgbuild_path.rename(target_path)
+
+
+def gen_new(old: str, spec: dict) -> str:
+    """Applies the changes specified in `modpkgbuild.yml`.
+
+    Args:
+        old (string):
+            The content of the upstream PKGBUILD.
+        spec (dictionary):
+            The data loaded from modpkgbuild.yml.
+
+    Returns:
+        (string) The content of the new PKGBUILD.
+    """
+    new = []
+    pos = 0
+
+    for r in spec['replacements']:
+        # Save the position of the end of the last match in the old PKGBUILD
+        prev_pos = pos
+
+        if not r.get('regex', False):
+            # Search for the next match in the old PKGBUILD, starting at the
+            # end of the last match, so that the changes specified in
+            # modpkgbuild.yml are applied in order. Advance the position
+            # tracker to the position of the beginning of the next match. It
+            # is an error if a match cannot be found.
+            try:
+                pos += old[prev_pos:].index(r['old'])
+            except ValueError:
+                raise ReplacementError(
+                    f"substring '{r['old']}' "
+                    f"in replacement '{r['description']}' not found"
+                )
+
+            # The text between the end of the last match and the start of the
+            # next match are the same in the old PKGBUILD and in the new
+            # PKGBUILD. Append it to the new PKGBUILD.
+            new += old[prev_pos:pos]
+            # At this position, append the replacement text to the new
+            # PKGBUILD
+            new += r['new']
+            # Advance the position tracker, which tracks our position in the
+            # old PKGBUILD, by the length of the matched and the replaced
+            # text
+            pos += len(r['old'])
+        else:
+            try:
+                pattern = re.compile(r['old'])
+            except re.PatternError as e:
+                raise SpecError(
+                    f"invalid regex in replacement '{r['description']}': {e}"
+                )
+
+            # Search for the next match in the old PKGBUILD, starting at the
+            # end of the last match, so that the changes specified in
+            # modpkgbuild.yml are applied in order
+            match = re.search(pattern, old[prev_pos:])
+
+            # It is an error if a match cannot be found
+            if not match:
+                raise ReplacementError(
+                    f"pattern '{pattern.pattern}' "
+                    f"in replacement '{r['description']}' not matched"
+                )
+
+            # Advance the position tracker to the position of the beginning of
+            # the next match
+            pos += match.start()
+            # The text between the end of the last match and the start of the
+            # next match are the same in the old PKGBUILD and in the new
+            # PKGBUILD. Append it to the new PKGBUILD.
+            new += old[prev_pos:pos]
+            # At this position, append the replacement text to the new
+            # PKGBUILD
+            new += match.expand(r['new'])
+            # Advance the position tracker, which tracks our position in the
+            # old PKGBUILD, by the length of the matched and the replaced
+            # text
+            pos += len(match[0])
+
+    # Append any remaining text in the old PKGBUILD to the new PKGBUILD
+    new += old[pos:]
+    return ''.join(new)
+
+
+def read_old(repo: str) -> str:
+    """Clones the upstream git repo and reads its PKGBUILD.
+
+    Args:
+        repo (string):
+            The URL to the upstream git repository.
+
+    Returns:
+        (string) The content of the upstream PKGBUILD.
+    """
+    tmpdir = tempfile.TemporaryDirectory()
+
+    subprocess.run(
+        ['git', 'clone', repo, tmpdir.name],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+    with open(Path(tmpdir.name) / 'PKGBUILD') as f:
+        return f.read()
+
+
+def parse_spec() -> dict:
+    """Loads and validates modpkgbuild.yml.
+
+    Returns:
+        (dictionary) The data loaded from modpkgbuild.yml.
+    """
+    spec = load_spec()
+
+    validate_spec(spec)
+    return spec
+
+
+def load_spec() -> dict:
+    """Loads modpkgbuild.yml.
+
+    Returns:
+        (dictionary) The data loaded from modpkgbuild.yml.
+    """
+    with open('./modpkgbuild.yml') as f:
+        spec = yaml.load(f.read(), Loader=SafeLoader)
+
+    return spec
+
+
+def validate_spec(spec: dict):
+    """Validates the data loaded from modpkgbuild.yml.
+
+    Args:
+        spec (dictionary):
+            The data loaded from modpkgbuild.yml.
+    """
+    if not isinstance(spec, dict):
+        raise SpecError('expected a YAML mapping')
+
+    try:
+        if not isinstance(spec['repo'], str):
+            raise SpecError("'repo' must be a string")
+        elif not isinstance(spec['replacements'], list):
+            raise SpecError("'replacements' must be a list")
+    except KeyError as e:
+        raise SpecError(f'missing required field {e}')
+
+    for i, r in enumerate(spec['replacements']):
+        try:
+            if not isinstance(r['description'], str):
+                raise SpecError(
+                    f"'description' in replacement {i + 1} must be a string"
+                )
+            elif not isinstance(r['old'], str):
+                raise SpecError(
+                    f"'old' in replacement '{r['description']}' must be a string"
+                )
+            elif not isinstance(r['new'], str):
+                raise SpecError(
+                    f"'new' in replacement '{r['description']}' must be a string"
+                )
+        except KeyError as e:
+            raise SpecError(
+                'missing required field {} in replacement {}'.format(
+                    e,
+                    f"'{r['description']}'" if r.get('description') else i + 1,
+                )
+            )
+            raise
+
+
+def parse_args():
+    """Prints help message if necessary."""
+    parser = argparse.ArgumentParser(
+        description="""
+Create one PKGBUILD from another by applying changes specified in a YAML file.
+""",
+        epilog="""
+Must be run in the same directory as a modpkgbuild.yml.
+The PKGBUILD is written to the current working directory.
+Prints a diff to stderr on success.
+""",
+    )
+    return parser.parse_args()
+
+
+def message(*args: str, **kwargs):
+    """Prints messages to stderr."""
+    print('modpkgbuild.py:', *args, **kwargs, file=sys.stderr)
+
+
+def main():
+    parse_args()
+
+    try:
+        spec = parse_spec()
+        old = read_old(spec['repo'])
+        new = gen_new(old, spec)
+        write_new(new)
+    except OSError as e:
+        message(
+            f' {e.filename}:' if e.filename else ' ',
+            e.strerror or str(e),
+            sep='',
+        )
+        return 1
+    except yaml.YAMLError as e:
+        message('failed to parse modpkgbuild.yml:', str(e))
+        return 2
+    except SpecError as e:
+        message('invalid modpkgbuild.yml:', str(e))
+        return 2
+    except subprocess.CalledProcessError as e:
+        message(e.stderr)
+        return e.returncode
+    except ReplacementError as e:
+        message(str(e))
+        return 1
+
+    message(
+        'new PKGBUILD successfully written to ./PKGBUILD,',
+        'with the following changes from the old PKGBUILD:',
+    )
+    sys.stderr.writelines(
+        difflib.unified_diff(
+            old.splitlines(keepends=True),
+            new.splitlines(keepends=True),
+            fromfile=f'{spec["repo"]}:PKGBUILD',
+            tofile='PKGBUILD',
+        )
+    )