Skip to content

gh-90890: Reorder mailbox.Maildir method documentation #113071

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Dec 14, 2023
80 changes: 40 additions & 40 deletions Doc/library/mailbox.rst
Original file line number Diff line number Diff line change
Expand Up @@ -383,46 +383,6 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
last 36 hours. The Maildir specification says that mail-reading programs
should do this occasionally.

Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special
remarks:


.. method:: add(message)
__setitem__(key, message)
update(arg)

.. warning::

These methods generate unique file names based upon the current process
ID. When using multiple threads, undetected name clashes may occur and
cause corruption of the mailbox unless threads are coordinated to avoid
using these methods to manipulate the same mailbox simultaneously.


.. method:: flush()

All changes to Maildir mailboxes are immediately applied, so this method
does nothing.


.. method:: lock()
unlock()

Maildir mailboxes do not support (or require) locking, so these methods do
nothing.


.. method:: close()

:class:`Maildir` instances do not keep any open files and the underlying
mailboxes do not support locking, so this method does nothing.


.. method:: get_file(key)

Depending upon the host platform, it may not be possible to modify or
remove the underlying message while the returned file remains open.


.. method:: get_flags(key)

Expand Down Expand Up @@ -525,6 +485,46 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.

.. versionadded:: 3.13

Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special
remarks:


.. method:: add(message)
__setitem__(key, message)
update(arg)

.. warning::

These methods generate unique file names based upon the current process
ID. When using multiple threads, undetected name clashes may occur and
cause corruption of the mailbox unless threads are coordinated to avoid
using these methods to manipulate the same mailbox simultaneously.


.. method:: flush()

All changes to Maildir mailboxes are immediately applied, so this method
does nothing.


.. method:: lock()
unlock()

Maildir mailboxes do not support (or require) locking, so these methods do
nothing.


.. method:: close()

:class:`Maildir` instances do not keep any open files and the underlying
mailboxes do not support locking, so this method does nothing.


.. method:: get_file(key)

Depending upon the host platform, it may not be possible to modify or
remove the underlying message while the returned file remains open.


.. seealso::

Expand Down