[2.0] Possible Breaking Changes

[pepoluan]

trafficstars

This issue is just tracking the ideas for changes that will possibly break backward-compatibility in 2.0:

Do note that these are ideas and not concrete plans. They may -- and likely will -- change, and some might even get abandoned.

(In no particular order; the numbers are just for ease of reference. Please do not reorder, just strikeout using ~~...~~ if idea is abandoned.)

1. Drop non-Controller-affecting kwargs, gather them in ~~**kwargs~~ **SMTP_Parameters

2. Enforce Command Limit unconditionally (not optionally like in 1.x)

3. Drop 4-arg EHLO handler and go exclusively 5-arg EHLO handler

4. Drop auth_callback and use authenticator exclusively

5. Stop misusing MISSING -- it should have one purpose and one purpose only: indicate no user-supplied hook

6. Drop support for ehlo_hook, rset_hook, and process_message

7. Separate support for 8BITMIME from decode_data

8. Implement 8BITMIME when SMTPUTF8 is specfied

9. Embed StreamReaderProtocol (see #210 )

10. Change hostname parameter of Controller to host This matches the parameter name of loop.create_server, and not conflicting with the hostname parameter of SMTP, allowing pass-through of Controller's **kwargs to SMTP. (See also No. 1 above)

11. Use different logger for "verbose" logging, so mail.log contains only the most important log entries (see #239)

12. Handler hooks will no longer be required to return a response to clients; if a hook returns None (or something Falsy), SMTP should continue as is the hook is MISSING (see #154)

13. Uniformize Handler Hook signatures. As we saw in #157, when we need to give more data to a handler, we're forced to implement a complex detection mechanism to determine how much args to send to the hook. If we replace each individual hook signature with, say, (server, session, envelope, data where data is a Dict[str,Any], if we need to send new data, we won't have to determine how many args the hook supports; just add a new key:value pair and send.

14. Uniformize Handler Hook returns. In concordance with No.13, how do we determine if a handler hook is "old version" or "new version"? Since the signatures are now the same, the only way is to determine the type and/or contents of the return value. Rather than having a proliferation of "specialized return classes" (as currently used by the authenticator callback) needing a bunch of isinstance()s, we can uniformize on a HookReturn object, which itself can contain a version attribute (or similar). Based on version, the SMTP method implementation can process the HookReturn object differently... or not.

15. Decompose the SMTP class into base "Protocol" and "Method Classes". When instantiated, the SMTP class will perform a "composition" of SMTP Method Classes. This idea might even get extended further into a "plugin" system, allowing 3rd party "methods" to be deployed as separate packages. In a way, similar to "pytest" and "twine" and various other tools-with-plugins packages.

16. Don't manage the loop (run_forever, stop & close, etc.) if loop is given caller The principle is that the caller sets up the loop, probably to run several things concurrently, and therefore will probably not appreciate it if our Controller suddenly ends the loop.

17. Change the name of the modules to be more semantically consistent. For example, why is it controller instead of controllers if it actually contains more than one controller class? We should name it in a similar way to handlers

18. Stop proliferation of parameters to SMTP.__init__() and pass in a "config dict" instead. Currently SMTP.__init__() has 18 (eighteen!) parameters. This is simply too many. If we pass in a "config dict" instead, we can simplify the class greatly.

19. Separate AUTH methods into its own class that can be separately instantiable. Currently, SMTP.__init__() need to always scan itself to find the AUTH methods. Due to how asyncio.create_server works (it seems to re-initialize SMTP for every new connection, CMIIW), this makes SMTP initialization quite slow for subsequent connections, because we cannot maintain a ref to the AUTH methods inbetween inits. If we move the methods to a separate class, we can instantiate that class once and cache the method refs in a classvar in SMTP, saving time on subsequent SMTP connections.

20. Similarly to No.19 above, we should also separate SMTP methods to its own class. Exact same reason as No.19: Speeds up subsequent SMTP connections by caching method refs.

21. Implement more secure defaults as discussed in #374

In-between 1.2.3 and 2.0, additional DeprecationWarnings will be added to the code.