Metadata-Version: 2.4
Name: v2ray-finder
Version: 0.7.0
Summary: Search and collect V2Ray servers from GitHub repositories
Author-email: Ali Sadeghi Aghili <alisadeghiaghili@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/alisadeghiaghili/v2ray-finder
Project-URL: Repository, https://github.com/alisadeghiaghili/v2ray-finder
Project-URL: Issues, https://github.com/alisadeghiaghili/v2ray-finder/issues
Project-URL: Source Code, https://github.com/alisadeghiaghili/v2ray-finder
Keywords: v2ray,proxy,vpn,github,vmess,vless,trojan,shadowsocks,subscription
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
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: requests>=2.31.0
Provides-Extra: gui
Requires-Dist: PySide6>=6.4.0; extra == "gui"
Provides-Extra: cli-rich
Requires-Dist: rich>=13.7.0; extra == "cli-rich"
Provides-Extra: async
Requires-Dist: aiohttp>=3.8.0; extra == "async"
Requires-Dist: httpx>=0.24.0; extra == "async"
Provides-Extra: cache
Requires-Dist: diskcache>=5.6.0; extra == "cache"
Provides-Extra: all
Requires-Dist: PySide6>=6.4.0; extra == "all"
Requires-Dist: rich>=13.7.0; extra == "all"
Requires-Dist: aiohttp>=3.8.0; extra == "all"
Requires-Dist: httpx>=0.24.0; extra == "all"
Requires-Dist: diskcache>=5.6.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: aiohttp>=3.8.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Requires-Dist: diskcache>=5.6.0; extra == "dev"
Dynamic: license-file

# v2ray-finder

[![PyPI version](https://badge.fury.io/py/v2ray-finder.svg)](https://badge.fury.io/py/v2ray-finder)
[![Python Versions](https://img.shields.io/pypi/pyversions/v2ray-finder.svg)](https://pypi.org/project/v2ray-finder/)
[![Tests](https://github.com/alisadeghiaghili/v2ray-finder/workflows/Tests/badge.svg)](https://github.com/alisadeghiaghili/v2ray-finder/actions)
[![Code Quality](https://github.com/alisadeghiaghili/v2ray-finder/workflows/Code%20Quality/badge.svg)](https://github.com/alisadeghiaghili/v2ray-finder/actions)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![GitHub Stars](https://img.shields.io/github/stars/alisadeghiaghili/v2ray-finder?style=flat)](https://github.com/alisadeghiaghili/v2ray-finder/stargazers)

[فارسی](README.fa.md) | [English](README.en.md) | [Deutsch](README.de.md) | [📋 CHANGELOG](CHANGELOG.md)

---

A **high-performance** tool to **fetch, aggregate, validate and health-check public V2Ray server configs** from GitHub and curated subscription sources.

**Built with love for eternal freedom ❤️**

---

## 🗂️ Repository Structure

This is a **monorepo** containing two independent implementations of v2ray-finder:

| Directory | Language | Description |
|-----------|----------|-------------|
| *(root)* | 🐍 Python | Original Python implementation — PyPI package, CLI, GUI |
| [`dotnet/`](dotnet/) | ⚡ .NET / C# | .NET port — contributed by the community |

Each implementation is self-contained. You can use either one independently.

---

## 🐍 Python — Quick Start

```python
from v2ray_finder import Pipeline, StopController

pipeline = Pipeline(check_health=True)
result = pipeline.run()
for score in result.scores[:5]:
    print(score.grade, score.config[:80])
```

```bash
pip install v2ray-finder                # core
pip install "v2ray-finder[async]"       # + httpx for concurrent fetch
pip install "v2ray-finder[all]"         # everything
```

> **Full Python docs:** [README.en.md](README.en.md) | **فارسی:** [README.fa.md](README.fa.md) | **Changelog:** [CHANGELOG.md](CHANGELOG.md)

---

## ⚡ .NET — Quick Start

See [`dotnet/README.md`](dotnet/README.md) for installation and usage.

---

## 🚀 What's New in v0.7.0 (Python)

🛡️ **Structured error model** — `FetchResult.structured_error` with `category` / `kind` / `message` hierarchy (V1-D2)  
🔄 **xray Layer-3 port-contention retry** — auto-retry on a fresh OS port when xray fails to bind (V1-D4)  
🖥️ **GUI fully migrated to Pipeline** — Stop button, real progress bar, Score/Grade/Latency columns, Failed Sources panel (V1-A2)  

---

## 🧪 Test Coverage (Python)

~85% across Python 3.8–3.12, Linux, macOS & Windows.

---

## 📝 License

Apache License 2.0 © 2026 Ali Sadeghi Aghili

This project is licensed under the **Apache License 2.0**. Any derivative work,
port, or redistribution must retain the [`NOTICE`](NOTICE) file and credit the
original author. See [`LICENSE`](LICENSE) for full terms.
