v2kit 0.1__tar.gz → 0.2__tar.gz

v2kit-0.2/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+## [0.2] - 2026-06-04
+### Added
+- `VMESSConfig` class
+- `VLESSConfig` class
+- `TrojanConfig` class
+- `ShadowsocksConfig` class
+- `V2kitError` class
+- `V2kitValidationError` class
+- `V2kitParseError` class
+- `parse` function
+### Changed
+- `README.md` updated
+- Test system modified
+- `is_vmess` function `config` parameter renamed to `uri`
+- `is_vless` function `config` parameter renamed to `uri`
+- `is_trojan` function `config` parameter renamed to `uri`
+- `is_shadowsocks` function `config` parameter renamed to `uri`
+- `encode_subscription` function `configs` parameter renamed to `entries`
+## [0.1] - 2026-05-16
+### Added
+- `is_vmess` function
+- `is_vless` function
+- `is_trojan` function
+- `is_shadowsocks` function
+- `relabel` function
+- `encode_subscription` function
+- `decode_subscription` function
+
+[Unreleased]: https://github.com/sepandhaghighi/v2kit/compare/v0.2...dev
+[0.2]: https://github.com/sepandhaghighi/v2kit/compare/v0.1...v0.2
+[0.1]: https://github.com/sepandhaghighi/v2kit/compare/bb5a2cb...v0.1
+
+
+

{v2kit-0.1 → v2kit-0.2}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: v2kit
-Version: 0.1
+Version: 0.2
 Summary: V2Kit: A Lightweight Toolkit for V2Ray Config Manipulation
 Home-page: https://github.com/sepandhaghighi/v2kit
-Download-URL: https://github.com/sepandhaghighi/v2kit/tarball/v0.1
+Download-URL: https://github.com/sepandhaghighi/v2kit/tarball/v0.2
 Author: Sepand Haghighi
 Author-email: me@sepand.tech
 License: MIT
@@ -49,6 +49,7 @@ Dynamic: summary
 <a href="https://www.python.org/"><img src="https://img.shields.io/badge/built%20with-Python3-green.svg" alt="built with Python3"></a>
 <a href="https://github.com/sepandhaghighi/v2kit"><img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/sepandhaghighi/v2kit"></a>
 <a href="https://badge.fury.io/py/v2kit"><img src="https://badge.fury.io/py/v2kit.svg" alt="PyPI version"></a>
+<a href="https://codecov.io/gh/sepandhaghighi/v2kit"><img src="https://codecov.io/gh/sepandhaghighi/v2kit/graph/badge.svg?token=ytuuYF0NmT"></a>
 </div>			
 				
 ## Overview	
@@ -83,38 +84,79 @@ V2Kit is a lightweight and extensible Python toolkit for working with V2Ray prox
 	</tr>
 </table>
 
+<table>
+    <tr> 
+        <td align="center">Code Quality</td>
+        <td align="center"><a href="https://app.codacy.com/gh/sepandhaghighi/v2kit/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img src="https://app.codacy.com/project/badge/Grade/c0b30b55e04740b2894fe1aa4eef6589"></a></td>
+        <td align="center"><a href="https://www.codefactor.io/repository/github/sepandhaghighi/v2kit"><img src="https://www.codefactor.io/repository/github/sepandhaghighi/v2kit/badge" alt="CodeFactor"></a></td>
+    </tr>
+</table>
+
 ## Installation		
 
 ### Source Code
