Metadata-Version: 2.4
Name: v2socks
Version: 1.0.0
Summary: A generic Python library to run V2Ray configurations as local SOCKS5 proxies.
Author-email: Hiddenioum <alex.brown.info.official@gmail.com>
License: MIT
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.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: Programming Language :: Python :: 3.14
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# v2socks

Convert V2Ray/Xray configurations (VLESS, VMess, Trojan, Reality) to local SOCKS5 proxies in Python.

[📚 English Documentation](https://hiddenioum.github.io/v2socks/) | [📚 مستندات فارسی](https://hiddenioum.github.io/v2socks/fa/)

---

## Installation

Install the package via pip:

```bash
pip install v2socks
```

---

## Quick Start

Run a local SOCKS5 proxy from a V2Ray config link and fetch your new IP location:

```python
import requests
from v2socks import V2Socks

# Start proxy on an auto-allocated free port (Xray core downloads automatically on first run)
with V2Socks("your-v2ray-config-link-here") as proxy:
    print(f"Proxy is running on local port: {proxy.port()}")
    
    # Use with requests
    proxies = {"http": proxy.socks_url, "https": proxy.socks_url}
    ip_info = requests.get("http://ip-api.com/json", proxies=proxies).json()
    print(f"Connected! Country: {ip_info.get('country')}")
```

---

## Features

- **Zero Configuration**: Automatically detects your platform (Windows, Linux, macOS) and downloads the stable Xray core on the first run.
- **Framework Agnostic**: Fully decoupled from any bot or client libraries. Exposes a standard SOCKS5 URL.
- **xHTTP Protocol Support**: Supports the latest V2Ray/Xray protocols including VLESS, VMess, Trojan, Reality, WebSocket, gRPC, and xHTTP.
- **Multiple Clients**: Run multiple client proxies simultaneously on different free ports.
- **Delay Testing**: Built-in latency testing using a raw TCP SOCKS5 handshake (in milliseconds).
- **Context Manager**: Pythonic `with` blocks ensure background processes are stopped and cleaned up cleanly on exit.

---

## Examples

### Running Multiple Proxies Simultaneously

```python
from v2socks import V2Socks

config_1 = "vless://..."
config_2 = "vmess://..."

# Start first proxy on automatic port, and second on custom port 10808
with V2Socks(config_1) as proxy1, V2Socks(config_2, port=10808) as proxy2:
    print(f"Proxy 1: socks5://127.0.0.1:{proxy1.port()}")
    print(f"Proxy 2: socks5://127.0.0.1:{proxy2.port()}")
```

### Custom Xray Path

Use your own pre-installed Xray executable globally instead of the auto-downloaded one:

```python
from v2socks import V2Socks

V2Socks.set_core_path("/usr/bin/xray")
```

---

## API Reference

### `V2Socks(config_link, port=None, verbose=False)`
- **`start()`**: Starts the background Xray client.
- **`stop()`**: Terminates the client and cleans up config files.
- **`port() -> int`**: Returns the active local SOCKS5 proxy port.
- **`is_alive() -> bool`**: Returns `True` if the client process is running.
- **`delay(target="https://www.google.com", timeout=5.0) -> float`**: Measures connection delay to the target URL in milliseconds.
- **`export_config() -> dict`**: Exports the generated Xray JSON configuration.
- **`host`** *(Property)*: Returns `"127.0.0.1"`.
- **`socks_url`** *(Property)*: Returns `"socks5://127.0.0.1:port"`.

### Class Methods
- **`V2Socks.set_core_path(path: str)`**: Set custom path to Xray core globally.
- **`V2Socks.is_active(port: int) -> bool`**: Check if there is an active client running on `port`.

### Module Functions
- **`check_updates() -> dict`**: Check for updates on GitHub. Returns a dictionary containing `has_update`, `latest_version`, and `local_version`.
- **`update_core(version=None)`**: Update local Xray core to the latest or a specific release version.

---

## Exceptions

All exceptions inherit from the base class `V2SocksError`:

- **`ParseError`**: Config link parsing failed or protocol is unsupported.
- **`CoreNotFoundError`**: Xray executable is missing or not executable.
- **`DownloadError`**: Xray download or extraction failed.
- **`ConnectionError`**: Connection to target or delay check failed.

---

## FAQ

#### Where is the Xray binary downloaded?
The binary is downloaded to `~/.v2socks/bin/` so it is shared across all Python projects and is not deleted when reinstalling the package.

#### Does it support Windows and macOS?
Yes, `v2socks` is fully cross-platform and supports Windows, Linux, and macOS (Intel & Apple Silicon).

---

## License

MIT
