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/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
+ )