Merge pull request #794 from oberstet/big_polish

Big polish

README.rst

@@ -32,14 +32,14 @@ Features
 --------
 
 -  framework for `WebSocket <http://tools.ietf.org/html/rfc6455>`__ and `WAMP <http://wamp-proto.org/>`__ clients and servers
--  compatible with Python 2.6, 2.7, 3.3 and 3.4
+-  compatible with Python 2.7 and 3.3 or later
 -  runs on `CPython <http://python.org/>`__, `PyPy <http://pypy.org/>`__ and `Jython <http://jython.org/>`__
 -  runs under `Twisted <http://twistedmatrix.com/>`__ and `asyncio <http://docs.python.org/3.4/library/asyncio.html>`__ - implements WebSocket
    `RFC6455 <http://tools.ietf.org/html/rfc6455>`__ and Draft Hybi-10+
 -  implements `WebSocket compression <http://tools.ietf.org/html/draft-ietf-hybi-permessage-compression>`__
 -  implements `WAMP <http://wamp-proto.org/>`__, the Web Application Messaging Protocol
 -  high-performance, fully asynchronous implementation
--  best-in-class standards conformance (100% strict passes with `Autobahn Testsuite <http://crossbar.io/autobahn#testsuite>`__)
+-  best-in-class standards conformance (100% strict passes with `Autobahn Testsuite <http://crossbar.io/autobahn#testsuite>`__: `Client <http://autobahn.ws/testsuite/reports/clients/index.html>__` `Server <http://autobahn.ws/testsuite/reports/servers/index.html>`__)
 -  message-, frame- and streaming-APIs for WebSocket
 -  supports TLS (secure WebSocket) and proxies
 -  Open-source (`MIT license <https://github.com/crossbario/autobahn-python/blob/master/LICENSE>`__)

autobahn/_version.py

@@ -24,4 +24,4 @@
 #
 ###############################################################################
 
-__version__ = u'0.17.3'
+__version__ = u'0.18.0'

autobahn/asyncio/rawsocket.py

@@ -33,7 +33,8 @@
     import trollius as asyncio
 import struct
 import math
-from autobahn.util import _LazyHexFormatter
+
+from autobahn.util import public, _LazyHexFormatter
 from autobahn.wamp.exception import ProtocolError, SerializationError, TransportLost
 from autobahn.asyncio.util import peer2str, get_serializers
 import txaio
@@ -153,7 +154,8 @@ def stringReceived(self, data):
 
 class RawSocketProtocol(PrefixProtocol):
 
-    def __init__(self, max_size=None):
+    def __init__(self):
+        max_size = None
         if max_size:
             exp = int(math.ceil(math.log(max_size, 2))) - 9
             if exp > 15:
@@ -224,9 +226,6 @@ def __init__(self, msg, code=0):
 
 class RawSocketClientProtocol(RawSocketProtocol):
 
-    def __init__(self, max_size=None):
-        RawSocketProtocol.__init__(self, max_size=max_size)
-
     def check_serializer(self, ser_id):
         return True
 
@@ -254,9 +253,6 @@ def connection_made(self, transport):
 
 class RawSocketServerProtocol(RawSocketProtocol):
 
-    def __init__(self, max_size=None):
-        RawSocketProtocol.__init__(self, max_size=max_size)
-
     def supports_serializer(self, ser_id):
         raise NotImplementedError()
 
@@ -327,7 +323,7 @@ def isOpen(self):
 
 
 # this is asyncio dependent part of WAMP protocol
-class WampRawSocketMixinAsyncio():
+class WampRawSocketMixinAsyncio(object):
     """
     Base class for asyncio-based WAMP-over-RawSocket protocols.
     """
@@ -364,9 +360,14 @@ def abort(self):
             raise TransportLost()
 
 
+@public
 class WampRawSocketServerProtocol(WampRawSocketMixinGeneral, WampRawSocketMixinAsyncio, RawSocketServerProtocol):
     """
-    Base class for Twisted-based WAMP-over-RawSocket server protocols.
+    asyncio-based WAMP-over-RawSocket server protocol.
+
+    Implements:
+
+        * :class:`autobahn.wamp.interfaces.ITransport`
     """
 
     def supports_serializer(self, ser_id):
@@ -394,10 +395,16 @@ def get_channel_id(self, channel_id_type=u'tls-unique'):
         # return transport_channel_id(self.transport, is_server=True, channel_id_type=channel_id_type)
 
 
+@public
 class WampRawSocketClientProtocol(WampRawSocketMixinGeneral, WampRawSocketMixinAsyncio, RawSocketClientProtocol):
     """
-    Base class for Twisted-based WAMP-over-RawSocket client protocols.
+    asyncio-based WAMP-over-RawSocket client protocol.
+
+    Implements:
+
+        * :class:`autobahn.wamp.interfaces.ITransport`
     """
+
     @property
     def serializer_id(self):
         if not hasattr(self, '_serializer'):
