docs for email.generator are missing a comment on special multipart/signed handling

[dhke]

BPO	31887
Nosy	@warsaw, @bitdancer, @miss-islington
PRs	bpo-31887: Adds documentations for special multipart/signed handling #4268
Files	email-generator-multipart-signed-docs.patch: proposed documentation update

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2019-01-05.21:58:48.100>
created_at = <Date 2017-10-27.17:23:47.792>
labels = ['type-feature', '3.8', 'expert-email']
title = 'docs for email.generator are missing a comment on special multipart/signed handling'
updated_at = <Date 2019-01-05.21:58:48.099>
user = 'https://bugs.python.org/dhke'

bugs.python.org fields:

activity = <Date 2019-01-05.21:58:48.099>
actor = 'cheryl.sabella'
assignee = 'none'
closed = True
closed_date = <Date 2019-01-05.21:58:48.100>
closer = 'cheryl.sabella'
components = ['email']
creation = <Date 2017-10-27.17:23:47.792>
creator = 'dhke'
dependencies = []
files = ['47243']
hgrepos = []
issue_num = 31887
keywords = ['patch']
message_count = 3.0
messages = ['305127', '305130', '329268']
nosy_count = 4.0
nosy_names = ['barry', 'r.david.murray', 'dhke', 'miss-islington']
pr_nums = ['4268']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue31887'
versions = ['Python 3.8']

[dhke]

The documentation for email.generator.{Bytes,}Generator do not mention that Generator._handle_multipart_signed() exists and disables header folding for subparts of multipart/signed.

This may cause some frustration, since, as implemented, rendering a message part enclosed in multipart/signed causes headers to fold differently than rendering the respective message part individually:

>>> text = MIMEText('', 'plain', 'utf-8')
>>> text['X-X'] = 'a b c d e f g h i j k l m n o p q r s t u v w x y z a b c d e f g h i j k l m n o p'
>>> print(text.as_string())
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: base64
X-X: a b c d e f g h i j k l m n o p q r s t u v w x y z a b c d e f g h i j k
 l m n o p


>>> signed = MIMEMultipart('signed', filename='smime.p7s')
>>> signed.attach(text)
>>> print(signed.as_string())
Content-Type: multipart/signed; filename="smime.p7s";
 boundary="===============8046244967080646804=="
MIME-Version: 1.0

--===============8046244967080646804==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: base64
X-X: a b c d e f g h i j k l m n o p q r s t u v w x y z a b c d e f g h i j k l m n o p

--===============8046244967080646804==--

This breaks SMIME signatures when using the partial render to generate the signature.

A possible workaround is to set maxheaderlen=0 for the partial render, which is the same as what Generator._handle_multipart_signed() does, but to do that one needs to know about the special processing.

Attached is a suggestion at a documentation fix that remedies this problem at least for the online docs.

[bitdancer]

The patch looks good to me if someone wants to make a PR out of it. If you wouldn't mind digitally signing the CLA, Peter, that would make PSF legal happy, though I doubt a one sentence doc patch is really an issue.

[miss-islington]

New changeset 622935d by Miss Islington (bot) (Saptak Sengupta) in branch 'master':
bpo-31887: Adds documentations for special multipart/signed handling (GH-4268)
622935d