Metadata-Version: 2.3
Name: websockets_proxy
Version: 0.1.3
Summary: Connect to websockets through a proxy server.
Project-URL: Homepage, https://github.com/racinette/websockets_proxy
Project-URL: Issues, https://github.com/racinette/websockets_proxy/issues
Author-email: Andrei Karavatski <verolomnyy@gmail.com>
Maintainer-email: Andrei Karavatski <verolomnyy@gmail.com>
License: MIT License
        
        Copyright (c) 2023 Andrei Karavatski
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: async,http,http proxy,https,socks4,socks5,websocket client,websocket proxy,websockets,websockets proxy,ws,wss
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: python-socks[asyncio]
Requires-Dist: websockets
Description-Content-Type: text/markdown

# websockets_proxy

This module will enable you to use [websockets](https://github.com/python-websockets/websockets) package with proxies.

Proxy heavy-lifting is done by [python-socks](https://github.com/romis2012/python-socks) package.

# Usage

To install, use:

```
pip install websockets_proxy
```

All you need is create a proxy object and pass it into `proxy_connect` constructor:

```python
from websockets_proxy import Proxy, proxy_connect


proxy = Proxy.from_url("...")
async with proxy_connect("wss://example.com", proxy=proxy) as ws:
    ...
```

`proxy_connect` constructor accepts the same arguments as regular `connect` constructor, 
with the addition of `proxy` and `proxy_conn_timeout`, which are self-explanatory.

> **With this patch you cannot use `sock` keyword argument, because it is used to connect to a proxy server.**

> **You must create your `Proxy` objects within a running event loop** (inside an `async` function). 
> This is a [python-socks](https://github.com/romis2012/python-socks) limitation. 
> If you define your `Proxy` objects outside of running event loop, you'll get this kind of error: `RuntimeError: Task <Task pending name=...> attached to a different loop`.

# WebSocket proxy checker

## Server
Here is a simple `aiohttp` server, which allows you to check, if your proxy connections work as expected:

```python
import asyncio

from aiohttp import web, WSMsgType, WSMessage


HOST = '0.0.0.0'
PORT = 9999

app = web.Application()


async def websocket_handler(request: web.Request) -> web.StreamResponse:
    ws = web.WebSocketResponse()
    await ws.prepare(request)
    await ws.send_str(str(request.remote))
    await ws.close()
    print('accepted connection from', request.remote)
    return ws


app.add_routes([
    web.get('/', websocket_handler)
])


async def main():
    runner = web.AppRunner(app)
    await runner.setup()
    site = web.TCPSite(runner, host=HOST, port=PORT)
    await site.start()
    print('server is running')
    await asyncio.Future()


if __name__ == '__main__':
    asyncio.run(main())
```


## Client
An example of a client-side proxy checker script:

```python
import asyncio

from websockets_proxy import Proxy, proxy_connect
from websockets import connect


# this script is written with the above checker server in mind
CHECKER_URL = 'ws://address:port'


async def main():
    async with connect(CHECKER_URL) as ws:
        async for msg in ws:
            ip_no_proxy = msg
            print("Your IP:", ip_no_proxy)
    print('.')
    # be sure to create your "Proxy" objects inside an async function
    proxy = Proxy.from_url("http://login:password@address:port")
    async with proxy_connect(CHECKER_URL, proxy=proxy) as ws:
        async for msg in ws:
            ip_with_proxy = msg
            print("(async with) Proxy IP", ip_with_proxy)
    print('.')

    ws = await proxy_connect(CHECKER_URL, proxy=proxy)
    async for msg in ws:
        ip_with_proxy = msg
        print("(await) Proxy IP", ip_with_proxy)
    await ws.close()
    print('.')


if __name__ == "__main__":
    asyncio.run(main())

```
