Type hinting and janitor work

Restructured the message module to ensure outgoing and incoming messages are
clearly separated. Furthermore, addresses of messages are now more strictly
bound in case the protocol defines that a message can only be sent to one
specific participant (server, client, initiator, responder).

All message properties have been refactored to be `NewType`s.

Cleaned up the `Path` class which should now be both a tiny bit more
performant and use less memory.

Further changes:

Add mypy type checker to Travis.
Remove dead code in the message module and its dependencies that is only
required for a client.
All usages of `asyncio.ensure_future` have been replaced by
`loop.create_task`, resolves #95 (and made the type annotations easier).

Author: lgrahl

.travis.yml

@@ -67,12 +67,13 @@ install:
 - "pip install .[dev]"
 - pip install codecov
 
-# Run flake8, isort, check docs & tests
+# Run flake8, isort, mypy, check docs & tests
 script:
 - >
   if [[ "$TRAVIS_PYTHON_VERSION" != "pypy3" ]]; then
     flake8 . || travis_terminate 1;
     isort -rc -c . || (isort -rc -df . && return 1) || travis_terminate 1;
+    MYPYPATH=${PWD}/stubs mypy saltyrtc examples || travis_terminate 1;
   fi
 - python setup.py checkdocs
 - >

MANIFEST.in

@@ -4,4 +4,5 @@ include README.rst
 recursive-include docs *
 prune docs/_build
 recursive-include examples *
-recursive-include tests *
+recursive-include stubs *
+recursive-include tests *

README.rst

@@ -17,20 +17,20 @@ Prerequisites
 
 .. code-block:: bash
 
-    $ sudo apt-get install python3 python3-pip
+    sudo apt-get install python3 python3-pip
 
 We recommend using `venv`_ to create an isolated Python environment:
 
 .. code-block:: bash
 
-    $ pyvenv venv
+    pyvenv venv
 
 You can switch into the created virtual environment *venv* by running
 this command:
 
 .. code-block:: bash
 
-    $ source venv/bin/activate
+    source venv/bin/activate
 
 While the virtual environment is active, all packages installed using
 ``pip`` will be installed into this environment.
@@ -39,7 +39,7 @@ To deactivate the virtual environment, just run:
 
 .. code-block:: bash
 
-    $ deactivate
+    deactivate
 
 If you want easier handling of your virtualenvs, you might also want to
 take a look at `virtualenvwrapper`_.
@@ -53,7 +53,7 @@ Install the module by running:
 
 .. code-block:: bash
 
-    $ pip install saltyrtc.server
+    pip install saltyrtc.server
 
 The dependency ``libnacl`` will be installed automatically. However, you
 may need to install `libsodium`_ for ``libnacl`` to work.
@@ -67,7 +67,7 @@ command to see usage information:
 
 .. code-block:: bash
 
-    $ saltyrtc-server --help
+    saltyrtc-server --help
 
 Contributing
 ************
@@ -77,19 +77,20 @@ optional ``dev`` requirements of the project in an editable environment:
 
 .. code-block:: bash
 
-    $ git clone https://github.com/saltyrtc/saltyrtc-server-python.git
-    $ cd saltyrtc-server-python
-    $ pip install -e .[dev]
+    git clone https://github.com/saltyrtc/saltyrtc-server-python.git
+    cd saltyrtc-server-python
+    pip install -e .[dev]
 
 Before creating a pull request, it is recommended to run the following
 commands to check for code style violations (``flake8``), optimise
-imports (``isort``) and run the project's tests:
+imports (``isort``), do a static type analysis and run the project's tests:
 
 .. code-block:: bash
 
-    $ flake8 .
-    $ isort -rc .
-    $ py.test
+    flake8 .
+    isort -rc .
+    MYPYPATH=${PWD}/stubs mypy saltyrtc examples
+    py.test
 
 Reporting Security Issues
 *************************

RELEASING.md

@@ -8,6 +8,7 @@ Signing key: https://lgrahl.de/pub/pgp-key.txt
    ```bash
    flake8 .
    isort -rc -c . || isort -rc -df
+   MYPYPATH=${PWD}/stubs mypy saltyrtc examples
    py.test
    ```
 

examples/debug.py

@@ -1,50 +1,61 @@
 import asyncio
 import os
+import ssl  # noqa
 import sys
+from typing import Any  # noqa
+from typing import List  # noqa
+from typing import Optional
 
 import logbook.more
 
 import saltyrtc.server
+from saltyrtc.server.typing import Coroutine  # noqa
+from saltyrtc.server.typing import ServerSecretPermanentKey  # noqa
 
 
-def env(name, default=None):
-    return os.environ.get(name, default)
+def env(name: str, default: Optional[str] = None) -> Optional[str]:
+    try:
+        return os.environ[name]
+    except KeyError:
+        return default
 
 
-def require_env(name):
+def require_env(name: str) -> str:
     value = env(name)
     if value is None:
         print("Missing '{}' env variable".format(name))
         sys.exit(1)
     return value
 
 
-def main():
+def main() -> None:
     """
     Run the SaltyRTC server until Ctrl+C has been pressed.
     """
     loop = asyncio.get_event_loop()
 
     # Create SSL context
+    ssl_context = None  # type: Optional[ssl.SSLContext]
     if env('SALTYRTC_DISABLE_TLS') != 'yes-and-i-know-what-im-doing':
         ssl_context = saltyrtc.server.create_ssl_context(
             certfile=require_env('SALTYRTC_TLS_CERT'),
             keyfile=require_env('SALTYRTC_TLS_KEY'),
             dh_params_file=require_env('SALTYRTC_DH_PARAMS'),
         )
