aio-libs / aio-libs/aiosmtpd

[2.0] Possible Breaking Changes

オープン
#229 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
API compatibility integration tech-debt
主要言語
Python
スター
373
フォーク
105
平均マージ
4分
マージ済み PR(30日)
2

説明

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](https://aiosmtpd.readthedocs.io/en/latest/aiosmtpd/docs/handlers.html#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](https://github.com/aio-libs/aiosmtpd/blob/dd255876a69133c50d1ffd9ad1cae87bffdd8c8d/aiosmtpd/smtp.py#L378-L395) 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](https://aiosmtpd.readthedocs.io/en/latest/auth.html#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 `DeprecationWarning`s will be added to the code.

コントリビューションガイド

コントリビューションガイドを開く

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。