[Python-checkins] bpo-30088: Document that existing dir structure isn't verified by mailbox.Maildir (GH-1163)

[Miss Islington (bot)]

https://github.com/python/cpython/commit/b815669c833c543b0f6696c3121a179f6b2383a6
commit: b815669c833c543b0f6696c3121a179f6b2383a6
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2019-07-13T07:59:48-07:00
summary:

bpo-30088: Document that existing dir structure isn't verified by mailbox.Maildir (GH-1163)


Hi,

I've faced an issue w/ `mailbox.Maildir()`. The case is following:
1. I create a folder with `tempfile.TemporaryDirectory()`, so it's empty
2. I pass that folder path as an argument when instantiating `mailbox.Maildir()`
3. Then I receive an exception happening because "there's no such file or directory" (namely `cur`, `tmp` or `new`) during interaction with Maildir

**Expected result:** subdirs are created during `Maildir()` instance creation.

**Actual result:** subdirs are assumed as existing which leads to exceptions during use.

**Workaround:** remove the actual dir before passing the path to `Maildir()`. It will be created automatically with all subdirs needed.

**Fix:** This PR. Basically it adds creation of subdirs regardless of whether the base dir existed before.

https://bugs.python.org/issue30088
(cherry picked from commit e44184749c2fd0921867ea5cd20b8e226c2146c2)

Co-authored-by: Sviatoslav Sydorenko <wk at sydorenko.org.ua>

files:
A Misc/NEWS.d/next/Documentation/2019-07-13-12-43-01.bpo-30088.CIcBjy.rst
M Doc/library/mailbox.rst
M Misc/ACKS

diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst
index d901ad2cc1c4..f82a3b200deb 100644
--- a/Doc/library/mailbox.rst
+++ b/Doc/library/mailbox.rst
@@ -308,6 +308,9 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
    representation. If *create* is ``True``, the mailbox is created if it does not
    exist.
 
+   If *create* is ``True`` and the *dirname* path exists, it will be treated as
+   an existing maildir without attempting to verify its directory layout.
+
    It is for historical reasons that *dirname* is named as such rather than *path*.
 
    Maildir is a directory-based mailbox format invented for the qmail mail
diff --git a/Misc/ACKS b/Misc/ACKS
index 53285403e695..f7032a1a96a2 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1608,6 +1608,7 @@ Kalle Svensson
 Andrew Svetlov
 Paul Swartz
 Al Sweigart
+Sviatoslav Sydorenko
 Thenault Sylvain
 Péter Szabó
 John Szakmeister
diff --git a/Misc/NEWS.d/next/Documentation/2019-07-13-12-43-01.bpo-30088.CIcBjy.rst b/Misc/NEWS.d/next/Documentation/2019-07-13-12-43-01.bpo-30088.CIcBjy.rst
new file mode 100644
index 000000000000..a39fe3fbbcb6
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2019-07-13-12-43-01.bpo-30088.CIcBjy.rst
@@ -0,0 +1 @@
+Documented that :class:`mailbox.Maildir` constructor doesn't attempt to verify the maildir folder layout correctness. Patch by Sviatoslav Sydorenko.
\ No newline at end of file