1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
|
|AbL|
=====
| |Version| |Build Status| |Coverage| |Docs|
--------------
*Open-source (MIT) real-time framework for Web, Mobile & Internet of Things.*
|AbL| is part of the `Autobahn`_ project and provides open-source implementations of
* `The WebSocket Protocol <http://tools.ietf.org/html/rfc6455>`__
* `The Web Application Messaging Protocol (WAMP) <http://wamp.ws/>`__
in Python 2 and 3, running on `Twisted`_ **or** `asyncio`_.
-----
Autobahn Features
-----------------
`WebSocket`_ allows `bidirectional real-time messaging <http://crossbario.com/blog/post/websocket-why-what-can-i-use-it/>`_ on the Web while `WAMP`_ provides applications with `high-level communication abstractions <http://wamp.ws/why/>`__ (remote procedure calling and publish/subscribe) in an open standard WebSocket-based protocol.
|AbL| features:
* framework for `WebSocket`_ and `WAMP`_ clients
* compatible with Python 2.7 and 3.3+
* runs on `CPython`_, `PyPy`_ and `Jython`_
* runs under `Twisted`_ and `asyncio`_
* implements WebSocket `RFC6455`_ (and draft versions Hybi-10+)
* implements `WebSocket compression <http://tools.ietf.org/html/draft-ietf-hybi-permessage-compression>`__
* implements `WAMP`_, the Web Application Messaging Protocol
* supports TLS (secure WebSocket) and proxies
* Open-source (`MIT license <https://github.com/crossbario/autobahn-python/blob/master/LICENSE>`__)
...and much more.
Further, |AbL| is written with these goals:
1. high-performance, fully asynchronous and scalable code
2. best-in-class standards conformance and security
We do take those design and implementation goals quite serious. For example, |AbL| has 100% strict passes with `AutobahnTestsuite`_, the quasi industry standard of WebSocket protocol test suites we originally created only to test |AbL| ;)
For (hopefully) current test reports from the Testsuite see
* `WebSocket client functionality <http://autobahn.ws/reports/clients/>`_
* `WebSocket server functionality <http://autobahn.ws/reports/servers/>`_
.. note::
In the following, we will just refer to |Ab| instead of the
more precise term |AbL| and there is no
ambiguity.
What can I do with Autobahn?
----------------------------
WebSocket is great for apps like **chat**, **trading**, **multi-player games** or **real-time charts**. It allows you to **actively push information** to clients as it happens. (See also :ref:`run_all_examples`)
.. image:: _static/wamp-demos.png
:alt: ascii-cast of all WAMP demos running
:height: 443
:width: 768
:target: wamp/examples.html#run-all-examples
:scale: 40%
:align: right
Further, WebSocket allows you to real-time enable your Web user interfaces: **always current information** without reloads or polling. UIs no longer need to be a boring, static thing. Looking for the right communication technology for your next-generation Web apps? Enter WebSocket.
And WebSocket works great not only on the Web, but also as a protocol for wiring up the **Internet-of-Things (IoT)**. Connecting a sensor or actor to other application components in real-time over an efficient protocol. Plus: you are using the *same* protocol to connect frontends like Web browsers.
While WebSocket already is quite awesome, it is still low-level. Which is why we have WAMP. WAMP allows you to **compose your application from loosely coupled components** that talk in real-time with each other - using nice high-level communication patterns ("Remote Procedure Calls" and "Publish & Subscribe").
WAMP enables application architectures with application code **distributed freely across processes and devices** according to functional aspects. Since WAMP implementations exist for **multiple languages**, WAMP applications can be **polyglot**. Application components can be implemented in a language and run on a device which best fit the particular use case.
WAMP is a routed protocol, so you need a WAMP router. We suggest using `Crossbar.io <http://crossbar.io>`_, but there are also `other implementations <http://wamp.ws/implementations/>`_ available.
More:
* `WebSocket - Why, what, and - can I use it? <http://crossbario.com/blog/post/websocket-why-what-can-i-use-it/>`_
* `Why WAMP? <http://wamp.ws/why/>`_
Show me some code!
------------------
A sample **WebSocket server**:
.. code-block:: python
from autobahn.twisted.websocket import WebSocketServerProtocol
# or: from autobahn.asyncio.websocket import WebSocketServerProtocol
class MyServerProtocol(WebSocketServerProtocol):
def onConnect(self, request):
print("Client connecting: {}".format(request.peer))
def onOpen(self):
print("WebSocket connection open.")
def onMessage(self, payload, isBinary):
if isBinary:
print("Binary message received: {} bytes".format(len(payload)))
else:
print("Text message received: {}".format(payload.decode('utf8')))
## echo back message verbatim
self.sendMessage(payload, isBinary)
def onClose(self, wasClean, code, reason):
print("WebSocket connection closed: {}".format(reason))
Complete example code:
* `WebSocket Echo (Twisted-based) <https://github.com/crossbario/autobahn-python/tree/master/examples/twisted/websocket/echo>`_
* `WebSocket Echo (Asyncio-based) <https://github.com/crossbario/autobahn-python/tree/master/examples/asyncio/websocket/echo>`_
Introduction to WebSocket Programming with |ab|:
* :doc:`websocket/programming`
---------
A sample **WAMP application component** implementing all client roles:
.. code-block:: python
from autobahn.twisted.wamp import ApplicationSession
# or: from autobahn.asyncio.wamp import ApplicationSession
class MyComponent(ApplicationSession):
@inlineCallbacks
def onJoin(self, details):
# 1) subscribe to a topic
def onevent(msg):
print("Got event: {}".format(msg))
yield self.subscribe(onevent, 'com.myapp.hello')
# 2) publish an event
self.publish('com.myapp.hello', 'Hello, world!')
# 3) register a procedure for remoting
def add2(x, y):
return x + y
self.register(add2, 'com.myapp.add2');
# 4) call a remote procedure
res = yield self.call('com.myapp.add2', 2, 3)
print("Got result: {}".format(res))
Complete example code:
* `Twisted Example <https://github.com/crossbario/autobahn-python/blob/master/examples/twisted/wamp/overview/>`__
* `asyncio Example <https://github.com/crossbario/autobahn-python/blob/master/examples/asyncio/wamp/overview/>`__
Introduction to WAMP Programming with |ab|:
* :doc:`wamp/programming`
----------
Where to start
--------------
To get started, jump to :doc:`installation`.
For developers new to asynchronous programming, Twisted or asyncio, we've collected some useful pointers and information in :doc:`asynchronous-programming`.
For **WebSocket developers**, :doc:`websocket/programming` explains all you need to know about using |ab| as a WebSocket library, and includes a full reference for the relevant parts of the API.
:doc:`websocket/examples` lists WebSocket code examples covering a broader range of uses cases and advanced WebSocket features.
For **WAMP developers**, :doc:`wamp/programming` gives an introduction for programming with WAMP in Python using |ab|.
:doc:`wamp/examples` lists WAMP code examples covering all features of WAMP.
Get in touch
------------
Development of |ab| takes place on the GitHub `source repository <https://github.com/crossbario/autobahn-python>`_.
.. note::
We are open for contributions, whether that's code or documentation! Preferably via pull requests.
We also take **bug reports** at the `issue tracker <https://github.com/crossbario/autobahn-python/issues>`_.
The best place to **ask questions** is on the `mailing list <https://groups.google.com/forum/#!forum/autobahnws>`_. We'd also love to hear about your project and what you are using |ab| for!
Another option is `StackOverflow <http://stackoverflow.com>`_ where `questions <http://stackoverflow.com/questions/tagged/autobahn?sort=newest>`__ related to |ab| are tagged `"autobahn" <http://stackoverflow.com/tags/autobahn/info>`__ (or `"autobahnws" <http://stackoverflow.com/tags/autobahnws/info>`__).
The best way to **Search the Web** for related material is by using these (base) search terms:
* `"autobahnpython" <https://www.google.com/search?q=autobahnpython>`__
* `"autobahnws" <https://www.google.com/search?q=autobahnws>`__
You can also reach users and developers on **IRC** channel ``#autobahn`` at `freenode.net <http://www.freenode.net/>`__.
Finally, we are on `Twitter <https://twitter.com/autobahnws>`_.
Contributing
------------
|ab| is an open source project, and hosted on GitHub. The `GitHub repository <https://github.com/crossbario/autobahn-python>`_ includes the documentation.
We're looking for all kinds of contributions - from simple fixes of typos in the code or documentation to implementation of new features and additions of tutorials.
If you want to contribute to the code or the documentation: we use the Fork & Pull Model.
This means that you fork the repo, make changes to your fork, and then make a pull request here on the main repo.
This `article on GitHub <https://help.github.com/articles/using-pull-requests>`_ gives more detailed information on how the process works.
In order to run the unit-tests, we use `Tox <http://tox.readthedocs.org/en/latest/>`_ to build the various test-environments. To run them all, simply run ``tox`` from the top-level directory of the clone.
For test-coverage, see the Makefile target ``test_coverage``, which deletes the coverage data and then runs the test suite with various tox test-environments before outputting HTML annotated coverage to ``./htmlcov/index.html`` and a coverage report to the terminal.
There are two environment variables the tests use: ``USE_TWISTED=1`` or ``USE_ASYNCIO=1`` control whether to run unit-tests that are specific to one framework or the other.
See ``tox.ini`` for details on how to run in the different environments.
Release Testing
---------------
Before pushing a new release, three levels of tests need to pass:
1. the unit tests (see above)
2. the [WebSocket level tests](wstest/README.md)
3. the [WAMP level tests](examples/README.md) (*)
> (*): these will launch a Crossbar.io router for testing
Sitemap
-------
Please see :ref:`site_contents` for a full site-map.
.. |Version| image:: https://img.shields.io/pypi/v/autobahn.svg
:target: https://pypi.python.org/pypi/autobahn
.. |GitHub Stars| image:: https://img.shields.io/github/stars/crossbario/autobahn-python.svg?style=social&label=Star
:target: https://github.com/crossbario/autobahn-python
.. |Master Branch| image:: https://img.shields.io/badge/branch-master-orange.svg
:target: https://travis-ci.org/crossbario/autobahn-python.svg?branch=master
.. |Build Status| image:: https://travis-ci.org/crossbario/autobahn-python.svg?branch=master
:target: https://travis-ci.org/crossbario/autobahn-python
.. |Coverage| image:: https://img.shields.io/codecov/c/github/crossbario/autobahn-python/master.svg
:target: https://codecov.io/github/crossbario/autobahn-python
.. |Docs| image:: https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat
:target: http://autobahn.readthedocs.org/en/latest/
|
