[New-bugs-announce] [issue31887] docs for email.generator are missing a comment on special multipart/signed handling

[Peter Wullinger]

New submission from Peter Wullinger <python at dhke.de>:

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.

----------
components: email
files: email-generator-multipart-signed-docs.patch
keywords: patch
messages: 305127
nosy: barry, dhke, r.david.murray
priority: normal
severity: normal
status: open
title: docs for email.generator are missing a comment on special multipart/signed handling
type: enhancement
versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8
Added file: https://bugs.python.org/file47243/email-generator-multipart-signed-docs.patch

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue31887>
_______________________________________