-- Download [Version 0.1](https://github.com/sepandhaghighi/v2kit/archive/v0.1.zip) or [Latest Source](https://github.com/sepandhaghighi/v2kit/archive/dev.zip)
+- Download [Version 0.2](https://github.com/sepandhaghighi/v2kit/archive/v0.2.zip) or [Latest Source](https://github.com/sepandhaghighi/v2kit/archive/dev.zip)
 - `pip install .`				
 
 ### PyPI
 
 - Check [Python Packaging User Guide](https://packaging.python.org/installing/)     
-- `pip install v2kit==0.1`						
+- `pip install v2kit==0.2`						
+
+## Supported Protocols
+
+V2Kit currently supports the following protocols:
+
+| Protocol    | Detection  | Parsing  | Relabeling  | Config Model |
+| ----------- | ---------  | -------  | ----------  | ------------ |
+| VMESS       | ✅         | ✅       | ✅          | ✅           |
+| VLESS       | ✅         | ✅       | ✅          | ✅           |
+| Trojan      | ✅         | ✅       | ✅          | ✅           |
+| Shadowsocks | ✅         | ✅       | ✅          | ✅           |
 
 
 ## Usage
 
+### URI Utilities
+
 ```python
 from v2kit import (
     decode_subscription,
     encode_subscription,
     is_vmess,
+    parse,
     relabel,
 )
 
-config = "vmess://eyJhZGQiOiIxMjcuMC4wLjEiLCJwcyI6Im9sZCJ9"
+uri = "vmess://eyJhZGQiOiIxMjcuMC4wLjEiLCJwcyI6Im9sZCJ9"
+
+new_uri = relabel(uri, "Germany-1")
+
+if is_vmess(new_uri):
+    print("VMESS URI detected")
 
-new_config = relabel(config, "Germany-1")
+config = parse(new_uri)
 
-if is_vmess(new_config):
-    print("VMESS config detected")
+config.update_label("Germany-2")
 
-subscription = encode_subscription([new_config])
+subscription = encode_subscription([config])
 
-configs = decode_subscription(subscription)
+uris = decode_subscription(subscription)
+```
+
+### Configs
+
+```python
+from v2kit import VMESSConfig
+
+config = VMESSConfig(
+    uuid="550e8400-e29b-41d4-a716-446655440000",
+    address="example.com",
+    port=443,
+    label="Germany-1",
+)
+
+uri = config.to_uri()
 ```
 
 ## Issues & Bug Reports			
@@ -166,6 +208,24 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+## [0.2] - 2026-06-04
+### Added
+- `VMESSConfig` class
+- `VLESSConfig` class
+- `TrojanConfig` class
+- `ShadowsocksConfig` class
+- `V2kitError` class
+- `V2kitValidationError` class
+- `V2kitParseError` class
+- `parse` function
+### Changed
+- `README.md` updated
+- Test system modified
+- `is_vmess` function `config` parameter renamed to `uri`
+- `is_vless` function `config` parameter renamed to `uri`
+- `is_trojan` function `config` parameter renamed to `uri`
+- `is_shadowsocks` function `config` parameter renamed to `uri`
+- `encode_subscription` function `configs` parameter renamed to `entries`
 ## [0.1] - 2026-05-16
 ### Added
 - `is_vmess` function
@@ -176,7 +236,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - `encode_subscription` function
 - `decode_subscription` function
 
-[Unreleased]: https://github.com/sepandhaghighi/v2kit/compare/v0.1...dev
+[Unreleased]: https://github.com/sepandhaghighi/v2kit/compare/v0.2...dev
+[0.2]: https://github.com/sepandhaghighi/v2kit/compare/v0.1...v0.2
 [0.1]: https://github.com/sepandhaghighi/v2kit/compare/bb5a2cb...v0.1
 
 

{v2kit-0.1 → v2kit-0.2}/README.md

@@ -4,6 +4,7 @@
 <a href="https://www.python.org/"><img src="https://img.shields.io/badge/built%20with-Python3-green.svg" alt="built with Python3"></a>
 <a href="https://github.com/sepandhaghighi/v2kit"><img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/sepandhaghighi/v2kit"></a>
 <a href="https://badge.fury.io/py/v2kit"><img src="https://badge.fury.io/py/v2kit.svg" alt="PyPI version"></a>
+<a href="https://codecov.io/gh/sepandhaghighi/v2kit"><img src="https://codecov.io/gh/sepandhaghighi/v2kit/graph/badge.svg?token=ytuuYF0NmT"></a>
 </div>			
 				
 ## Overview	
@@ -38,38 +39,79 @@ V2Kit is a lightweight and extensible Python toolkit for working with V2Ray prox
 	</tr>
 </table>
 
+<table>
+    <tr> 
+        <td align="center">Code Quality</td>
+        <td align="center"><a href="https://app.codacy.com/gh/sepandhaghighi/v2kit/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img src="https://app.codacy.com/project/badge/Grade/c0b30b55e04740b2894fe1aa4eef6589"></a></td>
+        <td align="center"><a href="https://www.codefactor.io/repository/github/sepandhaghighi/v2kit"><img src="https://www.codefactor.io/repository/github/sepandhaghighi/v2kit/badge" alt="CodeFactor"></a></td>
+    </tr>
+</table>
+
 ## Installation		
 
 ### Source Code
-- Download [Version 0.1](https://github.com/sepandhaghighi/v2kit/archive/v0.1.zip) or [Latest Source](https://github.com/sepandhaghighi/v2kit/archive/dev.zip)
+- Download [Version 0.2](https://github.com/sepandhaghighi/v2kit/archive/v0.2.zip) or [Latest Source](https://github.com/sepandhaghighi/v2kit/archive/dev.zip)
 - `pip install .`				
 
 ### PyPI
 
 - Check [Python Packaging User Guide](https://packaging.python.org/installing/)     
-- `pip install v2kit==0.1`						
+- `pip install v2kit==0.2`						
+
+## Supported Protocols
+
+V2Kit currently supports the following protocols:
+
+| Protocol    | Detection  | Parsing  | Relabeling  | Config Model |
+| ----------- | ---------  | -------  | ----------  | ------------ |
+| VMESS       | ✅         | ✅       | ✅          | ✅           |
+| VLESS       | ✅         | ✅       | ✅          | ✅           |
+| Trojan      | ✅         | ✅       | ✅          | ✅           |
+| Shadowsocks | ✅         | ✅       | ✅          | ✅           |
 
 
 ## Usage
 
+### URI Utilities
+
 ```python
 from v2kit import (
     decode_subscription,
     encode_subscription,
     is_vmess,
+    parse,
     relabel,
 )
 
-config = "vmess://eyJhZGQiOiIxMjcuMC4wLjEiLCJwcyI6Im9sZCJ9"
+uri = "vmess://eyJhZGQiOiIxMjcuMC4wLjEiLCJwcyI6Im9sZCJ9"
+
+new_uri = relabel(uri, "Germany-1")
 
-new_config = relabel(config, "Germany-1")
+if is_vmess(new_uri):
+    print("VMESS URI detected")
 
-if is_vmess(new_config):
-    print("VMESS config detected")
+config = parse(new_uri)
 
-subscription = encode_subscription([new_config])
+config.update_label("Germany-2")
+
+subscription = encode_subscription([config])
+
+uris = decode_subscription(subscription)
+```
+
+### Configs
+
+```python
+from v2kit import VMESSConfig
+
+config = VMESSConfig(
+    uuid="550e8400-e29b-41d4-a716-446655440000",
+    address="example.com",
+    port=443,
+    label="Germany-1",
+)
 
-configs = decode_subscription(subscription)
+uri = config.to_uri()
 ```
 
 ## Issues & Bug Reports			

{v2kit-0.1 → v2kit-0.2}/SECURITY.md

@@ -4,8 +4,8 @@
 
 | Version       | Supported          |
 | ------------- | ------------------ |
-| 0.1           | :white_check_mark: |
-| < 0.1         | :x:                |
+| 0.2           | :white_check_mark: |
+| < 0.2         | :x:                |
 
 ## Reporting a Vulnerability
 

{v2kit-0.1 → v2kit-0.2}/setup.py

@@ -33,7 +33,7 @@ def read_description() -> str:
 setup(
     name='v2kit',
     packages=['v2kit'],
-    version='0.1',
+    version='0.2',
     description='V2Kit: A Lightweight Toolkit for V2Ray Config Manipulation',
     long_description=read_description(),
     long_description_content_type='text/markdown',
@@ -41,7 +41,7 @@ setup(
     author='Sepand Haghighi',
     author_email='me@sepand.tech',
     url='https://github.com/sepandhaghighi/v2kit',
-    download_url='https://github.com/sepandhaghighi/v2kit/tarball/v0.1',
+    download_url='https://github.com/sepandhaghighi/v2kit/tarball/v0.2',
     keywords="v2ray v2ray-config v2ray-tools vmess vless trojan shadowsocks proxy subscription network",
     project_urls={
         'Source': 'https://github.com/sepandhaghighi/v2kit'},

v2kit-0.2/tests/test_errors.py

@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+
+import pytest
+from v2kit import VMESSConfig, VLESSConfig, TrojanConfig, ShadowsocksConfig
+from v2kit import relabel, encode_subscription, decode_subscription, parse
+from v2kit import V2kitError, V2kitValidationError, V2kitParseError
+from v2kit.validators import _validate_uri
+
+
+INVALID_PROTOCOL = "http://example.com"
+
+INVALID_VMESS = "vmess://invalid-base64"
+
+VALID_VLESS = (
+    "vless://1c4b4bca-e3ff-4ca8-a062-6f399ad3cf45@example.com:443"
+    "?security=tls#test"
+)
+
+VALID_UUID = (
+    "1c4b4bca-e3ff-4ca8-a062-6f399ad3cf45"
+)
+
+
+def test_validate_uri_non_string():
+    with pytest.raises(V2kitValidationError):
+        _validate_uri(123)
+
+
+def test_validate_uri_empty():
+    with pytest.raises(V2kitValidationError):
+        _validate_uri("")
+
+
+def test_validate_uri_missing_scheme():
+    with pytest.raises(V2kitValidationError):
+        _validate_uri("invalid-config")
+
+
+def test_validate_uri_unsupported_protocol():
+    with pytest.raises(V2kitValidationError):
+        _validate_uri(INVALID_PROTOCOL)
+
+
+def test_validate_invalid_vmess():
+    with pytest.raises(V2kitValidationError):
+        _validate_uri(INVALID_VMESS)
+
+
+def test_relabel_invalid_config():
+    with pytest.raises(V2kitValidationError):
+        relabel("invalid", "label")
+
+
+def test_relabel_empty_label():
+    with pytest.raises(V2kitValidationError):
+        relabel(VALID_VLESS, "")
+
+
+def test_relabel_non_string_label():
+    with pytest.raises(V2kitValidationError):
+        relabel(VALID_VLESS, 123)
+
+
+def test_encode_subscription_invalid_config():
+    configs = [
+        VALID_VLESS,
+        "invalid-config",
+    ]
+
+    with pytest.raises(V2kitValidationError):
+        encode_subscription(configs)
+
+
+def test_decode_subscription_non_string():
+    with pytest.raises(V2kitValidationError):
+        decode_subscription(123)
+
+
+def test_decode_subscription_invalid_data():
+    with pytest.raises(Exception):
+        decode_subscription("invalid-base64")
+
+
+def test_decode_subscription_invalid_config():
+    invalid_subscription = (
+        "aW52YWxpZC1jb25maWc="
+    )
+
+    with pytest.raises(V2kitValidationError):
+        decode_subscription(invalid_subscription)
+
+
+def test_exception_hierarchy():
+    assert issubclass(
+        V2kitValidationError,
+        V2kitError,
+    )
+
+    assert issubclass(
+        V2kitParseError,
+        V2kitValidationError,
+    )
+
+
+def test_parse_invalid_uri():
+    with pytest.raises(V2kitParseError):
+        parse("invalid")
+
+
+def test_parse_unsupported_protocol():
+    with pytest.raises(V2kitParseError):
+        parse("http://example.com")
+
+
+def test_vless_invalid_uuid():
+    with pytest.raises(V2kitValidationError):
+        VLESSConfig(
+            uuid="invalid",
+            address="example.com",
+            port=443,
+        )
+
+
+def test_vless_invalid_port():
+    with pytest.raises(V2kitValidationError):
+        VLESSConfig(
+            uuid=VALID_UUID,
+            address="example.com",
+            port=70000,
+        )
+
+
+def test_vless_empty_address():
+    with pytest.raises(V2kitValidationError):
+        VLESSConfig(
+            uuid=VALID_UUID,
+            address="",
+            port=443,
+        )
+
+
+def test_vmess_invalid_alter_id():
+    with pytest.raises(V2kitValidationError):
+        VMESSConfig(
+            uuid=VALID_UUID,
+            address="example.com",
+            port=443,
+            alter_id=-1,
+        )
+
+
+def test_trojan_empty_password():
+    with pytest.raises(V2kitValidationError):
+        TrojanConfig(
+            password="",
+            address="example.com",
+            port=443,
+        )
+
+
+def test_shadowsocks_empty_encryption():
+    with pytest.raises(V2kitValidationError):
+        ShadowsocksConfig(
+            encryption="",
+            password="secret",
+            address="example.com",
+            port=8388,
+        )

{v2kit-0.1 → v2kit-0.2}/tests/test_functions.py

@@ -1,8 +1,9 @@
 # -*- coding: utf-8 -*-
 
 import json
-from v2kit import is_vmess, is_vless, is_trojan, is_shadowsocks
+from v2kit import is_vmess, is_vless, is_trojan, is_shadowsocks, parse
 from v2kit import relabel, encode_subscription, decode_subscription
+from v2kit import VMESSConfig, VLESSConfig, TrojanConfig, ShadowsocksConfig
 from v2kit.utils import _encode_base64
 
 
@@ -12,7 +13,7 @@ def create_vmess(label="test"):
         "ps": label,
         "add": "example.com",
         "port": "443",
-        "id": "11111111-1111-1111-1111-111111111111",
+        "id": "1c4b4bca-e3ff-4ca8-a062-6f399ad3cf45",
         "aid": "0",
         "net": "ws",
         "type": "none",
@@ -29,7 +30,7 @@ def create_vmess(label="test"):
 VMESS_CONFIG = create_vmess()
 
 VLESS_CONFIG = (
-    "vless://uuid@example.com:443"
+    "vless://1c4b4bca-e3ff-4ca8-a062-6f399ad3cf45@example.com:443"
     "?security=tls#vless-test"
 )
 
@@ -63,6 +64,22 @@ def test_is_vmess_negative():
     assert is_vmess(VLESS_CONFIG) is False
 
 
+def test_is_vmess_invalid():
+    assert is_vmess("invalid") is False
+
+
+def test_is_vless_invalid():
+    assert is_vless("invalid") is False
+
+
+def test_is_trojan_invalid():
+    assert is_trojan("invalid") is False
+
+
+def test_is_shadowsocks_invalid():
+    assert is_shadowsocks("invalid") is False
+
+
 def test_relabel_vmess():
     result = relabel(VMESS_CONFIG, "new-label")
 
@@ -131,3 +148,61 @@ def test_encode_decode_subscription_roundtrip():
     decoded = decode_subscription(encoded)
 
     assert decoded == configs
+
+
+def test_encode_subscription_with_models():
+    config = parse(VLESS_CONFIG)
+
+    result = encode_subscription([config])
+
+    assert isinstance(result, str)
+
+
+def test_encode_subscription_no_validation():
+    result = encode_subscription(
+        ["invalid-config"],
+        validate=False,
+    )
+
+    assert isinstance(result, str)
+
+
+def test_decode_subscription_no_validation():
+    encoded = _encode_base64(
+        "invalid-config"
+    )
+
+    result = decode_subscription(
+        encoded,
+        validate=False,
+    )
+
+    assert result == ["invalid-config"]
+
+
+def test_parse_vmess():
+    assert isinstance(
+        parse(VMESS_CONFIG),
+        VMESSConfig,
+    )
+
+
+def test_parse_vless():
+    assert isinstance(
+        parse(VLESS_CONFIG),
+        VLESSConfig,
+    )
+
+
+def test_parse_trojan():
+    assert isinstance(
+        parse(TROJAN_CONFIG),
+        TrojanConfig,
+    )
+
+
+def test_parse_shadowsocks():
+    assert isinstance(
+        parse(SHADOWSOCKS_CONFIG),
+        ShadowsocksConfig,
+    )