1Websocket Server
2=======================
3
4[![CircleCI](https://circleci.com/gh/Pithikos/python-websocket-server/tree/master.svg?style=svg)](https://circleci.com/gh/Pithikos/python-websocket-server/tree/master)
5
6A minimal Websockets Server in Python with no external dependencies.
7
8  * Python2 and Python3 support
9  * Clean simple API
10  * Multiple clients
11  * No dependencies
12
13Notice that this implementation does not support the more advanced features
14like SSL etc. The project is focused mainly on making it easy to run a
15websocket server for prototyping, testing or for making a GUI for your application.
16
17
18Installation
19=======================
20
21You can use the project in three ways.
22
23  1. Copy/paste the *websocket_server.py* file in your project and use it directly
24  2. `pip install git+https://github.com/Pithikos/python-websocket-server` (latest code)
25  3. `pip install websocket-server` (might not be up-to-date)
26
27For coding details have a look at the [*server.py*](https://github.com/Pithikos/python-websocket-server/blob/master/server.py) example and the [API](https://github.com/Pithikos/python-websocket-server#api).
28
29
30Usage
31=======================
32You can get a feel of how to use the websocket server by running
33
34    python server.py
35
36Then just open `client.html` in your browser and you should be able to send and receive messages.
37
38
39Testing
40=======
41
42Run all tests
43
44    tox
45
46
47API
48=======================
49
50The API is simply methods and properties of the `WebsocketServer` class.
51
52## WebsocketServer
53
54The WebsocketServer can be initialized with the below parameters.
55
56*`port`* - The port clients will need to connect to.
57
58*`host`* - By default the `127.0.0.1` is used which allows connections only from the current machine. If you wish to allow all network machines to connect, you need to pass `0.0.0.0` as hostname.
59
60*`loglevel`* - logging level to print. By default WARNING is used. You can use `logging.DEBUG` or `logging.INFO` for more verbose output.
61
62
63### Properties
64
65| Property | Description          |
66|----------|----------------------|
67| clients  | A list of `client`   |
68
69
70### Methods
71
72| Method                      | Description                                                                           | Takes           | Gives |
73|-----------------------------|---------------------------------------------------------------------------------------|-----------------|-------|
74| `set_fn_new_client()`       | Sets a callback function that will be called for every new `client` connecting to us  | function        | None  |
75| `set_fn_client_left()`      | Sets a callback function that will be called for every `client` disconnecting from us | function        | None  |
76| `set_fn_message_received()` | Sets a callback function that will be called when a `client` sends a message          | function        | None  |
77| `send_message()`            | Sends a `message` to a specific `client`. The message is a simple string.             | client, message | None  |
78| `send_message_to_all()`     | Sends a `message` to **all** connected clients. The message is a simple string.       | message         | None  |
79
80
81### Callback functions
82
83| Set by                      | Description                                       | Parameters              |
84|-----------------------------|---------------------------------------------------|-------------------------|
85| `set_fn_new_client()`       | Called for every new `client` connecting to us    | client, server          |
86| `set_fn_client_left()`      | Called for every `client` disconnecting from us   | client, server          |
87| `set_fn_message_received()` | Called when a `client` sends a `message`          | client, server, message |
88
89
90The client passed to the callback is the client that left, sent the message, etc. The server might not have any use to use. However it is passed in case you want to send messages to clients.
91
92
93Example:
94````py
95import logging
96from websocket_server import WebsocketServer
97
98def new_client(client, server):
99	server.send_message_to_all("Hey all, a new client has joined us")
100
101server = WebsocketServer(13254, host='127.0.0.1', loglevel=logging.INFO)
102server.set_fn_new_client(new_client)
103server.run_forever()
104````
105
106## Client
107
108Client is just a dictionary passed along methods.
109
110```py
111{
112	'id'      : client_id,
113	'handler' : client_handler,
114	'address' : (addr, port)
115}
116```
117