You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
odrling 56445429e0
4 years ago
.circleci Get a clean, non-strict mypy run. 4 years ago
compliance Update compliance testing scripts for Python 3.6. 4 years ago
docs The official name is lowercase. 4 years ago
example Take advantage of loop.create_future(). 4 years ago
logo Fine-tune logo. 4 years ago
performance Take advantage of loop.create_future(). 4 years ago
src/websockets7 frankensteinization 4 years ago
tests Normalize quotes in a # fmt: off section. 4 years ago
.appveyor.yml Drop support for Python 3.5. 4 years ago
.gitignore Get a clean, non-strict mypy run. 4 years ago
.readthedocs.yml Indicate which functions are coroutines. 4 years ago
.travis.yml Drop support for Python 3.5. 4 years ago Add code of conduct. 5 years ago
LICENSE Better two months early than ten months late. 4 years ago Improve project layout. 5 years ago
Makefile Small cleanup. 4 years ago
README.rst Fine-tune logo. 4 years ago
setup.cfg Drop support for Python 3.5. 4 years ago frankensteinization 4 years ago
tox.ini Lock mypy version. 4 years ago


.. image:: logo/horizontal.svg
   :width: 480px
   :alt: websockets

|rtd| |pypi-v| |pypi-pyversions| |pypi-l| |pypi-wheel| |circleci| |codecov|

.. |rtd| image::

.. |pypi-v| image::

.. |pypi-pyversions| image::

.. |pypi-l| image::

.. |pypi-wheel| image::

.. |circleci| image::

.. |codecov| image::

What is ``websockets``?

``websockets`` is a library for building WebSocket servers_ and clients_ in
Python with a focus on correctness and simplicity.

.. _servers:
.. _clients:

Built on top of ``asyncio``, Python's standard asynchronous I/O framework, it
provides an elegant coroutine-based API.

Here's how a client sends and receives messages:

.. copy-pasted because GitHub doesn't support the include directive

.. code:: python

    #!/usr/bin/env python

    import asyncio
    import websockets

    async def hello(uri):
        async with websockets.connect(uri) as websocket:
            await websocket.send("Hello world!")
            await websocket.recv()


And here's an echo server:

.. code:: python

    #!/usr/bin/env python

    import asyncio
    import websockets

    async def echo(websocket, path):
        async for message in websocket:
            await websocket.send(message)

        websockets.serve(echo, 'localhost', 8765))

Does that look good?

`Start here!`_

.. _Start here!:

Why should I use ``websockets``?

The development of ``websockets`` is shaped by four principles:

1. **Simplicity**: all you need to understand is ``msg = await ws.recv()`` and
   ``await ws.send(msg)``; ``websockets`` takes care of managing connections
   so you can focus on your application.

2. **Robustness**: ``websockets`` is built for production; for example it was
   the only library to `handle backpressure correctly`_ before the issue
   became widely known in the Python community.

3. **Quality**: ``websockets`` is heavily tested. Continuous integration fails
   under 100% branch coverage. Also it passes the industry-standard `Autobahn

4. **Performance**: memory use is configurable. An extension written in C
   accelerates expensive operations. It's pre-compiled for Linux, macOS and
   Windows and packaged in the wheel format for each system and Python version.

Documentation is a first class concern in the project. Head over to `Read the
Docs`_ and see for yourself.

Professional support is available if you — or your company — are so inclined.
`Get in touch`_.

(If you contribute to ``websockets`` and would like to become an official
support provider, let me know.)

.. _Read the Docs:
.. _handle backpressure correctly:
.. _Autobahn Testsuite:
.. _Get in touch:

Why shouldn't I use ``websockets``?

* If you prefer callbacks over coroutines: ``websockets`` was created to
  provide the best coroutine-based API to manage WebSocket connections in
  Python. Pick another library for a callback-based API.
* If you're looking for a mixed HTTP / WebSocket library: ``websockets`` aims
  at being an excellent implementation of :rfc:`6455`: The WebSocket Protocol
  and :rfc:`7692`: Compression Extensions for WebSocket. Its support for HTTP
  is minimal — just enough for a HTTP health check.
* If you want to use Python 2: ``websockets`` builds upon ``asyncio`` which
  only works on Python 3. ``websockets`` requires Python ≥ 3.6.

What else?

Bug reports, patches and suggestions are welcome!

Please open an issue_ or send a `pull request`_.

.. _issue:
.. _pull request:

Participants must uphold the `Contributor Covenant code of conduct`_.

.. _Contributor Covenant code of conduct:

``websockets`` is released under the `BSD license`_.

.. _BSD license: