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/enums.py ADDED
@@ -0,0 +1,39 @@
1
+ """Enums for proxy protocols, host types, and string formats."""
2
+
3
+ from enum import StrEnum
4
+
5
+
6
+ class ProxyServerProtocol(StrEnum):
7
+ """Supported network protocols for proxy servers."""
8
+
9
+ HTTP = "http"
10
+ HTTPS = "https"
11
+ SOCKS4 = "socks4"
12
+ SOCKS5 = "socks5"
13
+
14
+
15
+ PROXY_DEFAULT_PORT_BY_PROTOCOL = {
16
+ ProxyServerProtocol.HTTP: 80,
17
+ ProxyServerProtocol.HTTPS: 443,
18
+ ProxyServerProtocol.SOCKS4: 1080,
19
+ ProxyServerProtocol.SOCKS5: 1080,
20
+ }
21
+
22
+
23
+ class HostValueType(StrEnum):
24
+ """Classification of the host representation type."""
25
+
26
+ HOSTNAME = "hostname"
27
+ IPV4 = "ipv4"
28
+ IPV6 = "ipv6"
29
+
30
+
31
+ class ProxyStringFormat(StrEnum):
32
+ """Supported serialization and parsing formats for proxy strings."""
33
+
34
+ URL = "url"
35
+ HOST_PORT = "host:port"
36
+ USER_PASS_HOST_PORT = "user:pass:host:port"
37
+ USER_PASS_AT_HOST_PORT = "user:pass@host:port"
38
+ HOST_PORT_USER_PASS = "host:port:user:pass"
39
+ HOST_PORT_AT_USER_PASS = "host:port@user:pass"
@@ -0,0 +1,63 @@
1
+ """Exceptions for proxy-string."""
2
+
3
+
4
+ class ProxyStringError(Exception):
5
+ """Base exception for all proxy-string errors."""
6
+
7
+
8
+ class InvalidProxyStringError(ProxyStringError):
9
+ """Raised when the input proxy string is invalid or cannot be parsed."""
10
+
11
+ def __init__(self, message: str, *, proxy_string: str | None = None) -> None:
12
+ super().__init__(message)
13
+ self.proxy_string = proxy_string
14
+
15
+
16
+ class InvalidProxyURLError(ProxyStringError):
17
+ """Raised when the input proxy URL is malformed or invalid."""
18
+
19
+ def __init__(self, message: str, *, url: str | None = None) -> None:
20
+ super().__init__(message)
21
+ self.url = url
22
+
23
+
24
+ class ProxyConfigurationError(ProxyStringError):
25
+ """Base exception for proxy configuration and constraint errors."""
26
+
27
+
28
+ class ProtocolConstraintError(ProxyConfigurationError):
29
+ """Raised when protocol network constraints are violated."""
30
+
31
+ def __init__(
32
+ self,
33
+ message: str,
34
+ *,
35
+ protocol: str | None = None,
36
+ host: str | None = None,
37
+ ) -> None:
38
+ super().__init__(message)
39
+ self.protocol = protocol
40
+ self.host = host
41
+
42
+
43
+ class UnsupportedPackageError(ProxyConfigurationError):
44
+ """Raised when a third-party client library is not supported."""
45
+
46
+ def __init__(self, message: str, *, package_name: str | None = None) -> None:
47
+ super().__init__(message)
48
+ self.package_name = package_name
49
+
50
+
51
+ class ProtocolNotSupportedError(ProxyConfigurationError):
52
+ """Raised when a proxy protocol is not supported by the target library."""
53
+
54
+ def __init__(
55
+ self,
56
+ message: str,
57
+ *,
58
+ package_name: str | None = None,
59
+ protocol: str | None = None,
60
+ ) -> None:
61
+ super().__init__(message)
62
+ self.package_name = package_name
63
+ self.protocol = protocol
@@ -0,0 +1,149 @@
1
+ """Parsers and regex patterns for text-formatted proxy strings."""
2
+
3
+ import re
4
+ from contextlib import suppress
5
+ from typing import Any
6
+
7
+ from .enums import ProxyStringFormat
8
+ from .exceptions import InvalidProxyStringError, ProxyStringError
9
+ from .whatwg_url import parse_url
10
+
11
+ PROXY_STRING_FORMATS = {
12
+ ProxyStringFormat.HOST_PORT: "{host}:{port}",
13
+ ProxyStringFormat.USER_PASS_HOST_PORT: "{username}:{password}:{host}:{port}",
14
+ ProxyStringFormat.USER_PASS_AT_HOST_PORT: "{username}:{password}@{host}:{port}",
15
+ ProxyStringFormat.HOST_PORT_USER_PASS: "{host}:{port}:{username}:{password}",
16
+ ProxyStringFormat.HOST_PORT_AT_USER_PASS: "{host}:{port}@{username}:{password}",
17
+ }
18
+
19
+ VALID_IPV6_ADDRESS_REGEX = (
20
+ r"(?:(?:[0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|(?:[0-9a-fA-F]{1,4}:){1,7}:"
21
+ r"|(?:[0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}"
22
+ r"|(?:[0-9a-fA-F]{1,4}:){1,5}(?::[0-9a-fA-F]{1,4}){1,2}"
23
+ r"|(?:[0-9a-fA-F]{1,4}:){1,4}(?::[0-9a-fA-F]{1,4}){1,3}"
24
+ r"|(?:[0-9a-fA-F]{1,4}:){1,3}(?::[0-9a-fA-F]{1,4}){1,4}"
25
+ r"|(?:[0-9a-fA-F]{1,4}:){1,2}(?::[0-9a-fA-F]{1,4}){1,5}"
26
+ r"|[0-9a-fA-F]{1,4}:(?:(?::[0-9a-fA-F]{1,4}){1,6})"
27
+ r"|:(?:(?::[0-9a-fA-F]{1,4}){1,7}|:)"
28
+ r"|fe80:(?::[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}"
29
+ r"|::(?:ffff(?::0{1,4}){0,1}:){0,1}(?:(?:25[0-5]|(?:2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}"
30
+ r"(?:25[0-5]|(?:2[0-4]|1{0,1}[0-9]){0,1}[0-9])"
31
+ r"|(?:[0-9a-fA-F]{1,4}:){1,4}:(?:(?:25[0-5]|(?:2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}"
32
+ r"(?:25[0-5]|(?:2[0-4]|1{0,1}[0-9]){0,1}[0-9]))"
33
+ )
34
+ HOST_PATTERN = rf"(?P<host>[^@:\s]+|\[?{VALID_IPV6_ADDRESS_REGEX}\]?)"
35
+ PORT_PATTERN = (
36
+ r"(?P<port>(?:6553[0-5]|655[0-2][0-9]|65[0-4][0-9]{2}|6[0-4][0-9]{3}|[1-5][0-9]{4}|[0-9]{1,4}))"
37
+ )
38
+ USERNAME_PATTERN = r"(?P<username>[^@:\s]*)"
39
+ PASSWORD_PATTERN = r"(?P<password>[^@:\s]*)"
40
+
41
+ PROXY_FORMAT_REGEXPS = {}
42
+ for psf_name, psf_value in PROXY_STRING_FORMATS.items():
43
+ re_pattern = psf_value.format(
44
+ host=HOST_PATTERN, port=PORT_PATTERN, username=USERNAME_PATTERN, password=PASSWORD_PATTERN
45
+ )
46
+ re_pattern = "^" + re_pattern + "$"
47
+ PROXY_FORMAT_REGEXPS[psf_name] = re.compile(re_pattern)
48
+
49
+
50
+ def parse_proxy_string(
51
+ proxy_string: str,
52
+ proxy_format: ProxyStringFormat,
53
+ ) -> dict[str, Any]:
54
+ """Parses a proxy string according to the specified format.
55
+
56
+ Args:
57
+ proxy_string: Proxy string to parse.
58
+ proxy_format: Expected ProxyStringFormat.
59
+
60
+ Returns:
61
+ dict[str, Any]: Extracted proxy parameters (host, port, username, password).
62
+
63
+ Raises:
64
+ InvalidProxyStringError: If the string does not match the expected format.
65
+ """
66
+ proxy_string = proxy_string.strip()
67
+ if proxy_format == ProxyStringFormat.URL:
68
+ return parse_url(proxy_string)
69
+
70
+ match = PROXY_FORMAT_REGEXPS[proxy_format].match(proxy_string)
71
+ if match is not None:
72
+ groups = match.groupdict()
73
+ username = groups.get("username")
74
+ password = groups.get("password")
75
+ if username == "" and password == "":
76
+ username = None
77
+ password = None
78
+ return {
79
+ "host": groups["host"],
80
+ "port": int(groups["port"]),
81
+ "username": username or None,
82
+ "password": password,
83
+ }
84
+
85
+ raise InvalidProxyStringError(
86
+ "Unable to parse the proxy string: invalid format.", proxy_string=proxy_string
87
+ )
88
+
89
+
90
+ def detect_possible_formats(
91
+ proxy_string: str,
92
+ ) -> tuple[tuple[ProxyStringFormat, dict[str, Any]], ...]:
93
+ """Detects viable proxy string formats and attempts to parse the string.
94
+
95
+ Note:
96
+ When credentials (usernames or passwords) contain only digits and fall into
97
+ a valid port range (0..65535), 4-part colon-delimited strings can be ambiguous.
98
+ Explicitly passing `ProxyStringFormat` is recommended in such cases.
99
+
100
+ Args:
101
+ proxy_string: Raw proxy string without scheme.
102
+
103
+ Returns:
104
+ tuple[tuple[ProxyStringFormat, dict[str, Any]], ...]: Parsed formats and data dictionaries.
105
+ """
106
+ proxy_string = proxy_string.strip()
107
+
108
+ # (1) check if proxy string is an URL
109
+ if "://" in proxy_string:
110
+ with suppress(ProxyStringError, ValueError):
111
+ return (
112
+ (ProxyStringFormat.URL, parse_proxy_string(proxy_string, ProxyStringFormat.URL)),
113
+ )
114
+ return ()
115
+
116
+ matches: list[tuple[ProxyStringFormat, dict[str, Any]]] = []
117
+
118
+ # (2) check if proxy string contains "@" ("u:p@h:p" or "h:p@u:p")
119
+ if "@" in proxy_string:
120
+ possible_formats = (
121
+ ProxyStringFormat.USER_PASS_AT_HOST_PORT,
122
+ ProxyStringFormat.HOST_PORT_AT_USER_PASS,
123
+ )
124
+ for fmt in possible_formats:
125
+ with suppress(ProxyStringError, ValueError):
126
+ matches.append((fmt, parse_proxy_string(proxy_string, fmt)))
127
+ return tuple(matches)
128
+
129
+ # (3) check if proxy string is just host + port (hostname and IPv4 only)
130
+ if proxy_string.count(":") == 1:
131
+ with suppress(ProxyStringError, ValueError):
132
+ return (
133
+ (
134
+ ProxyStringFormat.HOST_PORT,
135
+ parse_proxy_string(proxy_string, ProxyStringFormat.HOST_PORT),
136
+ ),
137
+ )
138
+ return ()
139
+
140
+ # (4) check for the rest formats
141
+ possible_formats = (
142
+ ProxyStringFormat.HOST_PORT, # actually, for IPv6 only
143
+ ProxyStringFormat.HOST_PORT_USER_PASS,
144
+ ProxyStringFormat.USER_PASS_HOST_PORT,
145
+ )
146
+ for fmt in possible_formats:
147
+ with suppress(ProxyStringError, ValueError):
148
+ matches.append((fmt, parse_proxy_string(proxy_string, fmt)))
149
+ return tuple(matches)
@@ -0,0 +1,117 @@
1
+ """URL parsing, escaping, and scheme resolution helpers."""
2
+
3
+ from urllib.parse import quote, unquote
4
+
5
+ from .enums import ProxyServerProtocol
6
+
7
+
8
+ def quote_all(input_string: str, encoding: str = "utf-8", errors: str = "strict") -> str:
9
+ """Percent-encodes all reserved characters in a string.
10
+
11
+ Encodes every character that is not alphanumeric, without treating
12
+ any characters as safe.
13
+
14
+ Args:
15
+ input_string: The string to percent-encode.
16
+ encoding: The text encoding to use (defaults to 'utf-8').
17
+ errors: Error handling scheme for decoding errors.
18
+
19
+ Returns:
20
+ str: The fully percent-encoded string.
21
+ """
22
+ return quote(input_string, safe="", encoding=encoding, errors=errors)
23
+
24
+
25
+ def unquote_all(input_string: str, encoding: str = "utf-8", errors: str = "strict") -> str:
26
+ """Decodes percent-encoded characters in a string.
27
+
28
+ Args:
29
+ input_string: The percent-encoded string.
30
+ encoding: The text encoding to use (defaults to 'utf-8').
31
+ errors: Error handling scheme for decoding errors.
32
+
33
+ Returns:
34
+ str: The decoded string.
35
+ """
36
+ return unquote(input_string, encoding=encoding, errors=errors)
37
+
38
+
39
+ def build_url(
40
+ scheme: str,
41
+ host: str,
42
+ port: int,
43
+ username: str | None = None,
44
+ password: str | None = None,
45
+ ) -> str:
46
+ """Constructs a standard URL string from individual proxy components.
47
+
48
+ Args:
49
+ scheme: The URL scheme/protocol (e.g. 'http', 'socks5h').
50
+ host: Hostname or IP address (IPv6 will be bracketed if needed).
51
+ port: Connection port number.
52
+ username: Optional username credential.
53
+ password: Optional password credential.
54
+
55
+ Returns:
56
+ str: Formatted URL string.
57
+ """
58
+ if username is not None and password is not None:
59
+ target_user_passw = f"{quote_all(username)}:{quote_all(password)}@"
60
+ elif username is not None:
61
+ target_user_passw = f"{quote_all(username)}@"
62
+ elif password is not None:
63
+ target_user_passw = f":{quote_all(password)}@"
64
+ else:
65
+ target_user_passw = ""
66
+
67
+ if ":" in host and not host.startswith("["):
68
+ host = f"[{host}]"
69
+
70
+ return f"{scheme}://{target_user_passw}{host}:{port}"
71
+
72
+
73
+ def get_scheme(
74
+ protocol: ProxyServerProtocol | str,
75
+ remote_dns: bool | None,
76
+ socks_ext: bool = True,
77
+ ) -> str:
78
+ """Determines the appropriate URL scheme based on protocol and DNS resolution mode.
79
+
80
+ Args:
81
+ protocol: Proxy protocol enum member or protocol name string.
82
+ remote_dns: Whether remote DNS resolution is enabled.
83
+ socks_ext: Whether to use extended SOCKS schemes ('socks4a', 'socks5h').
84
+
85
+ Returns:
86
+ str: Resolved scheme string.
87
+ """
88
+ protocol = protocol.lower()
89
+ if remote_dns and socks_ext:
90
+ if protocol == ProxyServerProtocol.SOCKS4:
91
+ return "socks4a"
92
+ if protocol == ProxyServerProtocol.SOCKS5:
93
+ return "socks5h"
94
+ return protocol
95
+
96
+
97
+ def get_protocol(scheme: str) -> tuple[ProxyServerProtocol, bool | None]:
98
+ """Resolves a scheme name into a ProxyServerProtocol and remote_dns flag.
99
+
100
+ Args:
101
+ scheme: URL scheme string (e.g. 'socks5h', 'http').
102
+
103
+ Returns:
104
+ tuple[ProxyServerProtocol, bool | None]: Tuple of protocol enum and remote_dns setting.
105
+
106
+ Raises:
107
+ ValueError: If scheme is not a recognized proxy protocol.
108
+ """
109
+ scheme = scheme.lower()
110
+ if scheme in ("socks5h", "socks4a"):
111
+ remote_dns = True
112
+ elif scheme in ("socks5", "socks4"):
113
+ remote_dns = None
114
+ else:
115
+ remote_dns = False
116
+ protocol = ProxyServerProtocol({"socks5h": "socks5", "socks4a": "socks4"}.get(scheme, scheme))
117
+ return protocol, remote_dns
@@ -0,0 +1,198 @@
1
+ """WHATWG URL standard backend integration and IDNA decoding."""
2
+
3
+ from functools import lru_cache
4
+ from ipaddress import IPv4Address, ip_address
5
+ from typing import Any
6
+
7
+ from . import url_tools
8
+ from .enums import PROXY_DEFAULT_PORT_BY_PROTOCOL, HostValueType, ProxyServerProtocol
9
+ from .exceptions import InvalidProxyURLError, ProtocolConstraintError, ProxyStringError
10
+
11
+ _backends: list[str] = []
12
+
13
+ try:
14
+ import can_ada
15
+
16
+ can_ada_parse = can_ada.parse
17
+
18
+ def can_ada_decode(v: str) -> str:
19
+ return can_ada.idna_decode(v.encode()) # type: ignore
20
+
21
+ _backends.append("can_ada")
22
+ except ImportError:
23
+ pass
24
+
25
+ try:
26
+ import ada_url
27
+
28
+ ada_url_parse = ada_url.URL
29
+
30
+ ada_url_decode = ada_url.idna_to_unicode
31
+ ada_url_host_type = ada_url.HostType
32
+ _backends.append("ada_url")
33
+ except ImportError:
34
+ pass
35
+
36
+ try:
37
+ import pywhatwgurl
38
+
39
+ pywhatwgurl_parse = pywhatwgurl.URL
40
+
41
+ def pywhatwgurl_decode(v: str) -> str:
42
+ return pywhatwgurl.domain_to_unicode(v, be_strict=True)
43
+
44
+ _backends.append("pywhatwgurl")
45
+ except ImportError:
46
+ pass
47
+
48
+ if not _backends:
49
+ raise ProxyStringError("No WHATWG/URL backend found!")
50
+
51
+ AVAILABLE_BACKENDS: tuple[str, ...] = tuple(_backends)
52
+ CURRENT_BACKEND: str = AVAILABLE_BACKENDS[0]
53
+
54
+
55
+ def _detect_host_type(host: str, parsed_url: Any) -> HostValueType:
56
+ """Detects host type for the parsed URL.
57
+
58
+ Args:
59
+ host: Host string (stripped of brackets if IPv6).
60
+ parsed_url: Parsed URL object from the backend parser.
61
+
62
+ Returns:
63
+ HostValueType: Detected classification of the host.
64
+ """
65
+ if CURRENT_BACKEND == "ada_url":
66
+ if parsed_url.host_type is ada_url_host_type.IPV4:
67
+ return HostValueType.IPV4
68
+ if parsed_url.host_type is ada_url_host_type.IPV6:
69
+ return HostValueType.IPV6
70
+ return HostValueType.HOSTNAME
71
+
72
+ try:
73
+ addr = ip_address(host)
74
+ except ValueError:
75
+ return HostValueType.HOSTNAME
76
+
77
+ return HostValueType.IPV4 if isinstance(addr, IPv4Address) else HostValueType.IPV6
78
+
79
+
80
+ def _extract_explicit_port(uri: str) -> int | None:
81
+ """Extracts an explicit port number from the URI authority component if present.
82
+
83
+ Args:
84
+ uri: The URI component following the scheme delimiter '://'.
85
+
86
+ Returns:
87
+ int | None: Explicit port number as integer, or None if no port is specified.
88
+ """
89
+ authority = uri.split("/")[0].split("?")[0].split("#")[0]
90
+ host_port = authority.rpartition("@")[2]
91
+ if "]" in host_port:
92
+ after_bracket = host_port.rpartition("]")[2]
93
+ if after_bracket.startswith(":"):
94
+ port_str = after_bracket[1:]
95
+ return int(port_str) if port_str.isdigit() else None
96
+ return None
97
+ if ":" in host_port:
98
+ port_str = host_port.rpartition(":")[2]
99
+ return int(port_str) if port_str.isdigit() else None
100
+ return None
101
+
102
+
103
+ @lru_cache
104
+ def _parse_url_cached(url: str) -> dict[str, Any]:
105
+ if "://" not in url:
106
+ raise InvalidProxyURLError("Proxy URL must be a valid absolute URL!", url=url)
107
+
108
+ scheme, _, uri = url.partition("://")
109
+ try:
110
+ protocol, remote_dns = url_tools.get_protocol(scheme)
111
+ except ValueError as e:
112
+ raise InvalidProxyURLError(f"Invalid proxy scheme: '{scheme}'", url=url) from e
113
+
114
+ parse = globals()[f"{CURRENT_BACKEND}_parse"]
115
+
116
+ normalized_url = f"http://{uri}"
117
+ try:
118
+ parsed_url = parse(normalized_url)
119
+ except Exception as e:
120
+ raise InvalidProxyURLError(f"Invalid proxy URL: '{url}'", url=url) from e
121
+
122
+ host = parsed_url.hostname
123
+ if not host:
124
+ raise InvalidProxyURLError("Proxy URL host is required.", url=url)
125
+
126
+ host = host.strip("[]")
127
+ port_str = parsed_url.port
128
+ parsed_port = int(port_str) if port_str and port_str != "0" else None
129
+ explicit_port = _extract_explicit_port(uri)
130
+ if parsed_port is not None:
131
+ port = parsed_port
132
+ elif explicit_port is not None and explicit_port != 0:
133
+ port = explicit_port
134
+ else:
135
+ port = PROXY_DEFAULT_PORT_BY_PROTOCOL[protocol]
136
+
137
+ authority = uri.split("/")[0].split("?")[0].split("#")[0]
138
+ username = url_tools.unquote_all(parsed_url.username) if parsed_url.username else None
139
+ if "@" in authority:
140
+ userinfo = authority.rpartition("@")[0]
141
+ password = url_tools.unquote_all(parsed_url.password) if ":" in userinfo else None
142
+ else:
143
+ password = None
144
+
145
+ host_type = _detect_host_type(host, parsed_url)
146
+
147
+ if host_type is HostValueType.IPV6 and protocol is ProxyServerProtocol.SOCKS4:
148
+ raise ProtocolConstraintError(
149
+ "SOCKS4 protocol does not support IPv6 addresses.",
150
+ protocol=protocol,
151
+ host=host,
152
+ )
153
+
154
+ return {
155
+ "protocol": protocol,
156
+ "host": host,
157
+ "port": port,
158
+ "username": username,
159
+ "password": password,
160
+ "remote_dns": remote_dns,
161
+ "host_value_type": host_type,
162
+ "skip_validation": True,
163
+ }
164
+
165
+
166
+ def parse_url(url: str) -> dict[str, Any]:
167
+ """Parses a proxy URL into a dictionary of proxy attributes.
168
+
169
+ Args:
170
+ url: Absolute proxy URL string.
171
+
172
+ Returns:
173
+ dict[str, Any]: Parsed proxy attributes.
174
+
175
+ Raises:
176
+ InvalidProxyURLError: If URL has no scheme, missing host, or SOCKS4 is used with IPv6.
177
+ """
178
+ return _parse_url_cached(url).copy()
179
+
180
+
181
+ def clear_cache() -> None:
182
+ """Clears internal WHATWG URL and IDNA parser caches."""
183
+ _parse_url_cached.cache_clear()
184
+ decode_idna.cache_clear()
185
+
186
+
187
+ @lru_cache
188
+ def decode_idna(encoded_domain: str) -> str:
189
+ """Decodes a punycode/IDNA domain to Unicode.
190
+
191
+ Args:
192
+ encoded_domain: Punycode-encoded domain name.
193
+
194
+ Returns:
195
+ str: Unicode representation of the domain name.
196
+ """
197
+ decode = globals()[f"{CURRENT_BACKEND}_decode"]
198
+ return decode(encoded_domain)