wip

autobahn/asyncio/rawsocket.py

@@ -154,7 +154,8 @@ class PrefixProtocol(asyncio.Protocol):
 
 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:
@@ -225,9 +226,6 @@ class HandshakeError(Exception):
 
 class RawSocketClientProtocol(RawSocketProtocol):
 
-    def __init__(self, max_size=None):
-        RawSocketProtocol.__init__(self, max_size=max_size)
-
     def check_serializer(self, ser_id):
         return True
 
@@ -255,9 +253,6 @@ class RawSocketClientProtocol(RawSocketProtocol):
 
 class RawSocketServerProtocol(RawSocketProtocol):
 
-    def __init__(self, max_size=None):
-        RawSocketProtocol.__init__(self, max_size=max_size)
-
     def supports_serializer(self, ser_id):
         raise NotImplementedError()
 
@@ -368,7 +363,11 @@ class WampRawSocketMixinAsyncio(object):
 @public
 class WampRawSocketServerProtocol(WampRawSocketMixinGeneral, WampRawSocketMixinAsyncio, RawSocketServerProtocol):
     """
-    Base class for asyncio-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):
@@ -399,8 +398,13 @@ class WampRawSocketServerProtocol(WampRawSocketMixinGeneral, WampRawSocketMixinA
 @public
 class WampRawSocketClientProtocol(WampRawSocketMixinGeneral, WampRawSocketMixinAsyncio, RawSocketClientProtocol):
     """
-    Base class for asyncio-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'):
@@ -432,7 +436,7 @@ class WampRawSocketFactory(object):
 @public
 class WampRawSocketServerFactory(WampRawSocketFactory):
     """
-    Base class for asyncio-based WAMP-over-RawSocket server factories.
+    asyncio-based WAMP-over-RawSocket server protocol factory.
     """
     protocol = WampRawSocketServerProtocol
 
@@ -442,10 +446,11 @@ class WampRawSocketServerFactory(WampRawSocketFactory):
         :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
+        :param serializers: A list of WAMP serializers to use (or ``None``
-           :class:`autobahn.wamp.interfaces.ISerializer`.
+            for all available serializers).
-        :type serializers: list
+        :type serializers: list of objects implementing
+            :class:`autobahn.wamp.interfaces.ISerializer`
         """
         if callable(factory):
             self._factory = factory
@@ -466,7 +471,7 @@ class WampRawSocketServerFactory(WampRawSocketFactory):
 @public
 class WampRawSocketClientFactory(WampRawSocketFactory):
     """
-    Base class for asyncio-based WAMP-over-RawSocket client factories.
+    asyncio-based WAMP-over-RawSocket client factory.
     """
     protocol = WampRawSocketClientProtocol
 
@@ -476,10 +481,11 @@ class WampRawSocketClientFactory(WampRawSocketFactory):
         :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
+        :param serializer: The WAMP serializer to use (or ``None`` for
-           :class:`autobahn.wamp.interfaces.ISerializer`.
+           "best" serializer, chosen as the first serializer available from
-        :type serializer: obj
+           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

@@ -56,6 +56,11 @@ __all__ = (
 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()
@@ -89,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
@@ -104,8 +110,8 @@ class ApplicationRunner(object):
 
         :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=``
+           method, to which this value is passed as the ``ssl``
-           kwarg.
+           keyword parameter.
         :type ssl: :class:`ssl.SSLContext` or bool
         """
         assert(type(url) == six.text_type)
@@ -125,6 +131,10 @@ class ApplicationRunner(object):
         :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():

autobahn/asyncio/websocket.py

