deb-python-autobahn/docs/installation.rst
Tobias Oberstein 5d2b2a937f cleanup
2016-04-30 17:33:08 +02:00

8.0 KiB

Installation

This document describes the prerequisites and the installation of .

Requirements

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. Asyncio comes bundled with Python 3.4+. For Python 3.3, install it from here. For Python 2, trollius will work.

Supported Configurations

Here are the configurations supported by :

Python Twisted asyncio Notes
CPython 2.7 yes yes asyncio support via trollius
CPython 3.3 yes yes asyncio support via tulip
CPython 3.4+ yes yes asyncio in the standard library
PyPy 2.2+ yes yes asyncio support via trollius
Jython 2.7+ yes ? Issues: 1, 2

Performance Note

is portable, well tuned code. You can further accelerate performance by

  • Running under PyPy (recommended!) or
  • on CPython, install the native accelerators wsaccel and 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 benchmarking running on the RaspberryPi (a tiny embedded computer) under PyPy.

Installing Autobahn

Using Docker

We offer Docker Images with pre-installed. To use this, if you have Docker already installed, just do

sudo docker run -it crossbario/autobahn-python:cpy2 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 Python 2, 3 or PyPy (Python 2 only for now).

There are the flavors which are based on the official Python 2, 3 and PyPy images, plus Python 2 and 3 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 from the Python Package Index using Pip

pip install autobahn

You can also specify install variants (see below). E.g. to install Twisted automatically as a dependency

pip install autobahn[twisted]

And to install asyncio backports automatically when required

pip install autobahn[asyncio]

Install from Sources

To install from sources, clone the repository:

git clone git@github.com:crossbario/autobahn-python.git

checkout a tagged release:

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:

cd autobahn
python setup.py install

You can also use pip for the last step, which allows to specify install variants (see below)

pip install -e .[twisted]

Install Variants

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)

Install variants can be combined, e.g. to install with all optional packages for use with Twisted on CPython:

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 and install Python 2.7 32-Bit
  2. Add C:\Python27;C:\Python27\Scripts; to your PATH
  3. Download the Pip install script 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

>>> from autobahn import __version__ >>> print(__version__) 0.9.1

Depending on Autobahn

To require as a dependency of your package, include the following in your setup.py script

install_requires = ["autobahn>=0.9.1"]

You can also depend on an install variant which automatically installs dependent packages

install_requires = ["autobahn[twisted]>=0.9.1"]

The latter will automatically install Twisted as a dependency.


Where to go

Now you've got installed, depending on your needs, head over to

  • asynchronous-programming - An very short introduction plus pointers to good Web resources.
  • websocket/programming - A guide to programming WebSocket applications with
  • wamp/programming - A guide to programming WAMP applications with