gh-90890: New methods to access mailbox.Maildir message info and flags (#103905)

New methods to access mailbox.Maildir message info and flags:
get_info, set_info, get_flags, set_flags, add_flag, remove_flag.

These methods speed up accessing a message's info and/or flags and are
useful when it is not necessary to access the message's contents,
as when iterating over a Maildir to find messages with specific flags.

---------

* Add more str type checking
* modernize to f-strings instead of %

Co-authored-by: Gregory P. Smith <greg@krypto.org>

1 files changed, 50 insertions, 0 deletions

diff --git a/Lib/mailbox.py b/Lib/mailbox.py
index 59834a2..36afade 100644
--- a/Lib/mailbox.py
+++ b/Lib/mailbox.py
@@ -395,6 +395,56 @@ class Maildir(Mailbox):
         f = open(os.path.join(self._path, self._lookup(key)), 'rb')
         return _ProxyFile(f)
 
+    def get_info(self, key):
+        """Get the keyed message's "info" as a string."""
+        subpath = self._lookup(key)
+        if self.colon in subpath:
+            return subpath.split(self.colon)[-1]
+        return ''
+
+    def set_info(self, key, info: str):
+        """Set the keyed message's "info" string."""
+        if not isinstance(info, str):
+            raise TypeError(f'info must be a string: {type(info)}')
+        old_subpath = self._lookup(key)
+        new_subpath = old_subpath.split(self.colon)[0]
+        if info:
+            new_subpath += self.colon + info
+        if new_subpath == old_subpath:
+            return
+        old_path = os.path.join(self._path, old_subpath)
+        new_path = os.path.join(self._path, new_subpath)
+        os.rename(old_path, new_path)
+        self._toc[key] = new_subpath
+
+    def get_flags(self, key):
+        """Return as a string the standard flags that are set on the keyed message."""
+        info = self.get_info(key)
+        if info.startswith('2,'):
+            return info[2:]
+        return ''
+
+    def set_flags(self, key, flags: str):
+        """Set the given flags and unset all others on the keyed message."""
+        if not isinstance(flags, str):
+            raise TypeError(f'flags must be a string: {type(flags)}')
+        # TODO: check if flags are valid standard flag characters?
+        self.set_info(key, '2,' + ''.join(sorted(set(flags))))
+
+    def add_flag(self, key, flag: str):
+        """Set the given flag(s) without changing others on the keyed message."""
+        if not isinstance(flag, str):
+            raise TypeError(f'flag must be a string: {type(flag)}')
+        # TODO: check that flag is a valid standard flag character?
+        self.set_flags(key, ''.join(set(self.get_flags(key)) | set(flag)))
+
+    def remove_flag(self, key, flag: str):
+        """Unset the given string flag(s) without changing others on the keyed message."""
+        if not isinstance(flag, str):
+            raise TypeError(f'flag must be a string: {type(flag)}')
+        if self.get_flags(key):
+            self.set_flags(key, ''.join(set(self.get_flags(key)) - set(flag)))
+
     def iterkeys(self):
         """Return an iterator over keys."""
         self._refresh()