Skip to content

Commit 1758898

Browse files
Update README.md
1 parent 851f308 commit 1758898

1 file changed

Lines changed: 7 additions & 47 deletions

File tree

README.md

Lines changed: 7 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,20 @@
33
[![PyPI Version](https://img.shields.io/pypi/v/python-v2ray.svg)](https://pypi.org/project/python-v2ray/)
44
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
55
[![Python Versions](https://img.shields.io/pypi/pyversions/python-v2ray.svg)](https://pypi.org/project/python-v2ray/)
6+
[![Documentation](https://img.shields.io/badge/docs-latest-teal.svg)](https://arshiacomplus.github.io/docs/python-v2ray/)
67

78
A powerful, high-level Python wrapper for managing and testing V2Ray/Xray-core and Hysteria clients.
89

910
This library abstracts the complexities of binary management, multi-format config parsing, and concurrent connection testing, providing a clean and streamlined API for developers.
1011

12+
**For full installation guides, core concepts, and the complete API reference, please visit our [full documentation site](https://arshiacomplus.github.io/docs/python-v2ray/).**
13+
1114
---
1215

1316
## ✨ Features
1417

1518
- **Automated Binary Management**: Automatically downloads and manages the necessary `Xray-core`, `Hysteria`, and test engine binaries for your platform (Windows, macOS, Linux).
16-
- **Unified Config Parser**: Seamlessly parses various subscription link formats (`vless`, `vmess`, `trojan`, `ss`, `hysteria2`) into a standardized Python object model.
19+
- **Unified Config Parser**: Seamlessly parses various subscription link formats (`vless`, `vmess`, `trojan`, `ss`, `hysteria2`, `mvless`) into a standardized Python object model.
1720
- **High-Speed Concurrent Testing**: Utilizes a hybrid architecture (Python + Go) to test dozens of configurations simultaneously, reporting latency and connection status in seconds.
1821
- **Dynamic Config Builder**: A fluent builder API to programmatically construct complex Xray JSON configurations with custom inbounds, outbounds, and routing rules.
1922
- **Live Statistics**: Connect to a running Xray-core instance's gRPC API to fetch live traffic statistics (uplink & downlink).
@@ -29,7 +32,8 @@ pip install python-v2ray
2932

3033
## ⚡️ Quick Start: Test a List of Proxies
3134

32-
This example demonstrates the core functionality: downloading dependencies, parsing URIs, and running a connection test.
35+
This example demonstrates the core functionality: downloading dependencies, parsing URIs, and running a connection test. For more advanced examples, please see our [full documentation](https://arshiacomplus.github.io/docs/python-v2ray/).
36+
3337

3438
```python
3539
from pathlib import Path
@@ -97,44 +101,6 @@ if __name__ == "__main__":
97101
run_tests()
98102
```
99103

100-
## 🏛 Architecture: The Best of Python & Go
101-
102-
`python-v2ray` employs a hybrid architecture for maximum efficiency:
103-
104-
- **Python Orchestrator**: The high-level logic, config management, binary downloading, and process orchestration are handled in Python for its readability and flexibility.
105-
- **Go Test Engine**: Performance-critical network operations, such as concurrent TCP/SOCKS dialing and latency tests, are delegated to a compiled Go binary (`core_engine`).
106-
107-
Communication between the two layers is achieved via IPC (`stdin`/`stdout`) with a simple JSON-based protocol. This design combines the development speed of Python with the raw network performance of Go.
108-
109-
## 🛠 Advanced Usage: Running a Single Proxy
110-
111-
```python
112-
from python_v2ray.core import XrayCore
113-
from python_v2ray.config_parser import parse_uri, XrayConfigBuilder
114-
115-
# Your target proxy URI
116-
uri = "vless://YOUR_UUID@your.domain.com:443?security=tls&sni=your.domain.com#MyProxy"
117-
118-
params = parse_uri(uri)
119-
if params:
120-
# Programmatically build a configuration
121-
builder = XrayConfigBuilder()
122-
builder.add_inbound({
123-
"port": 10808, "listen": "127.0.0.1", "protocol": "socks",
124-
"settings": {"auth": "noauth", "udp": True}
125-
})
126-
outbound = builder.build_outbound_from_params(params)
127-
builder.add_outbound(outbound)
128-
129-
# Run Xray with the generated config
130-
# The 'with' statement ensures the process is terminated automatically
131-
with XrayCore(config_builder=builder) as xray:
132-
print("Xray is running. SOCKS proxy is available on 127.0.0.1:10808")
133-
# Your application logic here...
134-
# ...
135-
print("Xray has been stopped.")
136-
```
137-
138104
## 🙏 Acknowledgments
139105

140106
This project would not be possible without the incredible work of the teams behind the core technologies it relies on. Special thanks to:
@@ -144,13 +110,7 @@ This project would not be possible without the incredible work of the teams behi
144110

145111
## 🤝 Contributing
146112

147-
Contributions are welcome! Please feel free to fork the repository, make changes, and submit a pull request.
148-
149-
1. Fork the Project
150-
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
151-
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
152-
4. Push to the Branch (`git push origin feature/AmazingFeature`)
153-
5. Open a Pull Request
113+
Contributions are welcome! Please see our [contribution guidelines](link/to/contributing.md) for more details.
154114

155115
## 📜 License
156116

0 commit comments

Comments
 (0)