Skip to content

Commit 4d5d9ac

Browse files
authored
gh-90890: Reorder mailbox.Maildir method documentation (GH-113071)
When new mailbox.Maildir methods were added for 3.13.0a2, their documentation was added at the end of the mailbox.Maildir section instead of grouping them with other methods Maildir adds to Mailbox. This commit moves the new methods' documentation adjacent to documentation for existing Maildir-specific methods, so that the "special remarks" for common methods remains at the end.
1 parent b4f2c89 commit 4d5d9ac

File tree

1 file changed

+40
-40
lines changed

1 file changed

+40
-40
lines changed

Doc/library/mailbox.rst

Lines changed: 40 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -383,46 +383,6 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
383383
last 36 hours. The Maildir specification says that mail-reading programs
384384
should do this occasionally.
385385

386-
Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special
387-
remarks:
388-
389-
390-
.. method:: add(message)
391-
__setitem__(key, message)
392-
update(arg)
393-
394-
.. warning::
395-
396-
These methods generate unique file names based upon the current process
397-
ID. When using multiple threads, undetected name clashes may occur and
398-
cause corruption of the mailbox unless threads are coordinated to avoid
399-
using these methods to manipulate the same mailbox simultaneously.
400-
401-
402-
.. method:: flush()
403-
404-
All changes to Maildir mailboxes are immediately applied, so this method
405-
does nothing.
406-
407-
408-
.. method:: lock()
409-
unlock()
410-
411-
Maildir mailboxes do not support (or require) locking, so these methods do
412-
nothing.
413-
414-
415-
.. method:: close()
416-
417-
:class:`Maildir` instances do not keep any open files and the underlying
418-
mailboxes do not support locking, so this method does nothing.
419-
420-
421-
.. method:: get_file(key)
422-
423-
Depending upon the host platform, it may not be possible to modify or
424-
remove the underlying message while the returned file remains open.
425-
426386

427387
.. method:: get_flags(key)
428388

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

526486
.. versionadded:: 3.13
527487

488+
Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special
489+
remarks:
490+
491+
492+
.. method:: add(message)
493+
__setitem__(key, message)
494+
update(arg)
495+
496+
.. warning::
497+
498+
These methods generate unique file names based upon the current process
499+
ID. When using multiple threads, undetected name clashes may occur and
500+
cause corruption of the mailbox unless threads are coordinated to avoid
501+
using these methods to manipulate the same mailbox simultaneously.
502+
503+
504+
.. method:: flush()
505+
506+
All changes to Maildir mailboxes are immediately applied, so this method
507+
does nothing.
508+
509+
510+
.. method:: lock()
511+
unlock()
512+
513+
Maildir mailboxes do not support (or require) locking, so these methods do
514+
nothing.
515+
516+
517+
.. method:: close()
518+
519+
:class:`Maildir` instances do not keep any open files and the underlying
520+
mailboxes do not support locking, so this method does nothing.
521+
522+
523+
.. method:: get_file(key)
524+
525+
Depending upon the host platform, it may not be possible to modify or
526+
remove the underlying message while the returned file remains open.
527+
528528

529529
.. seealso::
530530

0 commit comments

Comments
 (0)