fix: address code review findings (docs part)

Author: lavr

.github/workflows/tests.yaml

@@ -72,7 +72,7 @@ jobs:
           cache: pip
       - name: install dependencies
         run: |
-          pip install -e .
+          pip install -e ".[html]"
           pip install sphinx -r docs/requirements.txt
       - name: build docs
         run: sphinx-build -W -b html docs docs/_build/html

docs/api.rst

@@ -84,6 +84,38 @@ Message Methods
                  "user": "login", "password": "secret"}
        )
 
+.. method:: Message.send_async(to=None, set_mail_to=True, mail_from=None, set_mail_from=False, render=None, smtp_mail_options=None, smtp_rcpt_options=None, smtp=None)
+
+   Send the message via SMTP asynchronously. Requires ``aiosmtplib``
+   (install with ``pip install emails[async]``).
+
+   Parameters are the same as :meth:`send`, except ``smtp`` accepts a dict
+   or an :class:`AsyncSMTPBackend` instance.
+
+   When ``smtp`` is a dict, a temporary :class:`AsyncSMTPBackend` is created
+   and closed after sending. When an existing backend is passed, the caller
+   is responsible for closing it.
+
+   :returns: :class:`SMTPResponse` or ``None``
+
+   Example::
+
+       response = await msg.send_async(
+           to="user@example.com",
+           smtp={"host": "smtp.example.com", "port": 587, "tls": True,
+                 "user": "login", "password": "secret"}
+       )
+
+   Using a shared backend for multiple sends::
+
+       from emails.backend.smtp.aio_backend import AsyncSMTPBackend
+
+       async with AsyncSMTPBackend(host="smtp.example.com", port=587,
+                                   tls=True, user="login",
+                                   password="secret") as backend:
+           for msg in messages:
+               await msg.send_async(smtp=backend)
+
 .. method:: Message.attach(\*\*kwargs)
 
    Attach a file to the message. Sets ``content_disposition`` to ``'attachment'``
@@ -233,6 +265,12 @@ Message Properties
 
    Get or set the template rendering context dictionary.
 
+.. attribute:: Message.transformer
+
+   Access the HTML transformer for custom image/link transformations.
+   Lazily created on first access. See the :doc:`HTML Transformations <transformations>`
+   section for usage examples.
+
 
 SMTPResponse
 ------------
@@ -281,6 +319,53 @@ Returned by :meth:`Message.send`. Contains information about the SMTP transactio
                print(f"Refused: {response.refused_recipients}")
 
 
+AsyncSMTPBackend
+----------------
+
+For async sending via :meth:`Message.send_async`. Requires ``aiosmtplib``
+(install with ``pip install emails[async]``).
+
+.. class:: emails.backend.smtp.aio_backend.AsyncSMTPBackend(ssl=False, fail_silently=True, mail_options=None, \*\*kwargs)
+
+   Manages an async SMTP connection. Supports ``async with`` for automatic cleanup.
+
+   :param host: SMTP server hostname.
+   :param port: SMTP server port.
+   :param ssl: Use implicit TLS (SMTPS).
+   :param tls: Use STARTTLS after connecting.
+   :param user: SMTP username for authentication.
+   :param password: SMTP password for authentication.
+   :param timeout: Connection timeout in seconds (default: ``5``).
+   :param fail_silently: If ``True`` (default), SMTP errors are captured in the
+       response rather than raised.
+   :param mail_options: Default SMTP MAIL command options.
+
+   .. method:: sendmail(from_addr, to_addrs, msg, mail_options=None, rcpt_options=None)
+      :async:
+
+      Send a message. Automatically retries once on server disconnect.
+
+      :returns: :class:`SMTPResponse` or ``None``
+
+   .. method:: close()
+      :async:
+
+      Close the SMTP connection.
+
+   Example::
+
+       from emails.backend.smtp.aio_backend import AsyncSMTPBackend
+
+       async with AsyncSMTPBackend(host="smtp.example.com", port=587,
+                                   tls=True, user="me",
+                                   password="secret") as backend:
+           response = await backend.sendmail(
+               from_addr="sender@example.com",
+               to_addrs=["recipient@example.com"],
+               msg=message
+           )
+
+
 Loaders
 -------
 

docs/conf.py

@@ -12,6 +12,7 @@
     'sphinx.ext.coverage',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
+    'sphinx_togglebutton',
 ]
 
 templates_path = ['_templates']

docs/install.rst

@@ -20,3 +20,9 @@ To use Jinja2 templates (the ``T()`` shortcut):
 .. code-block:: bash
 
     $ pip install emails[jinja]
+
+To use async sending (``send_async()``):
+
+.. code-block:: bash
+
+    $ pip install emails[async]

docs/requirements.txt

@@ -1 +1,2 @@
 furo
+sphinx-togglebutton