From 8d1a9aaf6fb6bd546b271746fe9cfa1c5fab06a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Blondon?= Date: Sat, 9 Dec 2017 17:13:41 +0100 Subject: [PATCH 01/11] Context manager available for mailbox instances --- Lib/mailbox.py | 6 ++++++ Lib/test/test_mailbox.py | 5 +++++ 2 files changed, 11 insertions(+) diff --git a/Lib/mailbox.py b/Lib/mailbox.py index 056251dce0ada3..792145587d627a 100644 --- a/Lib/mailbox.py +++ b/Lib/mailbox.py @@ -38,6 +38,12 @@ def __init__(self, path, factory=None, create=True): self._path = os.path.abspath(os.path.expanduser(path)) self._factory = factory + def __enter__(self): + return self + + def __exit__(self, type, value, traceback): + self.close() + def add(self, message): """Add message and return assigned key.""" raise NotImplementedError('Method must be implemented by subclass') diff --git a/Lib/test/test_mailbox.py b/Lib/test/test_mailbox.py index 3807b95b158263..644e55fd8e9a6b 100644 --- a/Lib/test/test_mailbox.py +++ b/Lib/test/test_mailbox.py @@ -532,6 +532,11 @@ def _test_flush_or_close(self, method, should_call_close): self.assertIn(self._box.get_string(key), contents) oldbox.close() + def test_use_context_manager(self): + # Mailboxes are usable as a context manager + with self._factory(self._path) as box: + self.assertIsInstance(box, self._box.__class__) + def test_dump_message(self): # Write message representations to disk for input in (email.message_from_string(_sample_message), From 47fd0fe00fd1008f4dde9c6397a31bc5d97efd85 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Blondon?= Date: Sun, 10 Dec 2017 22:17:50 +0100 Subject: [PATCH 02/11] Add documentation about availability of 'with' statement --- Doc/library/mailbox.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index 81244c2ed02bd3..00b2f6b071e20d 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -76,6 +76,13 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. message. Failing to lock the mailbox runs the risk of losing messages or corrupting the entire mailbox. + The :class:`Mailbox` class supports the :keyword:`with` statement. When used + like this, the Mailbox :meth:`close` method is called automatically when the + :keyword:`with` statement exits. + + .. versionchanged:: 3.7 + Support for the :keyword:`with` statement was added. + :class:`Mailbox` instances have the following methods: From ae45e882fae84e03d247e1778c223e8120c409e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Blondon?= Date: Fri, 15 Dec 2017 09:10:41 +0100 Subject: [PATCH 03/11] Lock Mailbox when used in a context manager --- Doc/library/mailbox.rst | 4 ++-- Lib/mailbox.py | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index 00b2f6b071e20d..e315775eca0621 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -77,8 +77,8 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. corrupting the entire mailbox. The :class:`Mailbox` class supports the :keyword:`with` statement. When used - like this, the Mailbox :meth:`close` method is called automatically when the - :keyword:`with` statement exits. + like this, the Mailbox get a lock when the :keyword:`with` statement enters and + release it and :meth:`close` when the :keyword:`with` statement exits. .. versionchanged:: 3.7 Support for the :keyword:`with` statement was added. diff --git a/Lib/mailbox.py b/Lib/mailbox.py index 792145587d627a..3d0c9195df14c5 100644 --- a/Lib/mailbox.py +++ b/Lib/mailbox.py @@ -39,6 +39,7 @@ def __init__(self, path, factory=None, create=True): self._factory = factory def __enter__(self): + self.lock() return self def __exit__(self, type, value, traceback): From 382e57faca4454aa0d51598a21c01eecf2f013d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Blondon?= Date: Fri, 15 Dec 2017 09:35:51 +0100 Subject: [PATCH 04/11] add news about the context manager for Mailbox --- .../next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst diff --git a/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst b/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst new file mode 100644 index 00000000000000..5e0b3da3a783b3 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst @@ -0,0 +1,2 @@ +Mailbox instances can be used in the context manager. The Mailbox is locked +at enter and unlocked and closed at exit. From fd4d2409ec37d157ff30e367ed5a93b9a97287bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Blondon?= Date: Mon, 18 Dec 2017 21:05:12 +0100 Subject: [PATCH 05/11] fix speling errors --- Doc/library/mailbox.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index e315775eca0621..4adf72970c50cf 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -77,8 +77,9 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. corrupting the entire mailbox. The :class:`Mailbox` class supports the :keyword:`with` statement. When used - like this, the Mailbox get a lock when the :keyword:`with` statement enters and - release it and :meth:`close` when the :keyword:`with` statement exits. + like this, the Mailbox acquires a lock when the :keyword:`with` statement + enters and releases it and :meth:`close` when the :keyword:`with` statement + exits. .. versionchanged:: 3.7 Support for the :keyword:`with` statement was added. From 3c68123894a546f21ff41f52c4d2429f72b49b27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Blondon?= Date: Mon, 18 Dec 2017 21:05:12 +0100 Subject: [PATCH 06/11] fix spelling errors --- Doc/library/mailbox.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index e315775eca0621..4adf72970c50cf 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -77,8 +77,9 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. corrupting the entire mailbox. The :class:`Mailbox` class supports the :keyword:`with` statement. When used - like this, the Mailbox get a lock when the :keyword:`with` statement enters and - release it and :meth:`close` when the :keyword:`with` statement exits. + like this, the Mailbox acquires a lock when the :keyword:`with` statement + enters and releases it and :meth:`close` when the :keyword:`with` statement + exits. .. versionchanged:: 3.7 Support for the :keyword:`with` statement was added. From 755dc1c2bf4c1179e32b6c2eb86ae120f780d8f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Blondon?= Date: Fri, 5 Jul 2019 18:57:50 +0200 Subject: [PATCH 07/11] update versionchanged to 3.9; improve News sentence --- Doc/library/mailbox.rst | 2 +- .../next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index 4adf72970c50cf..de3dcecb8d0441 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -81,7 +81,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. enters and releases it and :meth:`close` when the :keyword:`with` statement exits. - .. versionchanged:: 3.7 + .. versionchanged:: 3.9 Support for the :keyword:`with` statement was added. :class:`Mailbox` instances have the following methods: diff --git a/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst b/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst index 5e0b3da3a783b3..bb28411b43b8be 100644 --- a/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst +++ b/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst @@ -1,2 +1,2 @@ -Mailbox instances can be used in the context manager. The Mailbox is locked +Mailbox instances can be used as a context manager. The Mailbox is locked at enter and unlocked and closed at exit. From 6814da0fdef13419193da7f5a969a26becefba8a Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Tue, 10 Feb 2026 14:54:46 +0100 Subject: [PATCH 08/11] For classes with `_locked` and `_file`, test locking & closing --- Lib/test/test_mailbox.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Lib/test/test_mailbox.py b/Lib/test/test_mailbox.py index 62b008115ed94a..c6f2ab4b2a5163 100644 --- a/Lib/test/test_mailbox.py +++ b/Lib/test/test_mailbox.py @@ -1127,6 +1127,16 @@ def test_ownership_after_flush(self): self.assertEqual(st.st_gid, other_gid) self.assertEqual(st.st_mode, mode) + def test_context_manager_locks_and_closes(self): + # Context manager locks/unlocks and closes. + # (This test uses an implementation detail to get the state.) + self.assertFalse(self._box._locked) + with self._box as context_object: + self.assertIs(self._box, context_object) + self.assertTrue(self._box._locked) + self.assertFalse(self._box._file.closed) + self.assertFalse(self._box._locked) + self.assertTrue(self._box._file.closed) class _TestMboxMMDF(_TestSingleFile): From bef0829361f0fac5f8f7a815be99d61c86ebe939 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Tue, 10 Feb 2026 14:56:39 +0100 Subject: [PATCH 09/11] Simpler assertion that the manager produces itself --- Lib/test/test_mailbox.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Lib/test/test_mailbox.py b/Lib/test/test_mailbox.py index c6f2ab4b2a5163..7421076ddd4c3a 100644 --- a/Lib/test/test_mailbox.py +++ b/Lib/test/test_mailbox.py @@ -544,8 +544,8 @@ def _test_flush_or_close(self, method, should_call_close): def test_use_context_manager(self): # Mailboxes are usable as a context manager - with self._factory(self._path) as box: - self.assertIsInstance(box, self._box.__class__) + with self._box as box: + self.assertIs(self._box, box) def test_dump_message(self): # Write message representations to disk From 49403ae43c9d2cde95246b8bdb6d0e57f926738c Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 11 Feb 2026 13:46:59 +0100 Subject: [PATCH 10/11] Apply suggestions from code review Co-authored-by: R. David Murray --- Doc/library/mailbox.rst | 6 +++--- .../next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst | 3 +-- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index f9a2d1ecb75379..42d11d3cad6b02 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -79,9 +79,9 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. corrupting the entire mailbox. The :class:`Mailbox` class supports the :keyword:`with` statement. When used - like this, the Mailbox acquires a lock when the :keyword:`with` statement - enters and releases it and :meth:`close` when the :keyword:`with` statement - exits. + as a context manager, :class:`!Mailbox` calls :meth:`lock` when the context is entered, + returns the mailbox object as the context object, and at context end calls :meth:`close`, + thereby releasing the lock. .. versionchanged:: next Support for the :keyword:`with` statement was added. diff --git a/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst b/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst index bb28411b43b8be..9e4c9edc2beddf 100644 --- a/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst +++ b/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst @@ -1,2 +1 @@ -Mailbox instances can be used as a context manager. The Mailbox is locked -at enter and unlocked and closed at exit. +:mod:`Mailbox` instances can now be used as a context manager. The Mailbox is locked on context entry and unlocked and closed at context exit. From bbddd8ae20a9874c3fad2f87093fc4f9da208432 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 12 Feb 2026 10:58:20 +0100 Subject: [PATCH 11/11] Fix docs nits --- Doc/library/mailbox.rst | 8 ++++---- .../next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst | 3 ++- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index 05679ddf47e339..3b0c17c838c879 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -78,10 +78,10 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. message. Failing to lock the mailbox runs the risk of losing messages or corrupting the entire mailbox. - The :class:`Mailbox` class supports the :keyword:`with` statement. When used - as a context manager, :class:`!Mailbox` calls :meth:`lock` when the context is entered, - returns the mailbox object as the context object, and at context end calls :meth:`close`, - thereby releasing the lock. + The :class:`!Mailbox` class supports the :keyword:`with` statement. When used + as a context manager, :class:`!Mailbox` calls :meth:`lock` when the context is entered, + returns the mailbox object as the context object, and at context end calls :meth:`close`, + thereby releasing the lock. .. versionchanged:: next Support for the :keyword:`with` statement was added. diff --git a/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst b/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst index 9e4c9edc2beddf..b22289835620df 100644 --- a/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst +++ b/Misc/NEWS.d/next/Library/2017-12-15-09-32-57.bpo-32234.XaOkhR.rst @@ -1 +1,2 @@ -:mod:`Mailbox` instances can now be used as a context manager. The Mailbox is locked on context entry and unlocked and closed at context exit. +:class:`mailbox.Mailbox` instances can now be used as a context manager. +The Mailbox is locked on context entry and unlocked and closed at context exit.