Metadata-Version: 2.4
Name: socks5-killswitch
Version: 0.0.1
Summary: SOCKS5 proxy session with kill switch — if the proxy drops, your real IP is never exposed.
Project-URL: Homepage, https://github.com/mykola/socks5-killswitch
Project-URL: Issues, https://github.com/mykola/socks5-killswitch/issues
Author: Mykola
License-Expression: MIT
License-File: LICENSE
Keywords: killswitch,privacy,proxy,requests,socks5
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: pysocks<2,>=1.7.1
Requires-Dist: requests<3,>=2.28
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-cov<7,>=4; extra == 'dev'
Requires-Dist: pytest<9,>=7; extra == 'dev'
Requires-Dist: responses<1,>=0.23; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: types-requests>=2.28; extra == 'dev'
Description-Content-Type: text/markdown

# socks5-killswitch

SOCKS5 proxy session for Python with **kill switch** — if the proxy drops, your real IP is never exposed.

Built on top of `requests.Session`. If any request fails, the session permanently blocks all further requests instead of falling back to a direct connection.

## Install

```bash
pip install socks5-killswitch
```

## Quick start

```python
from socks5_killswitch import create_session, ProxyError

session = create_session(
    host="proxy.example.com",
    port=1080,
    username="your-socks5-user",
    password="your-socks5-pass",
)

# All requests go through the proxy
resp = session.get("https://example.com")

# Periodic leak check — verifies visible IP != real IP
session.check_ip()

# If proxy fails — ProxyError is raised, all further requests blocked
```

## How the kill switch works

1. **On `create_session()`** — detects your real IP, verifies the proxy gives a different one.
2. **On any request failure** — instantly blocks ALL further requests (no fallback to direct).
3. **`check_ip()`** — manual/periodic check that visible IP != real IP.

## API

### `create_session(host, port, username, password, timeout=15, ip_check_url=...)`

Factory that returns a verified `SafeSession`. Raises `ProxyError` if the proxy is unreachable or the IP leaks.

### `SafeSession`

Extends `requests.Session`. Every request goes through the SOCKS5 proxy. On failure, the kill switch activates and all subsequent calls raise `ProxyError`.

- `check_ip() -> str` — verify the session is behind the proxy. Returns the visible IP.
- `_killed: bool` — kill switch state (read-only in practice).

### `ProxyError`

Raised when the proxy fails or an IP leak is detected.

## Notes

- Uses `socks5://` (not `socks5h://`) — DNS is resolved locally.
- Supports binary POST data (e.g. AMF2 payloads).
- Pure library — no `.env`, no config files. All parameters are passed explicitly.

## License

MIT
