---
description: base class for websocket operations
---

# Websocket

`wsgi.websocket` in WSGI environment dictionary

**In app this is the `client`**

```python
...
def on_message(message, client):
    # client is a websocket object
    ...
```

**In Middleware, Framework, Handler this is the `wsgi.websocket` in environment**

```python
...
@app.route("/")
def handle_websocket(environ, start_response):
    wsock = environ.get("wsgi.websocket")
    ...
```

```python
...
@bottle.route("/")
def handle_websocket():
    wsock = request.environ.get("wsgi.websocket")
    ...
```

### Class variables

* `origin` - HTTP `Origin` header
* `protocol` - supported websocket sub protocol
* `version` - websocket version(1, 8 or 7)
* `path` - required path by client(eg:-if websocket url which client opened is `ws://localhost/hello/world?user=Ksengine&pass=1234`, path is `/hello/world`)
* `logger` = default logger([Python Docs](https://docs.python.org/3/library/logging.html))
* `do_compress` - is compressed messages required by client

### Class methods

* `handle_close` - handle close messages from client. WSocket automatically handles this.
* `handle_ping` - handle ping(keep alive) messages from client. WSocket automatically handles this.
* `handle_pong` - handle pong messages from client.
* `receive` - receive one messages from client. handles `close` , `ping`, `pong` messages. returns
  * text messages - utf-8 strings
  *   binary messages - bytes

      raises `WebSocketError` if client closed. Returns `None` on any  error like `UnicodeError`  `ProtocolError` or `socket` error.
* `send` - Send a frame over the websocket with message as its payload. This method has following arguments.
  * `message` - binary(as `bytes`) or text(as unicode `str`) message.
  * `binary` - make this argument `True`, if message is `bytes`.
  * `do_compress` - Default value is `True`. set `False` to send not compressed message. To send compressed messages client should support it.
  * `close` - Close the websocket and connection, sending the specified code and message. The underlying socket object is _not_ closed, that is the responsibility of the initiator.This method has two arguments.
    * `code` - Should be a valid websocket close code. Default is `1000` .
    * `message` - reson for closing websocket connection as `str`.

### Change methods

create websocket class inherited child class. **for Framework and App only**

```python
...
from wsocket import Websocket, ProtocolError
import struct
class new_class(Websocket):
    def handle_close(self, payload):
        if not payload:
            self.close(1000, "")
            return

        if len(payload) < 2:
            raise ProtocolError("Invalid close frame: %s" % payload)

        code = struct.unpack("!H", payload[:2])[0]
        payload = payload[2:]
        if payload:
            payload.decode("utf-8")

        if not self._is_valid_close_code(code):
            raise ProtocolError("Invalid close code %s" % code)

        self.close(code, payload)

    def handle_ping(self, payload):
        self.send_frame(payload, self.OPCODE_PONG)

    def handle_pong(self, payload):
        pass

WSocketApp.websocket_class = new_class
...
```
