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, 103 insertions, 1 deletions

diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst
index b27deb2..05ffaf6 100644
--- a/Doc/library/mailbox.rst
+++ b/Doc/library/mailbox.rst
@@ -424,6 +424,108 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
       remove the underlying message while the returned file remains open.
 
 
+   .. method:: get_flags(key)
+
+      Return as a string the flags that are set on the message
+      corresponding to *key*.
+      This is the same as ``get_message(key).get_flags()`` but much
+      faster, because it does not open the message file.
+      Use this method when iterating over the keys to determine which
+      messages are interesting to get.
+
+      If you do have a :class:`MaildirMessage` object, use
+      its :meth:`~MaildirMessage.get_flags` method instead, because
+      changes made by the message's :meth:`~MaildirMessage.set_flags`,
+      :meth:`~MaildirMessage.add_flag` and :meth:`~MaildirMessage.remove_flag`
+      methods are not reflected here until the mailbox's
+      :meth:`__setitem__` method is called.
+
+      .. versionadded:: 3.13
+
+
+   .. method:: set_flags(key, flags)
+
+      On the message corresponding to *key*, set the flags specified
+      by *flags* and unset all others.
+      Calling ``some_mailbox.set_flags(key, flags)`` is similar to ::
+
+         one_message = some_mailbox.get_message(key)
+         one_message.set_flags(flags)
+         some_mailbox[key] = one_message
+
+      but faster, because it does not open the message file.
+
+      If you do have a :class:`MaildirMessage` object, use
+      its :meth:`~MaildirMessage.set_flags` method instead, because
+      changes made with this mailbox method will not be visible to the
+      message object's method, :meth:`~MaildirMessage.get_flags`.
+
+      .. versionadded:: 3.13
+
+
+   .. method:: add_flag(key, flag)
+
+      On the message corresponding to *key*, set the flags specified
+      by *flag* without changing other flags. To add more than one
+      flag at a time, *flag* may be a string of more than one character.
+
+      Considerations for using this method versus the message object's
+      :meth:`~MaildirMessage.add_flag` method are similar to
+      those for :meth:`set_flags`; see the discussion there.
+
+      .. versionadded:: 3.13
+
+
+   .. method:: remove_flag(key, flag)
+
+      On the message corresponding to *key*, unset the flags specified
+      by *flag* without changing other flags. To remove more than one
+      flag at a time, *flag* may be a string of more than one character.
+
+      Considerations for using this method versus the message object's
+      :meth:`~MaildirMessage.remove_flag` method are similar to
+      those for :meth:`set_flags`; see the discussion there.
+
+      .. versionadded:: 3.13
+
+
+   .. method:: get_info(key)
+
+      Return a string containing the info for the message
+      corresponding to *key*.
+      This is the same as ``get_message(key).get_info()`` but much
+      faster, because it does not open the message file.
+      Use this method when iterating over the keys to determine which
+      messages are interesting to get.
+
+      If you do have a :class:`MaildirMessage` object, use
+      its :meth:`~MaildirMessage.get_info` method instead, because
+      changes made by the message's :meth:`~MaildirMessage.set_info` method
+      are not reflected here until the mailbox's :meth:`__setitem__` method
+      is called.
+
+      .. versionadded:: 3.13
+
+
+   .. method:: set_info(key, info)
+
+      Set the info of the message corresponding to *key* to *info*.
+      Calling ``some_mailbox.set_info(key, flags)`` is similar to ::
+
+         one_message = some_mailbox.get_message(key)
+         one_message.set_info(info)
+         some_mailbox[key] = one_message
+
+      but faster, because it does not open the message file.
+
+      If you do have a :class:`MaildirMessage` object, use
+      its :meth:`~MaildirMessage.set_info` method instead, because
+      changes made with this mailbox method will not be visible to the
+      message object's method, :meth:`~MaildirMessage.get_info`.
+
+      .. versionadded:: 3.13
+
+
 .. seealso::
 
    `maildir man page from Courier <https://www.courier-mta.org/maildir.html>`_
@@ -838,7 +940,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
       .. note::
 
          A message is typically moved from :file:`new` to :file:`cur` after its
-         mailbox has been accessed, whether or not the message is has been
+         mailbox has been accessed, whether or not the message has been
          read. A message ``msg`` has been read if ``"S" in msg.get_flags()`` is
          ``True``.