proxy-string 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,185 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py,cover
50
+ .hypothesis/
51
+ .pytest_cache/
52
+ cover/
53
+
54
+ # Translations
55
+ *.mo
56
+ *.pot
57
+
58
+ # Django stuff:
59
+ *.log
60
+ local_settings.py
61
+ db.sqlite3
62
+ db.sqlite3-journal
63
+
64
+ # Flask stuff:
65
+ instance/
66
+ .webassets-cache
67
+
68
+ # Scrapy stuff:
69
+ .scrapy
70
+
71
+ # Sphinx documentation
72
+ docs/_build/
73
+
74
+ # PyBuilder
75
+ .pybuilder/
76
+ target/
77
+
78
+ # Jupyter Notebook
79
+ .ipynb_checkpoints
80
+
81
+ # IPython
82
+ profile_default/
83
+ ipython_config.py
84
+
85
+ # pyenv
86
+ # For a library or package, you might want to ignore these files since the code is
87
+ # intended to run in multiple environments; otherwise, check them in:
88
+ # .python-version
89
+
90
+ # pipenv
91
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
93
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
94
+ # install all needed dependencies.
95
+ #Pipfile.lock
96
+
97
+ # UV
98
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
99
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
100
+ # commonly ignored for libraries.
101
+ #uv.lock
102
+
103
+ # poetry
104
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
106
+ # commonly ignored for libraries.
107
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108
+ #poetry.lock
109
+
110
+ # pdm
111
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
112
+ #pdm.lock
113
+ # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
114
+ # in version control.
115
+ # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
116
+ .pdm.toml
117
+ .pdm-python
118
+ .pdm-build/
119
+
120
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
121
+ __pypackages__/
122
+
123
+ # Celery stuff
124
+ celerybeat-schedule
125
+ celerybeat.pid
126
+
127
+ # SageMath parsed files
128
+ *.sage.py
129
+
130
+ # Environments
131
+ .env
132
+ .venv
133
+ env/
134
+ venv/
135
+ ENV/
136
+ env.bak/
137
+ venv.bak/
138
+
139
+ # Spyder project settings
140
+ .spyderproject
141
+ .spyproject
142
+
143
+ # Rope project settings
144
+ .ropeproject
145
+
146
+ # mkdocs documentation
147
+ /site
148
+
149
+ # mypy
150
+ .mypy_cache/
151
+ .dmypy.json
152
+ dmypy.json
153
+
154
+ # Pyre type checker
155
+ .pyre/
156
+
157
+ # pytype static type analyzer
158
+ .pytype/
159
+
160
+ # Cython debug symbols
161
+ cython_debug/
162
+
163
+ # PyCharm
164
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
165
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
166
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
167
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
168
+ #.idea/
169
+
170
+ # Ruff stuff:
171
+ .ruff_cache/
172
+
173
+ # PyPI configuration file
174
+ .pypirc
175
+
176
+ .old
177
+ .tests.old
178
+ test.py
179
+ test2.py
180
+ test3.py
181
+ *.wpr
182
+ *.wpu
183
+
184
+ # Antigravity agents / skills
185
+ .agents/
@@ -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.
@@ -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).