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
proxy_string/base.py
ADDED
|
@@ -0,0 +1,698 @@
|
|
|
1
|
+
"""Main ProxyServer data class and conversion methods."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
from collections.abc import AsyncGenerator, Generator, Mapping
|
|
5
|
+
from contextlib import suppress
|
|
6
|
+
from ipaddress import IPv4Address, IPv6Address
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
from typing import Any, Literal, Self, overload
|
|
9
|
+
|
|
10
|
+
import aiofiles
|
|
11
|
+
from attrs import evolve, field, frozen, validators
|
|
12
|
+
|
|
13
|
+
from . import url_tools
|
|
14
|
+
from .enums import HostValueType, ProxyServerProtocol, ProxyStringFormat
|
|
15
|
+
from .exceptions import (
|
|
16
|
+
InvalidProxyStringError,
|
|
17
|
+
ProtocolConstraintError,
|
|
18
|
+
ProtocolNotSupportedError,
|
|
19
|
+
ProxyConfigurationError,
|
|
20
|
+
ProxyStringError,
|
|
21
|
+
UnsupportedPackageError,
|
|
22
|
+
)
|
|
23
|
+
from .parsers import PROXY_STRING_FORMATS, detect_possible_formats, parse_proxy_string
|
|
24
|
+
from .whatwg_url import decode_idna, parse_url
|
|
25
|
+
|
|
26
|
+
SupportedPackage = Literal[
|
|
27
|
+
"aiohttp",
|
|
28
|
+
"curl_cffi",
|
|
29
|
+
"httpx",
|
|
30
|
+
"httpx2",
|
|
31
|
+
"playwright",
|
|
32
|
+
"pycurl",
|
|
33
|
+
"requests",
|
|
34
|
+
"urllib",
|
|
35
|
+
"urllib3",
|
|
36
|
+
]
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _check_for_protocol_support(
|
|
40
|
+
proxy_conn_obj: "ProxyServer",
|
|
41
|
+
package_name: str,
|
|
42
|
+
supported_schemes: tuple[str, ...],
|
|
43
|
+
socks_ext: bool = True,
|
|
44
|
+
) -> None:
|
|
45
|
+
"""Verifies that the proxy protocol scheme is supported by the target client library.
|
|
46
|
+
|
|
47
|
+
Args:
|
|
48
|
+
proxy_conn_obj: ProxyServer instance to validate.
|
|
49
|
+
package_name: Name of the target client library.
|
|
50
|
+
supported_schemes: Tuple of scheme strings supported by the library.
|
|
51
|
+
socks_ext: Whether to use extended SOCKS schemes.
|
|
52
|
+
|
|
53
|
+
Raises:
|
|
54
|
+
ProtocolNotSupportedError: If the scheme is not in supported_schemes.
|
|
55
|
+
"""
|
|
56
|
+
scheme = url_tools.get_scheme(
|
|
57
|
+
proxy_conn_obj.protocol,
|
|
58
|
+
proxy_conn_obj.remote_dns,
|
|
59
|
+
socks_ext=socks_ext,
|
|
60
|
+
)
|
|
61
|
+
if scheme not in supported_schemes:
|
|
62
|
+
raise ProtocolNotSupportedError(
|
|
63
|
+
f"Package '{package_name}' does not support the '{scheme}' protocol.",
|
|
64
|
+
package_name=package_name,
|
|
65
|
+
protocol=scheme,
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _validate_protocol(inst: Any, attr: Any, value: ProxyServerProtocol) -> None:
|
|
70
|
+
"""Validates that protocol argument is a string or ProxyServerProtocol.
|
|
71
|
+
|
|
72
|
+
Args:
|
|
73
|
+
inst: Instance being validated.
|
|
74
|
+
attr: Attribute metadata.
|
|
75
|
+
value: Protocol value to validate.
|
|
76
|
+
|
|
77
|
+
Raises:
|
|
78
|
+
TypeError: If value is not a string or ProxyServerProtocol.
|
|
79
|
+
"""
|
|
80
|
+
if not isinstance(value, (str, ProxyServerProtocol)):
|
|
81
|
+
raise TypeError(f"'{attr.name}' must be str or ProxyServerProtocol (got {value!r}).")
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
@frozen
|
|
85
|
+
class ProxyServer:
|
|
86
|
+
"""Immutable representation of proxy server connection data and credentials.
|
|
87
|
+
|
|
88
|
+
Attributes:
|
|
89
|
+
host: Hostname or IP address of the proxy server.
|
|
90
|
+
port: Connection port number (0..65535).
|
|
91
|
+
protocol: Proxy network protocol (HTTP, HTTPS, SOCKS4, SOCKS5).
|
|
92
|
+
username: Optional authentication username.
|
|
93
|
+
password: Optional authentication password.
|
|
94
|
+
remote_dns: Whether DNS resolution should occur on the proxy server.
|
|
95
|
+
unicode_host: Unicode representation of the host (for IDN/punycode).
|
|
96
|
+
host_value_type: Host classification (HOSTNAME, IPV4, or IPV6).
|
|
97
|
+
"""
|
|
98
|
+
|
|
99
|
+
# main public properties
|
|
100
|
+
host: str = field(
|
|
101
|
+
validator=[validators.instance_of(str), validators.min_len(1)],
|
|
102
|
+
eq=True,
|
|
103
|
+
hash=True,
|
|
104
|
+
repr=True,
|
|
105
|
+
)
|
|
106
|
+
port: int = field(
|
|
107
|
+
default=0,
|
|
108
|
+
converter=int,
|
|
109
|
+
validator=[validators.ge(0), validators.le(65535)],
|
|
110
|
+
eq=True,
|
|
111
|
+
hash=True,
|
|
112
|
+
repr=True,
|
|
113
|
+
)
|
|
114
|
+
protocol: ProxyServerProtocol = field(
|
|
115
|
+
default=ProxyServerProtocol.HTTP,
|
|
116
|
+
validator=_validate_protocol,
|
|
117
|
+
eq=True,
|
|
118
|
+
hash=True,
|
|
119
|
+
repr=True,
|
|
120
|
+
kw_only=True,
|
|
121
|
+
)
|
|
122
|
+
username: str | None = field(
|
|
123
|
+
default=None,
|
|
124
|
+
validator=validators.optional(validators.instance_of(str)),
|
|
125
|
+
eq=True,
|
|
126
|
+
hash=True,
|
|
127
|
+
repr=lambda v: repr(v) if v is not None else "None",
|
|
128
|
+
kw_only=True,
|
|
129
|
+
)
|
|
130
|
+
password: str | None = field(
|
|
131
|
+
default=None,
|
|
132
|
+
validator=validators.optional(validators.instance_of(str)),
|
|
133
|
+
eq=True,
|
|
134
|
+
hash=True,
|
|
135
|
+
repr=lambda v: "'***'" if v is not None else "None",
|
|
136
|
+
kw_only=True,
|
|
137
|
+
)
|
|
138
|
+
remote_dns: bool | None = field(
|
|
139
|
+
default=None,
|
|
140
|
+
validator=validators.optional(validators.instance_of(bool)),
|
|
141
|
+
eq=True,
|
|
142
|
+
hash=True,
|
|
143
|
+
repr=True,
|
|
144
|
+
kw_only=True,
|
|
145
|
+
)
|
|
146
|
+
# private properties
|
|
147
|
+
_host_value_type: HostValueType | None = field(
|
|
148
|
+
default=None,
|
|
149
|
+
validator=validators.optional(validators.instance_of(HostValueType)),
|
|
150
|
+
eq=False,
|
|
151
|
+
hash=False,
|
|
152
|
+
repr=False,
|
|
153
|
+
kw_only=True,
|
|
154
|
+
)
|
|
155
|
+
_skip_validation: bool = field(
|
|
156
|
+
default=False,
|
|
157
|
+
validator=validators.instance_of(bool),
|
|
158
|
+
eq=False,
|
|
159
|
+
hash=False,
|
|
160
|
+
repr=False,
|
|
161
|
+
kw_only=True,
|
|
162
|
+
)
|
|
163
|
+
|
|
164
|
+
def __attrs_post_init__(self) -> None:
|
|
165
|
+
"""Sets default port and resolves default remote_dns flag for the protocol."""
|
|
166
|
+
if self._skip_validation:
|
|
167
|
+
if self._host_value_type is None:
|
|
168
|
+
raise ProxyConfigurationError(
|
|
169
|
+
"The 'host_value_type' parameter must be specified when validation is skipped."
|
|
170
|
+
)
|
|
171
|
+
object.__setattr__(self, "_skip_validation", False)
|
|
172
|
+
return
|
|
173
|
+
|
|
174
|
+
scheme = url_tools.get_scheme(self.protocol, self.remote_dns)
|
|
175
|
+
if scheme in ("http", "https") and self.remote_dns is True:
|
|
176
|
+
raise ProtocolConstraintError(
|
|
177
|
+
f"{scheme.upper()} protocol does not support remote DNS resolution.",
|
|
178
|
+
protocol=scheme,
|
|
179
|
+
host=self.host,
|
|
180
|
+
)
|
|
181
|
+
elif scheme in ("socks4a", "socks5h") and self.remote_dns is False:
|
|
182
|
+
raise ProtocolConstraintError(
|
|
183
|
+
f"Conflicting configuration: scheme '{scheme}' requires remote DNS resolution, "
|
|
184
|
+
"but 'remote_dns' is set to False.",
|
|
185
|
+
protocol=scheme,
|
|
186
|
+
host=self.host,
|
|
187
|
+
)
|
|
188
|
+
|
|
189
|
+
parsed = parse_url(
|
|
190
|
+
url_tools.build_url(scheme, self.host, self.port, self.username, self.password)
|
|
191
|
+
)
|
|
192
|
+
|
|
193
|
+
remote_dns = self.remote_dns if parsed["remote_dns"] is None else parsed["remote_dns"]
|
|
194
|
+
|
|
195
|
+
object.__setattr__(self, "protocol", parsed["protocol"])
|
|
196
|
+
object.__setattr__(self, "host", parsed["host"])
|
|
197
|
+
object.__setattr__(self, "port", parsed["port"])
|
|
198
|
+
object.__setattr__(self, "username", parsed["username"])
|
|
199
|
+
object.__setattr__(self, "password", parsed["password"])
|
|
200
|
+
object.__setattr__(self, "remote_dns", remote_dns)
|
|
201
|
+
object.__setattr__(self, "_host_value_type", parsed["host_value_type"])
|
|
202
|
+
object.__setattr__(self, "_skip_validation", False)
|
|
203
|
+
|
|
204
|
+
@property
|
|
205
|
+
def url(self) -> str:
|
|
206
|
+
"""Returns the full URL representation including credentials.
|
|
207
|
+
|
|
208
|
+
Returns:
|
|
209
|
+
str: Absolute proxy URL.
|
|
210
|
+
"""
|
|
211
|
+
return self.to_url()
|
|
212
|
+
|
|
213
|
+
@property
|
|
214
|
+
def origin(self) -> str:
|
|
215
|
+
"""Returns the origin URL excluding authentication credentials.
|
|
216
|
+
|
|
217
|
+
Returns:
|
|
218
|
+
str: Proxy origin URL without credentials.
|
|
219
|
+
"""
|
|
220
|
+
return self.to_url(exclude_credentials=True)
|
|
221
|
+
|
|
222
|
+
@property
|
|
223
|
+
def unicode_host(self) -> str:
|
|
224
|
+
"""Returns the host decoded from IDNA Punycode to Unicode if applicable.
|
|
225
|
+
|
|
226
|
+
Returns:
|
|
227
|
+
str: Unicode representation of the host name.
|
|
228
|
+
"""
|
|
229
|
+
if self._host_value_type is HostValueType.HOSTNAME:
|
|
230
|
+
return decode_idna(self.host)
|
|
231
|
+
return self.host
|
|
232
|
+
|
|
233
|
+
@property
|
|
234
|
+
def unicode_url(self) -> str:
|
|
235
|
+
"""Returns the URL representation with Unicode host and credentials.
|
|
236
|
+
|
|
237
|
+
Returns:
|
|
238
|
+
str: Proxy URL with decoded Unicode hostname.
|
|
239
|
+
"""
|
|
240
|
+
scheme = url_tools.get_scheme(self.protocol, self.remote_dns, socks_ext=True)
|
|
241
|
+
return url_tools.build_url(
|
|
242
|
+
scheme, self.unicode_host, self.port, self.username, self.password
|
|
243
|
+
)
|
|
244
|
+
|
|
245
|
+
@property
|
|
246
|
+
def host_ip_address(self) -> IPv4Address | IPv6Address | None:
|
|
247
|
+
"""Returns the IP address object if the host is an IP, otherwise None.
|
|
248
|
+
|
|
249
|
+
Returns:
|
|
250
|
+
IPv4Address | IPv6Address | None: Parsed IP address object or None.
|
|
251
|
+
"""
|
|
252
|
+
if self._host_value_type is HostValueType.IPV4:
|
|
253
|
+
return IPv4Address(self.host)
|
|
254
|
+
if self._host_value_type is HostValueType.IPV6:
|
|
255
|
+
return IPv6Address(self.host)
|
|
256
|
+
return None
|
|
257
|
+
|
|
258
|
+
@property
|
|
259
|
+
def host_value_type(self) -> HostValueType:
|
|
260
|
+
"""Returns the classification of the host (HOSTNAME, IPV4, or IPV6).
|
|
261
|
+
|
|
262
|
+
Returns:
|
|
263
|
+
HostValueType: Host classification enum member.
|
|
264
|
+
"""
|
|
265
|
+
assert self._host_value_type is not None
|
|
266
|
+
return self._host_value_type
|
|
267
|
+
|
|
268
|
+
@property
|
|
269
|
+
def is_authenticated(self) -> bool:
|
|
270
|
+
"""Returns True if the proxy has credentials (username or password).
|
|
271
|
+
|
|
272
|
+
Returns:
|
|
273
|
+
bool: True if username or password is set, False otherwise.
|
|
274
|
+
"""
|
|
275
|
+
return bool(self.username or self.password)
|
|
276
|
+
|
|
277
|
+
@property
|
|
278
|
+
def is_socks(self) -> bool:
|
|
279
|
+
"""Returns True if the proxy protocol is a SOCKS protocol (SOCKS4 or SOCKS5).
|
|
280
|
+
|
|
281
|
+
Returns:
|
|
282
|
+
bool: True if protocol is SOCKS4 or SOCKS5, False otherwise.
|
|
283
|
+
"""
|
|
284
|
+
return self.protocol in (
|
|
285
|
+
ProxyServerProtocol.SOCKS4,
|
|
286
|
+
ProxyServerProtocol.SOCKS5,
|
|
287
|
+
)
|
|
288
|
+
|
|
289
|
+
@property
|
|
290
|
+
def is_ssl(self) -> bool:
|
|
291
|
+
"""Returns True if the proxy connection uses TLS/SSL (HTTPS).
|
|
292
|
+
|
|
293
|
+
Returns:
|
|
294
|
+
bool: True if protocol is HTTPS, False otherwise.
|
|
295
|
+
"""
|
|
296
|
+
return self.protocol is ProxyServerProtocol.HTTPS
|
|
297
|
+
|
|
298
|
+
def __str__(self) -> str:
|
|
299
|
+
"""Returns the URL representation of the proxy server."""
|
|
300
|
+
return self.to_url()
|
|
301
|
+
|
|
302
|
+
@classmethod
|
|
303
|
+
def from_dict(cls, input_dict: Mapping[str, Any]) -> Self:
|
|
304
|
+
"""Creates a ProxyServer instance from a dictionary of parameters.
|
|
305
|
+
|
|
306
|
+
Args:
|
|
307
|
+
input_dict: Dictionary containing proxy configuration keys
|
|
308
|
+
('host', 'port', 'protocol' or 'scheme', 'username', 'password', 'remote_dns').
|
|
309
|
+
|
|
310
|
+
Returns:
|
|
311
|
+
ProxyServer: A new ProxyServer instance.
|
|
312
|
+
|
|
313
|
+
Raises:
|
|
314
|
+
TypeError: If input_dict is not a Mapping.
|
|
315
|
+
ProxyConfigurationError: If 'host' is missing or empty.
|
|
316
|
+
"""
|
|
317
|
+
if not isinstance(input_dict, Mapping):
|
|
318
|
+
raise TypeError("Input data must be a dictionary or mapping!")
|
|
319
|
+
|
|
320
|
+
if "host" not in input_dict or not input_dict["host"]:
|
|
321
|
+
raise ProxyConfigurationError("Input dictionary must contain a non-empty 'host' key.")
|
|
322
|
+
|
|
323
|
+
port = input_dict.get("port")
|
|
324
|
+
kwargs: dict[str, Any] = {
|
|
325
|
+
"host": input_dict["host"],
|
|
326
|
+
# first try to get "scheme" since scheme can be "socks4a" or "socks5h"
|
|
327
|
+
"protocol": input_dict.get(
|
|
328
|
+
"scheme", input_dict.get("protocol", ProxyServerProtocol.HTTP)
|
|
329
|
+
),
|
|
330
|
+
"username": input_dict.get("username"),
|
|
331
|
+
"password": input_dict.get("password"),
|
|
332
|
+
"remote_dns": input_dict.get("remote_dns"),
|
|
333
|
+
}
|
|
334
|
+
if port is not None:
|
|
335
|
+
kwargs["port"] = port
|
|
336
|
+
|
|
337
|
+
return cls(**kwargs)
|
|
338
|
+
|
|
339
|
+
@classmethod
|
|
340
|
+
def from_json(cls, input_json: str) -> Self:
|
|
341
|
+
"""Creates a ProxyServer instance from a JSON-formatted string.
|
|
342
|
+
|
|
343
|
+
Args:
|
|
344
|
+
input_json: JSON string representing proxy parameters.
|
|
345
|
+
|
|
346
|
+
Returns:
|
|
347
|
+
ProxyServer: A new ProxyServer instance.
|
|
348
|
+
|
|
349
|
+
Raises:
|
|
350
|
+
json.JSONDecodeError: If input_json is not valid JSON.
|
|
351
|
+
"""
|
|
352
|
+
input_dict = json.loads(input_json)
|
|
353
|
+
return cls.from_dict(input_dict)
|
|
354
|
+
|
|
355
|
+
@classmethod
|
|
356
|
+
def from_string(
|
|
357
|
+
cls,
|
|
358
|
+
proxy_string: str,
|
|
359
|
+
*,
|
|
360
|
+
string_format: ProxyStringFormat | None = None,
|
|
361
|
+
protocol: ProxyServerProtocol | None = None,
|
|
362
|
+
) -> Self:
|
|
363
|
+
"""Creates a ProxyServer instance by parsing a formatted proxy string.
|
|
364
|
+
|
|
365
|
+
Args:
|
|
366
|
+
proxy_string: Formatted proxy string (e.g. 'host:port', 'user:pass@host:port').
|
|
367
|
+
string_format: Optional explicit ProxyStringFormat to match against.
|
|
368
|
+
Recommended when usernames or passwords are numeric to avoid
|
|
369
|
+
port ambiguity in 4-part colon-delimited strings.
|
|
370
|
+
protocol: Optional protocol override (defaults to parsed protocol or HTTP).
|
|
371
|
+
|
|
372
|
+
Returns:
|
|
373
|
+
ProxyServer: A new ProxyServer instance.
|
|
374
|
+
|
|
375
|
+
Raises:
|
|
376
|
+
InvalidProxyStringError: If the string does not match the expected format.
|
|
377
|
+
"""
|
|
378
|
+
proxy_string = proxy_string.strip()
|
|
379
|
+
if string_format:
|
|
380
|
+
parsed_proxy = dict(parse_proxy_string(proxy_string, string_format))
|
|
381
|
+
if protocol:
|
|
382
|
+
parsed_proxy["protocol"] = protocol
|
|
383
|
+
parsed_proxy.pop("skip_validation", None)
|
|
384
|
+
return cls(**parsed_proxy)
|
|
385
|
+
|
|
386
|
+
possible_formats = detect_possible_formats(proxy_string)
|
|
387
|
+
|
|
388
|
+
for _, parsed_proxy in possible_formats:
|
|
389
|
+
parsed = dict(parsed_proxy)
|
|
390
|
+
if protocol:
|
|
391
|
+
parsed["protocol"] = protocol
|
|
392
|
+
parsed.pop("skip_validation", None)
|
|
393
|
+
|
|
394
|
+
with suppress(ProxyStringError, ValueError):
|
|
395
|
+
return cls(**parsed)
|
|
396
|
+
|
|
397
|
+
raise InvalidProxyStringError(
|
|
398
|
+
f"Unable to parse the proxy string: '{proxy_string}'!", proxy_string=proxy_string
|
|
399
|
+
)
|
|
400
|
+
|
|
401
|
+
@classmethod
|
|
402
|
+
def from_url(cls, url: str) -> Self:
|
|
403
|
+
"""Creates a ProxyServer instance by parsing a proxy URL.
|
|
404
|
+
|
|
405
|
+
Args:
|
|
406
|
+
url: A complete proxy URL (e.g. 'http://user:pass@proxy.com:8080').
|
|
407
|
+
|
|
408
|
+
Returns:
|
|
409
|
+
ProxyServer: A new ProxyServer instance.
|
|
410
|
+
|
|
411
|
+
Raises:
|
|
412
|
+
InvalidProxyURLError: If the URL format, scheme, or host is invalid.
|
|
413
|
+
"""
|
|
414
|
+
return cls(**parse_url(url))
|
|
415
|
+
|
|
416
|
+
@classmethod
|
|
417
|
+
def from_file( # noqa: PLR0913
|
|
418
|
+
cls,
|
|
419
|
+
input_file: str | Path,
|
|
420
|
+
*,
|
|
421
|
+
string_format: ProxyStringFormat | None = None,
|
|
422
|
+
protocol: ProxyServerProtocol | None = None,
|
|
423
|
+
encoding: str = "utf-8",
|
|
424
|
+
encoding_errors: str = "strict",
|
|
425
|
+
ignore_invalid: bool = False,
|
|
426
|
+
) -> Generator[Self, None, None]:
|
|
427
|
+
"""Yields ProxyServer instances by reading proxy strings from a file.
|
|
428
|
+
|
|
429
|
+
Args:
|
|
430
|
+
input_file: Path to the proxy text file.
|
|
431
|
+
string_format: Optional explicit ProxyStringFormat for rows.
|
|
432
|
+
Recommended when usernames or passwords are numeric to avoid
|
|
433
|
+
port ambiguity in 4-part colon-delimited strings.
|
|
434
|
+
protocol: Optional protocol override for all rows.
|
|
435
|
+
encoding: Text encoding of the file (defaults to 'utf-8').
|
|
436
|
+
encoding_errors: Text codec error handling mode passed to open() (defaults to 'strict').
|
|
437
|
+
ignore_invalid: If True, rows that cannot be parsed are skipped.
|
|
438
|
+
If False (default), raises InvalidProxyStringError or ValueError.
|
|
439
|
+
|
|
440
|
+
Yields:
|
|
441
|
+
ProxyServer: Parsed proxy server instances.
|
|
442
|
+
|
|
443
|
+
Raises:
|
|
444
|
+
InvalidProxyStringError: If a row cannot be parsed and ignore_invalid is False.
|
|
445
|
+
"""
|
|
446
|
+
with open(input_file, encoding=encoding, errors=encoding_errors) as infile:
|
|
447
|
+
for row in infile:
|
|
448
|
+
line = row.strip()
|
|
449
|
+
if not line or line.startswith("#"):
|
|
450
|
+
continue
|
|
451
|
+
try:
|
|
452
|
+
yield cls.from_string(line, string_format=string_format, protocol=protocol)
|
|
453
|
+
except (ProxyStringError, ValueError):
|
|
454
|
+
if not ignore_invalid:
|
|
455
|
+
raise
|
|
456
|
+
|
|
457
|
+
@classmethod
|
|
458
|
+
async def from_file_async( # noqa: PLR0913
|
|
459
|
+
cls,
|
|
460
|
+
input_file: str | Path,
|
|
461
|
+
*,
|
|
462
|
+
string_format: ProxyStringFormat | None = None,
|
|
463
|
+
protocol: ProxyServerProtocol | None = None,
|
|
464
|
+
encoding: str = "utf-8",
|
|
465
|
+
encoding_errors: str = "strict",
|
|
466
|
+
ignore_invalid: bool = False,
|
|
467
|
+
) -> AsyncGenerator[Self, None]:
|
|
468
|
+
"""Asynchronously yields ProxyServer instances by reading a file.
|
|
469
|
+
|
|
470
|
+
Args:
|
|
471
|
+
input_file: Path to the proxy text file.
|
|
472
|
+
string_format: Optional explicit ProxyStringFormat for rows.
|
|
473
|
+
Recommended when usernames or passwords are numeric to avoid
|
|
474
|
+
port ambiguity in 4-part colon-delimited strings.
|
|
475
|
+
protocol: Optional protocol override for all rows.
|
|
476
|
+
encoding: Text encoding of the file (defaults to 'utf-8').
|
|
477
|
+
encoding_errors: Text codec error handling mode passed to open() (defaults to 'strict').
|
|
478
|
+
ignore_invalid: If True, rows that cannot be parsed are skipped.
|
|
479
|
+
If False (default), raises InvalidProxyStringError or ValueError.
|
|
480
|
+
|
|
481
|
+
Yields:
|
|
482
|
+
ProxyServer: Parsed proxy server instances.
|
|
483
|
+
|
|
484
|
+
Raises:
|
|
485
|
+
InvalidProxyStringError: If a row cannot be parsed and ignore_invalid is False.
|
|
486
|
+
"""
|
|
487
|
+
async with aiofiles.open(input_file, encoding=encoding, errors=encoding_errors) as infile:
|
|
488
|
+
async for row in infile:
|
|
489
|
+
line = row.strip()
|
|
490
|
+
if not line or line.startswith("#"):
|
|
491
|
+
continue
|
|
492
|
+
try:
|
|
493
|
+
yield cls.from_string(line, string_format=string_format, protocol=protocol)
|
|
494
|
+
except (ProxyStringError, ValueError):
|
|
495
|
+
if not ignore_invalid:
|
|
496
|
+
raise
|
|
497
|
+
|
|
498
|
+
def to_dict(self) -> dict[str, Any]:
|
|
499
|
+
"""Serializes proxy server attributes into a dictionary.
|
|
500
|
+
|
|
501
|
+
Returns:
|
|
502
|
+
dict: Dictionary with host, port, protocol, username, password, remote_dns.
|
|
503
|
+
"""
|
|
504
|
+
return {
|
|
505
|
+
"host": self.host,
|
|
506
|
+
"port": self.port,
|
|
507
|
+
"protocol": self.protocol,
|
|
508
|
+
"username": self.username,
|
|
509
|
+
"password": self.password,
|
|
510
|
+
"remote_dns": self.remote_dns,
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
def to_json(self) -> str:
|
|
514
|
+
"""Serializes proxy server attributes into a JSON string.
|
|
515
|
+
|
|
516
|
+
Returns:
|
|
517
|
+
str: JSON representation of the proxy server.
|
|
518
|
+
"""
|
|
519
|
+
return json.dumps(self.to_dict())
|
|
520
|
+
|
|
521
|
+
def to_string(
|
|
522
|
+
self,
|
|
523
|
+
string_format: ProxyStringFormat | None = None,
|
|
524
|
+
) -> str:
|
|
525
|
+
"""Formats the proxy server into a specified or auto-selected string format.
|
|
526
|
+
|
|
527
|
+
Args:
|
|
528
|
+
string_format: Format template from ProxyStringFormat. If None, defaults
|
|
529
|
+
to HOST_PORT_USER_PASS when credentials are present, otherwise HOST_PORT.
|
|
530
|
+
|
|
531
|
+
Returns:
|
|
532
|
+
str: Formatted proxy string.
|
|
533
|
+
"""
|
|
534
|
+
if string_format is ProxyStringFormat.URL:
|
|
535
|
+
return self.to_url()
|
|
536
|
+
|
|
537
|
+
if string_format is None:
|
|
538
|
+
string_format = (
|
|
539
|
+
ProxyStringFormat.HOST_PORT_USER_PASS
|
|
540
|
+
if self.username is not None or self.password is not None
|
|
541
|
+
else ProxyStringFormat.HOST_PORT
|
|
542
|
+
)
|
|
543
|
+
|
|
544
|
+
format_str = PROXY_STRING_FORMATS[string_format]
|
|
545
|
+
return format_str.format(
|
|
546
|
+
host=self.host,
|
|
547
|
+
port=self.port,
|
|
548
|
+
username=self.username or "",
|
|
549
|
+
password=self.password or "",
|
|
550
|
+
)
|
|
551
|
+
|
|
552
|
+
def to_url(self, socks_ext: bool = True, exclude_credentials: bool = False) -> str:
|
|
553
|
+
"""Serializes proxy server to URL string.
|
|
554
|
+
|
|
555
|
+
Args:
|
|
556
|
+
socks_ext: Whether to use extended SOCKS schemes ('socks4a', 'socks5h').
|
|
557
|
+
exclude_credentials: If True, omits username and password from the URL.
|
|
558
|
+
|
|
559
|
+
Returns:
|
|
560
|
+
str: Proxy server URL.
|
|
561
|
+
"""
|
|
562
|
+
scheme = url_tools.get_scheme(self.protocol, self.remote_dns, socks_ext)
|
|
563
|
+
|
|
564
|
+
if exclude_credentials:
|
|
565
|
+
return url_tools.build_url(scheme, self.host, self.port)
|
|
566
|
+
return url_tools.build_url(scheme, self.host, self.port, self.username, self.password)
|
|
567
|
+
|
|
568
|
+
def with_host(self, host: str) -> Self:
|
|
569
|
+
"""Returns a copy of the proxy with a modified host.
|
|
570
|
+
|
|
571
|
+
Args:
|
|
572
|
+
host: The new host name or IP address.
|
|
573
|
+
|
|
574
|
+
Returns:
|
|
575
|
+
Self: A new proxy server instance.
|
|
576
|
+
"""
|
|
577
|
+
return evolve(self, host=host)
|
|
578
|
+
|
|
579
|
+
def with_port(self, port: int) -> Self:
|
|
580
|
+
"""Returns a copy of the proxy with a modified port.
|
|
581
|
+
|
|
582
|
+
Args:
|
|
583
|
+
port: The new port number.
|
|
584
|
+
|
|
585
|
+
Returns:
|
|
586
|
+
Self: A new proxy server instance.
|
|
587
|
+
"""
|
|
588
|
+
return evolve(self, port=port)
|
|
589
|
+
|
|
590
|
+
def with_protocol(self, protocol: ProxyServerProtocol | str) -> Self:
|
|
591
|
+
"""Returns a copy of the proxy with a modified protocol.
|
|
592
|
+
|
|
593
|
+
Args:
|
|
594
|
+
protocol: The new proxy protocol enum member or protocol name string.
|
|
595
|
+
|
|
596
|
+
Returns:
|
|
597
|
+
Self: A new proxy server instance.
|
|
598
|
+
"""
|
|
599
|
+
return evolve(self, protocol=protocol)
|
|
600
|
+
|
|
601
|
+
def with_username(self, username: str | None) -> Self:
|
|
602
|
+
"""Returns a copy of the proxy with a modified username.
|
|
603
|
+
|
|
604
|
+
Args:
|
|
605
|
+
username: The new username credential.
|
|
606
|
+
|
|
607
|
+
Returns:
|
|
608
|
+
Self: A new proxy server instance.
|
|
609
|
+
"""
|
|
610
|
+
return evolve(self, username=username)
|
|
611
|
+
|
|
612
|
+
def with_password(self, password: str | None) -> Self:
|
|
613
|
+
"""Returns a copy of the proxy with a modified password.
|
|
614
|
+
|
|
615
|
+
Args:
|
|
616
|
+
password: The new password credential.
|
|
617
|
+
|
|
618
|
+
Returns:
|
|
619
|
+
Self: A new proxy server instance.
|
|
620
|
+
"""
|
|
621
|
+
return evolve(self, password=password)
|
|
622
|
+
|
|
623
|
+
def with_creds(self, username: str | None, password: str | None) -> Self:
|
|
624
|
+
"""Returns a copy of the proxy with modified credentials.
|
|
625
|
+
|
|
626
|
+
Args:
|
|
627
|
+
username: The new username credential.
|
|
628
|
+
password: The new password credential.
|
|
629
|
+
|
|
630
|
+
Returns:
|
|
631
|
+
Self: A new proxy server instance.
|
|
632
|
+
"""
|
|
633
|
+
return evolve(self, username=username, password=password)
|
|
634
|
+
|
|
635
|
+
def with_remote_dns(self, remote_dns: bool | None) -> Self:
|
|
636
|
+
"""Returns a copy of the proxy with a modified remote_dns flag.
|
|
637
|
+
|
|
638
|
+
Args:
|
|
639
|
+
remote_dns: Whether DNS resolution should occur on the proxy.
|
|
640
|
+
|
|
641
|
+
Returns:
|
|
642
|
+
Self: A new proxy server instance.
|
|
643
|
+
"""
|
|
644
|
+
return evolve(self, remote_dns=remote_dns)
|
|
645
|
+
|
|
646
|
+
@overload
|
|
647
|
+
def prepare_for(self, package_name: Literal["urllib", "requests"]) -> dict[str, str]: ...
|
|
648
|
+
|
|
649
|
+
@overload
|
|
650
|
+
def prepare_for(self, package_name: Literal["playwright"]) -> dict[str, str | None]: ...
|
|
651
|
+
|
|
652
|
+
@overload
|
|
653
|
+
def prepare_for(
|
|
654
|
+
self,
|
|
655
|
+
package_name: Literal["urllib3", "httpx", "httpx2", "aiohttp", "pycurl", "curl_cffi"],
|
|
656
|
+
) -> str: ...
|
|
657
|
+
|
|
658
|
+
@overload
|
|
659
|
+
def prepare_for(self, package_name: SupportedPackage | str) -> dict[str, Any] | str: ...
|
|
660
|
+
|
|
661
|
+
def prepare_for(self, package_name: SupportedPackage | str) -> dict[str, Any] | str:
|
|
662
|
+
"""Prepares proxy configuration for third-party libraries.
|
|
663
|
+
|
|
664
|
+
Args:
|
|
665
|
+
package_name: Target library name ('urllib', 'requests', 'urllib3',
|
|
666
|
+
'httpx', 'httpx2', 'aiohttp', 'playwright', 'pycurl', or 'curl_cffi').
|
|
667
|
+
|
|
668
|
+
Returns:
|
|
669
|
+
dict[str, Any] | str: Library-specific proxy configuration structure.
|
|
670
|
+
|
|
671
|
+
Raises:
|
|
672
|
+
UnsupportedPackageError: If the package is not supported.
|
|
673
|
+
ProtocolNotSupportedError: If the protocol is incompatible.
|
|
674
|
+
"""
|
|
675
|
+
match package_name.strip().lower():
|
|
676
|
+
case "urllib":
|
|
677
|
+
_check_for_protocol_support(self, "urllib", ("http", "https"))
|
|
678
|
+
url = self.to_url(socks_ext=True)
|
|
679
|
+
return {"http": url, "https": url}
|
|
680
|
+
case "requests":
|
|
681
|
+
url = self.to_url(socks_ext=True)
|
|
682
|
+
return {"http": url, "https": url}
|
|
683
|
+
case "urllib3" | "httpx" | "httpx2" | "aiohttp" | "pycurl" | "curl_cffi":
|
|
684
|
+
return self.to_url(socks_ext=True)
|
|
685
|
+
case "playwright":
|
|
686
|
+
_check_for_protocol_support(
|
|
687
|
+
self, "playwright", ("http", "https", "socks5"), socks_ext=False
|
|
688
|
+
)
|
|
689
|
+
return {
|
|
690
|
+
"server": self.to_url(socks_ext=False, exclude_credentials=True),
|
|
691
|
+
"username": self.username,
|
|
692
|
+
"password": self.password,
|
|
693
|
+
}
|
|
694
|
+
case _:
|
|
695
|
+
raise UnsupportedPackageError(
|
|
696
|
+
f"Package '{package_name}' is not supported.",
|
|
697
|
+
package_name=package_name,
|
|
698
|
+
)
|