diff --git a/README.md b/README.md deleted file mode 100644 index 88331bdc..00000000 --- a/README.md +++ /dev/null @@ -1,120 +0,0 @@ -# Autobahn|Python - -[![Version](https://img.shields.io/pypi/v/autobahn.svg)](https://pypi.python.org/pypi/autobahn) -[![Downloads](https://img.shields.io/pypi/dm/autobahn.svg)](https://pypi.python.org/pypi/autobahn) -[![GitHub Stars](https://img.shields.io/github/stars/tavendo/AutobahnPython.svg?style=social&label=Star)](https://github.com/tavendo/AutobahnPython) -[![Build Status](https://travis-ci.org/tavendo/AutobahnPython.svg?branch=master)](https://travis-ci.org/tavendo/AutobahnPython) -[![Coverage](https://img.shields.io/codecov/c/github/tavendo/AutobahnPython/master.svg)](https://codecov.io/github/tavendo/AutobahnPython) - -**Quick Links**: [Source Code](https://github.com/tavendo/AutobahnPython) - [Docs](http://autobahn.ws/python) - [WebSocket Examples](http://autobahn.ws/python/websocket/examples.html) - [WAMP Examples](http://autobahn.ws/python/wamp/examples.html) - **[Crossbar.io](http://crossbar.io)** - -**Community**: [Mailing list](http://groups.google.com/group/autobahnws) - [StackOverflow](http://stackoverflow.com/questions/tagged/autobahn) - [Twitter](https://twitter.com/autobahnws) - [IRC #autobahn/chat.freenode.net](https://webchat.freenode.net/) - ---- - -## Introduction - -**Autobahn|Python** is a subproject of [Autobahn](http://autobahn.ws/) 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 running on [**Twisted**](http://twistedmatrix.com/) and [**asyncio**](http://docs.python.org/3.4/library/asyncio.html). - -You can use **Autobahn|Python** to create clients and servers in Python speaking just plain WebSocket or WAMP. - -**WebSocket** allows [bidirectional real-time messaging on the Web](http://tavendo.com/blog/post/websocket-why-what-can-i-use-it/) and [WAMP](http://wamp.ws/) adds real-time application messaging abstractions on top of WebSocket. - -**WAMP** provides asynchronous **Remote Procedure Calls** and **Publish & Subscribe** for applications in *one* protocol running over [WebSocket](http://tools.ietf.org/html/rfc6455). WAMP is a *routed* protocol, so you need a **WAMP Router** to connect your **Autobahn|Python** based clients. We provide [Crossbar.io](http://crossbar.io), but there are [other options](http://wamp.ws/implementations/#routers) as well. - -## Features - -* framework for [WebSocket](http://tools.ietf.org/html/rfc6455) and [WAMP](http://wamp.ws/) clients and servers -* compatible with Python 2.6, 2.7, 3.3 and 3.4 -* runs on [CPython](http://python.org/), [PyPy](http://pypy.org/) and [Jython](http://jython.org/) -* runs under [Twisted](http://twistedmatrix.com/) and [asyncio](http://docs.python.org/3.4/library/asyncio.html) -* implements WebSocket [RFC6455](http://tools.ietf.org/html/rfc6455), Draft Hybi-10+, Hixie-76 -* implements [WebSocket compression](http://tools.ietf.org/html/draft-ietf-hybi-permessage-compression) -* implements [WAMP](http://wamp.ws/), the Web Application Messaging Protocol -* high-performance, fully asynchronous implementation -* best-in-class standards conformance (100% strict passes with [Autobahn Testsuite](http://autobahn.ws/testsuite)) -* message-, frame- and streaming-APIs for WebSocket -* supports TLS (secure WebSocket) and proxies -* Open-source ([MIT license](https://github.com/tavendo/AutobahnPython/blob/master/LICENSE)) - -## Show me some code - -To give you a first impression, here are two examples. We have lot more [in the repo](https://github.com/tavendo/AutobahnPython/tree/master/examples). - -### WebSocket Echo Server - -Here is a simple WebSocket Echo Server that will echo back any WebSocket message received: - -```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)) -``` - -To actually run above server protocol, you need some lines of [boilerplate](http://autobahn.ws/python/websocket/programming.html#running-a-server). - -### WAMP Application Component - -Here is a WAMP Application Component that performs all four types of actions that WAMP provides: - -1. **subscribe** to a topic -2. **publish** an event -3. **register** a procedure -4. **call** a procedure - -```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 so we receive events - def onevent(msg): - print("Got event: {}".format(msg)) - - yield self.subscribe(onevent, 'com.myapp.hello') - - # 2. publish an event to a topic - self.publish('com.myapp.hello', 'Hello, world!') - - # 3. register a procedure for remote calling - 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)) -``` - -Above code will work on Twisted and asyncio by changing a single line (the base class of `MyComponent`)! - -To actually run above application component, you need some lines of [boilerplate](http://autobahn.ws/python/wamp/programming.html#running-components) and a [WAMP Router](http://crossbar.io). diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..bda88b85 --- /dev/null +++ b/README.rst @@ -0,0 +1,145 @@ +Autobahn\|Python +================ + +WebSocket & WAMP for Python on Twisted and asyncio. + +| |Version| |Downloads| |GitHub Stars| + +-------------- + +| **Quick Links**: `Source Code `__ - `Docs `__ - `WebSocket Examples `__ - `WAMP Examples `__ - `Crossbar.io `__ +| **Community**: `Mailing list `__ - `StackOverflow `__ - `Twitter `__ - `IRC #autobahn/chat.freenode.net `__ +| +| |Master Branch| |Build Status| |Coverage| + +Introduction +------------ + +**Autobahn\|Python** is a subproject of `Autobahn `__ and provides open-source +implementations of + +- `The WebSocket Protocol `__ +- `The Web Application Messaging Protocol (WAMP) `__ + +for Python 2 and 3, and running on `Twisted `__ and `asyncio `__. + +You can use **Autobahn\|Python** to create clients and servers in Python speaking just plain WebSocket or WAMP. + +**WebSocket** allows `bidirectional real-time messaging on the Web `__ and beyond, while `WAMP `__ adds real-time application communication on top of WebSocket. + +**WAMP** provides asynchronous **Remote Procedure Calls** and **Publish & Subscribe** for applications in *one* protocol running over `WebSocket `__. WAMP is a *routed* protocol, so you need a **WAMP Router** to connect your **Autobahn\|Python** based clients. We provide `Crossbar.io `__, but there are `other options `__ as well. + +Features +-------- + +- framework for `WebSocket `__ and `WAMP `__ clients and servers +- compatible with Python 2.6, 2.7, 3.3 and 3.4 +- runs on `CPython `__, `PyPy `__ and `Jython `__ +- runs under `Twisted `__ and `asyncio `__ - implements WebSocket + `RFC6455 `__, Draft Hybi-10+, Hixie-76 +- implements `WebSocket compression `__ +- implements `WAMP `__, the Web Application Messaging Protocol +- high-performance, fully asynchronous implementation +- best-in-class standards conformance (100% strict passes with `Autobahn Testsuite `__) +- message-, frame- and streaming-APIs for WebSocket +- supports TLS (secure WebSocket) and proxies +- Open-source (`MIT license `__) + +Show me some code +----------------- + +To give you a first impression, here are two examples. We have lot more `in the repo `__. + +WebSocket Echo Server +~~~~~~~~~~~~~~~~~~~~~ + +Here is a simple WebSocket Echo Server that will echo back any WebSocket +message received: + +.. code:: 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)) + +To actually run above server protocol, you need some lines of `boilerplate `__. + +WAMP Application Component +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here is a WAMP Application Component that performs all four types of +actions that WAMP provides: + +#. **subscribe** to a topic +#. **publish** an event +#. **register** a procedure +#. **call** a procedure + +.. code:: 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 so we receive events + def onevent(msg): + print("Got event: {}".format(msg)) + + yield self.subscribe(onevent, 'com.myapp.hello') + + # 2. publish an event to a topic + self.publish('com.myapp.hello', 'Hello, world!') + + # 3. register a procedure for remote calling + 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)) + +Above code will work on Twisted and asyncio by changing a single line +(the base class of ``MyComponent``). To actually run above application component, you need some lines of `boilerplate `__ and a `WAMP Router `__. + +.. |Version| image:: https://img.shields.io/pypi/v/autobahn.svg + :target: https://pypi.python.org/pypi/autobahn + +.. |Downloads| image:: https://img.shields.io/pypi/dm/autobahn.svg + :target: https://pypi.python.org/pypi/autobahn + +.. |GitHub Stars| image:: https://img.shields.io/github/stars/tavendo/AutobahnPython.svg?style=social&label=Star + :target: https://github.com/tavendo/AutobahnPython + +.. |Master Branch| image:: https://img.shields.io/badge/branch-master-orange.svg + :target: https://travis-ci.org/tavendo/AutobahnPython.svg?branch=master + +.. |Build Status| image:: https://travis-ci.org/tavendo/AutobahnPython.svg?branch=master + :target: https://travis-ci.org/tavendo/AutobahnPython + +.. |Coverage| image:: https://img.shields.io/codecov/c/github/tavendo/AutobahnPython/master.svg + :target: https://codecov.io/github/tavendo/AutobahnPython diff --git a/setup.py b/setup.py index fef55098..c48b7119 100644 --- a/setup.py +++ b/setup.py @@ -43,29 +43,6 @@ CPY = platform.python_implementation() == 'CPython' PY3 = sys.version_info >= (3,) PY33 = (3, 3) <= sys.version_info < (3, 4) -LONGSDESC = """ -.. |ab| replace:: **Autobahn**\|Python - -|ab| is a networking library that is part of the `Autobahn `__ -project and provides implementations of - -* `The WebSocket Protocol `__ -* `The Web Application Messaging Protocol (WAMP) `__ - -for `Twisted `__ and -`asyncio `__, -on Python 2 & 3 and for writing servers and clients. - -WebSocket allows bidirectional real-time messaging on the Web and WAMP -adds asynchronous *Remote Procedure Calls* and *Publish & Subscribe* on -top of WebSocket. - -More information: - -* `Project Site `__ -* `Source Code `__ -""" - LONGSDESC = open('README.rst').read() # get version string from "autobahn/__init__.py"