Make code style review pass.

1 files changed, 66 insertions, 55 deletions

diff --git a/src/mailman/handlers/docs/dmarc-mitigations.rst b/src/mailman/handlers/docs/dmarc-mitigations.rst
index d26fc6bdd..12a0de0ff 100644
--- a/src/mailman/handlers/docs/dmarc-mitigations.rst
+++ b/src/mailman/handlers/docs/dmarc-mitigations.rst
@@ -4,128 +4,138 @@ DMARC Mitigations
 
 In order to mitigate the effects of DMARC_ on mailing list traffic, list
 administrators have the ability to apply transformations to messages delivered
-to list members.  These transformations are applied only to individual messages
-sent to list members and not to messages in digests, archives, or gated to
-USENET.
+to list members.  These transformations are applied only to individual
+messages sent to list members and not to messages in digests, archives, or
+gated via NNTP.
 
-The messages can be transformed by either munging the From: header and putting
-original From: in Cc: or Reply-To: or by wrapping the original message in an
-outer message From: the list.
+The messages can be transformed by either munging the ``From:`` header and
+putting original ``From:`` in ``Cc:`` or ``Reply-To:``, or by wrapping the
+original message in an outer message ``From:`` the list.
 
-Exactly what transformations are applied depends on a number of list settings.
+Exactly which transformations are applied depends on a number of list settings.
 
 The settings and their effects are:
 
 ``anonymous_list``
-   If True, no mitigations are ever applied because the message
-   is already From: the list.
+   If True, no mitigations are ever applied because the message is already
+   ``From:`` the list.
 ``dmarc_mitigate_action``
-   The action to apply to messages From: a domain
-   publishing a DMARC policy of reject or quarantine or to all messages
-   depending on the next setting.
+   The action to apply to messages ``From:`` a domain publishing a DMARC
+   policy of **reject** or **quarantine**, or to all messages depending on the
+   setting of ``dmarc_mitigate_unconditionally``.
 ``dmarc_mitigate_unconditionally``
-   A Flag to apply dmarc_mitigate_action to all messages, but only if
-   dmarc_mitigate_action is neither reject or discard.
+   If True, apply ``dmarc_mitigate_action`` to all messages, but only if
+   ``dmarc_mitigate_action`` is neither ``reject`` or ``discard``.
 ``dmarc_moderation_notice``
-   Text to include in any rejection notice to be sent
-   when dmarc_policy_mitigation of reject applies.  This overrides the bult-in
-   default text.
+   Text to include in any rejection notice to be sent when
+   ``dmarc_policy_mitigation`` of ``reject`` applies.  This overrides the
+   built-in default text.
 ``dmarc_wrapped_message_text``
-   Text to be added as a separate text/plain MIME
-   part preceding the original message part in the wrapped message when a
-   wrap_message mitigation applies.  If this is not provided the separate
-   text/plain MIME part is not added.
+   Text to be added as a separate ``text/plain`` MIME part preceding the
+   original message part in the wrapped message when a ``wrap_message``
+   mitigation applies.  If this is not provided the separate ``text/plain``
+   MIME part is not added.
 ``reply_goes_to_list``
-   If this is set to other than no_munging of Reply-To,
-   the original From: goes in Cc: rather than Reply-To:.  This is intended to
-   make MUA functions of reply and reply-all have the same effect with
+   If this is set to other than no-munging of ``Reply-To:``, the original
+   ``From:`` goes in ``Cc:`` rather than ``Reply-To:``.  This is intended to
+   make MUA functions of *reply* and *reply-all* have the same effect with
    messages to which mitigations have been applied as they do with other
    messages.
 
-The possible actions for dmarc_mitigate_action are:
+The possible actions for ``dmarc_mitigate_action`` are:
 
 ``no_mitigation``
    Make no transformation to the message.
 ``munge_from``
-   Change the From: header and put the original From: in Reply-To:
-   or in some cases Cc:
+   Change the ``From:`` header and put the original ``From:`` in ``Reply-To:``
+   or in some cases ``Cc:``.
 ``wrap_message``
-   Wrap the message in an outer message with headers as in
-   munge_from.
+   Wrap the message in an outer message with headers from the original message
+   as in ``munge_from``.
 ``reject``
-   Bounce the message back to the sender with a default reason or one
-   supplied in dmarc_moderation_notice.
+   Bounce the message back to the sender with a default reason or one supplied
+   in ``dmarc_moderation_notice``.
 ``discard``
    Silently discard the message.
 
