Refactor filename matching logic to separate classes

Signed-off-by: Olivier Mehani <shtrom@ssji.net>

Author: shtrom

rotate_backups/__init__.py

@@ -260,10 +260,111 @@ def rotate_backups(directory, rotation_scheme, **options):
     program.rotate_backups(directory)
 
 
+class Match:
+    """An interface-like class for a date match."""
+
+    def match_to_datetime(self) -> datetime.datetime:
+        """Return a datetime from the Match."""
+        pass
+
+
+class Matcher:
+    """An interface-like class for a date-matching scheme."""
+
+    def search(self, location: str, entry: str) -> Match:
+        """Process an entry in a location and return a Match."""
+        pass
+
+
+class FilenameMatch(Match):
+    """A match based on a filename pattern."""
+
+    match: re.Match = None
+
+    def __init__(self, match: re.Match):
+        """Make a Match from a regular expression match."""
+        self.match = match
+
+    def match_to_datetime(self) -> datetime.datetime:
+        """
+        Convert the regular expression match to a :class:`~datetime.datetime` value.
+
+        :returns: A :class:`~datetime.datetime` value.
+        :raises: :exc:`exceptions.ValueError` when a required date component is
+                 not captured by the pattern, the captured value is an empty
+                 string or the captured value cannot be interpreted as a
+                 base-10 integer.
+
+        .. seealso:: :data:`SUPPORTED_DATE_COMPONENTS`
+        """
+        kw = {}
+        captures = self.match.groupdict()
+        for component, required in SUPPORTED_DATE_COMPONENTS:
+            value = captures.get(component)
+            if value:
+                kw[component] = int(value, 10)
+            elif required:
+                raise ValueError("Missing required date component! (%s)" % component)
+            else:
+                kw[component] = 0
+        return datetime.datetime(**kw)
+
+
+class FilenameMatcher(Matcher):
+    """A date-matching scheme based on filenames."""
+
+    timestamp_pattern: re.Pattern = None
+
+    def __init__(self, timestamp_pattern: re.Pattern):
+        """Make a Matcher based on a regular expression pattern to apply to filenames."""
+        self.timestamp_pattern = timestamp_pattern
+
+    def search(self, location: str, entry: str) -> FilenameMatch:
+        """Apply the pattern to the entry's name, and return a Match if found."""
+        if match := self.timestamp_pattern.search(entry):
+            return FilenameMatch(match)
+
+    @mutable_property
+    def timestamp_pattern(self):
+        """
+        The pattern used to extract timestamps from filenames (defaults to :data:`TIMESTAMP_PATTERN`).
+
+        The value of this property is a compiled regular expression object.
+        Callers can provide their own compiled regular expression which
+        makes it possible to customize the compilation flags (see the
+        :func:`re.compile()` documentation for details).
+
+        The regular expression pattern is expected to be a Python compatible
+        regular expression that defines the named capture groups 'year',
+        'month' and 'day' and optionally 'hour', 'minute' and 'second'.
+
+        String values are automatically coerced to compiled regular expressions
+        by calling :func:`~humanfriendly.coerce_pattern()`, in this case only
+        the :data:`re.VERBOSE` flag is used.
+
+        If the caller provides a custom pattern it will be validated
+        to confirm that the pattern contains named capture groups
+        corresponding to each of the required date components
+        defined by :data:`SUPPORTED_DATE_COMPONENTS`.
+        """
+        return TIMESTAMP_PATTERN
+
+    @timestamp_pattern.setter
+    def timestamp_pattern(self, value):
+        """Coerce the value of :attr:`timestamp_pattern` to a compiled regular expression."""
+        pattern = coerce_pattern(value, re.VERBOSE)
+        for component, required in SUPPORTED_DATE_COMPONENTS:
+            if component not in pattern.groupindex and required:
+                raise ValueError("Pattern is missing required capture group! (%s)" % component)
+        set_property(self, 'timestamp_pattern', pattern)
+
+
 class RotateBackups(PropertyManager):
 
     """Python API for the ``rotate-backups`` program."""
 
+    _matcher: Matcher = FilenameMatcher(TIMESTAMP_PATTERN)
+
     def __init__(self, rotation_scheme, **options):
         """
         Initialize a :class:`RotateBackups` object.
@@ -449,37 +550,25 @@ def strict(self):
 
     @mutable_property
     def timestamp_pattern(self):
-        """
-        The pattern used to extract timestamps from filenames (defaults to :data:`TIMESTAMP_PATTERN`).
-
-        The value of this property is a compiled regular expression object.
-        Callers can provide their own compiled regular expression which
-        makes it possible to customize the compilation flags (see the
-        :func:`re.compile()` documentation for details).
-
-        The regular expression pattern is expected to be a Python compatible
-        regular expression that defines the named capture groups 'year',
-        'month' and 'day' and optionally 'hour', 'minute' and 'second'.
-
-        String values are automatically coerced to compiled regular expressions
-        by calling :func:`~humanfriendly.coerce_pattern()`, in this case only
-        the :data:`re.VERBOSE` flag is used.
-
-        If the caller provides a custom pattern it will be validated
-        to confirm that the pattern contains named capture groups
-        corresponding to each of the required date components
-        defined by :data:`SUPPORTED_DATE_COMPONENTS`.
-        """
-        return TIMESTAMP_PATTERN
+        """Pattern to use to extract a timestamp from a filename."""
+        return self.matcher.timestamp_pattern
 
     @timestamp_pattern.setter
     def timestamp_pattern(self, value):
-        """Coerce the value of :attr:`timestamp_pattern` to a compiled regular expression."""
-        pattern = coerce_pattern(value, re.VERBOSE)
-        for component, required in SUPPORTED_DATE_COMPONENTS:
-            if component not in pattern.groupindex and required:
-                raise ValueError("Pattern is missing required capture group! (%s)" % component)
-        set_property(self, 'timestamp_pattern', pattern)
+        """Pattern to use to extract a timestamp from a filename."""
+        self.matcher.timestamp_pattern = value
+
+    @mutable_property
+    def matcher(self):
+        """Matcher to use to extract a timestamp from a file."""
+        return self._matcher
+
+    @matcher.setter
+    def matcher(self, matcher):
+        """Matcher to use to extract a timestamp from a file."""
+        if not isinstance(matcher, Matcher):
+            raise ValueError(f'{matcher} is not a Matcher')
+        set_property(self, '_matcher', matcher)
 
     def rotate_concurrent(self, *locations, **kw):
         """
