feat(copy): add exclude_from parameter for rsync-based copy in Singularity builds (#526)

* feat(copy): add exclude_from parameter for rsync-based copy in Singularity builds

* refactor(copy): rename exclude_from to _exclude_from and reorder docstring alphabetically

Renamed the parameter `exclude_from` to `_exclude_from` to follow HPCCM
convention that container framework-specific options begin with an underscore
(e.g., `_chown`, `_mkdir`, `_post`).

Also reordered the parameter documentation block in `copy.py` to maintain
alphabetical order within the class docstring for consistency.

* chore(copy): remove unnecessary info log for rsync exclude_from

Removes the redundant `logging.info()` statement in the rsync exclusion
branch of the copy primitive to keep logging output minimal and consistent
with other primitives.

* test(copy): improve _exclude_from tests

Refactors the _exclude_from tests to use assertEqual() with full expected
recipe strings instead of multiple substring checks. This aligns the test
style with other HPCCM copy primitive tests.

Note:
When `_exclude_from` is used, an empty %files section is still emitted after
the rsync-based %setup block. This is intentional to preserve compatibility
with the existing copy control flow. The extra section is harmless and may
be removed in a future cleanup.

* refactor(copy): simplify _exclude_from initialization with default []

Author: allansp84

hpccm/primitives/copy.py

@@ -44,6 +44,17 @@ class copy(object):
 
     dest: Path in the container image to copy the file(s)
 
+    _exclude_from: String or list of strings.  One or more filenames
+    containing rsync-style exclude patterns (e.g., `.apptainerignore`).
+    Only used when building for Singularity or Apptainer.  If specified,
+    the copy operation is emitted in the `%setup` section using
+    `rsync --exclude-from=<file>` rather than the standard `%files`
+    copy directive.  This enables selective exclusion of files and
+    directories during the image build, for example to omit large data
+    files, caches, or temporary artifacts.  Multiple exclusion files may
+    be provided as a list or tuple.  The default is an empty list
+    (Singularity specific).
+
     files: A dictionary of file pairs, source and destination, to copy
     into the container image.  If specified, has precedence over
     `dest` and `src`.
@@ -80,6 +91,10 @@ class copy(object):
     copy(files={'a': '/tmp/a', 'b': '/opt/b'})
     ```
 
+    ```python
+    copy(src='.', dest='/opt/app', _exclude_from='.apptainerignore')
+    ```
+
     """
 
     def __init__(self, **kwargs):
@@ -96,6 +111,12 @@ def __init__(self, **kwargs):
         self._post = kwargs.get('_post', '')  # Singularity specific
         self.__src = kwargs.get('src', '')
 
+        ef = kwargs.get('_exclude_from', [])
+        if isinstance(ef, (list, tuple)):
+            self.__exclude_from = list(ef)
+        elif ef:
+            self.__exclude_from = [ef]
+
         if self._mkdir and self._post:
             logging.error('_mkdir and _post are mutually exclusive!')
             self._post = False # prefer _mkdir
@@ -211,6 +232,13 @@ def __str__(self):
                 dest = pair['dest']
                 src = pair['src']
 
+                # Use rsync if exclusion file provided and not multi-stage copy
+                if self.__exclude_from and not self.__from:
+                    excl_opts = ' '.join('--exclude-from={}'.format(x) for x in self.__exclude_from)
+                    pre.append('    mkdir -p ${{SINGULARITY_ROOTFS}}{0}'.format(dest))
+                    pre.append('    rsync -av {0} {1}/ ${{SINGULARITY_ROOTFS}}{2}/'.format(excl_opts, src, dest))
+                    continue
+
                 if self._post:
                     dest = '/'
 

test/test_copy.py

@@ -255,3 +255,32 @@ def test_from_temp_staging(self):
         """Singularity files from previous stage in tmp"""
         c = copy(_from='base', src='foo', dest='/var/tmp/foo')
         self.assertEqual(str(c), '%files from base\n    foo /var/tmp/foo')
+
+    @singularity
+    def test_exclude_from_single_singularity(self):
+        """rsync-based copy with _exclude_from (single source)"""
+        c = copy(src='.', dest='/opt/app', _exclude_from='.apptainerignore')
+        self.assertEqual(str(c),
+r'''%setup
+    mkdir -p ${SINGULARITY_ROOTFS}/opt/app
+    rsync -av --exclude-from=.apptainerignore ./ ${SINGULARITY_ROOTFS}/opt/app/
+%files
+''')
+
+    @singularity
+    def test_exclude_from_multiple_singularity(self):
+        """rsync-based copy with multiple _exclude_from files"""
+        c = copy(src='data', dest='/opt/data',
+                 _exclude_from=['.ignore1', '.ignore2'])
+        self.assertEqual(str(c),
+r'''%setup
+    mkdir -p ${SINGULARITY_ROOTFS}/opt/data
+    rsync -av --exclude-from=.ignore1 --exclude-from=.ignore2 data/ ${SINGULARITY_ROOTFS}/opt/data/
+%files
+''')
+
+    @docker
+    def test_exclude_from_docker_ignored(self):
+        """_exclude_from ignored in Docker context"""
+        c = copy(src='.', dest='/opt/app', _exclude_from='.apptainerignore')
+        self.assertEqual(str(c), 'COPY . /opt/app')