Tidying __init__

.gitignore

@@ -38,3 +38,4 @@ prof/
 ~temp*
 *.sw[a-p]
 pyvenv.cfg
+aiosmtpd_test.log

aiosmtpd/__init__.py

@@ -4,7 +4,7 @@
 import warnings
 
 
-__version__ = "1.4.4"
+__version__ = "1.5.0a3"
 
 
 def _get_or_new_eventloop() -> asyncio.AbstractEventLoop:

aiosmtpd/controller.py

@@ -347,6 +347,11 @@ def __init__(
         server_hostname: Optional[str] = None,
         **SMTP_parameters,
     ):
+        """
+        `Documentation can be found here
+        <http://aiosmtpd.readthedocs.io/en/latest/aiosmtpd\
+/docs/controller.html#controller-api>`_.
+        """
         super().__init__(
             handler,
             loop,

aiosmtpd/docs/smtp.rst

@@ -94,7 +94,7 @@ Server hooks
 ============
 
 .. warning:: These methods are deprecated.  See :ref:`handler hooks <hooks>`
-             instead.
+             instead. Support for these hooks **will be removed in 2.0**.
 
 The ``SMTP`` server class also implements some hooks which your subclass can
 override to provide additional responses.
@@ -127,8 +127,25 @@ aiosmtpd.smtp
 
 .. py:module:: aiosmtpd.smtp
 
+
+Type Aliases
+------------
+
+For type hinting, we provide several `Type Aliases`_
+
 .. py:data:: AuthenticatorType
-   :value: Callable[[SMTP, Session, Envelope, str, Any], AuthResult]
+    :value: Callable[[SMTP, Session, Envelope, str, Any], AuthResult]
+
+    Type hint for the :func:`Authenticator` function.
+
+.. py:data:: AuthMechanismType
+    :value: Callable[["SMTP", List[str]], Awaitable[Any]]
+
+    Type hint for :ref:`authmech`.
+
+
+Decorators
+----------
 
 .. decorator:: auth_mechanism(actual_name)
 
@@ -143,6 +160,22 @@ aiosmtpd.smtp
 
       The decorated method's name MUST still start with ``auth_``
 
+.. decorator:: syntax(text, extended=None, when=None)
+
+    :param text: The help text for (E)SMTP HELP
+    :type text: str
+    :param extended: Additional help text for ESMTP HELP;
+        will be appended to *text*.
+    :type extended: str
+    :param when: The name of attribute of SMTP class to check;
+        if the value of the attribute is *Falsey*,
+        then HELP will not be available for that command.
+    :type when: str
+
+
+Classes
+-------
+
 .. class:: AuthResult
 
    Contains the result of the Authentication Procedure.
@@ -158,13 +191,26 @@ aiosmtpd.smtp
 
    For more information, please refer to the :ref:`auth` page.
 
-.. class:: SMTP(handler, *, data_size_limit=33554432, enable_SMTPUTF8=False, \
-   decode_data=False, hostname=None, ident=None, tls_context=None, \
-   require_starttls=False, timeout=300, auth_required=False, \
-   auth_require_tls=True, auth_exclude_mechanism=None, auth_callback=None, \
-   authenticator=None, command_call_limit=None, \
-   proxy_protocol_timeout=None, \
-   loop=None)
+.. class:: SMTP(\
+   handler,\
+   *,\
+   loop=None,\
+   hostname=None,\
+   ident=None,\
+   timeout=300,\
+   data_size_limit=DATA_SIZE_DEFAULT,\
+   enable_SMTPUTF8=False,\
+   decode_data=False,\
+   tls_context=None,\
+   require_starttls=False,\
+   auth_required=False,\
+   auth_require_tls=True,\
+   auth_exclude_mechanism=None,\
+   auth_callback=None,\
+   authenticator=None,\
+   command_call_limit=None,\
+   proxy_protocol_timeout=None,\
+   )
 
    |
    | :part:`Parameters`
@@ -174,6 +220,14 @@ aiosmtpd.smtp
       An instance of a :ref:`handler <handlers>` class that optionally can implement
       :ref:`hooks`.
 
+   .. py:attribute:: loop
+      :type: asyncio.AbstractEventLoop
+      :value: None
+      :noindex:
+
+      The asyncio event loop to use.
+      If not given, :meth:`asyncio.new_event_loop` will be called to create the event loop.
+
    .. py:attribute:: data_size_limit
       :type: int
       :value: 33554432
@@ -371,14 +425,14 @@ aiosmtpd.smtp
 
       .. versionadded:: 1.4
 
-   .. py:attribute:: loop
-      :noindex:
+   |
+   | :part:`Attributes & Properties`
 
-      The asyncio event loop to use.
-      If not given, :meth:`asyncio.new_event_loop` will be called to create the event loop.
+   .. note::
 
-   |
-   | :part:`Attributes & Methods`
+      All *writable* attributes are "live", meaning that changing any one of them will result
+      in immediate change to the ``SMTP`` class behavior. All attributes below are writable
+      unless explicitly stated as "Read-Only".
 
    .. py:attribute:: line_length_limit
 
@@ -459,12 +513,11 @@ aiosmtpd.smtp
 
    .. attribute:: loop
 
-      The event loop being used.  This will either be the given *loop*
+      **Read-only.** The event loop being used.  This will either be the given *loop*
       argument, or the new event loop that was created.
 
-   .. attribute:: authenticated
-
-      A flag that indicates whether authentication had succeeded.
+   |
+   | :part:`Methods`
 
    .. method:: _create_session()
 
@@ -571,3 +624,4 @@ advertised, and the ``STARTTLS`` command will not be accepted.
 .. _`asyncio transport`: https://docs.python.org/3/library/asyncio-protocol.html#asyncio-transport
 .. _StreamReaderProtocol: https://docs.python.org/3.6/library/asyncio-stream.html#streamreaderprotocol
 .. |StreamReaderProtocol| replace:: ``StreamReaderProtocol``
+.. _`Type Aliases`: https://docs.python.org/3/library/typing.html#type-aliases

aiosmtpd/lmtp.py

@@ -10,7 +10,7 @@
 class LMTP(SMTP):
     show_smtp_greeting: bool = False
 
-    @syntax('LHLO hostname')
+    @syntax("LHLO hostname")
     async def smtp_LHLO(self, arg: str) -> None:
         """The LMTP greeting, used instead of HELO/EHLO."""
         await super().smtp_EHLO(arg)

aiosmtpd/main.py

@@ -91,7 +91,7 @@ def _parser() -> ArgumentParser:
         action="count",
         help=(
             "Increase debugging output. Every ``-d`` increases debugging level by one."
-        )
+        ),
     )
     parser.add_argument(
         "-l",