flask-sock

library0.7.0pypypi✓ verified 28d ago

Flask-Sock provides WebSocket support for Flask applications, enabling real-time, bi-directional communication. Unlike other solutions, it works directly with the Flask development web server and does not require a greenlet-based server like gevent or eventlet for basic operation. It is also compatible with production WSGI servers such as Gunicorn (with threading), Eventlet, or Gevent. The current version is 0.7.0, with a periodic release cadence.

web-framework http-networking

pip install flask-sock

github ↗package ↗

INSTALL

IMPORT

SIG · FLASK-SOCK

flask-sock

web-frameworkpythonv0.7.0

Install

2.4s avg

Import

683ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.7.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.692s · 23.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.4s · import 0.674s · 24MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Sock

✓ from flask_sock import Sock

Flask

✓ from flask import Flask

This quickstart sets up a basic Flask application with a WebSocket endpoint that echoes back any received message. Instantiate `Flask` and `Sock`, then use the `@sock.route()` decorator to define WebSocket handlers. The `ws` object within the handler provides `receive()` and `send()` methods for communication.

from flask import Flask from flask_sock import Sock import os app = Flask(__name__) sock = Sock(app) @app.route('/') def index(): return 'Hello, Flask-Sock!' @sock.route('/echo') def echo(ws): while True: data = ws.receive() if data is None: # Client disconnected break print(f"Received: {data}") ws.send(data) if __name__ == '__main__': # For development, Flask's built-in server works. # For production, use Gunicorn with --threads, Eventlet, or Gevent. app.run(debug=True)

Debug

Known issues

breakingVersion 0.4.0 of `flask-sock` and newer explicitly introduced a dependency on `Flask 2.x`. Applications using these versions must ensure they are running Flask 2.0.0 or higher, as older Flask versions are no longer supported.

fix

Upgrade your Flask installation to version 2.0.0 or higher (`pip install 'Flask>=2.0.0'`).

affects: >=0.4.0

gotchaWhen deploying `flask-sock` applications with Gunicorn, each active WebSocket connection consumes a worker process by default. To efficiently handle multiple concurrent WebSocket clients, Gunicorn must be configured to use threads (e.g., `gunicorn -b :5000 --threads 100 module:app`).

fix

Use the `--threads` option with Gunicorn to allow a single worker to handle multiple connections concurrently.

affects: All

gotchaAs of version 0.5.2, WebSocket server options, such as `ping_interval` and `max_message_size`, can be configured via `app.config['SOCK_SERVER_OPTIONS']`. Failing to set `ping_interval` (e.g., to 25 seconds) can lead to unexpected disconnections for idle WebSocket connections due to proxy timeouts.

fix

Configure `app.config['SOCK_SERVER_OPTIONS'] = {'ping_interval': 25}` in your Flask application to maintain active connections and prevent timeouts for idle clients.

affects: >=0.5.2

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'flask_sock'

The 'flask_sock' package is not installed in your Python environment or the environment where your application is running.

fix

Run `pip install flask-sock` to install the library.

ConnectionError

This generic error often occurs when the WebSocket client fails to establish a connection with the server, possibly due to the Flask development server's limitations with WebSockets, incorrect server configuration, or a client-side issue like a misconfigured WebSocket URL.

fix

Ensure your Flask application is running with a compatible WSGI server (like Gunicorn with threads, Eventlet, or Gevent for production) and that your client's WebSocket URL is correct. For development, ensure Flask and Werkzeug are updated to versions 2.0+ which offer better WebSocket support.

AttributeError: 'Sock' object has no attribute 'register_blueprint'

Flask-Sock does not directly support registering WebSocket routes on Flask Blueprints in the same manner as `flask-sockets` or standard Flask HTTP routes.

fix

Instead of `sock.register_blueprint()`, define `sock.route` decorators directly on the `Sock` object, or pass the blueprint instance to the `sock.route` decorator's `bp` argument.

Receive error -- socket is closed

This error occurs when your application attempts to read from or write to a WebSocket connection after the client has already disconnected or the socket has been explicitly closed.

fix

Implement proper error handling (e.g., try-except blocks) around `ws.receive()` and `ws.send()` calls to gracefully handle disconnections. Ensure any stored WebSocket objects are removed from active lists when a client disconnects.

Error during WebSocket handshake: Unexpected response code: 400

The client attempted to establish a WebSocket connection, but the server rejected it with an HTTP 400 Bad Request status, often due to cross-origin issues (CORS), an incorrect WebSocket protocol, or an improperly configured server.

fix

Check server-side logs for more specific error messages. If it's a CORS issue, configure `cors_allowed_origins` (if using Flask-SocketIO) or ensure your client's origin is permitted. Verify the client is using the correct WebSocket URL and protocol (e.g., `ws://` or `wss://`).

Upgrade

Version history

0.7.0latest on PyPI · released Oct 2, 2023

Audit

Dependencies

FlaskrequiredCore web framework dependency.

simple-websocketrequiredProvides the underlying WebSocket implementation.

pythonrequiredRequired Python version.

Agent activity

34 hits · last 30 days

node

Resources

githubhttps://github.com/miguelgrinberg/flask-sock ↗

packagehttps://pypi.org/project/flask-sock/ ↗