websockets-proxy

What it is and what it does

websockets_proxy adds proxy support to the websockets package, allowing you to establish WebSocket connections through HTTP and SOCKS proxies. It wraps the standard websockets connect function with a proxy-aware alternative, delegating proxy handling to python-socks. The package is designed for async/await code and requires creating Proxy objects within an active event loop.

The main use case is routing WebSocket traffic through corporate proxies, anonymization proxies, or other intermediaries. It accepts the same arguments as the standard websockets connect constructor, with added proxy and proxy_conn_timeout parameters. The tradeoff is that you cannot use the sock keyword argument directly, since it is reserved for proxy connection.

Use it for:

• Route WebSocket connections through corporate HTTP or SOCKS proxies in enterprise environments.
• Test WebSocket applications against proxy servers to verify proxy compatibility and behavior.
• Build async clients that need to tunnel WebSocket traffic through intermediary proxies for privacy or network segmentation.
• Connect to WebSocket APIs from behind restrictive network firewalls that require proxy routing.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Enables WebSocket connections through HTTP and SOCKS proxies by wrapping the websockets package with proxy support via python-socks.

Yes, if you need WebSocket proxy support in an async application. Install friction is low, the license is permissive, and there are no known vulnerabilities. The main caveat is dormancy—643 days without a release—so verify compatibility with your versions of websockets and python-socks before committing. The blocker (Proxy creation inside event loops) is a real constraint but documented and manageable.

Install

websockets-proxy on PyPI

pip install websockets-proxy

uv add websockets-proxy

poetry add websockets-proxy

Installing websockets-proxy

Before you install

Low install friction with only two runtime dependencies (websockets and python-socks). Maintenance is dormant—last commit was 2024-11-09 and no releases in 643 days—but the package is marked Production/Stable and the repository remains active.

License in practice

MIT License permits free use, modification, and distribution with minimal restrictions, making it suitable for both open-source and commercial projects.

Quickstart

pip install websockets_proxy

from websockets_proxy import Proxy, proxy_connect

proxy = Proxy.from_url("http://user:pass@proxy:port")
async with proxy_connect("wss://example.com", proxy=proxy) as ws:
    msg = await ws.recv()

Proxy objects must be created inside a running event loop (within an async function); creating them outside will raise RuntimeError about task attachment to a different loop.

Verify before relying

• Whether dormancy (643 days since last release) affects compatibility with recent websockets or python-socks versions.
• Performance characteristics when routing through various proxy types (HTTP vs SOCKS4 vs SOCKS5).
• Whether the sock keyword argument restriction impacts real-world use cases.

Package facts

Evidence: websockets_proxy-0.1.3-py3-none-any.whl

Keywords: async, http, http proxy, https, socks4, socks5, websocket client, websocket proxy, websockets, websockets proxy, ws, wss

Tags

More Libraries packages