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
|
Installation
============
This document describes the prerequisites and the installation of |Ab|.
Requirements
------------
|ab| runs on Python on top of these networking frameworks:
* `Twisted`_
* `asyncio`_
You will need at least one of those.
.. note::
Most of Autobahn's WebSocket and WAMP features are available on both Twisted and asyncio, so you are free to choose the underlying networking framework based on your own criteria.
For Twisted installation, please see `here <http://twistedmatrix.com/>`__. Asyncio comes bundled with Python 3.5+.
Supported Configurations
........................
Here are the configurations supported by |ab|:
+---------------+-----------+---------+---------------------------------+
| Python | Twisted | asyncio | Notes |
+---------------+-----------+---------+---------------------------------+
+---------------+-----------+---------+---------------------------------+
| CPython 3.5+ | yes | yes | asyncio in the standard library |
+---------------+-----------+---------+---------------------------------+
| PyPy 3 | yes | yes | asyncio in the standard library |
+---------------+-----------+---------+---------------------------------+
Performance Note
................
|ab| is portable, well tuned code. You can further accelerate performance by
* Running under `PyPy <http://pypy.org/>`_ (recommended!) or
* on CPython, install the native accelerators `wsaccel <https://pypi.python.org/pypi/wsaccel/>`_ and `ujson <https://pypi.python.org/pypi/ujson/>`_ (you can use the install variant ``acceleration`` for that - see below)
To give you an idea of the performance you can expect, here is a `blog post <http://crossbario.com/blog/post/autobahn-pi-benchmark/>`_ benchmarking |ab| running on the `RaspberryPi <http://www.raspberrypi.org/>`_ (a tiny embedded computer) under `PyPy <http://pypy.org/>`_.
Installing Autobahn
-------------------
Using Docker
............
We offer `Docker Images <https://hub.docker.com/r/crossbario/autobahn-python/>`_ with |ab| pre-installed. To use this, if you have Docker already installed, just do
``sudo docker run -it crossbario/autobahn-python python client.py --url ws://IP _of_WAMP_router:8080/ws --realm realm1``
This starts up a Docker container and `client.py`, which connects to a Crossbar.io router at the given URL and to the given realm.
There are several docker images to choose from, depending on whether you are using CPython or PyPy.
There are the flavors which are based on the official CPython and PyPy images, plus versions using Alpine Linux, which have a smaller footprint. (Note: Footprint only matters for the download once per machine, after that the cached image is used. Containers off the same image/layers only take up space corresponding to how different from the image they are, so image size is relatively less important when using multiple containers.)
Install from PyPI
.................
To install |ab| from the `Python Package Index <http://pypi.python.org/pypi/autobahn>`_ using `Pip <http://www.pip-installer.org/en/latest/installing.html>`_
.. code-block:: sh
pip install autobahn
You can also specify *install variants* (see below). E.g. to install Twisted automatically as a dependency
.. code-block:: sh
pip install autobahn[twisted]
And to install asyncio backports automatically when required
.. code-block:: sh
pip install autobahn[asyncio]
Install from Sources
....................
To install from sources, clone the repository:
.. code-block:: sh
git clone git@github.com:crossbario/autobahn-python.git
checkout a tagged release:
.. code-block:: sh
cd AutobahnPython
git checkout v0.9.1
.. warning::
You should only use *tagged* releases, not *master*. The latest code from *master* might be broken, unfinished and untested. So you have been warned ;)
Then do:
.. code-block:: sh
cd autobahn
python setup.py install
You can also use ``pip`` for the last step, which allows to specify install variants (see below)
.. code-block:: sh
pip install -e .[twisted]
Install Variants
................
|Ab| has the following install variants:
+-------------------+--------------------------------------------------------------------------------------------------------+
| **Variant** | **Description** |
+-------------------+--------------------------------------------------------------------------------------------------------+
| ``twisted`` | Install Twisted as a dependency |
+-------------------+--------------------------------------------------------------------------------------------------------+
| ``asyncio`` | Install asyncio as a dependency (or use stdlib) |
+-------------------+--------------------------------------------------------------------------------------------------------+
| ``accelerate`` | Install native acceleration packages on CPython |
+-------------------+--------------------------------------------------------------------------------------------------------+
| ``compress`` | Install packages for non-standard WebSocket compression methods |
+-------------------+--------------------------------------------------------------------------------------------------------+
| ``serialization`` | Install packages for additional WAMP serialization formats (currently `MsgPack <http://msgpack.org>`_) |
+-------------------+--------------------------------------------------------------------------------------------------------+
Install variants can be combined, e.g. to install |ab| with all optional packages for use with Twisted on CPython:
.. code-block:: sh
pip install autobahn[twisted,accelerate,compress,serialization]
Windows Installation
....................
For convenience, here are minimal instructions to install both Python and Autobahn/Twisted on Windows:
1. Go to the `Python web site <https://www.python.org/downloads/>`_ and install Python 3.7 32-Bit
2. Add ``C:\Python37;C:\Python37\Scripts;`` to your ``PATH``
3. Download the `Pip install script <https://bootstrap.pypa.io/get-pip.py>`_ and double click it (or run ``python get-pip.py`` from a command shell)
4. Open a command shell and run ``pip install autobahn[twisted]``
Check the Installation
----------------------
To check the installation, fire up the Python and run
.. doctest::
>>> from autobahn import __version__
>>> print(__version__)
0.9.1
Depending on Autobahn
---------------------
To require |Ab| as a dependency of your package, include the following in your ``setup.py`` script
.. code-block:: python
install_requires = ["autobahn>=0.9.1"]
You can also depend on an *install variant* which automatically installs dependent packages
.. code-block:: python
install_requires = ["autobahn[twisted]>=0.9.1"]
The latter will automatically install Twisted as a dependency.
-------
*Where to go*
Now you've got |Ab| installed, depending on your needs, head over to
* :doc:`asynchronous-programming` - An very short introduction plus pointers to good Web resources.
* :doc:`websocket/programming` - A guide to programming WebSocket applications with |ab|
* :doc:`wamp/programming` - A guide to programming WAMP applications with |ab|
|