-Here's what happens when we munge the From.
+Here's what happens when we munge the ``From:``.
+::
 
-    >>> from mailman.interfaces.mailinglist import (DMARCMitigateAction,
-    ... ReplyToMunging)
-    >>> mlist = create_list('test@example.com')
+    >>> from mailman.interfaces.mailinglist import (
+    ...     DMARCMitigateAction, ReplyToMunging)
+
+    >>> mlist = create_list('ant@example.com')
     >>> mlist.dmarc_mitigate_action = DMARCMitigateAction.munge_from
     >>> mlist.reply_goes_to_list = ReplyToMunging.no_munging
+
     >>> msg = message_from_string("""\
-    ... From: A Person <aperson@example.com>
-    ... To: test@example.com
+    ... From: Anne Person <aperson@example.com>
+    ... To: ant@example.com
     ...
     ... A message of great import.
     ... """)
     >>> msgdata = dict(dmarc=True, original_sender='aperson@example.com')
+
     >>> from mailman.handlers.dmarc import process
     >>> process(mlist, msg, msgdata)
     >>> print(msg.as_string())
-    To: test@example.com
-    From: A Person via Test <test@example.com>
-    Reply-To: A Person <aperson@example.com>
+    To: ant@example.com
+    From: Anne Person via Ant <ant@example.com>
+    Reply-To: Anne Person <aperson@example.com>
     <BLANKLINE>
     A message of great import.
     <BLANKLINE>
-    
+
 Here we wrap the message without adding a text part.
+::
 
     >>> mlist.dmarc_mitigate_action = DMARCMitigateAction.wrap_message
     >>> mlist.dmarc_wrapped_message_text = ''
+
     >>> msg = message_from_string("""\
-    ... From: A Person <aperson@example.com>
-    ... To: test@example.com
+    ... From: Anne Person <aperson@example.com>
+    ... To: ant@example.com
     ...
     ... A message of great import.
     ... """)
     >>> msgdata = dict(dmarc=True, original_sender='aperson@example.com')
+
     >>> process(mlist, msg, msgdata)
     >>> print(msg.as_string())
-    To: test@example.com
+    To: ant@example.com
     MIME-Version: 1.0
     Message-ID: <...>
-    From: A Person via Test <test@example.com>
-    Reply-To: A Person <aperson@example.com>
+    From: Anne Person via Ant <ant@example.com>
+    Reply-To: Anne Person <aperson@example.com>
     Content-Type: message/rfc822
     Content-Disposition: inline
     <BLANKLINE>
-    From: A Person <aperson@example.com>
-    To: test@example.com
+    From: Anne Person <aperson@example.com>
+    To: ant@example.com
     <BLANKLINE>
     A message of great import.
     <BLANKLINE>
 
 And here's a wrapped message with an added text part.
+::
 
     >>> mlist.dmarc_wrapped_message_text = 'The original message is attached.'
+
     >>> msg = message_from_string("""\
-    ... From: A Person <aperson@example.com>
-    ... To: test@example.com
+    ... From: Anne Person <aperson@example.com>
+    ... To: ant@example.com
     ...
     ... A message of great import.
     ... """)
     >>> msgdata = dict(dmarc=True, original_sender='aperson@example.com')
+
     >>> process(mlist, msg, msgdata)
     >>> print(msg.as_string())
-    To: test@example.com
+    To: ant@example.com
     MIME-Version: 1.0
     Message-ID: <...>
-    From: A Person via Test <test@example.com>
-    Reply-To: A Person <aperson@example.com>
+    From: Anne Person via Ant <ant@example.com>
+    Reply-To: Anne Person <aperson@example.com>
     Content-Type: multipart/mixed; boundary="..."
     <BLANKLINE>
     --...
@@ -140,12 +150,13 @@ And here's a wrapped message with an added text part.
     MIME-Version: 1.0
     Content-Disposition: inline
     <BLANKLINE>
-    From: A Person <aperson@example.com>
-    To: test@example.com
+    From: Anne Person <aperson@example.com>
+    To: ant@example.com
     <BLANKLINE>
     A message of great import.
     <BLANKLINE>
     --...--
     <BLANKLINE>
 
+
 .. _DMARC: https://wikipedia.org/wiki/DMARC