-    else:
-        ssl_context = None
 
     # Get permanent key
+    permanent_keys = None  # type: Optional[List[ServerSecretPermanentKey]]
     if env('SALTYRTC_DISABLE_SERVER_PERMANENT_KEY') != 'yes-and-i-know-what-im-doing':
         permanent_keys = [saltyrtc.server.load_permanent_key(
             require_env('SALTYRTC_SERVER_PERMANENT_KEY'))]
-    else:
-        permanent_keys = None
 
     # Start server
-    port = int(env('SALTYRTC_PORT', '8765'))
-    coroutine = saltyrtc.server.serve(ssl_context, permanent_keys, port=port)
+    port_str = env('SALTYRTC_PORT', '8765')
+    assert port_str is not None
+    port = int(port_str)
+    coroutine = saltyrtc.server.serve(
+        ssl_context, permanent_keys, port=port
+    )  # type: Coroutine[Any, Any, saltyrtc.server.Server]
     server = loop.run_until_complete(coroutine)
 
     # Wait until Ctrl+C has been pressed

examples/restartable.py

@@ -1,26 +1,35 @@
 import asyncio
 import os
 import signal
+import ssl  # noqa
 import sys
+from typing import Any  # noqa
+from typing import List  # noqa
+from typing import Optional
 
 import logbook.more
 
 import saltyrtc.server
+from saltyrtc.server.typing import Coroutine  # noqa
+from saltyrtc.server.typing import ServerSecretPermanentKey  # noqa
 
 
-def env(name, default=None):
-    return os.environ.get(name, default)
+def env(name: str, default: Optional[str] = None) -> Optional[str]:
+    try:
+        return os.environ[name]
+    except KeyError:
+        return default
 
 
-def require_env(name):
+def require_env(name: str) -> str:
     value = env(name)
     if value is None:
         print("Missing '{}' env variable".format(name))
         sys.exit(1)
     return value
 
 
-def main():
+def main() -> None:
     """
     Run the SaltyRTC server until Ctrl+C has been pressed.
 
@@ -31,32 +40,34 @@ def main():
 
     while True:
         # Create SSL context
+        ssl_context = None  # type: Optional[ssl.SSLContext]
         if env('SALTYRTC_DISABLE_TLS') != 'yes-and-i-know-what-im-doing':
             ssl_context = saltyrtc.server.create_ssl_context(
                 certfile=require_env('SALTYRTC_TLS_CERT'),
                 keyfile=require_env('SALTYRTC_TLS_KEY'),
                 dh_params_file=require_env('SALTYRTC_DH_PARAMS'),
             )
-        else:
-            ssl_context = None
 
         # Get permanent key
+        permanent_keys = None  # type: Optional[List[ServerSecretPermanentKey]]
         if env('SALTYRTC_DISABLE_SERVER_PERMANENT_KEY') != 'yes-and-i-know-what-im-doing':
             permanent_keys = [saltyrtc.server.load_permanent_key(
                 require_env('SALTYRTC_SERVER_PERMANENT_KEY'))]
-        else:
-            permanent_keys = None
 
         # Start server
-        port = int(env('SALTYRTC_PORT', '8765'))
-        coroutine = saltyrtc.server.serve(ssl_context, permanent_keys, port=port)
+        port_str = env('SALTYRTC_PORT', '8765')
+        assert port_str is not None
+        port = int(port_str)
+        coroutine = saltyrtc.server.serve(
+            ssl_context, permanent_keys, port=port
+        )  # type: Coroutine[Any, Any, saltyrtc.server.Server]
         server = loop.run_until_complete(coroutine)
 
         # Restart server on HUP signal
-        restart_signal = asyncio.Future(loop=loop)
+        restart_signal = asyncio.Future(loop=loop)  # type: asyncio.Future[None]
 
-        def _restart_signal_handler(*_):
-            restart_signal.set_result(True)
+        def _restart_signal_handler(*_: None) -> None:
+            restart_signal.set_result(None)
 
         # Register restart server routine
         loop.add_signal_handler(signal.SIGHUP, _restart_signal_handler)

saltyrtc/server/__init__.py

@@ -4,30 +4,23 @@
 """
 import itertools
 
-# noinspection PyUnresolvedReferences
-from .exception import *  # noqa
-# noinspection PyUnresolvedReferences
 from .common import *  # noqa
-# noinspection PyUnresolvedReferences
+from .events import *  # noqa
+from .exception import *  # noqa
 from .message import *  # noqa
-# noinspection PyUnresolvedReferences
 from .protocol import *  # noqa
-# noinspection PyUnresolvedReferences
 from .server import *  # noqa
-# noinspection PyUnresolvedReferences
 from .util import *  # noqa
-# noinspection PyUnresolvedReferences
-from .events import *  # noqa
 
 __all__ = tuple(itertools.chain(
-    ('bin',),
-    exception.__all__,  # noqa
+    ('bin', 'typing'),
     common.__all__,  # noqa
+    events.__all__,  # noqa
+    exception.__all__,  # noqa
     message.__all__,  # noqa
     protocol.__all__,  # noqa
     server.__all__,  # noqa
     util.__all__,  # noqa
-    events.__all__,  # noqa
 ))
 
 __author__ = 'Lennart Grahl <[email protected]>'