Add per-report-type mailbox delete options (#858)

* Add per-report-type mailbox delete options (#256)

Add four new [mailbox] options — delete_aggregate, delete_failure,
delete_smtp_tls, and delete_invalid — each defaulting to the value of
the overall delete option and individually overridable, so e.g.
delete = True with delete_failure = False deletes processed aggregate
and SMTP TLS report messages while archiving failure reports, and
delete_invalid = False keeps unparseable messages in the Invalid
archive subfolder for debugging.

get_dmarc_reports_from_mailbox() and watch_inbox() gained matching
bool | None keyword arguments (None = inherit from delete), resolved
once up front; the delete/test mutual-exclusion guard now checks the
effective per-type flags. The Gmail deletion-scope guard covers any
effective flag and forces all five options off when the scope is
missing. PARSEDMARC_MAILBOX_DELETE_* env vars work automatically.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Document per-type delete kwargs as bool | None with explicit inheritance

Copilot review: the docstrings typed the four per-report-type delete
parameters as plain bool, but None (the default) is the inheritance
mechanism — a library caller couldn't tell from the docs that None,
not False, means "inherit delete".

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Cover disposal error branches; scope the config= docstring claim

Codecov flagged the delete-error handler in the new per-type disposal
loop as the one uncovered patch line. Add two Maildir tests driving a
backend whose first delete/move call raises: the error is logged, the
affected message stays in the INBOX, and disposal continues to the
next report type. The move-error branch gets the symmetric test from
the same harness.

Copilot review: the config= docstring paragraph claimed all keyword
arguments listed above it are ignored when config= is provided, which
now falsely included the four per-type delete options. Scope the claim
to the parsing/enrichment arguments ParserConfig actually carries and
state that mailbox-handling arguments always apply.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Sean WhalenandClaude Fable 5 authored and GitHub committed 2026-07-26 13:31:37 -04:00
1 parent 264b9a4556
commit ae5f4c7915
6 files changed
+725 -66

No files matched your search

+202
View File
@@ -1552,6 +1552,146 @@ since = 2d
self.assertEqual(mock_watch_inbox.call_args.kwargs.get("since"), "2d")
class TestMailboxPerTypeDeleteOptions(unittest.TestCase):
"""The [mailbox] per-report-type delete options (issue #256) must reach
the library unchanged, including the difference between an explicit
``false`` and an unset option (``None``, meaning "inherit ``delete``")."""
def setUp(self):
from parsedmarc.log import logger as _logger
_logger.disabled = True
self._stdout_patch = patch("sys.stdout", new_callable=io.StringIO)
self._stderr_patch = patch("sys.stderr", new_callable=io.StringIO)
self._stdout_patch.start()
self._stderr_patch.start()
def tearDown(self):
from parsedmarc.log import logger as _logger
_logger.disabled = False
self._stderr_patch.stop()
self._stdout_patch.stop()
def _write_config(self, config_text):
with tempfile.NamedTemporaryFile("w", suffix=".ini", delete=False) as cfg:
cfg.write(config_text)
cfg_path = cfg.name
self.addCleanup(lambda: os.path.exists(cfg_path) and os.remove(cfg_path))
return cfg_path
IMAP_CONFIG = """[general]
silent = true
[imap]
host = imap.example.com
user = user
password = pass
[mailbox]
delete = true
delete_failure = false
"""
def _assert_per_type_delete_kwargs(self, kwargs):
self.assertIs(kwargs.get("delete"), True)
self.assertIs(kwargs.get("delete_failure"), False)
# Unset options stay None so the library applies the inheritance.
self.assertIsNone(kwargs.get("delete_aggregate"))
self.assertIsNone(kwargs.get("delete_smtp_tls"))
self.assertIsNone(kwargs.get("delete_invalid"))
@patch("parsedmarc.cli.get_dmarc_reports_from_mailbox")
@patch("parsedmarc.cli.watch_inbox")
@patch("parsedmarc.cli.IMAPConnection")
def testCliPassesPerTypeDeleteToWatchInbox(
self, mock_imap_connection, mock_watch_inbox, mock_get_mailbox_reports
):
mock_imap_connection.return_value = object()
mock_get_mailbox_reports.return_value = {
"aggregate_reports": [],
"failure_reports": [],
"smtp_tls_reports": [],
}
mock_watch_inbox.side_effect = FileExistsError("stop-watch-loop")
cfg_path = self._write_config(self.IMAP_CONFIG + "watch = true\n")
with patch.object(sys, "argv", ["parsedmarc", "-c", cfg_path]):
with self.assertRaises(SystemExit) as system_exit:
parsedmarc.cli._main()
self.assertEqual(system_exit.exception.code, 1)
self._assert_per_type_delete_kwargs(mock_watch_inbox.call_args.kwargs)
@patch("parsedmarc.cli.get_dmarc_reports_from_mailbox")
@patch("parsedmarc.cli.IMAPConnection")
def testCliPassesPerTypeDeleteToOneShotMailboxRun(
self, mock_imap_connection, mock_get_mailbox_reports
):
mock_imap_connection.return_value = object()
mock_get_mailbox_reports.return_value = {
"aggregate_reports": [],
"failure_reports": [],
"smtp_tls_reports": [],
}
cfg_path = self._write_config(self.IMAP_CONFIG)
with patch.object(sys, "argv", ["parsedmarc", "-c", cfg_path]):
parsedmarc.cli._main()
self._assert_per_type_delete_kwargs(mock_get_mailbox_reports.call_args.kwargs)
@patch("parsedmarc.cli.get_dmarc_reports_from_mailbox")
@patch("parsedmarc.cli.GmailConnection")
def testGmailScopeGuardForcesAllDeleteFlagsOff(
self, mock_gmail_connection, mock_get_mailbox_reports
):
"""The Gmail deletion scope is a mailbox-wide capability grant, so a
per-report-type delete option alone (with ``delete`` unset) is enough
to trip the guard, and a missing scope turns every delete flag off."""
mock_gmail_connection.return_value = MagicMock()
mock_get_mailbox_reports.return_value = {
"aggregate_reports": [],
"failure_reports": [],
"smtp_tls_reports": [],
}
cfg_path = self._write_config("""[general]
silent = true
[gmail_api]
credentials_file = /tmp/gmail-credentials.json
scopes = https://www.googleapis.com/auth/gmail.modify
[mailbox]
delete_aggregate = true
""")
from parsedmarc.log import logger as _logger
_logger.disabled = False
try:
with patch.object(sys, "argv", ["parsedmarc", "-c", cfg_path]):
with self.assertLogs("parsedmarc.log", level="ERROR") as logs:
parsedmarc.cli._main()
finally:
_logger.disabled = True
self.assertTrue(
any("Message deletion requires scope" in line for line in logs.output),
logs.output,
)
kwargs = mock_get_mailbox_reports.call_args.kwargs
for option in (
"delete",
"delete_aggregate",
"delete_failure",
"delete_smtp_tls",
"delete_invalid",
):
with self.subTest(option=option):
self.assertIs(kwargs.get(option), False)
class TestCliParserConfigWiring(unittest.TestCase):
"""Tests that _main() builds a single ParserConfig (via
_build_parser_config) from parsed opts and passes it as ``config=`` to
@@ -4484,6 +4624,68 @@ def _config_with(section: str, settings: dict) -> "ConfigParser":
return cp
class TestParseConfigMailbox(unittest.TestCase):
"""The [mailbox] section, including the per-report-type delete options
(issue #256). An option that is absent from the INI must be left alone
entirely: _main defaults the four per-type options to None so the library
inherits the overall ``delete`` value, and writing False for an absent key
would silently disable that inheritance."""
PER_TYPE_DELETE_OPTS = (
"mailbox_delete_aggregate",
"mailbox_delete_failure",
"mailbox_delete_smtp_tls",
"mailbox_delete_invalid",
)
def test_mailbox_full_section(self):
from parsedmarc.cli import _parse_config
cp = _config_with(
"mailbox",
{
"reports_folder": "Reports",
"archive_folder": "Processed",
"watch": "true",
"delete": "true",
"delete_aggregate": "true",
"delete_failure": "false",
"delete_smtp_tls": "true",
"delete_invalid": "false",
"test": "false",
"batch_size": "25",
"check_timeout": "60",
"since": "3d",
},
)
opts = _opts()
_parse_config(cp, opts)
self.assertEqual(opts.mailbox_reports_folder, "Reports")
self.assertEqual(opts.mailbox_archive_folder, "Processed")
self.assertIs(opts.mailbox_watch, True)
self.assertIs(opts.mailbox_delete, True)
self.assertIs(opts.mailbox_delete_aggregate, True)
# Explicitly false, not None: this type opts out of delete = true.
self.assertIs(opts.mailbox_delete_failure, False)
self.assertIs(opts.mailbox_delete_smtp_tls, True)
self.assertIs(opts.mailbox_delete_invalid, False)
self.assertIs(opts.mailbox_test, False)
self.assertEqual(opts.mailbox_batch_size, 25)
self.assertEqual(opts.mailbox_check_timeout, 60)
self.assertEqual(opts.mailbox_since, "3d")
def test_mailbox_absent_per_type_delete_keys_are_not_set(self):
from parsedmarc.cli import _parse_config
cp = _config_with("mailbox", {"delete": "true"})
opts = _opts()
_parse_config(cp, opts)
self.assertIs(opts.mailbox_delete, True)
for option in self.PER_TYPE_DELETE_OPTS:
with self.subTest(option=option):
self.assertFalse(hasattr(opts, option))
class TestParseConfigGeneral(unittest.TestCase):
"""The [general] section sets dozens of flags. Hit a representative
subset: filenames, save-toggles, DNS settings, output dir."""