proxy-string 1.0.1__tar.gz → 1.0.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,157 @@
1
+ Metadata-Version: 2.5
2
+ Name: proxy-string
3
+ Version: 1.0.2
4
+ Summary: Proxy server data representation and parser package.
5
+ Project-URL: Homepage, https://github.com/sergey-scat/proxy-string
6
+ Project-URL: Documentation, https://sergey-scat.github.io/proxy-string/
7
+ Project-URL: Issues, https://github.com/sergey-scat/proxy-string/issues
8
+ Author-email: Sergey Scat <py.unicaps@gmail.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Natural Language :: English
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Programming Language :: Python :: 3.15
23
+ Classifier: Topic :: Software Development :: Libraries
24
+ Requires-Python: <4,>=3.12
25
+ Requires-Dist: aiofiles>=25.1.0
26
+ Requires-Dist: attrs>=26.1.0
27
+ Requires-Dist: pywhatwgurl>=0.1.2
28
+ Provides-Extra: ada-url
29
+ Requires-Dist: ada-url>=4.0.0; extra == 'ada-url'
30
+ Provides-Extra: can-ada
31
+ Requires-Dist: can-ada>=3.1.0; extra == 'can-ada'
32
+ Description-Content-Type: text/markdown
33
+
34
+ <p align="center">
35
+ <img src="assets/logo.jpg" alt="proxy-string logo" width="220" />
36
+ </p>
37
+
38
+ <h1 align="center">proxy-string</h1>
39
+
40
+ <p align="center">
41
+ <a href="https://sergey-scat.github.io/proxy-string/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg" alt="Documentation" /></a>
42
+ <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg" alt="Python" /></a>
43
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
44
+ <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/code%20style-ruff-000000.svg" alt="Code style: ruff" /></a>
45
+ <a href="https://github.com/bwhmather/ty"><img src="https://img.shields.io/badge/types-ty-blueviolet.svg" alt="Checked with ty" /></a>
46
+ <a href="https://github.com/sergey-scat/proxy-string"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Coverage" /></a>
47
+ </p>
48
+
49
+ <p align="center">
50
+ A lightweight, type-safe Python library for parsing, validating, and converting proxy server connection data.
51
+ </p>
52
+
53
+ <p align="center">
54
+ <strong><a href="https://sergey-scat.github.io/proxy-string/">📖 Read the Documentation</a></strong>
55
+ </p>
56
+
57
+ ---
58
+
59
+ ## Features
60
+
61
+ - **WHATWG URL Standard**: Conforms to modern WHATWG URL standards via pure-Python `pywhatwgurl` with optional high-speed C++ backends (`can-ada`, `ada-url`).
62
+ - **Protocols Supported**: HTTP, HTTPS, SOCKS4, and SOCKS5 (with `socks4a` and `socks5h` remote DNS schemes).
63
+ - **Network Compatibility**: Full support for IPv4, IPv6 (RFC bracketed), UTF-8 Unicode credentials, and IDN / Punycode domain names.
64
+ - **Flexible Ingestion**: Parse from URLs, strings (with format auto-detection), dictionaries, JSON, and text files (sync & async generators).
65
+ - **Immutable & Safe**: Frozen `@attrs.frozen` instances with `with_*` evolution methods and strict port/protocol validation.
66
+ - **Client Integrations**: Built-in `prepare_for()` for `requests`, `httpx`, `aiohttp`, `playwright`, `curl_cffi`, and more.
67
+
68
+ ---
69
+
70
+ ## Installation
71
+
72
+ ```bash
73
+ # Using uv (recommended)
74
+ uv add proxy-string
75
+
76
+ # Using pip
77
+ pip install proxy-string
78
+ ```
79
+
80
+ For maximum URL parsing throughput, optional C++ WHATWG URL backends can be installed:
81
+
82
+ ```bash
83
+ uv add "proxy-string[can_ada]" # or "proxy-string[ada_url]"
84
+ ```
85
+
86
+ ---
87
+
88
+ ## Quick Start
89
+
90
+ ```python
91
+ from proxy_string import ProxyServer, ProxyServerProtocol
92
+
93
+ # 1. Parse from URL (supports Unicode credentials and remote DNS)
94
+ proxy = ProxyServer.from_url("socks5h://юзер:пароль@proxy.example.com:1080")
95
+ print(proxy.protocol) # ProxyServerProtocol.SOCKS5
96
+ print(proxy.remote_dns) # True
97
+
98
+ # 2. Parse from text string (format auto-detected)
99
+ auto = ProxyServer.from_string("192.168.1.1:8080:alice:secret")
100
+ print(auto.host) # '192.168.1.1'
101
+ print(auto.port) # 8080
102
+
103
+ # 3. Create modified copies (objects are immutable)
104
+ updated = auto.with_port(9090).with_creds("bob", "new_pass")
105
+
106
+ # 4. Export configuration for third-party HTTP clients
107
+ requests_config = updated.prepare_for("requests")
108
+ print(requests_config)
109
+ # {'http': 'http://bob:new_pass@192.168.1.1:9090', 'https': 'http://bob:new_pass@192.168.1.1:9090'}
110
+ ```
111
+
112
+ ---
113
+
114
+ ## Documentation
115
+
116
+ Full documentation with interactive search and detailed guides is available at:
117
+ **[https://sergey-scat.github.io/proxy-string/](https://sergey-scat.github.io/proxy-string/)**
118
+
119
+ - **[Installation Guide](https://sergey-scat.github.io/proxy-string/getting-started/installation/)**: Package installation and C++ backend selection.
120
+ - **[Quickstart Tutorial](https://sergey-scat.github.io/proxy-string/getting-started/quickstart/)**: Step-by-step introduction.
121
+ - **[Parsing Sources](https://sergey-scat.github.io/proxy-string/guides/parsing/)**: Parsing URLs, strings, files (sync/async), JSON, and IDN.
122
+ - **[Supported Formats](https://sergey-scat.github.io/proxy-string/guides/formats/)**: Detailed proxy string formats and auto-detection rules.
123
+ - **[Modifying Proxies](https://sergey-scat.github.io/proxy-string/guides/evolution/)**: Immutability and `with_*` methods.
124
+ - **[Client Integrations](https://sergey-scat.github.io/proxy-string/guides/integrations/)**: Configuration recipes for `requests`, `httpx`, `aiohttp`, `playwright`, `curl_cffi`, etc.
125
+ - **[API Reference](https://sergey-scat.github.io/proxy-string/reference/proxy-server/)**: Complete autogenerated reference for all classes and functions.
126
+
127
+ ---
128
+
129
+ ## Development
130
+
131
+ ```bash
132
+ # Clone the repository
133
+ git clone https://github.com/sergey-scat/proxy-string.git
134
+ cd proxy-string
135
+
136
+ # Install all dependencies including docs and dev groups
137
+ uv sync --all-extras --dev --group docs
138
+
139
+ # Run tests with coverage
140
+ uv run pytest
141
+
142
+ # Check code formatting and linting
143
+ uv run ruff check .
144
+ uv run ruff format --check .
145
+
146
+ # Static type check
147
+ uv run ty check src/proxy_string
148
+
149
+ # Build documentation locally
150
+ uv run mkdocs serve
151
+ ```
152
+
153
+ ---
154
+
155
+ ## License
156
+
157
+ This project is licensed under the [MIT License](LICENSE).
@@ -0,0 +1,124 @@
1
+ <p align="center">
2
+ <img src="assets/logo.jpg" alt="proxy-string logo" width="220" />
3
+ </p>
4
+
5
+ <h1 align="center">proxy-string</h1>
6
+
7
+ <p align="center">
8
+ <a href="https://sergey-scat.github.io/proxy-string/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg" alt="Documentation" /></a>
9
+ <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg" alt="Python" /></a>
10
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
11
+ <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/code%20style-ruff-000000.svg" alt="Code style: ruff" /></a>
12
+ <a href="https://github.com/bwhmather/ty"><img src="https://img.shields.io/badge/types-ty-blueviolet.svg" alt="Checked with ty" /></a>
13
+ <a href="https://github.com/sergey-scat/proxy-string"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Coverage" /></a>
14
+ </p>
15
+
16
+ <p align="center">
17
+ A lightweight, type-safe Python library for parsing, validating, and converting proxy server connection data.
18
+ </p>
19
+
20
+ <p align="center">
21
+ <strong><a href="https://sergey-scat.github.io/proxy-string/">📖 Read the Documentation</a></strong>
22
+ </p>
23
+
24
+ ---
25
+
26
+ ## Features
27
+
28
+ - **WHATWG URL Standard**: Conforms to modern WHATWG URL standards via pure-Python `pywhatwgurl` with optional high-speed C++ backends (`can-ada`, `ada-url`).
29
+ - **Protocols Supported**: HTTP, HTTPS, SOCKS4, and SOCKS5 (with `socks4a` and `socks5h` remote DNS schemes).
30
+ - **Network Compatibility**: Full support for IPv4, IPv6 (RFC bracketed), UTF-8 Unicode credentials, and IDN / Punycode domain names.
31
+ - **Flexible Ingestion**: Parse from URLs, strings (with format auto-detection), dictionaries, JSON, and text files (sync & async generators).
32
+ - **Immutable & Safe**: Frozen `@attrs.frozen` instances with `with_*` evolution methods and strict port/protocol validation.
33
+ - **Client Integrations**: Built-in `prepare_for()` for `requests`, `httpx`, `aiohttp`, `playwright`, `curl_cffi`, and more.
34
+
35
+ ---
36
+
37
+ ## Installation
38
+
39
+ ```bash
40
+ # Using uv (recommended)
41
+ uv add proxy-string
42
+
43
+ # Using pip
44
+ pip install proxy-string
45
+ ```
46
+
47
+ For maximum URL parsing throughput, optional C++ WHATWG URL backends can be installed:
48
+
49
+ ```bash
50
+ uv add "proxy-string[can_ada]" # or "proxy-string[ada_url]"
51
+ ```
52
+
53
+ ---
54
+
55
+ ## Quick Start
56
+
57
+ ```python
58
+ from proxy_string import ProxyServer, ProxyServerProtocol
59
+
60
+ # 1. Parse from URL (supports Unicode credentials and remote DNS)
61
+ proxy = ProxyServer.from_url("socks5h://юзер:пароль@proxy.example.com:1080")
62
+ print(proxy.protocol) # ProxyServerProtocol.SOCKS5
63
+ print(proxy.remote_dns) # True
64
+
65
+ # 2. Parse from text string (format auto-detected)
66
+ auto = ProxyServer.from_string("192.168.1.1:8080:alice:secret")
67
+ print(auto.host) # '192.168.1.1'
68
+ print(auto.port) # 8080
69
+
70
+ # 3. Create modified copies (objects are immutable)
71
+ updated = auto.with_port(9090).with_creds("bob", "new_pass")
72
+
73
+ # 4. Export configuration for third-party HTTP clients
74
+ requests_config = updated.prepare_for("requests")
75
+ print(requests_config)
76
+ # {'http': 'http://bob:new_pass@192.168.1.1:9090', 'https': 'http://bob:new_pass@192.168.1.1:9090'}
77
+ ```
78
+
79
+ ---
80
+
81
+ ## Documentation
82
+
83
+ Full documentation with interactive search and detailed guides is available at:
84
+ **[https://sergey-scat.github.io/proxy-string/](https://sergey-scat.github.io/proxy-string/)**
85
+
86
+ - **[Installation Guide](https://sergey-scat.github.io/proxy-string/getting-started/installation/)**: Package installation and C++ backend selection.
87
+ - **[Quickstart Tutorial](https://sergey-scat.github.io/proxy-string/getting-started/quickstart/)**: Step-by-step introduction.
88
+ - **[Parsing Sources](https://sergey-scat.github.io/proxy-string/guides/parsing/)**: Parsing URLs, strings, files (sync/async), JSON, and IDN.
89
+ - **[Supported Formats](https://sergey-scat.github.io/proxy-string/guides/formats/)**: Detailed proxy string formats and auto-detection rules.
90
+ - **[Modifying Proxies](https://sergey-scat.github.io/proxy-string/guides/evolution/)**: Immutability and `with_*` methods.
91
+ - **[Client Integrations](https://sergey-scat.github.io/proxy-string/guides/integrations/)**: Configuration recipes for `requests`, `httpx`, `aiohttp`, `playwright`, `curl_cffi`, etc.
92
+ - **[API Reference](https://sergey-scat.github.io/proxy-string/reference/proxy-server/)**: Complete autogenerated reference for all classes and functions.
93
+
94
+ ---
95
+
96
+ ## Development
97
+
98
+ ```bash
99
+ # Clone the repository
100
+ git clone https://github.com/sergey-scat/proxy-string.git
101
+ cd proxy-string
102
+
103
+ # Install all dependencies including docs and dev groups
104
+ uv sync --all-extras --dev --group docs
105
+
106
+ # Run tests with coverage
107
+ uv run pytest
108
+
109
+ # Check code formatting and linting
110
+ uv run ruff check .
111
+ uv run ruff format --check .
112
+
113
+ # Static type check
114
+ uv run ty check src/proxy_string
115
+
116
+ # Build documentation locally
117
+ uv run mkdocs serve
118
+ ```
119
+
120
+ ---
121
+
122
+ ## License
123
+
124
+ This project is licensed under the [MIT License](LICENSE).
@@ -44,6 +44,7 @@ can_ada = [
44
44
 
45
45
  [project.urls]
46
46
  Homepage = "https://github.com/sergey-scat/proxy-string"
47
+ Documentation = "https://sergey-scat.github.io/proxy-string/"
47
48
  Issues = "https://github.com/sergey-scat/proxy-string/issues"
48
49
 
49
50
  [dependency-groups]
@@ -54,6 +55,11 @@ dev = [
54
55
  "ruff>=0.17.4",
55
56
  "ty>=0.0.100",
56
57
  ]
58
+ docs = [
59
+ "mkdocs>=1.6.1",
60
+ "mkdocs-material>=9.8.1",
61
+ "mkdocstrings[python]>=1.0.8",
62
+ ]
57
63
 
58
64
  [tool.hatch.version]
59
65
  path = "src/proxy_string/__init__.py"
@@ -12,7 +12,7 @@ from .exceptions import (
12
12
  UnsupportedPackageError,
13
13
  )
14
14
 
15
- __version__ = "1.0.1"
15
+ __version__ = "1.0.2"
16
16
  __all__ = [
17
17
  "HostValueType",
18
18
  "InvalidProxyStringError",
@@ -1,476 +0,0 @@
1
- Metadata-Version: 2.5
2
- Name: proxy-string
3
- Version: 1.0.1
4
- Summary: Proxy server data representation and parser package.
5
- Project-URL: Homepage, https://github.com/sergey-scat/proxy-string
6
- Project-URL: Issues, https://github.com/sergey-scat/proxy-string/issues
7
- Author-email: Sergey Scat <py.unicaps@gmail.com>
8
- License-Expression: MIT
9
- License-File: LICENSE
10
- Classifier: Development Status :: 4 - Beta
11
- Classifier: Intended Audience :: Developers
12
- Classifier: License :: OSI Approved :: MIT License
13
- Classifier: Natural Language :: English
14
- Classifier: Operating System :: OS Independent
15
- Classifier: Programming Language :: Python
16
- Classifier: Programming Language :: Python :: 3
17
- Classifier: Programming Language :: Python :: 3 :: Only
18
- Classifier: Programming Language :: Python :: 3.12
19
- Classifier: Programming Language :: Python :: 3.13
20
- Classifier: Programming Language :: Python :: 3.14
21
- Classifier: Programming Language :: Python :: 3.15
22
- Classifier: Topic :: Software Development :: Libraries
23
- Requires-Python: <4,>=3.12
24
- Requires-Dist: aiofiles>=25.1.0
25
- Requires-Dist: attrs>=26.1.0
26
- Requires-Dist: pywhatwgurl>=0.1.2
27
- Provides-Extra: ada-url
28
- Requires-Dist: ada-url>=4.0.0; extra == 'ada-url'
29
- Provides-Extra: can-ada
30
- Requires-Dist: can-ada>=3.1.0; extra == 'can-ada'
31
- Description-Content-Type: text/markdown
32
-
33
- <p align="center">
34
- <img src="assets/logo.jpg" alt="proxy-string logo" width="220" />
35
- </p>
36
-
37
- <h1 align="center">proxy-string</h1>
38
-
39
- <p align="center">
40
- <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg" alt="Python" /></a>
41
- <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
42
- <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/code%20style-ruff-000000.svg" alt="Code style: ruff" /></a>
43
- <a href="https://github.com/bwhmather/ty"><img src="https://img.shields.io/badge/types-ty-blueviolet.svg" alt="Checked with ty" /></a>
44
- <a href="https://github.com/sergey-scat/proxy-string"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Coverage" /></a>
45
- </p>
46
-
47
- <p align="center">
48
- A lightweight, type-safe Python library for parsing, validating, and converting proxy server connection data.
49
- </p>
50
-
51
- <p align="center">
52
- Supports <strong>HTTP</strong>, <strong>HTTPS</strong>, <strong>SOCKS4</strong>, and <strong>SOCKS5</strong> (including remote DNS schemes <code>socks4a</code> and <code>socks5h</code>), with full compatibility for <strong>IPv4</strong>, <strong>IPv6</strong>, <strong>Unicode credentials</strong>, and <strong>IDN (Punycode)</strong> hostnames.
53
- </p>
54
-
55
- ---
56
-
57
- ## Features
58
-
59
- - **WHATWG URL Standard Compliance**: URL parsing conforms to modern WHATWG URL standards via `pywhatwgurl` (pure Python, installed by default), with optional high-performance C++ backends (`ada-url` and `can-ada`) selected automatically by speed priority.
60
- - **Unicode & IDN Ready**:
61
- - Full support for UTF-8 Unicode usernames and passwords with percent-encoding.
62
- - Transparent support for internationalized domain names (e.g. `代理服务器.中国` ↔ `xn--mnq04g52d6ywo0o.xn--fiqs8s`).
63
- - **Multi-Protocol Support**: Full support for HTTP, HTTPS, SOCKS4, and SOCKS5. Automatically maps `socks4a` and `socks5h` schemes to remote DNS resolution. Enforces protocol constraints (e.g. SOCKS4 IPv6 network restrictions).
64
- - **Flexible Parsing**:
65
- - Full URLs (e.g. `http://user:pass@192.168.1.1:8080`, `socks5h://...`).
66
- - Standard text formats (`host:port`, `user:pass:host:port`, `host:port@user:pass`, etc.) with automatic format detection.
67
- - Dictionaries (`from_dict`) and JSON strings (`from_json`).
68
- - Batch parsing from text files: synchronous (`from_file`) and asynchronous (`from_file_async`) generators with comment and whitespace filtering.
69
- - **Immutable & Safe**: Data objects are frozen (`@attrs.frozen`), hashable, and comparable. Strict validation for ports (`0..65535`), protocols, and hostnames.
70
- - **Evolution Methods**: Convenient `with_*` methods (`with_host`, `with_port`, `with_protocol`, `with_creds`, etc.) returning modified immutable copies.
71
- - **Third-Party Client Integration**: Built-in `prepare_for()` method returning ready-to-use proxy configuration structures for `requests`, `httpx`, `httpx2`, `aiohttp`, `playwright`, `urllib`, `urllib3`, `pycurl`, and `curl_cffi`, strictly type-checked via `SupportedPackage` Literal.
72
-
73
- ---
74
-
75
- ## Installation
76
-
77
- Install using `pip`:
78
-
79
- ```bash
80
- pip install proxy-string
81
- ```
82
-
83
- Or using [`uv`](https://docs.astral.sh/uv/):
84
-
85
- ```bash
86
- uv add proxy-string
87
- ```
88
-
89
- ### Optional High-Speed Backends
90
-
91
- For maximum URL parsing throughput, install optional C++ WHATWG URL backends:
92
-
93
- ```bash
94
- # Using pip
95
- pip install "proxy-string[ada_url]"
96
- pip install "proxy-string[can_ada]"
97
-
98
- # Using uv
99
- uv add "proxy-string[ada_url]"
100
- uv add "proxy-string[can_ada]"
101
- ```
102
-
103
- When installed, `proxy-string` automatically selects the fastest available backend:
104
- `can-ada` → `ada-url` → `pywhatwgurl`.
105
-
106
- ---
107
-
108
- ## Quick Start
109
-
110
- ```python
111
- from proxy_string import ProxyServer, ProxyServerProtocol
112
-
113
- # 1. Direct initialization (Unicode credentials supported)
114
- proxy = ProxyServer(
115
- host="proxy.example.com",
116
- port=8080,
117
- protocol=ProxyServerProtocol.HTTPS,
118
- username="юзер",
119
- password="пароль",
120
- )
121
- print(proxy.to_url())
122
- # https://%D1%8E%D0%B7%D0%B5%D1%80:%D0%BF%D0%B0%D1%80%D0%BE%D0%BB%D1%8C@proxy.example.com:8080
123
-
124
- # 2. Parse from URL
125
- socks_proxy = ProxyServer.from_url("socks5h://user:pass@10.0.0.1:1080")
126
- print(socks_proxy.protocol) # ProxyServerProtocol.SOCKS5
127
- print(socks_proxy.remote_dns) # True
128
-
129
- # 3. Parse from string (automatic format detection)
130
- auto_proxy = ProxyServer.from_string("192.168.1.100:8080:alice:password123")
131
- print(auto_proxy.host) # '192.168.1.100'
132
- print(auto_proxy.port) # 8080
133
- print(auto_proxy.username) # 'alice'
134
- ```
135
-
136
- ---
137
-
138
- ## Supported String Formats
139
-
140
- The `ProxyStringFormat` enum supports the most widely used proxy list formats:
141
-
142
- | Enum Member | Pattern Format | Example |
143
- | :--- | :--- | :--- |
144
- | `ProxyStringFormat.URL` | `scheme://[user:pass@]host:port` | `http://user:pass@proxy.com:8080` |
145
- | `ProxyStringFormat.HOST_PORT` | `{host}:{port}` | `192.168.1.1:8080` |
146
- | `ProxyStringFormat.USER_PASS_HOST_PORT` | `{username}:{password}:{host}:{port}` | `user:pass:192.168.1.1:8080` |
147
- | `ProxyStringFormat.USER_PASS_AT_HOST_PORT` | `{username}:{password}@{host}:{port}` | `user:pass@192.168.1.1:8080` |
148
- | `ProxyStringFormat.HOST_PORT_USER_PASS` | `{host}:{port}:{username}:{password}` | `192.168.1.1:8080:user:pass` |
149
- | `ProxyStringFormat.HOST_PORT_AT_USER_PASS` | `{host}:{port}@{username}:{password}` | `192.168.1.1:8080@user:pass` |
150
-
151
- When calling `ProxyServer.from_string()` without specifying `string_format`, the format is detected automatically:
152
- - Strings with `://` are parsed as URLs.
153
- - Strings containing `@` match `user:pass@host:port` or `host:port@user:pass`.
154
- - Single-colon strings (`host:port`) match `HOST_PORT`.
155
- - Multi-colon strings match IPv6 `[::1]:8080`, `HOST_PORT_USER_PASS`, or `USER_PASS_HOST_PORT`.
156
-
157
- > [!TIP]
158
- > **Ambiguity with numeric credentials:**
159
- > In 4-part colon-delimited formats (`HOST_PORT_USER_PASS` vs `USER_PASS_HOST_PORT`), if the password or username consists only of digits and falls within the valid port range (`0..65535`), automatic detection can be ambiguous. In such cases, pass the explicit `string_format` (e.g. `string_format=ProxyStringFormat.HOST_PORT_USER_PASS`).
160
-
161
- ---
162
-
163
- ## Usage Guide
164
-
165
- ### Reading Proxies from Files
166
-
167
- Text files can include empty lines and comment lines prefixed with `#`:
168
-
169
- #### Synchronous File Reading
170
-
171
- ```python
172
- from proxy_string import ProxyServer
173
-
174
- # Parse all valid rows, ignoring malformed lines
175
- for proxy in ProxyServer.from_file("proxies.txt", ignore_invalid=True):
176
- print(proxy.to_url())
177
- ```
178
-
179
- #### Asynchronous File Reading
180
-
181
- Process proxy lists asynchronously using `aiofiles`:
182
-
183
- ```python
184
- import asyncio
185
- from proxy_string import ProxyServer, ProxyServerProtocol
186
-
187
-
188
- async def load_proxies():
189
- async for proxy in ProxyServer.from_file_async(
190
- "proxies.txt",
191
- protocol=ProxyServerProtocol.SOCKS5,
192
- ignore_invalid=True,
193
- ):
194
- print(f"Loaded: {proxy.host}:{proxy.port}")
195
-
196
-
197
- asyncio.run(load_proxies())
198
- ```
199
-
200
- ---
201
-
202
- ### Exporting and Serialization
203
-
204
- #### URL Formatting
205
-
206
- ```python
207
- proxy = ProxyServer.from_url("socks5h://user:pass@proxy.net:1080")
208
-
209
- # Standard URL representation
210
- print(proxy.to_url())
211
- # socks5h://user:pass@proxy.net:1080
212
-
213
- # URL without credentials
214
- print(proxy.to_url(exclude_credentials=True))
215
- # socks5h://proxy.net:1080
216
-
217
- # Base protocol scheme without socks4a/socks5h extension
218
- print(proxy.to_url(socks_ext=False))
219
- # socks5://user:pass@proxy.net:1080
220
-
221
- # Available via properties
222
- print(proxy.url)
223
- print(proxy.origin) # Excludes credentials
224
- print(str(proxy))
225
- ```
226
-
227
- #### Formatted String Output
228
-
229
- Serialize a `ProxyServer` into any supported text format:
230
-
231
- ```python
232
- from proxy_string import ProxyServer, ProxyStringFormat
233
-
234
- proxy = ProxyServer(
235
- host="192.168.1.1",
236
- port=8080,
237
- username="myuser",
238
- password="mypassword",
239
- )
240
-
241
- # Export to a specific format
242
- text = proxy.to_string(ProxyStringFormat.USER_PASS_AT_HOST_PORT)
243
- print(text)
244
- # myuser:mypassword@192.168.1.1:8080
245
-
246
- # Auto-format (defaults to HOST_PORT_USER_PASS if credentials exist, otherwise HOST_PORT)
247
- text = proxy.to_string()
248
- print(text)
249
- # 192.168.1.1:8080:myuser:mypassword
250
- ```
251
-
252
- #### Dictionary and JSON
253
-
254
- ```python
255
- proxy = ProxyServer.from_url("http://admin:secret@proxy.com:8080")
256
-
257
- # Dictionary
258
- d = proxy.to_dict()
259
- # {'host': 'proxy.com', 'port': 8080, 'protocol': <ProxyServerProtocol.HTTP: 'http'>, ...}
260
-
261
- # JSON
262
- json_str = proxy.to_json()
263
-
264
- # Reconstruct from dictionary or JSON
265
- p1 = ProxyServer.from_dict(d)
266
- p2 = ProxyServer.from_json(json_str)
267
- ```
268
-
269
- ---
270
-
271
- ### Third-Party HTTP Client Preparation
272
-
273
- Use `prepare_for()` to obtain library-ready proxy configurations:
274
-
275
- ```python
276
- proxy = ProxyServer.from_url("http://user:pass@proxy.com:8080")
277
-
278
- # requests & urllib
279
- requests_proxies = proxy.prepare_for("requests")
280
- # {'http': 'http://user:pass@proxy.com:8080', 'https': 'http://user:pass@proxy.com:8080'}
281
-
282
- # httpx, httpx2, aiohttp, urllib3, pycurl, curl_cffi
283
- httpx_proxy = proxy.prepare_for("httpx")
284
- # 'http://user:pass@proxy.com:8080'
285
-
286
- # SupportedPackage Literal type provides IDE autocomplete and static type safety
287
- from proxy_string import SupportedPackage
288
-
289
- target_pkg: SupportedPackage = "httpx2"
290
- httpx2_proxy = proxy.prepare_for(target_pkg)
291
-
292
- # playwright
293
- playwright_proxy = proxy.prepare_for("playwright")
294
- # {'server': 'http://proxy.com:8080', 'username': 'user', 'password': 'pass'}
295
- ```
296
-
297
- ---
298
-
299
- ### Modifying Instances (`with_*` Methods)
300
-
301
- Because `ProxyServer` objects are immutable, use `with_*` methods to create updated copies:
302
-
303
- ```python
304
- proxy = ProxyServer(host="proxy.com", port=8080)
305
-
306
- # Evolve individual attributes
307
- p2 = proxy.with_port(9090)
308
- p3 = proxy.with_creds("admin", "secret")
309
- p4 = proxy.with_remote_dns(True)
310
- ```
311
-
312
- ---
313
-
314
- ### Internationalized Domain Names (IDN / Punycode)
315
-
316
- Non-ASCII domain names are converted to Punycode ASCII for standard network compatibility, while the original Unicode domain remains accessible:
317
-
318
- ```python
319
- from proxy_string import ProxyServer
320
-
321
- proxy = ProxyServer.from_url("https://代理服务器.中国")
322
-
323
- print(proxy.host)
324
- # xn--mnq04g52d6ywo0o.xn--fiqs8s
325
-
326
- print(proxy.unicode_host)
327
- # 代理服务器.中国
328
-
329
- print(proxy.unicode_url)
330
- # https://代理服务器.中国:443
331
- ```
332
-
333
- ---
334
-
335
- ### IPv6 Support
336
-
337
- IPv6 addresses can be passed with or without square brackets. The parser normalizes them into RFC-compliant bracketed URLs:
338
-
339
- ```python
340
- from proxy_string import ProxyServer
341
-
342
- # With square brackets
343
- p1 = ProxyServer.from_string("[2001:db8::1]:8080")
344
- print(p1.host) # '2001:db8::1'
345
- print(p1.to_url()) # 'http://[2001:db8::1]:8080'
346
-
347
- # Unbracketed
348
- p2 = ProxyServer(host="2001:db8::1", port=8080)
349
- print(p2.to_url()) # 'http://[2001:db8::1]:8080'
350
- ```
351
-
352
- ---
353
-
354
- ## API Reference
355
-
356
- ### `ProxyServer`
357
-
358
- #### Attributes & Properties
359
- - `host: str` — Hostname or IP address (Punycode-encoded for IDN).
360
- - `port: int` — Port number (`0..65535`). Defaults to protocol standard if omitted (80, 443, 1080).
361
- - `protocol: ProxyServerProtocol` — Protocol (`HTTP`, `HTTPS`, `SOCKS4`, `SOCKS5`).
362
- - `username: str | None` — Authentication username.
363
- - `password: str | None` — Authentication password (distinguishes empty password `""` from `None`).
364
- - `remote_dns: bool | None` — Whether DNS is resolved on the proxy server (SOCKS only).
365
- - `unicode_host: str` — Unicode representation of the hostname (for IDN).
366
- - `host_value_type: HostValueType` — Host classification (`HostValueType.HOSTNAME`, `HostValueType.IPV4`, or `HostValueType.IPV6`).
367
- - `host_ip_address: IPv4Address | IPv6Address | None` — Parsed IP address object if `host` is an IP.
368
- - `url: str` — Complete URL representation.
369
- - `origin: str` — URL representation excluding credentials.
370
- - `unicode_url: str` — URL representation with Unicode host.
371
- - `is_authenticated: bool` — `True` if credentials (`username` or `password`) are set.
372
- - `is_socks: bool` — `True` if protocol is a SOCKS variant (`SOCKS4` or `SOCKS5`).
373
- - `is_ssl: bool` — `True` if proxy connection uses TLS/SSL (`HTTPS`).
374
-
375
- #### Class Methods
376
- - `from_url(url: str) -> ProxyServer`
377
- - `from_string(proxy_string: str, *, string_format: ProxyStringFormat | None = None, protocol: ProxyServerProtocol | None = None) -> ProxyServer`
378
- - `from_file(input_file: str | Path, *, string_format: ProxyStringFormat | None = None, protocol: ProxyServerProtocol | None = None, encoding: str = "utf-8", encoding_errors: str = "strict", ignore_invalid: bool = False) -> Generator[ProxyServer, None, None]`
379
- - `from_file_async(input_file: str | Path, *, string_format: ProxyStringFormat | None = None, protocol: ProxyServerProtocol | None = None, encoding: str = "utf-8", encoding_errors: str = "strict", ignore_invalid: bool = False) -> AsyncGenerator[ProxyServer, None]`
380
- - `from_dict(input_dict: Mapping[str, Any]) -> ProxyServer`
381
- - `from_json(input_json: str) -> ProxyServer`
382
-
383
- #### Methods
384
- - `to_url(socks_ext: bool = True, exclude_credentials: bool = False) -> str`
385
- - `to_string(string_format: ProxyStringFormat | None = None) -> str`
386
- - `to_dict() -> dict[str, Any]`
387
- - `to_json() -> str`
388
- - `with_host(host: str) -> ProxyServer`
389
- - `with_port(port: int) -> ProxyServer`
390
- - `with_protocol(protocol: ProxyServerProtocol | str) -> ProxyServer`
391
- - `with_username(username: str | None) -> ProxyServer`
392
- - `with_password(password: str | None) -> ProxyServer`
393
- - `with_creds(username: str | None, password: str | None) -> ProxyServer`
394
- - `with_remote_dns(remote_dns: bool | None) -> ProxyServer`
395
- - `prepare_for(package_name: SupportedPackage) -> dict[str, Any] | str`
396
-
397
- ---
398
-
399
- ### Enumerations and Types
400
-
401
- - **`ProxyServerProtocol`**: `HTTP = "http"`, `HTTPS = "https"`, `SOCKS4 = "socks4"`, `SOCKS5 = "socks5"`
402
- - **`ProxyStringFormat`** (`StrEnum`): `URL = "url"`, `HOST_PORT = "host:port"`, `USER_PASS_HOST_PORT = "user:pass:host:port"`, `USER_PASS_AT_HOST_PORT = "user:pass@host:port"`, `HOST_PORT_USER_PASS = "host:port:user:pass"`, `HOST_PORT_AT_USER_PASS = "host:port@user:pass"`
403
- - **`HostValueType`**: `HOSTNAME = "hostname"`, `IPV4 = "ipv4"`, `IPV6 = "ipv6"`
404
- - **`SupportedPackage`**: `Literal["aiohttp", "curl_cffi", "httpx", "httpx2", "playwright", "pycurl", "requests", "urllib", "urllib3"]`
405
-
406
- ---
407
-
408
- ### Exceptions
409
-
410
- All custom exceptions inherit from `ProxyStringError` and provide structured attributes for programmatic inspection:
411
-
412
- - `ProxyStringError` — Base exception class for all `proxy-string` errors.
413
- - `InvalidProxyStringError` — Raised when a proxy string is malformed or cannot be parsed (stores `e.proxy_string`).
414
- - `InvalidProxyURLError` — Raised when a proxy URL is malformed, lacks an absolute scheme or host, or uses an unsupported scheme (stores `e.url`).
415
- - `ProxyConfigurationError` — Base exception for proxy configuration and protocol constraint errors.
416
- - `ProtocolConstraintError` — Raised when protocol network constraints are violated, such as SOCKS4 with IPv6 or HTTP with remote DNS resolution (stores `e.protocol`, `e.host`).
417
- - `UnsupportedPackageError` — Raised when an unsupported client library is passed to `prepare_for()` (stores `e.package_name`).
418
- - `ProtocolNotSupportedError` — Raised when a proxy protocol is incompatible with the target client library in `prepare_for()` (stores `e.package_name`, `e.protocol`).
419
-
420
- ```python
421
- from proxy_string import (
422
- InvalidProxyStringError,
423
- InvalidProxyURLError,
424
- ProtocolConstraintError,
425
- ProxyServer,
426
- ProxyStringError,
427
- )
428
-
429
- try:
430
- proxy = ProxyServer.from_string("invalid:format:extra:fields:123")
431
- except InvalidProxyStringError as e:
432
- print(f"String parsing error for '{e.proxy_string}': {e}")
433
-
434
- try:
435
- proxy = ProxyServer(host="2001:db8::1", protocol="socks4")
436
- except ProtocolConstraintError as e:
437
- print(f"Constraint violated for {e.protocol} on host {e.host}: {e}")
438
-
439
- try:
440
- proxy = ProxyServer.from_url("ftp://proxy.com:8080")
441
- except InvalidProxyURLError as e:
442
- print(f"URL error for '{e.url}': {e}")
443
- except ProxyStringError as e:
444
- print(f"General proxy error: {e}")
445
- ```
446
-
447
- ---
448
-
449
- ## Development
450
-
451
- Requirements: Python 3.12+, [`uv`](https://docs.astral.sh/uv/)
452
-
453
- ```bash
454
- # Clone the repository
455
- git clone https://github.com/sergey-scat/proxy-string.git
456
- cd proxy-string
457
-
458
- # Install dependencies including optional backends
459
- uv sync --all-extras
460
-
461
- # Run the test suite with coverage
462
- uv run pytest
463
-
464
- # Check code formatting and lints
465
- uv run ruff check
466
- uv run ruff format --check
467
-
468
- # Type check
469
- uv run ty check src/proxy_string
470
- ```
471
-
472
- ---
473
-
474
- ## License
475
-
476
- This project is licensed under the [MIT License](LICENSE).
@@ -1,444 +0,0 @@
1
- <p align="center">
2
- <img src="assets/logo.jpg" alt="proxy-string logo" width="220" />
3
- </p>
4
-
5
- <h1 align="center">proxy-string</h1>
6
-
7
- <p align="center">
8
- <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg" alt="Python" /></a>
9
- <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
10
- <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/code%20style-ruff-000000.svg" alt="Code style: ruff" /></a>
11
- <a href="https://github.com/bwhmather/ty"><img src="https://img.shields.io/badge/types-ty-blueviolet.svg" alt="Checked with ty" /></a>
12
- <a href="https://github.com/sergey-scat/proxy-string"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Coverage" /></a>
13
- </p>
14
-
15
- <p align="center">
16
- A lightweight, type-safe Python library for parsing, validating, and converting proxy server connection data.
17
- </p>
18
-
19
- <p align="center">
20
- Supports <strong>HTTP</strong>, <strong>HTTPS</strong>, <strong>SOCKS4</strong>, and <strong>SOCKS5</strong> (including remote DNS schemes <code>socks4a</code> and <code>socks5h</code>), with full compatibility for <strong>IPv4</strong>, <strong>IPv6</strong>, <strong>Unicode credentials</strong>, and <strong>IDN (Punycode)</strong> hostnames.
21
- </p>
22
-
23
- ---
24
-
25
- ## Features
26
-
27
- - **WHATWG URL Standard Compliance**: URL parsing conforms to modern WHATWG URL standards via `pywhatwgurl` (pure Python, installed by default), with optional high-performance C++ backends (`ada-url` and `can-ada`) selected automatically by speed priority.
28
- - **Unicode & IDN Ready**:
29
- - Full support for UTF-8 Unicode usernames and passwords with percent-encoding.
30
- - Transparent support for internationalized domain names (e.g. `代理服务器.中国` ↔ `xn--mnq04g52d6ywo0o.xn--fiqs8s`).
31
- - **Multi-Protocol Support**: Full support for HTTP, HTTPS, SOCKS4, and SOCKS5. Automatically maps `socks4a` and `socks5h` schemes to remote DNS resolution. Enforces protocol constraints (e.g. SOCKS4 IPv6 network restrictions).
32
- - **Flexible Parsing**:
33
- - Full URLs (e.g. `http://user:pass@192.168.1.1:8080`, `socks5h://...`).
34
- - Standard text formats (`host:port`, `user:pass:host:port`, `host:port@user:pass`, etc.) with automatic format detection.
35
- - Dictionaries (`from_dict`) and JSON strings (`from_json`).
36
- - Batch parsing from text files: synchronous (`from_file`) and asynchronous (`from_file_async`) generators with comment and whitespace filtering.
37
- - **Immutable & Safe**: Data objects are frozen (`@attrs.frozen`), hashable, and comparable. Strict validation for ports (`0..65535`), protocols, and hostnames.
38
- - **Evolution Methods**: Convenient `with_*` methods (`with_host`, `with_port`, `with_protocol`, `with_creds`, etc.) returning modified immutable copies.
39
- - **Third-Party Client Integration**: Built-in `prepare_for()` method returning ready-to-use proxy configuration structures for `requests`, `httpx`, `httpx2`, `aiohttp`, `playwright`, `urllib`, `urllib3`, `pycurl`, and `curl_cffi`, strictly type-checked via `SupportedPackage` Literal.
40
-
41
- ---
42
-
43
- ## Installation
44
-
45
- Install using `pip`:
46
-
47
- ```bash
48
- pip install proxy-string
49
- ```
50
-
51
- Or using [`uv`](https://docs.astral.sh/uv/):
52
-
53
- ```bash
54
- uv add proxy-string
55
- ```
56
-
57
- ### Optional High-Speed Backends
58
-
59
- For maximum URL parsing throughput, install optional C++ WHATWG URL backends:
60
-
61
- ```bash
62
- # Using pip
63
- pip install "proxy-string[ada_url]"
64
- pip install "proxy-string[can_ada]"
65
-
66
- # Using uv
67
- uv add "proxy-string[ada_url]"
68
- uv add "proxy-string[can_ada]"
69
- ```
70
-
71
- When installed, `proxy-string` automatically selects the fastest available backend:
72
- `can-ada` → `ada-url` → `pywhatwgurl`.
73
-
74
- ---
75
-
76
- ## Quick Start
77
-
78
- ```python
79
- from proxy_string import ProxyServer, ProxyServerProtocol
80
-
81
- # 1. Direct initialization (Unicode credentials supported)
82
- proxy = ProxyServer(
83
- host="proxy.example.com",
84
- port=8080,
85
- protocol=ProxyServerProtocol.HTTPS,
86
- username="юзер",
87
- password="пароль",
88
- )
89
- print(proxy.to_url())
90
- # https://%D1%8E%D0%B7%D0%B5%D1%80:%D0%BF%D0%B0%D1%80%D0%BE%D0%BB%D1%8C@proxy.example.com:8080
91
-
92
- # 2. Parse from URL
93
- socks_proxy = ProxyServer.from_url("socks5h://user:pass@10.0.0.1:1080")
94
- print(socks_proxy.protocol) # ProxyServerProtocol.SOCKS5
95
- print(socks_proxy.remote_dns) # True
96
-
97
- # 3. Parse from string (automatic format detection)
98
- auto_proxy = ProxyServer.from_string("192.168.1.100:8080:alice:password123")
99
- print(auto_proxy.host) # '192.168.1.100'
100
- print(auto_proxy.port) # 8080
101
- print(auto_proxy.username) # 'alice'
102
- ```
103
-
104
- ---
105
-
106
- ## Supported String Formats
107
-
108
- The `ProxyStringFormat` enum supports the most widely used proxy list formats:
109
-
110
- | Enum Member | Pattern Format | Example |
111
- | :--- | :--- | :--- |
112
- | `ProxyStringFormat.URL` | `scheme://[user:pass@]host:port` | `http://user:pass@proxy.com:8080` |
113
- | `ProxyStringFormat.HOST_PORT` | `{host}:{port}` | `192.168.1.1:8080` |
114
- | `ProxyStringFormat.USER_PASS_HOST_PORT` | `{username}:{password}:{host}:{port}` | `user:pass:192.168.1.1:8080` |
115
- | `ProxyStringFormat.USER_PASS_AT_HOST_PORT` | `{username}:{password}@{host}:{port}` | `user:pass@192.168.1.1:8080` |
116
- | `ProxyStringFormat.HOST_PORT_USER_PASS` | `{host}:{port}:{username}:{password}` | `192.168.1.1:8080:user:pass` |
117
- | `ProxyStringFormat.HOST_PORT_AT_USER_PASS` | `{host}:{port}@{username}:{password}` | `192.168.1.1:8080@user:pass` |
118
-
119
- When calling `ProxyServer.from_string()` without specifying `string_format`, the format is detected automatically:
120
- - Strings with `://` are parsed as URLs.
121
- - Strings containing `@` match `user:pass@host:port` or `host:port@user:pass`.
122
- - Single-colon strings (`host:port`) match `HOST_PORT`.
123
- - Multi-colon strings match IPv6 `[::1]:8080`, `HOST_PORT_USER_PASS`, or `USER_PASS_HOST_PORT`.
124
-
125
- > [!TIP]
126
- > **Ambiguity with numeric credentials:**
127
- > In 4-part colon-delimited formats (`HOST_PORT_USER_PASS` vs `USER_PASS_HOST_PORT`), if the password or username consists only of digits and falls within the valid port range (`0..65535`), automatic detection can be ambiguous. In such cases, pass the explicit `string_format` (e.g. `string_format=ProxyStringFormat.HOST_PORT_USER_PASS`).
128
-
129
- ---
130
-
131
- ## Usage Guide
132
-
133
- ### Reading Proxies from Files
134
-
135
- Text files can include empty lines and comment lines prefixed with `#`:
136
-
137
- #### Synchronous File Reading
138
-
139
- ```python
140
- from proxy_string import ProxyServer
141
-
142
- # Parse all valid rows, ignoring malformed lines
143
- for proxy in ProxyServer.from_file("proxies.txt", ignore_invalid=True):
144
- print(proxy.to_url())
145
- ```
146
-
147
- #### Asynchronous File Reading
148
-
149
- Process proxy lists asynchronously using `aiofiles`:
150
-
151
- ```python
152
- import asyncio
153
- from proxy_string import ProxyServer, ProxyServerProtocol
154
-
155
-
156
- async def load_proxies():
157
- async for proxy in ProxyServer.from_file_async(
158
- "proxies.txt",
159
- protocol=ProxyServerProtocol.SOCKS5,
160
- ignore_invalid=True,
161
- ):
162
- print(f"Loaded: {proxy.host}:{proxy.port}")
163
-
164
-
165
- asyncio.run(load_proxies())
166
- ```
167
-
168
- ---
169
-
170
- ### Exporting and Serialization
171
-
172
- #### URL Formatting
173
-
174
- ```python
175
- proxy = ProxyServer.from_url("socks5h://user:pass@proxy.net:1080")
176
-
177
- # Standard URL representation
178
- print(proxy.to_url())
179
- # socks5h://user:pass@proxy.net:1080
180
-
181
- # URL without credentials
182
- print(proxy.to_url(exclude_credentials=True))
183
- # socks5h://proxy.net:1080
184
-
185
- # Base protocol scheme without socks4a/socks5h extension
186
- print(proxy.to_url(socks_ext=False))
187
- # socks5://user:pass@proxy.net:1080
188
-
189
- # Available via properties
190
- print(proxy.url)
191
- print(proxy.origin) # Excludes credentials
192
- print(str(proxy))
193
- ```
194
-
195
- #### Formatted String Output
196
-
197
- Serialize a `ProxyServer` into any supported text format:
198
-
199
- ```python
200
- from proxy_string import ProxyServer, ProxyStringFormat
201
-
202
- proxy = ProxyServer(
203
- host="192.168.1.1",
204
- port=8080,
205
- username="myuser",
206
- password="mypassword",
207
- )
208
-
209
- # Export to a specific format
210
- text = proxy.to_string(ProxyStringFormat.USER_PASS_AT_HOST_PORT)
211
- print(text)
212
- # myuser:mypassword@192.168.1.1:8080
213
-
214
- # Auto-format (defaults to HOST_PORT_USER_PASS if credentials exist, otherwise HOST_PORT)
215
- text = proxy.to_string()
216
- print(text)
217
- # 192.168.1.1:8080:myuser:mypassword
218
- ```
219
-
220
- #### Dictionary and JSON
221
-
222
- ```python
223
- proxy = ProxyServer.from_url("http://admin:secret@proxy.com:8080")
224
-
225
- # Dictionary
226
- d = proxy.to_dict()
227
- # {'host': 'proxy.com', 'port': 8080, 'protocol': <ProxyServerProtocol.HTTP: 'http'>, ...}
228
-
229
- # JSON
230
- json_str = proxy.to_json()
231
-
232
- # Reconstruct from dictionary or JSON
233
- p1 = ProxyServer.from_dict(d)
234
- p2 = ProxyServer.from_json(json_str)
235
- ```
236
-
237
- ---
238
-
239
- ### Third-Party HTTP Client Preparation
240
-
241
- Use `prepare_for()` to obtain library-ready proxy configurations:
242
-
243
- ```python
244
- proxy = ProxyServer.from_url("http://user:pass@proxy.com:8080")
245
-
246
- # requests & urllib
247
- requests_proxies = proxy.prepare_for("requests")
248
- # {'http': 'http://user:pass@proxy.com:8080', 'https': 'http://user:pass@proxy.com:8080'}
249
-
250
- # httpx, httpx2, aiohttp, urllib3, pycurl, curl_cffi
251
- httpx_proxy = proxy.prepare_for("httpx")
252
- # 'http://user:pass@proxy.com:8080'
253
-
254
- # SupportedPackage Literal type provides IDE autocomplete and static type safety
255
- from proxy_string import SupportedPackage
256
-
257
- target_pkg: SupportedPackage = "httpx2"
258
- httpx2_proxy = proxy.prepare_for(target_pkg)
259
-
260
- # playwright
261
- playwright_proxy = proxy.prepare_for("playwright")
262
- # {'server': 'http://proxy.com:8080', 'username': 'user', 'password': 'pass'}
263
- ```
264
-
265
- ---
266
-
267
- ### Modifying Instances (`with_*` Methods)
268
-
269
- Because `ProxyServer` objects are immutable, use `with_*` methods to create updated copies:
270
-
271
- ```python
272
- proxy = ProxyServer(host="proxy.com", port=8080)
273
-
274
- # Evolve individual attributes
275
- p2 = proxy.with_port(9090)
276
- p3 = proxy.with_creds("admin", "secret")
277
- p4 = proxy.with_remote_dns(True)
278
- ```
279
-
280
- ---
281
-
282
- ### Internationalized Domain Names (IDN / Punycode)
283
-
284
- Non-ASCII domain names are converted to Punycode ASCII for standard network compatibility, while the original Unicode domain remains accessible:
285
-
286
- ```python
287
- from proxy_string import ProxyServer
288
-
289
- proxy = ProxyServer.from_url("https://代理服务器.中国")
290
-
291
- print(proxy.host)
292
- # xn--mnq04g52d6ywo0o.xn--fiqs8s
293
-
294
- print(proxy.unicode_host)
295
- # 代理服务器.中国
296
-
297
- print(proxy.unicode_url)
298
- # https://代理服务器.中国:443
299
- ```
300
-
301
- ---
302
-
303
- ### IPv6 Support
304
-
305
- IPv6 addresses can be passed with or without square brackets. The parser normalizes them into RFC-compliant bracketed URLs:
306
-
307
- ```python
308
- from proxy_string import ProxyServer
309
-
310
- # With square brackets
311
- p1 = ProxyServer.from_string("[2001:db8::1]:8080")
312
- print(p1.host) # '2001:db8::1'
313
- print(p1.to_url()) # 'http://[2001:db8::1]:8080'
314
-
315
- # Unbracketed
316
- p2 = ProxyServer(host="2001:db8::1", port=8080)
317
- print(p2.to_url()) # 'http://[2001:db8::1]:8080'
318
- ```
319
-
320
- ---
321
-
322
- ## API Reference
323
-
324
- ### `ProxyServer`
325
-
326
- #### Attributes & Properties
327
- - `host: str` — Hostname or IP address (Punycode-encoded for IDN).
328
- - `port: int` — Port number (`0..65535`). Defaults to protocol standard if omitted (80, 443, 1080).
329
- - `protocol: ProxyServerProtocol` — Protocol (`HTTP`, `HTTPS`, `SOCKS4`, `SOCKS5`).
330
- - `username: str | None` — Authentication username.
331
- - `password: str | None` — Authentication password (distinguishes empty password `""` from `None`).
332
- - `remote_dns: bool | None` — Whether DNS is resolved on the proxy server (SOCKS only).
333
- - `unicode_host: str` — Unicode representation of the hostname (for IDN).
334
- - `host_value_type: HostValueType` — Host classification (`HostValueType.HOSTNAME`, `HostValueType.IPV4`, or `HostValueType.IPV6`).
335
- - `host_ip_address: IPv4Address | IPv6Address | None` — Parsed IP address object if `host` is an IP.
336
- - `url: str` — Complete URL representation.
337
- - `origin: str` — URL representation excluding credentials.
338
- - `unicode_url: str` — URL representation with Unicode host.
339
- - `is_authenticated: bool` — `True` if credentials (`username` or `password`) are set.
340
- - `is_socks: bool` — `True` if protocol is a SOCKS variant (`SOCKS4` or `SOCKS5`).
341
- - `is_ssl: bool` — `True` if proxy connection uses TLS/SSL (`HTTPS`).
342
-
343
- #### Class Methods
344
- - `from_url(url: str) -> ProxyServer`
345
- - `from_string(proxy_string: str, *, string_format: ProxyStringFormat | None = None, protocol: ProxyServerProtocol | None = None) -> ProxyServer`
346
- - `from_file(input_file: str | Path, *, string_format: ProxyStringFormat | None = None, protocol: ProxyServerProtocol | None = None, encoding: str = "utf-8", encoding_errors: str = "strict", ignore_invalid: bool = False) -> Generator[ProxyServer, None, None]`
347
- - `from_file_async(input_file: str | Path, *, string_format: ProxyStringFormat | None = None, protocol: ProxyServerProtocol | None = None, encoding: str = "utf-8", encoding_errors: str = "strict", ignore_invalid: bool = False) -> AsyncGenerator[ProxyServer, None]`
348
- - `from_dict(input_dict: Mapping[str, Any]) -> ProxyServer`
349
- - `from_json(input_json: str) -> ProxyServer`
350
-
351
- #### Methods
352
- - `to_url(socks_ext: bool = True, exclude_credentials: bool = False) -> str`
353
- - `to_string(string_format: ProxyStringFormat | None = None) -> str`
354
- - `to_dict() -> dict[str, Any]`
355
- - `to_json() -> str`
356
- - `with_host(host: str) -> ProxyServer`
357
- - `with_port(port: int) -> ProxyServer`
358
- - `with_protocol(protocol: ProxyServerProtocol | str) -> ProxyServer`
359
- - `with_username(username: str | None) -> ProxyServer`
360
- - `with_password(password: str | None) -> ProxyServer`
361
- - `with_creds(username: str | None, password: str | None) -> ProxyServer`
362
- - `with_remote_dns(remote_dns: bool | None) -> ProxyServer`
363
- - `prepare_for(package_name: SupportedPackage) -> dict[str, Any] | str`
364
-
365
- ---
366
-
367
- ### Enumerations and Types
368
-
369
- - **`ProxyServerProtocol`**: `HTTP = "http"`, `HTTPS = "https"`, `SOCKS4 = "socks4"`, `SOCKS5 = "socks5"`
370
- - **`ProxyStringFormat`** (`StrEnum`): `URL = "url"`, `HOST_PORT = "host:port"`, `USER_PASS_HOST_PORT = "user:pass:host:port"`, `USER_PASS_AT_HOST_PORT = "user:pass@host:port"`, `HOST_PORT_USER_PASS = "host:port:user:pass"`, `HOST_PORT_AT_USER_PASS = "host:port@user:pass"`
371
- - **`HostValueType`**: `HOSTNAME = "hostname"`, `IPV4 = "ipv4"`, `IPV6 = "ipv6"`
372
- - **`SupportedPackage`**: `Literal["aiohttp", "curl_cffi", "httpx", "httpx2", "playwright", "pycurl", "requests", "urllib", "urllib3"]`
373
-
374
- ---
375
-
376
- ### Exceptions
377
-
378
- All custom exceptions inherit from `ProxyStringError` and provide structured attributes for programmatic inspection:
379
-
380
- - `ProxyStringError` — Base exception class for all `proxy-string` errors.
381
- - `InvalidProxyStringError` — Raised when a proxy string is malformed or cannot be parsed (stores `e.proxy_string`).
382
- - `InvalidProxyURLError` — Raised when a proxy URL is malformed, lacks an absolute scheme or host, or uses an unsupported scheme (stores `e.url`).
383
- - `ProxyConfigurationError` — Base exception for proxy configuration and protocol constraint errors.
384
- - `ProtocolConstraintError` — Raised when protocol network constraints are violated, such as SOCKS4 with IPv6 or HTTP with remote DNS resolution (stores `e.protocol`, `e.host`).
385
- - `UnsupportedPackageError` — Raised when an unsupported client library is passed to `prepare_for()` (stores `e.package_name`).
386
- - `ProtocolNotSupportedError` — Raised when a proxy protocol is incompatible with the target client library in `prepare_for()` (stores `e.package_name`, `e.protocol`).
387
-
388
- ```python
389
- from proxy_string import (
390
- InvalidProxyStringError,
391
- InvalidProxyURLError,
392
- ProtocolConstraintError,
393
- ProxyServer,
394
- ProxyStringError,
395
- )
396
-
397
- try:
398
- proxy = ProxyServer.from_string("invalid:format:extra:fields:123")
399
- except InvalidProxyStringError as e:
400
- print(f"String parsing error for '{e.proxy_string}': {e}")
401
-
402
- try:
403
- proxy = ProxyServer(host="2001:db8::1", protocol="socks4")
404
- except ProtocolConstraintError as e:
405
- print(f"Constraint violated for {e.protocol} on host {e.host}: {e}")
406
-
407
- try:
408
- proxy = ProxyServer.from_url("ftp://proxy.com:8080")
409
- except InvalidProxyURLError as e:
410
- print(f"URL error for '{e.url}': {e}")
411
- except ProxyStringError as e:
412
- print(f"General proxy error: {e}")
413
- ```
414
-
415
- ---
416
-
417
- ## Development
418
-
419
- Requirements: Python 3.12+, [`uv`](https://docs.astral.sh/uv/)
420
-
421
- ```bash
422
- # Clone the repository
423
- git clone https://github.com/sergey-scat/proxy-string.git
424
- cd proxy-string
425
-
426
- # Install dependencies including optional backends
427
- uv sync --all-extras
428
-
429
- # Run the test suite with coverage
430
- uv run pytest
431
-
432
- # Check code formatting and lints
433
- uv run ruff check
434
- uv run ruff format --check
435
-
436
- # Type check
437
- uv run ty check src/proxy_string
438
- ```
439
-
440
- ---
441
-
442
- ## License
443
-
444
- This project is licensed under the [MIT License](LICENSE).
File without changes
File without changes