nonecap 0.6.2__tar.gz → 0.8.0__tar.gz

{nonecap-0.6.2 → nonecap-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nonecap
-Version: 0.6.2
+Version: 0.8.0
 Summary: Official Python client for the NoneCap hCaptcha solving API.
 Project-URL: Homepage, https://nonecap.com
 Project-URL: Documentation, https://nonecap.com/api-reference
@@ -67,6 +67,7 @@ solve = nc.solve(
 
 print(solve.token)  # the hCaptcha token, ready to submit
 print(solve.resp_key)  # hcaptcha.getRespKey() equivalent, for sites that verify the pair
+print(solve.user_agent)  # submit the token with this User-Agent: some sites check the browser version
 ```
 
 `solve()` submits the captcha and waits until it's done, using the API's long-poll so you aren't hammering it with requests. It returns the solved solve, or raises if the solve fails or your timeout runs out.
@@ -170,7 +171,7 @@ except RateLimitError as err:
     time.sleep(err.retry_after or 1)
 ```
 
-The subclasses are `AuthenticationError` (401), `PermissionDeniedError` (403), `InsufficientCreditsError` (402, with `KeyCreditLimitError` when one API key hit its own cap), `ValidationError` (422/400, with a `param` naming the bad field; `PayloadTooLargeError` for 413 and `UnsupportedMediaTypeError` for 415), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, with `ConcurrencyLimitError` and `SitekeyRateLimitedError` telling the two apart; `retry_after` is the seconds the API asked you to wait), `APIError` (5xx, with `ServiceUnavailableError` for a maintenance pause), `APIConnectionError` and `APITimeoutError` (the request never landed), and `SolveTimeoutError` (your `solve()` budget ran out). Every error from a response carries `request_id`, the id to quote to support.
+The subclasses are `AuthenticationError` (401), `PermissionDeniedError` (403), `InsufficientCreditsError` (402, with `KeyCreditLimitError` when one API key hit its own cap), `ValidationError` (422/400, with a `param` naming the bad field; `PayloadTooLargeError` for 413 and `UnsupportedMediaTypeError` for 415), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, with `ConcurrencyLimitError`, `SitekeyRateLimitedError` and `ProxyUnavailableError` (your own proxy is refusing connections) telling them apart; `retry_after` is the seconds the API asked you to wait), `APIError` (5xx, with `ServiceUnavailableError` for a maintenance pause), `APIConnectionError` and `APITimeoutError` (the request never landed), and `SolveTimeoutError` (your `solve()` budget ran out). Every error from a response carries `request_id`, the id to quote to support.
 
 `SolveFailedError` carries the full `solve`. `solve.error.code` is a `SolveErrorCode`, `solve.error.reason` a typed sub-reason or `None` (`proxy_rejected`, `sitekey_rate_limited`, …), and `solve.error.retryable` says whether resubmitting the same request unchanged can succeed; `err.retryable`, `err.reason` and `err.solve_code` are shortcuts to those fields. Failed solves are never charged.
 

{nonecap-0.6.2 → nonecap-0.8.0}/README.md

@@ -36,6 +36,7 @@ solve = nc.solve(
 
 print(solve.token)  # the hCaptcha token, ready to submit
 print(solve.resp_key)  # hcaptcha.getRespKey() equivalent, for sites that verify the pair
+print(solve.user_agent)  # submit the token with this User-Agent: some sites check the browser version
 ```
 
 `solve()` submits the captcha and waits until it's done, using the API's long-poll so you aren't hammering it with requests. It returns the solved solve, or raises if the solve fails or your timeout runs out.
@@ -139,7 +140,7 @@ except RateLimitError as err:
     time.sleep(err.retry_after or 1)
 ```
 
-The subclasses are `AuthenticationError` (401), `PermissionDeniedError` (403), `InsufficientCreditsError` (402, with `KeyCreditLimitError` when one API key hit its own cap), `ValidationError` (422/400, with a `param` naming the bad field; `PayloadTooLargeError` for 413 and `UnsupportedMediaTypeError` for 415), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, with `ConcurrencyLimitError` and `SitekeyRateLimitedError` telling the two apart; `retry_after` is the seconds the API asked you to wait), `APIError` (5xx, with `ServiceUnavailableError` for a maintenance pause), `APIConnectionError` and `APITimeoutError` (the request never landed), and `SolveTimeoutError` (your `solve()` budget ran out). Every error from a response carries `request_id`, the id to quote to support.
+The subclasses are `AuthenticationError` (401), `PermissionDeniedError` (403), `InsufficientCreditsError` (402, with `KeyCreditLimitError` when one API key hit its own cap), `ValidationError` (422/400, with a `param` naming the bad field; `PayloadTooLargeError` for 413 and `UnsupportedMediaTypeError` for 415), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, with `ConcurrencyLimitError`, `SitekeyRateLimitedError` and `ProxyUnavailableError` (your own proxy is refusing connections) telling them apart; `retry_after` is the seconds the API asked you to wait), `APIError` (5xx, with `ServiceUnavailableError` for a maintenance pause), `APIConnectionError` and `APITimeoutError` (the request never landed), and `SolveTimeoutError` (your `solve()` budget ran out). Every error from a response carries `request_id`, the id to quote to support.
 
 `SolveFailedError` carries the full `solve`. `solve.error.code` is a `SolveErrorCode`, `solve.error.reason` a typed sub-reason or `None` (`proxy_rejected`, `sitekey_rate_limited`, …), and `solve.error.retryable` says whether resubmitting the same request unchanged can succeed; `err.retryable`, `err.reason` and `err.solve_code` are shortcuts to those fields. Failed solves are never charged.
 

