proxy-string 1.0.0__py3-none-any.whl
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.
- proxy_string/__init__.py +29 -0
- proxy_string/base.py +698 -0
- proxy_string/enums.py +39 -0
- proxy_string/exceptions.py +63 -0
- proxy_string/parsers.py +149 -0
- proxy_string/url_tools.py +117 -0
- proxy_string/whatwg_url.py +198 -0
- proxy_string-1.0.0.dist-info/METADATA +476 -0
- proxy_string-1.0.0.dist-info/RECORD +11 -0
- proxy_string-1.0.0.dist-info/WHEEL +4 -0
- proxy_string-1.0.0.dist-info/licenses/LICENSE +19 -0
|
@@ -0,0 +1,476 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: proxy-string
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Proxy server data representation and parser package.
|
|
5
|
+
Project-URL: Homepage, https://github.com/sergey-scat/proxy-server-parser
|
|
6
|
+
Project-URL: Issues, https://github.com/sergey-scat/proxy-server-parser/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.0.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-server-parser"><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--d1abbgf6aiiy.xn--p1ai`).
|
|
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://президент.рф:443")
|
|
322
|
+
|
|
323
|
+
print(proxy.host)
|
|
324
|
+
# xn--d1abbgf6aiiy.xn--p1ai
|
|
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-server-parser.git
|
|
456
|
+
cd proxy-server-parser
|
|
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).
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
proxy_string/__init__.py,sha256=gKq9CHjo7bY5syZ5Dum_XW5AFOQqdZxgAfLeEcLARNE,795
|
|
2
|
+
proxy_string/base.py,sha256=WrisKkTO4Qoa6iAyGoOccg3VuuxU-aozu_-NDidzaWs,25173
|
|
3
|
+
proxy_string/enums.py,sha256=Np52NV1K3RoqCFF1B0wqEIRdvFktqZldMD5XKXsjf0k,998
|
|
4
|
+
proxy_string/exceptions.py,sha256=hNtR4fGg9IA_U--tu1xnCST-3oZASdWQl1D2edeCdOI,1901
|
|
5
|
+
proxy_string/parsers.py,sha256=PT7nCijXvawViGOdZ5PY4-MwbsZB3HtsloUctRtgDc4,5791
|
|
6
|
+
proxy_string/url_tools.py,sha256=jyqXmX3Q1pkcE91iAf-H0FVhBJtAwRf0QwiqcWGPwD0,3825
|
|
7
|
+
proxy_string/whatwg_url.py,sha256=0fyKB6mNZNoGJiNrsPGxXZRr8DpEugZYuBbpcgN1WH0,6028
|
|
8
|
+
proxy_string-1.0.0.dist-info/METADATA,sha256=rO0Px05k3DJT--Hc-mdOJm8Z4v1AazFdK2zeUrcz-bI,17719
|
|
9
|
+
proxy_string-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
10
|
+
proxy_string-1.0.0.dist-info/licenses/LICENSE,sha256=6kbiFSfobTZ7beWiKnHpN902HgBx-Jzgcme0SvKqhKY,1091
|
|
11
|
+
proxy_string-1.0.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
Copyright (c) 2018 The Python Packaging Authority
|
|
2
|
+
|
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
4
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
5
|
+
in the Software without restriction, including without limitation the rights
|
|
6
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
7
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
8
|
+
furnished to do so, subject to the following conditions:
|
|
9
|
+
|
|
10
|
+
The above copyright notice and this permission notice shall be included in all
|
|
11
|
+
copies or substantial portions of the Software.
|
|
12
|
+
|
|
13
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
14
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
15
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
16
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
17
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
18
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
19
|
+
SOFTWARE.
|