@@ -642,8 +731,9 @@ def collect_backups(self, location):
         location = coerce_location(location)
         logger.info("Scanning %s for backups ..", location)
         location.ensure_readable(self.force)
+
         for entry in natsort(location.context.list_entries(location.directory)):
-            match = self.timestamp_pattern.search(entry)
+            match = self.matcher.search(location, entry)
             if match:
                 if self.exclude_list and any(fnmatch.fnmatch(entry, p) for p in self.exclude_list):
                     logger.verbose("Excluded %s (it matched the exclude list).", entry)
@@ -653,7 +743,7 @@ def collect_backups(self, location):
                     try:
                         backups.append(Backup(
                             pathname=os.path.join(location.directory, entry),
-                            timestamp=self.match_to_datetime(match),
+                            timestamp=match.match_to_datetime(),
                         ))
                     except ValueError as e:
                         logger.notice("Ignoring %s due to invalid date (%s).", entry, e)
@@ -663,31 +753,6 @@ def collect_backups(self, location):
             logger.info("Found %i timestamped backups in %s.", len(backups), location)
         return sorted(backups)
 
-    def match_to_datetime(self, match):
-        """
-        Convert a regular expression match to a :class:`~datetime.datetime` value.
-
-        :param match: A regular expression match object.
-        :returns: A :class:`~datetime.datetime` value.
-        :raises: :exc:`exceptions.ValueError` when a required date component is
-                 not captured by the pattern, the captured value is an empty
-                 string or the captured value cannot be interpreted as a
-                 base-10 integer.
-
-        .. seealso:: :data:`SUPPORTED_DATE_COMPONENTS`
-        """
-        kw = {}
-        captures = match.groupdict()
-        for component, required in SUPPORTED_DATE_COMPONENTS:
-            value = captures.get(component)
-            if value:
-                kw[component] = int(value, 10)
-            elif required:
-                raise ValueError("Missing required date component! (%s)" % component)
-            else:
-                kw[component] = 0
-        return datetime.datetime(**kw)
-
     def group_backups(self, backups):
         """
         Group backups collected by :func:`collect_backups()` by rotation frequencies.
@@ -781,25 +846,25 @@ class Location(PropertyManager):
 
     """:class:`Location` objects represent a root directory containing backups."""
 
-    @required_property
+    @ required_property
     def context(self):
         """An execution context created using :mod:`executor.contexts`."""
 
-    @required_property
+    @ required_property
     def directory(self):
         """The pathname of a directory containing backups (a string)."""
 
-    @lazy_property
+    @ lazy_property
     def have_ionice(self):
         """:data:`True` when ionice_ is available, :data:`False` otherwise."""
         return self.context.have_ionice
 
-    @lazy_property
+    @ lazy_property
     def have_wildcards(self):
         """:data:`True` if :attr:`directory` is a filename pattern, :data:`False` otherwise."""
         return '*' in self.directory
 
-    @lazy_property
+    @ lazy_property
     def mount_point(self):
         """
         The pathname of the mount point of :attr:`directory` (a string or :data:`None`).
@@ -814,17 +879,17 @@ def mount_point(self):
         except ExternalCommandFailed:
             return None
 
-    @lazy_property
+    @ lazy_property
     def is_remote(self):
         """:data:`True` if the location is remote, :data:`False` otherwise."""
         return isinstance(self.context, RemoteContext)
 
-    @lazy_property
+    @ lazy_property
     def ssh_alias(self):
         """The SSH alias of a remote location (a string or :data:`None`)."""
         return self.context.ssh_alias if self.is_remote else None
 
-    @property
+    @ property
     def key_properties(self):
         """
         A list of strings with the names of the :attr:`~custom_property.key` properties.
@@ -975,15 +1040,15 @@ class Backup(PropertyManager):
     :attr:`~property_manager.PropertyManager.key_properties`.
     """
 
-    @key_property
+    @ key_property
     def pathname(self):
         """The pathname of the backup (a string)."""
 
-    @key_property
+    @ key_property
     def timestamp(self):
         """The date and time when the backup was created (a :class:`~datetime.datetime` object)."""
 
-    @property
+    @ property
     def week(self):
         """The ISO week number of :attr:`timestamp` (a number)."""
         return self.timestamp.isocalendar()[1]