{nonecap-0.6.2 → nonecap-0.8.0}/src/nonecap/__init__.py

@@ -27,6 +27,7 @@ from ._errors import (
     NotFoundError,
     PayloadTooLargeError,
     PermissionDeniedError,
+    ProxyUnavailableError,
     RateLimitError,
     ServiceUnavailableError,
     SitekeyRateLimitedError,
@@ -97,6 +98,7 @@ __all__ = [
     "RateLimitError",
     "ConcurrencyLimitError",
     "SitekeyRateLimitedError",
+    "ProxyUnavailableError",
     "APIError",
     "ServiceUnavailableError",
     "APIConnectionError",

{nonecap-0.6.2 → nonecap-0.8.0}/src/nonecap/_errors.py

@@ -85,6 +85,12 @@ class SitekeyRateLimitedError(RateLimitError):
     Wait ``retry_after`` seconds; the message says whether a different proxy pool can help."""
 
 
+class ProxyUnavailableError(RateLimitError):
+    """429 — nearly every recent solve through the proxy you supplied failed because the
+    proxy refused the connection, so submits through it are shed. Fix the proxy or switch
+    exit; ``retry_after`` says when the next submit is let through to re-check it."""
+
+
 class APIError(NoneCapError):
     """5xx, or a response that was not the expected shape. ``request_id`` is the id to quote."""
 
@@ -184,6 +190,8 @@ def error_from_response(
         cls = ConcurrencyLimitError
     elif code == "sitekey_rate_limited":
         cls = SitekeyRateLimitedError
+    elif code == "proxy_unavailable":
+        cls = ProxyUnavailableError
     elif code in ("rate_limited", "ext_daily_limit"):
         cls = RateLimitError
     elif code == "maintenance":

{nonecap-0.6.2 → nonecap-0.8.0}/src/nonecap/_types.py

@@ -110,6 +110,11 @@ class Solve:
     """Milliseconds the solve waited in the queue before a worker picked it up."""
     resolve_ms: Optional[int]
     """Milliseconds of actual solving."""
+    user_agent: Optional[str] = None
+    """The browser user agent the solve presented while it earned ``token``. Some sites
+    reject a token submitted by a different browser version, so send the token with this
+    as your ``User-Agent`` header (and from the same IP as your proxy, if you gave one).
+    Set alongside ``token``, otherwise None."""
 
     @property
     def is_terminal(self) -> bool:
@@ -144,6 +149,7 @@ class Solve:
             finished_at=data.get("finished_at"),
             queue_ms=data.get("queue_ms"),
             resolve_ms=data.get("resolve_ms"),
+            user_agent=data.get("user_agent"),
         )
 
 

nonecap-0.8.0/src/nonecap/_version.py

@@ -0,0 +1 @@
+__version__ = "0.8.0"

{nonecap-0.6.2 → nonecap-0.8.0}/tests/conftest.py

@@ -45,6 +45,7 @@ def solve_payload(**overrides: Any) -> dict[str, Any]:
         "url": "https://example.com",
         "token": None,
         "resp_key": None,
+        "user_agent": None,
         "error": None,
         "credits_charged": None,
         "proxy_bytes": None,

{nonecap-0.6.2 → nonecap-0.8.0}/tests/test_client.py

@@ -16,6 +16,7 @@ from nonecap import (
     NotFoundError,
     PayloadTooLargeError,
     PermissionDeniedError,
+    ProxyUnavailableError,
     RateLimitError,
     ServiceUnavailableError,
     SitekeyRateLimitedError,
@@ -66,6 +67,23 @@ class TestRetrieve:
         nc = client_for(script)
         assert nc.solves.retrieve("solve_1").resp_key is None
 
+    def test_returns_the_user_agent_the_solve_presented(self) -> None:
+        ua = (
+            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+            " (KHTML, like Gecko) Chrome/152.0.0.0 Safari/537.36"
+        )
+        script = Script((200, solve_payload(status="solved", token="P1_tok", user_agent=ua)))
+        nc = client_for(script)
+        assert nc.solves.retrieve("solve_1").user_agent == ua
+
+    def test_user_agent_is_none_until_solved_or_when_absent(self) -> None:
+        nc = client_for(Script((200, solve_payload())))
+        assert nc.solves.retrieve("solve_1").user_agent is None
+        payload = solve_payload(status="solved", token="P1_tok")
+        del payload["user_agent"]
+        nc = client_for(Script((200, payload)))
+        assert nc.solves.retrieve("solve_1").user_agent is None
+
 
 class TestCreate:
     def test_posts_with_bearer_auth_and_json_body(self) -> None:
@@ -186,6 +204,8 @@ class TestErrorMapping:
             (429, "concurrency_limit_exceeded", ConcurrencyLimitError),
             (429, "concurrency_limit_exceeded", RateLimitError),
             (429, "sitekey_rate_limited", SitekeyRateLimitedError),
+            (429, "proxy_unavailable", ProxyUnavailableError),
+            (429, "proxy_unavailable", RateLimitError),
             (429, "rate_limited", RateLimitError),
             (409, "conflict", ConflictError),
             (404, "not_found", NotFoundError),

nonecap-0.6.2/src/nonecap/_version.py

@@ -1 +0,0 @@
-__version__ = "0.6.2"