@@ -196,7 +196,9 @@ class WebSocketServerProtocol(WebSocketAdapterProtocol, protocol.WebSocketServer
     """
     Base class for asyncio-based WebSocket server protocols.
 
-    Implements :class:`autobahn.websocket.interfaces.IWebSocketChannel`.
+    Implements:
+
+    * :class:`autobahn.websocket.interfaces.IWebSocketChannel`
     """
 
     log = txaio.make_logger()
@@ -207,7 +209,9 @@ class WebSocketClientProtocol(WebSocketAdapterProtocol, protocol.WebSocketClient
     """
     Base class for asyncio-based WebSocket client protocols.
 
-    Implements :class:`autobahn.websocket.interfaces.IWebSocketChannel`.
+    Implements:
+
+    * :class:`autobahn.websocket.interfaces.IWebSocketChannel`
     """
 
     log = txaio.make_logger()
@@ -238,7 +242,9 @@ class WebSocketServerFactory(WebSocketAdapterFactory, protocol.WebSocketServerFa
     """
     Base class for asyncio-based WebSocket server factories.
 
-    Implements :class:`autobahn.websocket.interfaces.IWebSocketServerChannelFactory`
+    Implements:
+
+    * :class:`autobahn.websocket.interfaces.IWebSocketServerChannelFactory`
     """
 
     protocol = WebSocketServerProtocol
@@ -262,7 +268,9 @@ class WebSocketClientFactory(WebSocketAdapterFactory, protocol.WebSocketClientFa
     """
     Base class for asyncio-based WebSocket client factories.
 
-    Implements :class:`autobahn.websocket.interfaces.IWebSocketClientChannelFactory`
+    Implements:
+
+    * :class:`autobahn.websocket.interfaces.IWebSocketClientChannelFactory`
     """
 
     def __init__(self, *args, **kwargs):
@@ -283,19 +291,34 @@ class WebSocketClientFactory(WebSocketAdapterFactory, protocol.WebSocketClientFa
 @public
 class WampWebSocketServerProtocol(websocket.WampWebSocketServerProtocol, WebSocketServerProtocol):
     """
-    Base class for asyncio-based WAMP-over-WebSocket server protocols.
+    asyncio-based WAMP-over-WebSocket server protocol.
+
+    Implements:
+
+    * :class:`autobahn.wamp.interfaces.ITransport`
     """
 
 
 @public
 class WampWebSocketServerFactory(websocket.WampWebSocketServerFactory, WebSocketServerFactory):
     """
-    Base class for asyncio-based WAMP-over-WebSocket server factories.
+    asyncio-based WAMP-over-WebSocket server factory.
     """
 
     protocol = WampWebSocketServerProtocol
 
     def __init__(self, factory, *args, **kwargs):
+        """
+
+        :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 all available serializers).
+        :type serializers: list of objects implementing
+            :class:`autobahn.wamp.interfaces.ISerializer`
+        """
 
         serializers = kwargs.pop('serializers', None)
 
@@ -310,19 +333,34 @@ class WampWebSocketServerFactory(websocket.WampWebSocketServerFactory, WebSocket
 @public
 class WampWebSocketClientProtocol(websocket.WampWebSocketClientProtocol, WebSocketClientProtocol):
     """
-    Base class for asyncio-based WAMP-over-WebSocket client protocols.
+    asyncio-based WAMP-over-WebSocket client protocols.
+
+    Implements:
+
+    * :class:`autobahn.wamp.interfaces.ITransport`
     """
 
 
 @public
 class WampWebSocketClientFactory(websocket.WampWebSocketClientFactory, WebSocketClientFactory):
     """
-    Base class for asyncio-based WAMP-over-WebSocket client factories.
+    asyncio-based WAMP-over-WebSocket client factory.
     """
 
     protocol = WampWebSocketClientProtocol
 
     def __init__(self, factory, *args, **kwargs):
+        """
+
+        :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
+           "best" serializer, chosen as the first serializer available from
+           this list: CBOR, MessagePack, UBJSON, JSON).
+        :type serializer: object implementing :class:`autobahn.wamp.interfaces.ISerializer`
+        """
 
         serializers = kwargs.pop('serializers', None)
 

autobahn/twisted/rawsocket.py

@@ -85,7 +85,7 @@ class WampRawSocketProtocol(Int32StringReceiver):
         #
         self._handshake_bytes = b''
 
-        # Clinet requested maximum length of serialized messages.
+        # Client requested maximum length of serialized messages.
         #
         self._max_len_send = None
 
@@ -175,7 +175,11 @@ class WampRawSocketProtocol(Int32StringReceiver):
 @public
 class WampRawSocketServerProtocol(WampRawSocketProtocol):
     """
-    Base class for Twisted-based WAMP-over-RawSocket server protocols.
+    Twisted-based WAMP-over-RawSocket server protocol.
+
+    Implements:
+
+        * :class:`autobahn.wamp.interfaces.ITransport`
     """
 
     def dataReceived(self, data):
@@ -263,7 +267,11 @@ class WampRawSocketServerProtocol(WampRawSocketProtocol):
 @public
 class WampRawSocketClientProtocol(WampRawSocketProtocol):
     """
-    Base class for Twisted-based WAMP-over-RawSocket client protocols.
+    Twisted-based WAMP-over-RawSocket client protocol.
+
+    Implements:
+
+        * :class:`autobahn.wamp.interfaces.ITransport`
     """
 
     def connectionMade(self):
@@ -354,8 +362,9 @@ class WampRawSocketFactory(Factory):
 @public
 class WampRawSocketServerFactory(WampRawSocketFactory):
     """
-    Base class for Twisted-based WAMP-over-RawSocket server factories.
+    Twisted-based WAMP-over-RawSocket server protocol factory.
     """
+
     protocol = WampRawSocketServerProtocol
 
     def __init__(self, factory, serializers=None):
@@ -364,10 +373,11 @@ class WampRawSocketServerFactory(WampRawSocketFactory):
         :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
+        :param serializers: A list of WAMP serializers to use (or ``None``
-           :class:`autobahn.wamp.interfaces.ISerializer`.
+            for all available serializers).
-        :type serializers: list
+        :type serializers: list of objects implementing
+            :class:`autobahn.wamp.interfaces.ISerializer`
         """
         if callable(factory):
             self._factory = factory
@@ -420,8 +430,9 @@ class WampRawSocketServerFactory(WampRawSocketFactory):
 @public
 class WampRawSocketClientFactory(WampRawSocketFactory):
     """
-    Base class for Twisted-based WAMP-over-RawSocket client factories.
+    Twisted-based WAMP-over-RawSocket client protocol factory.
     """
+
     protocol = WampRawSocketClientProtocol
 
     def __init__(self, factory, serializer=None):
@@ -430,10 +441,11 @@ class WampRawSocketClientFactory(WampRawSocketFactory):
         :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
+        :param serializer: The WAMP serializer to use (or ``None`` for
-           :class:`autobahn.wamp.interfaces.ISerializer`.
+           "best" serializer, chosen as the first serializer available from
-        :type serializer: obj
+           this list: CBOR, MessagePack, UBJSON, JSON).
+        :type serializer: object implementing :class:`autobahn.wamp.interfaces.ISerializer`
         """
         if callable(factory):
             self._factory = factory

autobahn/twisted/wamp.py

@@ -34,6 +34,8 @@ txaio.use_twisted()  # noqa
 
 from twisted.internet.defer import inlineCallbacks, succeed
 
+from autobahn.util import public
+
 from autobahn.websocket.util import parse_url as parse_ws_url
 from autobahn.rawsocket.util import parse_url as parse_rs_url
 
@@ -65,9 +67,15 @@ except (ImportError, SyntaxError):
     __all__.pop(__all__.index('Service'))
 
 
+@public
 class ApplicationSession(protocol.ApplicationSession):
     """
     WAMP application session for Twisted-based applications.
+
+    Implements:
+
+        * :class:`autobahn.wamp.interfaces.ITransportHandler`
+        * :class:`autobahn.wamp.interfaces.ISession`
     """
 
     log = txaio.make_logger()
@@ -86,6 +94,7 @@ class ApplicationSessionFactory(protocol.ApplicationSessionFactory):
     log = txaio.make_logger()
 
 
+@public
 class ApplicationRunner(object):
     """
     This class is a convenience tool mainly for development and quick hosting
@@ -101,10 +110,10 @@ class ApplicationRunner(object):
         """
 
         :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
@@ -149,15 +158,16 @@ class ApplicationRunner(object):
         else:
             return succeed(None)
 
+    @public
     def run(self, make, start_reactor=True, auto_reconnect=False, log_level='info'):
         """
         Run the application component.
 
-        :param make: A factory that produces instances of :class:`autobahn.asyncio.wamp.ApplicationSession`
+        :param make: A factory that produces instances of :class:`autobahn.twisted.wamp.ApplicationSession`
            when called with an instance of :class:`autobahn.wamp.types.ComponentConfig`.
         :type make: callable
 
-        :param start_reactor: if True (the default) this method starts
+        :param start_reactor: When ``True`` (the default) this method starts
            the Twisted reactor and doesn't return until the reactor
            stops. If there are any problems starting the reactor or
            connect()-ing, we stop the reactor and raise the exception

autobahn/twisted/websocket.py

@@ -506,10 +506,13 @@ def connectWS(factory, contextFactory=None, timeout=30, bindAddress=None):
 
     :param factory: The WebSocket protocol factory to be used for creating client protocol instances.
     :type factory: An :class:`autobahn.websocket.WebSocketClientFactory` instance.
+
     :param contextFactory: SSL context factory, required for secure WebSocket connections ("wss").
     :type contextFactory: A `twisted.internet.ssl.ClientContextFactory <http://twistedmatrix.com/documents/current/api/twisted.internet.ssl.ClientContextFactory.html>`_ instance.
+
     :param timeout: Number of seconds to wait before assuming the connection has failed.
     :type timeout: int
+
     :param bindAddress: A (host, port) tuple of local address to bind to, or None.
     :type bindAddress: tuple
 
@@ -547,10 +550,13 @@ def listenWS(factory, contextFactory=None, backlog=50, interface=''):
 
     :param factory: The WebSocket protocol factory to be used for creating server protocol instances.
     :type factory: An :class:`autobahn.websocket.WebSocketServerFactory` instance.
+
     :param contextFactory: SSL context factory, required for secure WebSocket connections ("wss").
     :type contextFactory: A twisted.internet.ssl.ContextFactory.
+
     :param backlog: Size of the listen queue.
     :type backlog: int
+
     :param interface: The interface (derived from hostname given) to bind to, defaults to '' (all).
     :type interface: str
 
@@ -575,19 +581,34 @@ def listenWS(factory, contextFactory=None, backlog=50, interface=''):
 @public
 class WampWebSocketServerProtocol(websocket.WampWebSocketServerProtocol, WebSocketServerProtocol):
     """
-    Base class for Twisted-based WAMP-over-WebSocket server protocols.
+    Twisted-based WAMP-over-WebSocket server protocol.
+
+    Implements:
+
+    * :class:`autobahn.wamp.interfaces.ITransport`
     """
 
 
 @public
 class WampWebSocketServerFactory(websocket.WampWebSocketServerFactory, WebSocketServerFactory):
     """
-    Base class for Twisted-based WAMP-over-WebSocket server factories.
+    Twisted-based WAMP-over-WebSocket server protocol factory.
     """
 
     protocol = WampWebSocketServerProtocol
 
     def __init__(self, factory, *args, **kwargs):
+        """
+
+        :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 all available serializers).
+        :type serializers: list of objects implementing
+            :class:`autobahn.wamp.interfaces.ISerializer`
+        """
 
         serializers = kwargs.pop('serializers', None)
 
@@ -602,19 +623,34 @@ class WampWebSocketServerFactory(websocket.WampWebSocketServerFactory, WebSocket
 @public
 class WampWebSocketClientProtocol(websocket.WampWebSocketClientProtocol, WebSocketClientProtocol):
     """
-    Base class for Twisted-based WAMP-over-WebSocket client protocols.
+    Twisted-based WAMP-over-WebSocket client protocol.
+
+    Implements:
+
+    * :class:`autobahn.wamp.interfaces.ITransport`
     """
 
 
 @public
 class WampWebSocketClientFactory(websocket.WampWebSocketClientFactory, WebSocketClientFactory):
     """
-    Base class for Twisted-based WAMP-over-WebSocket client factories.
+    Twisted-based WAMP-over-WebSocket client protocol factory.
     """
 
     protocol = WampWebSocketClientProtocol
 
     def __init__(self, factory, *args, **kwargs):
+        """
+
+        :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
+           "best" serializer, chosen as the first serializer available from
+           this list: CBOR, MessagePack, UBJSON, JSON).
+        :type serializer: object implementing :class:`autobahn.wamp.interfaces.ISerializer`
+        """
 
         serializers = kwargs.pop('serializers', None)
 

docs/changelog.rst

@@ -8,14 +8,14 @@ Changelog
 0.18.0
 ------
 
-`Published 2017-03-19 <https://pypi.python.org/pypi/autobahn/0.18.0>`__
+`Published 2017-03-26 <https://pypi.python.org/pypi/autobahn/0.18.0>`__
 
+* fix: big docs cleanup and polish
 * fix: docs for publisher black-/whitelisting based on authid/authrole
 * fix: serialization for publisher black-/whitelisting based on authid/authrole
 * new: allow to stop auto-reconnecting for Twisted ApplicationRunner
 * fix: allow empty realms (router decides) for asyncio ApplicationRunner
 
-
 0.17.2
 ------
 

docs/reference/autobahn.asyncio.rst

@@ -7,7 +7,7 @@ Autobahn asyncio specific classes. These are used when asyncio is run as the und
 WebSocket Protocols and Factories
 ---------------------------------
 
-Base classes for WebSocket clients and servers using asyncio.
+Classes for WebSocket clients and servers using asyncio.
 
 .. autoclass:: autobahn.asyncio.websocket.WebSocketServerProtocol
     :members:
@@ -25,7 +25,7 @@ Base classes for WebSocket clients and servers using asyncio.
 WAMP-over-WebSocket Protocols and Factories
 -------------------------------------------
 
-Base classes for WAMP-WebSocket clients and servers using asyncio.
+Classes for WAMP-WebSocket clients and servers using asyncio.
 
 .. autoclass:: autobahn.asyncio.websocket.WampWebSocketServerProtocol
     :members:
@@ -43,7 +43,7 @@ Base classes for WAMP-WebSocket clients and servers using asyncio.
 WAMP-over-RawSocket Protocols and Factories
 -------------------------------------------
 
-Base classes for WAMP-RawSocket clients and servers using asyncio.
+Classes for WAMP-RawSocket clients and servers using asyncio.
 
 .. autoclass:: autobahn.asyncio.rawsocket.WampRawSocketServerProtocol
     :members:
@@ -56,3 +56,15 @@ Base classes for WAMP-RawSocket clients and servers using asyncio.
 
 .. autoclass:: autobahn.asyncio.rawsocket.WampRawSocketClientFactory
     :members:
+
+
+WAMP Sessions
+-------------
+
+Classes for WAMP sessions using asyncio.
+
+.. autoclass:: autobahn.asyncio.wamp.ApplicationSession
+    :members:
+
+.. autoclass:: autobahn.asyncio.wamp.ApplicationRunner
+    :members:

docs/reference/autobahn.twisted.rst

@@ -7,7 +7,7 @@ Autobahn Twisted specific classes. These are used when Twisted is run as the und
 WebSocket Protocols and Factories
 ---------------------------------
 
-Base classes for WebSocket clients and servers using Twisted.
+Classes for WebSocket clients and servers using Twisted.
 
 .. autoclass:: autobahn.twisted.websocket.WebSocketServerProtocol
     :members:
@@ -25,7 +25,7 @@ Base classes for WebSocket clients and servers using Twisted.
 WAMP-over-WebSocket Protocols and Factories
 -------------------------------------------
 
-Base classes for WAMP-WebSocket clients and servers using Twisted.
+Classes for WAMP-WebSocket clients and servers using Twisted.
 
 .. autoclass:: autobahn.twisted.websocket.WampWebSocketServerProtocol
     :members:
@@ -43,7 +43,7 @@ Base classes for WAMP-WebSocket clients and servers using Twisted.
 WAMP-over-RawSocket Protocols and Factories
 -------------------------------------------
 
-Base classes for WAMP-RawSocket clients and servers using Twisted.
+Classes for WAMP-RawSocket clients and servers using Twisted.
 
 .. autoclass:: autobahn.twisted.rawsocket.WampRawSocketServerProtocol
     :members:
@@ -56,3 +56,15 @@ Base classes for WAMP-RawSocket clients and servers using Twisted.
 
 .. autoclass:: autobahn.twisted.rawsocket.WampRawSocketClientFactory
     :members:
+
+
+WAMP Sessions
+-------------
+
+Classes for WAMP sessions using Twisted.
+
+.. autoclass:: autobahn.twisted.wamp.ApplicationSession
+    :members:
+
+.. autoclass:: autobahn.twisted.wamp.ApplicationRunner
+    :members: