nodemaven 0.1.0__tar.gz

nodemaven-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NodeMaven
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nodemaven-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: nodemaven
+Version: 0.1.0
+Summary: Build and validate proxy connection strings. No transport, no retries.
+Author-email: NodeMaven <alexandr.kazmin@nodemaven.com>
+License-Expression: MIT
+Project-URL: Homepage, https://nodemaven.com
+Keywords: proxy,residential-proxy,scraping,http-proxy,playwright
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=1.1.0; python_version < "3.11"
+Dynamic: license-file
+
+# nodemaven
+
+Build and validate proxy connection strings.
+
+This library opens no socket. It builds the username a proxy gateway expects,
+refuses the input that gateway would mishandle, and hands the result to whatever
+HTTP client you already use.
+
+```
+pip install nodemaven
+```
+
+## Quickstart
+
+```python
+import requests
+from nodemaven import Proxy
+
+proxy = Proxy(login="your-login", password="your-password",
+              country="us", filter="medium")
+
+r = requests.get("https://api.ipify.org", proxies=proxy.requests())
+print(r.text)
+```
+
+Credentials can come from the environment instead, so nothing is in your source:
+
+```python
+# NODEMAVEN_LOGIN and NODEMAVEN_PASSWORD
+proxy = Proxy(country="us", filter="medium")
+```
+
+The same identity, for other clients:
+
+```python
+proxy.url()          # http://user:pass@gate.nodemaven.com:8080  - httpx, aiohttp, curl
+proxy.requests()     # {"http": ..., "https": ...}
+proxy.httpx()        # {"http://": ..., "https://": ...}
+proxy.playwright()   # {"server": ..., "username": ..., "password": ...}
+proxy.username       # the username on its own
+proxy.server         # host:port, no credentials
+```
+
+With Playwright, Patchright or Puppeteer:
+
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch()
+    context = browser.new_context(proxy=proxy.playwright())
+```
+
+## Sticky sessions
+
+One `Proxy` is one identity. Pin it to a sticky session:
+
+```python
+held = proxy.session("order-4417")
+```
+
+**The session key is the whole parameter set, not the session id.**
+`country=us, sid=A` and `country=us, sid=A, filter=medium` are two different
+sessions on the gateway, so adding or removing any parameter moves you to a
+different exit address. That is why parameters change through a method that
+returns a new object rather than by assignment - the move is a different
+identity, and the code should say so:
+
+```python
+germany = proxy.replace(country="de")   # a new identity, a new exit
+plain   = proxy.replace(filter=None)    # also a new identity
+```
+
+## Why the validation is the point
+
+A gateway is bad at telling you that you got the username wrong. Measured
+against this one on 2026-08-10, seven kinds of bad input produce seven
+different reactions and not one of them names the cause:
+
+| you sent | the gateway answers |
+|---|---|
+| bad country | `406 Not Acceptable` |
+| bad region | `406 Not Acceptable` |
+| bad city | `500 Internal Server Error` |
+| bad `filter` value | `407 Proxy Authentication Required` |
+| bad `ttl` value | `407 Proxy Authentication Required` |
+| empty value | nothing, the connection hangs about 20 s |
+| **unknown parameter name** | **`200`, and the parameter is ignored** |
+
+The two `407` replies send you to check credentials that are correct. The last
+row is worse than any of them: the request succeeds, your code carries on, and
+the setting you asked for was never applied. Nothing that comes back over the
+wire can tell you.
+
+So this library checks before anything is sent:
+
+```python
+>>> Proxy(login="u", password="p", contry="us")
+ParamError: NodeMaven does not know the parameter 'contry': it is answered with
+200 and dropped, so the connection would succeed and your setting would NOT be
+applied. Known: ['city', 'country', 'filter', 'ipv4', 'isp', 'region', 'sid',
+'speed', 'ttl']
+```
+
+## What this library does not do
+
+**It does not retry.** That is deliberate, and it is the one design decision
+here taken against a measurement rather than a preference.
+
+Retrying a refused request is the thing that most reliably makes the next one
+worse: each retry confirms automation to the target and burns the exit range for
+everyone else sharing the pool. Measured over 1464 attempts, the chance that the
+next attempt succeeds, by how many failures came immediately before it:
+
+| failures before | P(next attempt succeeds) |
+|---|---|
+| 0 | 75% |
+| 1 | 21% |
+| 3 | 5.9% |
+| 5 | 5.8% |
+| 6 | 1.6% |
+| 7-9 | 0.5% |
+
+294 attempts were spent past six consecutive failures and returned 3 pages - 98
+attempts per delivered page, against 1.7 in a healthy session. A library that
+shipped automatic retry as a default would be spending that on your behalf
+without telling you.
+
+It also does not own an HTTP client, a connection pool or a browser. Those are
+yours, and they are better than anything a vendor SDK would bundle.
+
+## Other gateways
+
+Parameters are data, not hardcoded keywords. A gateway is one TOML file - its
+prefix, separators, session parameter and the set of parameter names it actually
+recognises - and a definition read from disk goes through the same builder and
+the same validation as the one shipped here:
+
+```python
+from nodemaven import Proxy, load_file
+
+mine = load_file("my-gateway.toml")
+proxy = Proxy(provider=mine, login="u", password="p", country="us")
+```
+
+Every definition carries a `status`. `measured` means traffic has gone through
+that gateway and the dialect was read off the wire. `documented` means it was
+transcribed from documentation and never exercised. Only `nodemaven` is shipped
+here, and it is `measured`.
+
+## Requirements
+
+Python 3.9 or newer. No dependencies on 3.11 and newer; `tomli` on older ones.
+
+## License
+
+MIT.

nodemaven-0.1.0/README.md

@@ -0,0 +1,157 @@
+# nodemaven
+
+Build and validate proxy connection strings.
+
+This library opens no socket. It builds the username a proxy gateway expects,
+refuses the input that gateway would mishandle, and hands the result to whatever
+HTTP client you already use.
+
+```
+pip install nodemaven
+```
+
+## Quickstart
+
+```python
+import requests
+from nodemaven import Proxy
+
+proxy = Proxy(login="your-login", password="your-password",
+              country="us", filter="medium")
+
+r = requests.get("https://api.ipify.org", proxies=proxy.requests())
+print(r.text)
+```
+
+Credentials can come from the environment instead, so nothing is in your source:
+
+```python
+# NODEMAVEN_LOGIN and NODEMAVEN_PASSWORD
+proxy = Proxy(country="us", filter="medium")
+```
+
+The same identity, for other clients:
+
+```python
+proxy.url()          # http://user:pass@gate.nodemaven.com:8080  - httpx, aiohttp, curl
+proxy.requests()     # {"http": ..., "https": ...}
+proxy.httpx()        # {"http://": ..., "https://": ...}
+proxy.playwright()   # {"server": ..., "username": ..., "password": ...}
+proxy.username       # the username on its own
+proxy.server         # host:port, no credentials
+```
+
+With Playwright, Patchright or Puppeteer:
+
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch()
+    context = browser.new_context(proxy=proxy.playwright())
+```
+
+## Sticky sessions
+
+One `Proxy` is one identity. Pin it to a sticky session:
+
+```python
+held = proxy.session("order-4417")
+```
+
+**The session key is the whole parameter set, not the session id.**
+`country=us, sid=A` and `country=us, sid=A, filter=medium` are two different
+sessions on the gateway, so adding or removing any parameter moves you to a
+different exit address. That is why parameters change through a method that
+returns a new object rather than by assignment - the move is a different
+identity, and the code should say so:
+
+```python
+germany = proxy.replace(country="de")   # a new identity, a new exit
+plain   = proxy.replace(filter=None)    # also a new identity
+```
+
+## Why the validation is the point
+
+A gateway is bad at telling you that you got the username wrong. Measured
+against this one on 2026-08-10, seven kinds of bad input produce seven
+different reactions and not one of them names the cause:
+
+| you sent | the gateway answers |
+|---|---|
+| bad country | `406 Not Acceptable` |
+| bad region | `406 Not Acceptable` |
+| bad city | `500 Internal Server Error` |
+| bad `filter` value | `407 Proxy Authentication Required` |
+| bad `ttl` value | `407 Proxy Authentication Required` |
+| empty value | nothing, the connection hangs about 20 s |
+| **unknown parameter name** | **`200`, and the parameter is ignored** |
+
+The two `407` replies send you to check credentials that are correct. The last
+row is worse than any of them: the request succeeds, your code carries on, and
+the setting you asked for was never applied. Nothing that comes back over the
+wire can tell you.
+
+So this library checks before anything is sent:
+
+```python
+>>> Proxy(login="u", password="p", contry="us")
+ParamError: NodeMaven does not know the parameter 'contry': it is answered with
+200 and dropped, so the connection would succeed and your setting would NOT be
+applied. Known: ['city', 'country', 'filter', 'ipv4', 'isp', 'region', 'sid',
+'speed', 'ttl']
+```
+
+## What this library does not do
+
+**It does not retry.** That is deliberate, and it is the one design decision
+here taken against a measurement rather than a preference.
+
+Retrying a refused request is the thing that most reliably makes the next one
+worse: each retry confirms automation to the target and burns the exit range for
+everyone else sharing the pool. Measured over 1464 attempts, the chance that the
+next attempt succeeds, by how many failures came immediately before it:
+
+| failures before | P(next attempt succeeds) |
+|---|---|
+| 0 | 75% |
+| 1 | 21% |
+| 3 | 5.9% |
+| 5 | 5.8% |
+| 6 | 1.6% |
+| 7-9 | 0.5% |
+
+294 attempts were spent past six consecutive failures and returned 3 pages - 98
+attempts per delivered page, against 1.7 in a healthy session. A library that
+shipped automatic retry as a default would be spending that on your behalf
+without telling you.
+
+It also does not own an HTTP client, a connection pool or a browser. Those are
+yours, and they are better than anything a vendor SDK would bundle.
+
+## Other gateways
+
+Parameters are data, not hardcoded keywords. A gateway is one TOML file - its
+prefix, separators, session parameter and the set of parameter names it actually
+recognises - and a definition read from disk goes through the same builder and
+the same validation as the one shipped here:
+
+```python
+from nodemaven import Proxy, load_file
+
+mine = load_file("my-gateway.toml")
+proxy = Proxy(provider=mine, login="u", password="p", country="us")
+```
+
+Every definition carries a `status`. `measured` means traffic has gone through
+that gateway and the dialect was read off the wire. `documented` means it was
+transcribed from documentation and never exercised. Only `nodemaven` is shipped
+here, and it is `measured`.
+
+## Requirements
+
+Python 3.9 or newer. No dependencies on 3.11 and newer; `tomli` on older ones.
+
+## License
+
+MIT.

nodemaven-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nodemaven"
+dynamic = ["version"]
+description = "Build and validate proxy connection strings. No transport, no retries."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "NodeMaven", email = "alexandr.kazmin@nodemaven.com" }]
+keywords = ["proxy", "residential-proxy", "scraping", "http-proxy", "playwright"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: Proxy Servers",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+dependencies = ["tomli>=1.1.0; python_version < '3.11'"]
+
+[project.urls]
+Homepage = "https://nodemaven.com"
+
+[tool.setuptools.dynamic]
+version = { attr = "nodemaven.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+nodemaven = ["py.typed", "data/providers/*.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nodemaven-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nodemaven-0.1.0/src/nodemaven/__init__.py

@@ -0,0 +1,42 @@
+"""nodemaven - build and validate proxy connection strings.
+
+This package builds the username a proxy gateway expects, refuses the input that
+gateway would mishandle, and hands the result to whatever HTTP client you
+already use. It opens no socket, holds no session and retries nothing.
+
+    >>> from nodemaven import Proxy
+    >>> proxy = Proxy(login="user", password="pass", country="us", filter="medium")
+    >>> requests.get("https://api.ipify.org", proxies=proxy.requests())
+
+There is no retry policy here on purpose. Retrying a refused request is the one
+thing that reliably makes the next one worse: measured over 1464 attempts, the
+chance the next attempt succeeds falls from 75% with no prior failure to 5.8%
+after five and 0.5% after seven, and 294 attempts spent past six consecutive
+failures returned three pages - 98 attempts per delivered page against 1.7 in a
+healthy session. A library that hid that behind a default would be spending a
+shared pool's reputation on your behalf.
+"""
+
+from .errors import (
+    CredentialsError,
+    NodeMavenError,
+    ParamError,
+    ProviderError,
+)
+from .providers import Provider, available, load, load_file
+from .proxy import Proxy
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Proxy",
+    "Provider",
+    "load",
+    "load_file",
+    "available",
+    "NodeMavenError",
+    "ParamError",
+    "CredentialsError",
+    "ProviderError",
+    "__version__",
+]

nodemaven-0.1.0/src/nodemaven/data/providers/nodemaven.toml

@@ -0,0 +1,53 @@
+# NodeMaven.
+#
+# `status = "measured"` means this dialect was read off the wire rather than
+# copied out of documentation: every value below was confirmed by raw CONNECT
+# probes on the date recorded. A definition marked `documented` has never been
+# exercised, and the difference matters because a wrong username is invisible -
+# see `notes`.
+label = "NodeMaven"
+status = "measured"
+source = "dashboard proxy generator, plus raw CONNECT probes"
+source_read = "2026-08-12"
+
+# <login>-country-us-sid-abc123-ttl-10m
+prefix = "{login}"
+separator = "-"
+pair_separator = "-"
+session_param = "sid"
+
+host = "gate.nodemaven.com"
+port = 8080
+
+# Returned on the CONNECT reply, so an exit address costs one handshake and no
+# target traffic. Not guaranteed: more than one implementation answers on this
+# name, and only some of them send it, so handle its absence rather than
+# treating the first miss as an error.
+exit_ip_header = "X-Proxy-Exit-IP"
+
+# Confirmed to be recognised. Anything outside this set is refused before a
+# request exists, because the gateway answers an unknown name with 200 and the
+# setting silently dropped.
+known_params = ["country", "region", "city", "isp", "sid", "ttl", "filter",
+                "ipv4", "speed"]
+
+notes = """
+Measured 2026-08-10 by raw CONNECT probes.
+
+Sticky sessions key on the whole recognised parameter set, not on `sid` alone.
+`country=us, sid=A` and `country=us, sid=A, filter=medium` are two different
+sessions; `ttl` does not participate and `filter` does. Adding or removing any
+parameter moves you to another exit without saying so.
+
+Seven inputs, seven reactions, none of which names the cause:
+  bad country          406 Not Acceptable
+  bad region           406 Not Acceptable
+  bad city             500 Internal Server Error
+  bad filter value     407 Proxy Authentication Required
+  bad ttl value        407 Proxy Authentication Required
+  empty value          no reply, the connection hangs about 20 s
+  unknown parameter    200, the parameter is ignored
+
+The two 407 cases are actively misleading - they send you to check credentials
+that are correct. With no `country` the default country is not stable.
+"""

nodemaven-0.1.0/src/nodemaven/errors.py

@@ -0,0 +1,26 @@
+"""Errors this package raises.
+
+Every message says what will happen to the caller, not that a value is invalid.
+A gateway parameter that is wrong is not a style problem: the request usually
+still succeeds, on settings nobody asked for.
+"""
+
+from __future__ import annotations
+
+__all__ = ["NodeMavenError", "ParamError", "CredentialsError", "ProviderError"]
+
+
+class NodeMavenError(Exception):
+    """Base class, so a caller can catch everything from this package at once."""
+
+
+class ParamError(NodeMavenError, ValueError):
+    """Input the gateway would silently ignore, misreport, or hang on."""
+
+
+class CredentialsError(NodeMavenError, ValueError):
+    """No login or password was given and none was found in the environment."""
+
+
+class ProviderError(NodeMavenError, ValueError):
+    """A provider definition is missing or does not describe a gateway."""

nodemaven-0.1.0/src/nodemaven/providers.py

@@ -0,0 +1,158 @@
+"""A gateway dialect is data, never code.
+
+Every proxy vendor sells the same thing and spells it differently: its own
+separators, its own parameter names, its own reaction to a mistake. That
+difference is the whole of what a provider is from this package's point of view,
+so it is one TOML file rather than one Python module.
+
+The reason is not tidiness. A module invites a single ``if provider == ...``
+somewhere nobody reviews, and from then on two gateways are no longer going
+through the same code path. A data file cannot branch.
+
+``load()`` reads a definition shipped inside the package. ``load_file()`` reads
+one from disk, which is how this SDK talks to a gateway we do not ship a
+definition for - your own, or one you wrote yourself - without this package
+having to make any claim about it.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, FrozenSet, Optional
+
+from .errors import ProviderError
+
+if sys.version_info >= (3, 11):  # pragma: no cover - version dependent
+    import tomllib
+else:  # pragma: no cover - version dependent
+    import tomli as tomllib
+
+__all__ = ["Provider", "load", "load_file", "available"]
+
+DEFAULT_PROVIDER = "nodemaven"
+
+_REQUIRED = ("label", "known_params")
+
+
+@dataclass(frozen=True, eq=False)
+class Provider:
+    """One gateway's username dialect.
+
+    ``status`` is load-bearing and not documentation. ``measured`` means traffic
+    has actually gone through this gateway and the dialect was read off the
+    wire. ``documented`` means it was transcribed from a vendor's own
+    documentation on ``source_read`` and has never been exercised. The
+    distinction matters because a wrong username is invisible: at least one
+    gateway answers an unrecognised parameter name with 200 and the setting
+    silently dropped, so the connection succeeds on settings that were never
+    applied and nothing the gateway replies can tell you.
+    """
+
+    id: str
+    label: str
+    known_params: FrozenSet[str]
+    status: str = "documented"
+    prefix: str = "{login}"
+    separator: str = "-"
+    pair_separator: str = "-"
+    session_param: Optional[str] = None
+    host: Optional[str] = None
+    port: Optional[int] = None
+    aliases: Dict[str, str] = field(default_factory=dict)
+    exit_ip_header: Optional[str] = None
+    source: str = ""
+    source_read: str = ""
+    notes: str = ""
+
+    def spell(self, name: str) -> str:
+        """The name this gateway uses on the wire for a canonical parameter."""
+        return self.aliases.get(name, name)
+
+    @property
+    def is_measured(self) -> bool:
+        return self.status == "measured"
+
+
+def _data_dir() -> Path:
+    return Path(__file__).resolve().parent / "data" / "providers"
+
+
+def available() -> list:
+    """Ids of the definitions shipped inside this package."""
+    return sorted(p.stem for p in _data_dir().glob("*.toml")
+                  if not p.stem.startswith("_"))
+
+
+def load(provider_id: str = DEFAULT_PROVIDER) -> Provider:
+    """A definition shipped with this package."""
+    path = _data_dir() / f"{provider_id}.toml"
+    if not path.is_file():
+        raise ProviderError(
+            f"no provider definition {provider_id!r} is shipped here, so no "
+            f"username can be built for it. Shipped: {available()}. To use a "
+            f"gateway that is not in that list, write a .toml for it and pass "
+            f"it to load_file()."
+        )
+    return load_file(path, provider_id=provider_id)
+
+
+def load_file(path, provider_id: Optional[str] = None) -> Provider:
+    """A definition read from an arbitrary path.
+
+    This is the seam that lets the package address a gateway it ships no
+    definition for. Nothing about it is special-cased: a file loaded from disk
+    goes through the same validation and the same builder as a shipped one.
+    """
+    path = Path(path)
+    try:
+        with path.open("rb") as handle:
+            raw: Dict[str, Any] = tomllib.load(handle)
+    except OSError as exc:
+        raise ProviderError(f"cannot read the provider definition {path}: {exc}") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ProviderError(f"{path} is not valid TOML: {exc}") from exc
+
+    missing = [key for key in _REQUIRED if key not in raw]
+    if missing:
+        raise ProviderError(
+            f"{path} is missing {missing}, so it does not describe a gateway. "
+            f"Without known_params nothing can be validated, and an unknown "
+            f"parameter name is the one mistake a gateway does not report."
+        )
+
+    known = frozenset(str(name) for name in raw["known_params"])
+    aliases = {str(k): str(v) for k, v in (raw.get("aliases") or {}).items()}
+    unknown_alias = sorted(set(aliases) - known)
+    if unknown_alias:
+        raise ProviderError(
+            f"{path} aliases {unknown_alias} which are not in known_params, so "
+            f"those parameters would be refused before the alias was ever used."
+        )
+
+    session_param = raw.get("session_param") or None
+    if session_param and session_param not in known:
+        raise ProviderError(
+            f"{path} declares session_param {session_param!r} which is not in "
+            f"known_params, so every sticky session would be refused."
+        )
+
+    port = raw.get("port")
+    return Provider(
+        id=provider_id or path.stem,
+        label=str(raw["label"]),
+        known_params=known,
+        status=str(raw.get("status", "documented")),
+        prefix=str(raw.get("prefix", "{login}")),
+        separator=str(raw.get("separator", "-")),
+        pair_separator=str(raw.get("pair_separator", "-")),
+        session_param=session_param,
+        host=raw.get("host"),
+        port=int(port) if port is not None else None,
+        aliases=aliases,
+        exit_ip_header=raw.get("exit_ip_header"),
+        source=str(raw.get("source", "")),
+        source_read=str(raw.get("source_read", "")),
+        notes=str(raw.get("notes", "")),
+    )

nodemaven-0.1.0/src/nodemaven/proxy.py

@@ -0,0 +1,274 @@
+"""One proxy identity, and the strings a client needs to use it.
+
+This module opens no socket. It builds a username in the gateway's dialect,
+refuses input the gateway would mishandle, and hands the result to whatever HTTP
+client you already have.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Mapping, Optional
+from urllib.parse import quote
+
+from .errors import CredentialsError, ParamError
+from .providers import Provider, load
+
+__all__ = ["Proxy"]
+
+# Constructor names that are ours rather than the gateway's. A definition whose
+# known_params collide with one of these is refused at construction, because the
+# alternative is a parameter silently arriving as a credential or the reverse.
+_RESERVED = frozenset({"login", "password", "host", "port", "provider"})
+
+_REDACTED = "***"
+
+
+class Proxy:
+    """A set of gateway parameters plus the credentials to use them.
+
+    ::
+
+        proxy = Proxy(login="user", password="pass", country="us", sid="a1")
+        requests.get(url, proxies=proxy.requests())
+
+    Credentials fall back to the environment when not passed, under the
+    provider's id in upper case: ``NODEMAVEN_LOGIN``, ``NODEMAVEN_PASSWORD``,
+    ``NODEMAVEN_HOST``, ``NODEMAVEN_PORT``.
+
+    **One instance is one identity.** On the gateway this package ships a
+    definition for, the sticky session key is the whole recognised parameter
+    set and not the session id alone: ``country=us, sid=A`` and
+    ``country=us, sid=A, filter=medium`` are two different sessions, and adding
+    or removing any parameter moves you to a different exit address without
+    saying so. Build the object once and reuse it; use :meth:`replace` when you
+    intend to move, so that the move is written down.
+    """
+
+    __slots__ = ("_provider", "_login", "_password", "_host", "_port", "_params")
+
+    def __init__(
+        self,
+        *,
+        login: Optional[str] = None,
+        password: Optional[str] = None,
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+        provider: Optional[Provider] = None,
+        **params: Any,
+    ) -> None:
+        self._provider = provider if provider is not None else load()
+
+        collision = sorted(self._provider.known_params & _RESERVED)
+        if collision:
+            raise ParamError(
+                f"provider {self._provider.label} names {collision} as gateway "
+                f"parameters, and this constructor already uses those names for "
+                f"credentials. Pass those settings through replace() on a "
+                f"provider whose definition renames them, or rename them with "
+                f"an alias."
+            )
+
+        env = self._provider.id.upper().replace("-", "_")
+        self._login = login if login is not None else os.environ.get(f"{env}_LOGIN")
+        self._password = (
+            password if password is not None else os.environ.get(f"{env}_PASSWORD")
+        )
+        raw_host = host if host is not None else os.environ.get(f"{env}_HOST")
+        raw_port = port if port is not None else os.environ.get(f"{env}_PORT")
+
+        self._host = raw_host or self._provider.host
+        self._port = int(raw_port) if raw_port not in (None, "") else self._provider.port
+
+        if not self._login or not self._password:
+            missing = [
+                name
+                for name, value in (("login", self._login), ("password", self._password))
+                if not value
+            ]
+            raise CredentialsError(
+                f"no {' and no '.join(missing)} for {self._provider.label}: pass "
+                f"it to Proxy() or set {env}_LOGIN and {env}_PASSWORD in the "
+                f"environment. Nothing was built, so nothing will connect."
+            )
+        if not self._host or not self._port:
+            raise CredentialsError(
+                f"no gateway address for {self._provider.label}: pass host= and "
+                f"port= or set {env}_HOST and {env}_PORT."
+            )
+
+        self._params = _validate(self._provider, params)
+
+    # -- what a client needs ------------------------------------------------
+
+    @property
+    def provider(self) -> Provider:
+        return self._provider
+
+    @property
+    def params(self) -> Dict[str, str]:
+        """The gateway parameters, as they will be sent. A copy."""
+        return dict(self._params)
+
+    @property
+    def server(self) -> str:
+        """``host:port``, with no credentials in it."""
+        return f"{self._host}:{self._port}"
+
+    @property
+    def username(self) -> str:
+        """The proxy username carrying every parameter, in the gateway's dialect."""
+        provider = self._provider
+        parts = [provider.prefix.format(login=self._login)]
+        for key, value in self._params.items():
+            parts.append(f"{provider.spell(key)}{provider.pair_separator}{value}")
+        return provider.separator.join(parts)
+
+    def url(self, scheme: str = "http") -> str:
+        """``http://user:pass@host:port``, for requests, httpx, curl and aiohttp.
+
+        Both credentials are percent-encoded with an empty ``safe`` set. A URL
+        has structure, and the structure is made of the characters ``: @ / ? #``;
+        a password containing any of them cuts the string in the wrong place and
+        the client connects somewhere else entirely. ``pa/ss`` unencoded ends the
+        authority at the slash, so the host becomes ``pa``.
+
+        That failure is worse than an exception, because at least one browser
+        engine answers a proxy URL it cannot parse by connecting **directly**
+        without reporting it - the request then leaves from your own address
+        while everything downstream believes it went through the pool.
+
+        Note the asymmetry with :meth:`playwright`, which must not encode:
+        there the fields are passed separately and the library encodes them
+        itself, so encoding here as well turns ``pa/ss`` into ``pa%252Fss`` and
+        authentication fails while blaming the credentials.
+        """
+        user = quote(self.username, safe="")
+        secret = quote(self._password, safe="")
+        return f"{scheme}://{user}:{secret}@{self.server}"
+
+    def requests(self, scheme: str = "http") -> Dict[str, str]:
+        """A ``proxies=`` mapping for requests. Also works for aiohttp's ``proxy=``
+        via :meth:`url`."""
+        url = self.url(scheme)
+        return {"http": url, "https": url}
+
+    def httpx(self, scheme: str = "http") -> Dict[str, str]:
+        """A ``mounts``-style mapping for httpx. Modern httpx also takes
+        ``proxy=proxy.url()`` directly."""
+        url = self.url(scheme)
+        return {"http://": url, "https://": url}
+
+    def playwright(self) -> Dict[str, str]:
+        """A ``proxy=`` dict for Playwright, Patchright and Puppeteer.
+
+        Deliberately not percent-encoded - see :meth:`url`.
+        """
+        return {
+            "server": f"http://{self.server}",
+            "username": self.username,
+            "password": self._password,
+        }
+
+    # -- moving deliberately ------------------------------------------------
+
+    def replace(self, **changes: Any) -> "Proxy":
+        """A new identity with parameters added, changed, or removed with ``None``.
+
+        This returns a new object rather than mutating, because on a gateway
+        whose session key is the whole parameter set, changing a parameter is
+        not an adjustment to one identity - it is a different identity on a
+        different exit address. A method that returned ``self`` would hide that.
+        """
+        params: Dict[str, Any] = dict(self._params)
+        for key, value in changes.items():
+            if value is None:
+                params.pop(key, None)
+            else:
+                params[key] = value
+        return Proxy(
+            login=self._login,
+            password=self._password,
+            host=self._host,
+            port=self._port,
+            provider=self._provider,
+            **params,
+        )
+
+    def session(self, session_id: str) -> "Proxy":
+        """The same parameters, pinned to one sticky session.
+
+        A provider that declares no session parameter gets none, and the id is
+        dropped rather than sent under a guessed name: a name this gateway does
+        not know is answered with 200 and ignored, so every request would draw a
+        fresh exit while your code believed it was holding one.
+        """
+        if not self._provider.session_param:
+            raise ParamError(
+                f"{self._provider.label} declares no session parameter, so "
+                f"{session_id!r} cannot be sent and every request will leave "
+                f"from whichever exit the gateway picks."
+            )
+        return self.replace(**{self._provider.session_param: session_id})
+
+    # -- output that is not a credential ------------------------------------
+
+    def __repr__(self) -> str:
+        """Never carries the password.
+
+        The default repr of a container calls ``__repr__`` on its elements, and
+        tracebacks, ``pytest --showlocals`` and most logging setups print reprs
+        of locals. A password in here reaches CI logs and pasted bug reports
+        without anyone ever choosing to print it. :meth:`url` is the one place
+        the secret appears, and it is named so that it is obvious.
+        """
+        shown = "".join(f", {k}={v!r}" for k, v in self._params.items())
+        return (
+            f"Proxy(provider={self._provider.id!r}, server={self.server!r}, "
+            f"login={self._login!r}, password={_REDACTED!r}{shown})"
+        )
+
+
+def _validate(provider: Provider, params: Mapping[str, Any]) -> Dict[str, str]:
+    """Refuse client-side what the gateway will not report.
+
+    This is not politeness, it is the only check available. The gateway this
+    package ships a definition for answers seven kinds of bad input seven
+    different ways and none of them names the cause: a bad country or region
+    gives 406, a bad city 500, a bad filter or ttl value gives 407 - which sends
+    you to check credentials that are fine - an empty value hangs the connection
+    for about twenty seconds, and an unknown parameter name is answered with
+    **200 and the setting silently dropped**. That last one is why this function
+    exists: the request succeeds, and nothing that comes back can tell you the
+    setting was never applied.
+    """
+    out: Dict[str, str] = {}
+    for key, value in params.items():
+        if key not in provider.known_params:
+            raise ParamError(
+                f"{provider.label} does not know the parameter {key!r}: it is "
+                f"answered with 200 and dropped, so the connection would succeed "
+                f"and your setting would NOT be applied. "
+                f"Known: {sorted(provider.known_params)}"
+            )
+        if value is None or value == "":
+            raise ParamError(
+                f"empty value for {key!r}: the gateway does not reply to this, "
+                f"the connection hangs for about 20 s and then fails. Drop the "
+                f"parameter instead of passing an empty value."
+            )
+        if isinstance(value, bool):
+            value = "true" if value else "false"
+        text = str(value)
+        separators = sorted({provider.separator, provider.pair_separator} - {""})
+        bad = sorted({c for c in separators if c in text})
+        if bad:
+            raise ParamError(
+                f"the value of {key!r} is {text!r} and contains {bad}, which "
+                f"{provider.label} uses to separate parameters. The username "
+                f"would be split into different settings than you asked for. "
+                f"Session ids in particular cannot carry a {bad[0]!r} - use "
+                f"{text.replace(bad[0], '')!r} or another character."
+            )
+        out[key] = text
+    return out

nodemaven-0.1.0/src/nodemaven.egg-info/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: nodemaven
+Version: 0.1.0
+Summary: Build and validate proxy connection strings. No transport, no retries.
+Author-email: NodeMaven <alexandr.kazmin@nodemaven.com>
+License-Expression: MIT
+Project-URL: Homepage, https://nodemaven.com
+Keywords: proxy,residential-proxy,scraping,http-proxy,playwright
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=1.1.0; python_version < "3.11"
+Dynamic: license-file
+
+# nodemaven
+
+Build and validate proxy connection strings.
+
+This library opens no socket. It builds the username a proxy gateway expects,
+refuses the input that gateway would mishandle, and hands the result to whatever
+HTTP client you already use.
+
+```
+pip install nodemaven
+```
+
+## Quickstart
+
+```python
+import requests
+from nodemaven import Proxy
+
+proxy = Proxy(login="your-login", password="your-password",
+              country="us", filter="medium")
+
+r = requests.get("https://api.ipify.org", proxies=proxy.requests())
+print(r.text)
+```
+
+Credentials can come from the environment instead, so nothing is in your source:
+
+```python
+# NODEMAVEN_LOGIN and NODEMAVEN_PASSWORD
+proxy = Proxy(country="us", filter="medium")
+```
+
+The same identity, for other clients:
+
+```python
+proxy.url()          # http://user:pass@gate.nodemaven.com:8080  - httpx, aiohttp, curl
+proxy.requests()     # {"http": ..., "https": ...}
+proxy.httpx()        # {"http://": ..., "https://": ...}
+proxy.playwright()   # {"server": ..., "username": ..., "password": ...}
+proxy.username       # the username on its own
+proxy.server         # host:port, no credentials
+```
+
+With Playwright, Patchright or Puppeteer:
+
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch()
+    context = browser.new_context(proxy=proxy.playwright())
+```
+
+## Sticky sessions
+
+One `Proxy` is one identity. Pin it to a sticky session:
+
+```python
+held = proxy.session("order-4417")
+```
+
+**The session key is the whole parameter set, not the session id.**
+`country=us, sid=A` and `country=us, sid=A, filter=medium` are two different
+sessions on the gateway, so adding or removing any parameter moves you to a
+different exit address. That is why parameters change through a method that
+returns a new object rather than by assignment - the move is a different
+identity, and the code should say so:
+
+```python
+germany = proxy.replace(country="de")   # a new identity, a new exit
+plain   = proxy.replace(filter=None)    # also a new identity
+```
+
+## Why the validation is the point
+
+A gateway is bad at telling you that you got the username wrong. Measured
+against this one on 2026-08-10, seven kinds of bad input produce seven
+different reactions and not one of them names the cause:
+
+| you sent | the gateway answers |
+|---|---|
+| bad country | `406 Not Acceptable` |
+| bad region | `406 Not Acceptable` |
+| bad city | `500 Internal Server Error` |
+| bad `filter` value | `407 Proxy Authentication Required` |
+| bad `ttl` value | `407 Proxy Authentication Required` |
+| empty value | nothing, the connection hangs about 20 s |
+| **unknown parameter name** | **`200`, and the parameter is ignored** |
+
+The two `407` replies send you to check credentials that are correct. The last
+row is worse than any of them: the request succeeds, your code carries on, and
+the setting you asked for was never applied. Nothing that comes back over the
+wire can tell you.
+
+So this library checks before anything is sent:
+
+```python
+>>> Proxy(login="u", password="p", contry="us")
+ParamError: NodeMaven does not know the parameter 'contry': it is answered with
+200 and dropped, so the connection would succeed and your setting would NOT be
+applied. Known: ['city', 'country', 'filter', 'ipv4', 'isp', 'region', 'sid',
+'speed', 'ttl']
+```
+
+## What this library does not do
+
+**It does not retry.** That is deliberate, and it is the one design decision
+here taken against a measurement rather than a preference.
+
+Retrying a refused request is the thing that most reliably makes the next one
+worse: each retry confirms automation to the target and burns the exit range for
+everyone else sharing the pool. Measured over 1464 attempts, the chance that the
+next attempt succeeds, by how many failures came immediately before it:
+
+| failures before | P(next attempt succeeds) |
+|---|---|
+| 0 | 75% |
+| 1 | 21% |
+| 3 | 5.9% |
+| 5 | 5.8% |
+| 6 | 1.6% |
+| 7-9 | 0.5% |
+
+294 attempts were spent past six consecutive failures and returned 3 pages - 98
+attempts per delivered page, against 1.7 in a healthy session. A library that
+shipped automatic retry as a default would be spending that on your behalf
+without telling you.
+
+It also does not own an HTTP client, a connection pool or a browser. Those are
+yours, and they are better than anything a vendor SDK would bundle.
+
+## Other gateways
+
+Parameters are data, not hardcoded keywords. A gateway is one TOML file - its
+prefix, separators, session parameter and the set of parameter names it actually
+recognises - and a definition read from disk goes through the same builder and
+the same validation as the one shipped here:
+
+```python
+from nodemaven import Proxy, load_file
+
+mine = load_file("my-gateway.toml")
+proxy = Proxy(provider=mine, login="u", password="p", country="us")
+```
+
+Every definition carries a `status`. `measured` means traffic has gone through
+that gateway and the dialect was read off the wire. `documented` means it was
+transcribed from documentation and never exercised. Only `nodemaven` is shipped
+here, and it is `measured`.
+
+## Requirements
+
+Python 3.9 or newer. No dependencies on 3.11 and newer; `tomli` on older ones.
+
+## License
+
+MIT.

nodemaven-0.1.0/src/nodemaven.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/nodemaven/__init__.py
+src/nodemaven/errors.py
+src/nodemaven/providers.py
+src/nodemaven/proxy.py
+src/nodemaven/py.typed
+src/nodemaven.egg-info/PKG-INFO
+src/nodemaven.egg-info/SOURCES.txt
+src/nodemaven.egg-info/dependency_links.txt
+src/nodemaven.egg-info/requires.txt
+src/nodemaven.egg-info/top_level.txt
+src/nodemaven/data/providers/nodemaven.toml
+tests/test_proxy.py

nodemaven-0.1.0/src/nodemaven.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nodemaven-0.1.0/src/nodemaven.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[:python_version < "3.11"]
+tomli>=1.1.0

nodemaven-0.1.0/src/nodemaven.egg-info/top_level.txt

@@ -0,0 +1 @@
+nodemaven

nodemaven-0.1.0/tests/test_proxy.py

@@ -0,0 +1,131 @@
+"""Offline in full: no network, no credentials, no gateway.
+
+These cases are the seed of the golden vectors the other language SDKs will run.
+Anything asserted here is a statement about what a correct username is, not about
+how this implementation happens to be written.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from nodemaven import ParamError, Proxy, available, load
+
+CREDS = {"login": "acct", "password": "pw", "host": "gate.example.com", "port": 8080}
+
+
+@pytest.fixture(autouse=True)
+def no_gateway_env(monkeypatch):
+    """A test that reached for real credentials would spend real traffic."""
+    for name in ("LOGIN", "PASSWORD", "HOST", "PORT"):
+        monkeypatch.delenv(f"NODEMAVEN_{name}", raising=False)
+
+
+class TestTheUsername:
+    def test_parameters_are_spelled_in_the_gateway_dialect(self):
+        proxy = Proxy(country="us", filter="medium", sid="abc123", **CREDS)
+        assert proxy.username == "acct-country-us-filter-medium-sid-abc123"
+
+    def test_no_parameters_is_the_bare_login(self):
+        assert Proxy(**CREDS).username == "acct"
+
+    def test_order_follows_the_call(self):
+        a = Proxy(country="us", sid="x", **CREDS).username
+        b = Proxy(sid="x", country="us", **CREDS).username
+        assert a == "acct-country-us-sid-x"
+        assert b == "acct-sid-x-country-us"
+
+
+class TestValidationTheGatewayCannotDo:
+    def test_an_unknown_name_is_refused_before_anything_is_sent(self):
+        # The gateway answers this with 200 and drops the setting, so the run
+        # completes claiming a setting that was never applied.
+        with pytest.raises(ParamError, match="does not know the parameter"):
+            Proxy(contry="us", **CREDS)
+
+    def test_an_empty_value_is_refused(self):
+        # The gateway does not reply at all; the connection hangs about 20 s.
+        with pytest.raises(ParamError, match="empty value"):
+            Proxy(country="", **CREDS)
+
+    def test_a_separator_inside_a_value_is_refused(self):
+        # "us-east" would be parsed as country=us plus a parameter named east.
+        with pytest.raises(ParamError, match="separate parameters"):
+            Proxy(country="us-east", **CREDS)
+
+
+class TestTheUrlIsSafeToHandToAClient:
+    def test_credentials_are_percent_encoded(self):
+        proxy = Proxy(country="us", **{**CREDS, "password": "pa/ss@1:2"})
+        assert proxy.url() == (
+            "http://acct-country-us:pa%2Fss%401%3A2@gate.example.com:8080"
+        )
+
+    def test_the_slash_is_encoded_and_that_is_the_whole_point(self):
+        # quote() defaults to safe="/", which leaves the one character that ends
+        # the authority. Unencoded, the host below becomes "pa".
+        proxy = Proxy(**{**CREDS, "password": "pa/ss"})
+        assert "%2F" in proxy.url()
+        assert proxy.url().endswith("@gate.example.com:8080")
+
+    def test_the_playwright_dict_is_not_encoded(self):
+        # Playwright encodes the fields itself; encoding here too would send
+        # pa%252Fss and fail authentication while blaming the credentials.
+        proxy = Proxy(**{**CREDS, "password": "pa/ss"})
+        assert proxy.playwright()["password"] == "pa/ss"
+        assert proxy.playwright()["server"] == "http://gate.example.com:8080"
+
+
+class TestTheReprCarriesNoSecret:
+    def test_the_password_is_redacted(self):
+        proxy = Proxy(country="us", **{**CREDS, "password": "hunter2"})
+        assert "hunter2" not in repr(proxy)
+        assert "***" in repr(proxy)
+
+    def test_it_survives_being_put_in_a_container(self):
+        # A container's __str__ calls __repr__ on its elements, which is how a
+        # careful __str__ gets bypassed in a log line.
+        proxy = Proxy(**{**CREDS, "password": "hunter2"})
+        assert "hunter2" not in str([proxy])
+        assert "hunter2" not in str({"p": proxy})
+
+    def test_the_parameters_are_still_visible(self):
+        assert "country='us'" in repr(Proxy(country="us", **CREDS))
+
+
+class TestMovingIsANewIdentity:
+    def test_replace_returns_a_new_object(self):
+        first = Proxy(country="us", **CREDS)
+        second = first.replace(country="de")
+        assert first.username == "acct-country-us"
+        assert second.username == "acct-country-de"
+        assert first is not second
+
+    def test_none_removes_a_parameter(self):
+        proxy = Proxy(country="us", filter="medium", **CREDS).replace(filter=None)
+        assert proxy.username == "acct-country-us"
+
+    def test_session_uses_the_providers_own_name_for_it(self):
+        proxy = Proxy(country="us", **CREDS).session("order4417")
+        assert proxy.username == "acct-country-us-sid-order4417"
+
+    def test_a_session_id_carrying_the_separator_is_refused(self):
+        # `order-4417` is the obvious thing to use as a session key and this
+        # dialect cannot carry it: separator and pair separator are both "-",
+        # so `sid-order-4417` reads as sid=order followed by a parameter named
+        # 4417. Refusing is inference from the dialect rather than a measured
+        # gateway reply - see the open question in CLAUDE.md - and it errs
+        # towards a loud error over a silently different exit.
+        with pytest.raises(ParamError, match="cannot carry"):
+            Proxy(country="us", **CREDS).session("order-4417")
+
+
+class TestTheShippedDefinition:
+    def test_nodemaven_is_shipped_and_is_measured(self):
+        assert "nodemaven" in available()
+        assert load("nodemaven").is_measured
+
+    def test_the_session_parameter_is_asked_for_rather_than_spelled(self):
+        # Eleven call sites in the benchmark wrote "sid" directly. It is the name
+        # this gateway happens to use, which is exactly why the literal survived.
+        assert load("nodemaven").session_param == "sid"