Skip to content

docs: update Python and installation guidance #1851

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
puneetdixit200 wants to merge 1 commit into
base: master
Choose a base branch
from
+98 −99
Open

docs: update Python and installation guidance #1851

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 21 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ implementations of
- [The WebSocket Protocol](https://tools.ietf.org/html/rfc6455)
- [The Web Application Messaging Protocol (WAMP)](https://wamp-proto.org/)

for Python 3.7+ and running on
for Python 3.11+ and running on
[Twisted](https://twistedmatrix.com/) and
[asyncio](https://docs.python.org/3/library/asyncio.html).

Expand All @@ -65,9 +65,10 @@ as well.

Note

**Autobahn|Python** up to version v19.11.2 supported Python 2 and
3.4+, and up to version v20.7.1 supported Python 3.5+, and up to
version v21.2.1 supported Python 3.6+.
**Autobahn|Python** currently requires Python 3.11 or later. Earlier
release lines supported older Python versions: up to version v19.11.2
supported Python 2 and 3.4+, up to version v20.7.1 supported Python
3.5+, and up to version v21.2.1 supported Python 3.6+.

## Features

Expand Down Expand Up @@ -223,45 +224,23 @@ The Autobahn|Python OSS project:

## Package Releases

Autobahn|Python provides comprehensive binary wheel coverage for all major platforms and Python implementations.
Autobahn|Python publishes source distributions and pre-built wheels on
[PyPI](https://pypi.org/project/autobahn/) and
[GitHub Releases](https://github.com/crossbario/autobahn-python/releases).
The current release line requires Python 3.11 or later and publishes
wheels for CPython 3.11 through 3.14 and PyPy 3.11 across supported
Linux, macOS, and Windows targets.

### Generic
The recommended installation method is:

- **Source distribution**: `autobahn-25.9.1.tar.gz`
- **Pure Python 3 wheel**: `autobahn-25.9.1-py3-none-any.whl`
```console
python -m pip install autobahn
```

> **Note**: The pure Python wheel cannot include NVX (Native Vector Extensions) optimizations and will fall back to pure Python implementations. This provides maximum compatibility but slower performance compared to platform-specific wheels with native CFFI extensions.

### Linux

Available for x86_64 architecture with native CFFI extensions:

- `autobahn-25.9.1-cp311-cp311-linux_x86_64.whl`
- `autobahn-25.9.1-cp312-cp312-linux_x86_64.whl`
- `autobahn-25.9.1-cp313-cp313-linux_x86_64.whl`
- `autobahn-25.9.1-cp314-cp314-linux_x86_64.whl`
- `autobahn-25.9.1-pp311-pypy311_pp73-linux_x86_64.whl`

### macOS

Available for Apple Silicon (ARM64) architecture:

- `autobahn-25.9.1-cp312-cp312-macosx_15_0_arm64.whl`
- `autobahn-25.9.1-cp313-cp313-macosx_15_0_arm64.whl`
- `autobahn-25.9.1-cp314-cp314-macosx_11_0_arm64.whl`
- `autobahn-25.9.1-pp311-pypy311_pp73-macosx_11_0_arm64.whl`

### Windows

Available for x86_64 (AMD64) architecture:

- `autobahn-25.9.1-cp311-cp311-win_amd64.whl`
- `autobahn-25.9.1-cp312-cp312-win_amd64.whl`
- `autobahn-25.9.1-cp313-cp313-win_amd64.whl`
- `autobahn-25.9.1-cp314-cp314-win_amd64.whl`
- `autobahn-25.9.1-pp311-pypy311_pp73-win_amd64.whl`

All wheels include native CFFI extensions for optimal performance and are available from [PyPI](https://pypi.org/project/autobahn/) and [GitHub Releases](https://github.com/crossbario/autobahn-python/releases).
Pip will choose the best matching wheel for your Python implementation,
operating system, and CPU architecture. See the
[wheels inventory](https://autobahn.readthedocs.io/en/latest/wheels-inventory.html)
for the supported wheel matrix and NVX acceleration notes.

## Extensions

Expand All @@ -270,9 +249,8 @@ All wheels include native CFFI extensions for optimal performance and are availa
Autobahn runs on both Twisted and asyncio. To select the
respective netoworking framework, install flavor:

- `asyncio`: Install asyncio (when on Python 2, otherwise it's
included in the standard library already) and asyncio support
in Autobahn
- `asyncio`: Backwards-compatible no-op. Asyncio is included in the
Python standard library for all supported Python versions.
- `twisted`: Install Twisted and Twisted support in Autobahn

---
Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This guide will help you get started with **Autobahn|Python** quickly.
Prerequisites
-------------

* Python 3.9 or later
* Python 3.11 or later
* pip (Python package installer)

Quick Installation
Expand Down
3 changes: 2 additions & 1 deletion docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ and provides open-source implementations of:
* `The WebSocket Protocol <https://tools.ietf.org/html/rfc6455>`__
* `The Web Application Messaging Protocol (WAMP) <https://wamp-proto.org/>`__

for Python 3.9+, running on `Twisted <https://twisted.org/>`__ and
for Python 3.11+, running on `Twisted <https://twisted.org/>`__ and
`asyncio <https://docs.python.org/3/library/asyncio.html>`__.

Contents
Expand All @@ -43,6 +43,7 @@ Contents

overview
installation
wheels-inventory
getting-started
programming-guide/index
release-notes
Expand Down
126 changes: 73 additions & 53 deletions docs/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,36 +11,48 @@ Requirements
* `Twisted`_
* `asyncio`_

You will need at least one of those.
|ab| requires Python 3.11 or later. You will need at least one of the
networking frameworks above.

.. 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+.
For Twisted installation, please see `here <http://twistedmatrix.com/>`__.
Asyncio is included in the Python standard library for all supported
Python versions.


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 |
+---------------+-----------+---------+---------------------------------+
.. list-table::
:header-rows: 1

* - Python
- Twisted
- asyncio
- Notes
* - CPython 3.11, 3.12, 3.13, and 3.14
- yes
- yes
- Pre-built wheels are published for supported platforms.
* - PyPy 3.11
- yes
- yes
- Pre-built wheels are published for supported platforms.


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)
|ab| is portable, well tuned code. For best performance, use the
pre-built wheels published on PyPI when one is available for your Python
version and platform. Platform-specific wheels may include native CFFI
and NVX acceleration; the source distribution remains available for
unsupported wheel combinations. See :doc:`wheels-inventory` for the full
wheel matrix.

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/>`_.

Expand All @@ -67,23 +79,28 @@ There are the flavors which are based on the official CPython and PyPy images, p
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>`_
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
python -m pip install --upgrade pip
python -m pip install autobahn

This is the recommended installation method. Pip will select a
pre-built wheel when one matches your Python implementation, Python
version, operating system, and CPU architecture. Current releases publish
wheels for CPython 3.11 through 3.14 and PyPy 3.11 across the supported
Linux, macOS, and Windows targets documented in :doc:`wheels-inventory`.

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
python -m pip install "autobahn[twisted]"

pip install autobahn[asyncio]
No extra is needed for asyncio because it is included in the Python
standard library.


Install from Sources
Expand All @@ -99,61 +116,64 @@ checkout a tagged release:

.. code-block:: sh

cd AutobahnPython
git checkout v0.9.1
cd autobahn-python
git checkout v25.12.2

.. 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)
Then install the checkout:

.. code-block:: sh

pip install -e .[twisted]
python -m 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>`_) |
+-------------------+--------------------------------------------------------------------------------------------------------+
.. list-table::
:header-rows: 1

* - Variant
- Description
* - ``twisted``
- Install Twisted as a dependency.
* - ``asyncio``
- Backwards-compatible no-op; asyncio is in the Python standard library.
* - ``accelerate``
- Backwards-compatible no-op; native acceleration is provided by Autobahn wheels where supported.
* - ``compress``
- Install packages for non-standard WebSocket compression methods.
* - ``encryption``
- Install TLS and WAMP encryption/authentication packages.
* - ``scram``
- Install WAMP-SCRAM authentication packages.
* - ``serialization``
- Backwards-compatible no-op; WAMP serializers are included by default.
* - ``nvx``
- Backwards-compatible no-op; NVX acceleration is included in binary wheels where supported.
* - ``all``
- Install all optional feature dependencies.

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]
python -m pip install "autobahn[twisted,compress,encryption,scram]"


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``
1. Go to the `Python web site <https://www.python.org/downloads/>`_ and install a supported 64-bit Python 3.11 or later release.
2. Ensure Python and ``Scripts`` are available on 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]``
4. Open a command shell and run ``python -m pip install "autobahn[twisted]"``.


Check the Installation
Expand All @@ -165,7 +185,7 @@ To check the installation, fire up the Python and run

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


Depending on Autobahn
Expand All @@ -175,13 +195,13 @@ To require |Ab| as a dependency of your package, include the following in your `

.. code-block:: python

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

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

.. code-block:: python

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

The latter will automatically install Twisted as a dependency.

Expand Down
2 changes: 1 addition & 1 deletion docs/overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ and provides open-source implementations of:
* `The WebSocket Protocol <https://tools.ietf.org/html/rfc6455>`__ (RFC 6455)
* `The Web Application Messaging Protocol (WAMP) <https://wamp-proto.org/>`__

for Python 3.9+, running on `Twisted <https://twisted.org/>`__ and
for Python 3.11+, running on `Twisted <https://twisted.org/>`__ and
`asyncio <https://docs.python.org/3/library/asyncio.html>`__.

What is WebSocket?
Expand Down