@@ -417,17 +424,19 @@ class WampRawSocketFactory(object):
     Adapter class for asyncio-based WebSocket client and server factories.def dataReceived(self, data):
     """
 
-    log = txaio.make_logger()  # @UndefinedVariable
+    log = txaio.make_logger()
 
+    @public
     def __call__(self):
         proto = self.protocol()
         proto.factory = self
         return proto
 
 
+@public
 class WampRawSocketServerFactory(WampRawSocketFactory):
     """
-    Base class for Twisted-based WAMP-over-RawSocket server factories.
+    asyncio-based WAMP-over-RawSocket server protocol factory.
     """
     protocol = WampRawSocketServerProtocol
 
@@ -437,10 +446,11 @@ def __init__(self, factory, serializers=None):
         :param factory: A callable that produces instances that implement
             :class:`autobahn.wamp.interfaces.ITransportHandler`
         :type factory: callable
-        :param serializers: A list of WAMP serializers to use (or None for default
-           serializers). Serializers must implement
-           :class:`autobahn.wamp.interfaces.ISerializer`.
-        :type serializers: list
+
+        :param serializers: A list of WAMP serializers to use (or ``None``
+            for all available serializers).
+        :type serializers: list of objects implementing
+            :class:`autobahn.wamp.interfaces.ISerializer`
         """
         if callable(factory):
             self._factory = factory
@@ -458,9 +468,10 @@ def __init__(self, factory, serializers=None):
         self._serializers = {ser.RAWSOCKET_SERIALIZER_ID: ser for ser in serializers}
 
 
+@public
 class WampRawSocketClientFactory(WampRawSocketFactory):
     """
-    Base class for Twisted-based WAMP-over-RawSocket client factories.
+    asyncio-based WAMP-over-RawSocket client factory.
     """
     protocol = WampRawSocketClientProtocol
 
@@ -470,10 +481,11 @@ def __init__(self, factory, serializer=None):
         :param factory: A callable that produces instances that implement
             :class:`autobahn.wamp.interfaces.ITransportHandler`
         :type factory: callable
-        :param serializer: The WAMP serializer to use (or None for default
-           serializer). Serializers must implement
-           :class:`autobahn.wamp.interfaces.ISerializer`.
-        :type serializer: obj
+
+        :param serializer: The WAMP serializer to use (or ``None`` for
+           "best" serializer, chosen as the first serializer available from
+           this list: CBOR, MessagePack, UBJSON, JSON).
+        :type serializer: object implementing :class:`autobahn.wamp.interfaces.ISerializer`
         """
         if callable(factory):
             self._factory = factory

autobahn/asyncio/wamp.py

@@ -29,6 +29,7 @@
 
 import six
 
+from autobahn.util import public
 from autobahn.wamp import protocol
 from autobahn.wamp.types import ComponentConfig
 from autobahn.websocket.util import parse_url
@@ -51,11 +52,19 @@
 )
 
 
+@public
 class ApplicationSession(protocol.ApplicationSession):
     """
     WAMP application session for asyncio-based applications.
+
+    Implements:
+
+        * :class:`autobahn.wamp.interfaces.ITransportHandler`
+        * :class:`autobahn.wamp.interfaces.ISession`
     """
 
+    log = txaio.make_logger()
+
 
 class ApplicationSessionFactory(protocol.ApplicationSessionFactory):
     """
@@ -68,7 +77,10 @@ class ApplicationSessionFactory(protocol.ApplicationSessionFactory):
     Defaults to :class:`autobahn.asyncio.wamp.ApplicationSession`.
     """
 
+    log = txaio.make_logger()
+
 
+@public
 class ApplicationRunner(object):
     """
     This class is a convenience tool mainly for development and quick hosting
@@ -82,11 +94,12 @@ class ApplicationRunner(object):
 
     def __init__(self, url, realm, extra=None, serializers=None, ssl=None):
         """
+
         :param url: The WebSocket URL of the WAMP router to connect to (e.g. `ws://somehost.com:8090/somepath`)
-        :type url: unicode
+        :type url: str
 
         :param realm: The WAMP realm to join the application session to.
-        :type realm: unicode
+        :type realm: str
 
         :param extra: Optional extra configuration to forward to the application component.
         :type extra: dict
@@ -97,8 +110,8 @@ def __init__(self, url, realm, extra=None, serializers=None, ssl=None):
 
         :param ssl: An (optional) SSL context instance or a bool. See
            the documentation for the `loop.create_connection` asyncio
-           method, to which this value is passed as the ``ssl=``
-           kwarg.
+           method, to which this value is passed as the ``ssl``
+           keyword parameter.
         :type ssl: :class:`ssl.SSLContext` or bool
         """
         assert(type(url) == six.text_type)
@@ -110,13 +123,18 @@ def __init__(self, url, realm, extra=None, serializers=None, ssl=None):
         self.serializers = serializers
         self.ssl = ssl
 
+    @public
     def run(self, make, start_loop=True):
         """
         Run the application component.
 
         :param make: A factory that produces instances of :class:`autobahn.asyncio.wamp.ApplicationSession`
            when called with an instance of :class:`autobahn.wamp.types.ComponentConfig`.
         :type make: callable
+
+        :param start_loop: When ``True`` (the default) this method
+            start a new asyncio loop.
+        :type start_loop: bool
         """
         if callable(make):
             def create():