Header access methods in EmailMessage return strings, not header objects

Start with the EmailMessage header access methods and the Message base-class get_param() documentation described in the issue. Compare the documented params-based access with the current string return values, then inspect the related parameter-handling behavior. Done should mean that the chosen API behavior is consistent in code, documentation, and tests.

Summary

The behavior of the EmailMessage class does not match what the documentation says it will do when code using the class tries to fetch a header parameter value.

The class has a get_param() method, but that's defined in a base class, and the documentation says that the base class (Message) should only be used when maintaining legacy code. Instead, we're told:

Note that "existing parameter values of headers may be accessed through the params attribute of the header value (for example, msg['Content-Type'].params['charset']).

The problem is that msg['Content-Type'] returns a string, not a header object, which Python correctly complains "has no attribute 'params'."

It's not obvious (to me, anyway) why set_param() (also defined in the same base class) is OK to use, but not get_param() (which, by the way, actually works, in contrast with the approach given in the documentation). The docstring for get_param() (which I used to think of as the "canonical documentation" until one of the core devs gently set me straight) gives no indication that using get_param() is frowned upon, but the really canonical documentation says

This is a legacy method. On the EmailMessage class its functionality is replaced by the params property of the individual header objects returned by the header access methods.

I suppose this ticket could go either way: a bug in the code (which should be returning objects instead of strings for the header access methods) or a bug in the documentation. I went with the first option, since if the documentation is wrong and the header access methods really are supposed to return strings, then something will still need to be done with the code to expose the needed functionality. There's a comment on _get_params_preserve() (which get_params() and get_param() both use to do their thing) asking if it should be part of the public interface, so that would be one solution (though I'd still want to know why get_param() shouldn't be used).

Environment

• Python 3.11.1 (v3.11.1:a7a450f84a, Dec 6 2022, 15:24:06) [Clang 13.0.0 (clang-1300.0.29.30)] on darwin

Context

I ended up in this module when I noticed that the cgi module has been deprecated.

Deprecated since version 3.11, will be removed in version 3.13: The cgi module is deprecated (see PEP 594 for details and alternatives).

The FieldStorage class can typically be replaced with urllib.parse.parse_qsl() for GET and HEAD requests, and the email.message module or multipart for POST and PUT. Most utility functions have replacements.

That's about it for guidance on how to make the transition. I feel a little bit like as if I'm being thrown back to my experiences as a young dad trying to assemble the toys on Christmas Eve with instructions written in a foreign language. 😅