nonecap 0.1.0__tar.gz → 0.2.0__tar.gz

{nonecap-0.1.0 → nonecap-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nonecap
-Version: 0.1.0
+Version: 0.2.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
@@ -86,6 +86,48 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Cancelling a solve
+
+`solve()` is the simple path when you just want a token. When you need to hold a reference you can cancel — for clean shutdown, freeing a worker slot, or stopping early — use `solves.start()`. It submits the solve and hands back a `SolveHandle` right away, with the `id` already populated, instead of blocking on the result:
+
+```python
+handle = nc.solves.start(type="hcaptcha", sitekey=sitekey, url=url)
+print(handle.id)  # available immediately
+
+# Wait for it, just like solve():
+solve = handle.result(timeout=120)
+print(solve.token)
+```
+
+Holding the handle lets you stop a solve you no longer need — say, on shutdown or when a parallel attempt already won — instead of waiting on its result:
+
+```python
+handle = nc.solves.start(type="hcaptcha", sitekey=sitekey, url=url)
+
+# ... elsewhere / later, to stop it:
+handle.cancel()
+```
+
+`handle.result()` long-polls until the solve finishes and returns it, raising `SolveFailedError` / `SolveTimeoutError` like `solve()` does. The *terminal* outcome is memoized, so once the solve has settled, calling `result()` again replays it for free; a `SolveTimeoutError` is not memoized, so you can call `result()` again with a larger timeout to keep waiting. `handle.cancel()` stops a pending or in-flight solve and returns its final state — if the solve already finished, that's not an error, you just get the completed solve back.
+
+The async client mirrors this — `await` the start, the result, and the cancel:
+
+```python
+async with AsyncNoneCap(api_key="nc_live_...") as nc:
+    handle = await nc.solves.start(type="hcaptcha", sitekey=sitekey, url=url)
+    print(handle.id)
+
+    # Either wait for the outcome ...
+    solve = await handle.result(timeout=120)
+    print(solve.token)
+
+    # ... or, on another handle, cancel it instead of awaiting:
+    other = await nc.solves.start(type="hcaptcha", sitekey=sitekey, url=url)
+    await other.cancel()
+```
+
+Cancelled solves are never charged, and a solve you simply abandon expires uncharged at the server deadline — nothing is billed unless a solve actually succeeds. So `cancel()` is for cleanup and early-stop, not cost protection.
+
 ## Handling failures
 
 Every error this library raises extends `NoneCapError`, so you can catch the whole family or pick out the one you care about.
@@ -134,6 +176,8 @@ nc.solve(
     url=url,
     proxy={"scheme": "http", "host": "1.2.3.4", "port": 8080, "username": "u", "password": "p"},
     # or: proxy="http://u:p@1.2.3.4:8080"
+    # scheme can be http, https, socks5, socks5h, or socks4 (default http)
+    # e.g. proxy="socks5://u:p@1.2.3.4:1080"
 )
 ```
 

{nonecap-0.1.0 → nonecap-0.2.0}/README.md

@@ -55,6 +55,48 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Cancelling a solve
+
+`solve()` is the simple path when you just want a token. When you need to hold a reference you can cancel — for clean shutdown, freeing a worker slot, or stopping early — use `solves.start()`. It submits the solve and hands back a `SolveHandle` right away, with the `id` already populated, instead of blocking on the result:
+
+```python
+handle = nc.solves.start(type="hcaptcha", sitekey=sitekey, url=url)
+print(handle.id)  # available immediately
+
+# Wait for it, just like solve():
+solve = handle.result(timeout=120)
+print(solve.token)
+```
+
+Holding the handle lets you stop a solve you no longer need — say, on shutdown or when a parallel attempt already won — instead of waiting on its result:
+
+```python
+handle = nc.solves.start(type="hcaptcha", sitekey=sitekey, url=url)
+
+# ... elsewhere / later, to stop it:
+handle.cancel()
+```
+
+`handle.result()` long-polls until the solve finishes and returns it, raising `SolveFailedError` / `SolveTimeoutError` like `solve()` does. The *terminal* outcome is memoized, so once the solve has settled, calling `result()` again replays it for free; a `SolveTimeoutError` is not memoized, so you can call `result()` again with a larger timeout to keep waiting. `handle.cancel()` stops a pending or in-flight solve and returns its final state — if the solve already finished, that's not an error, you just get the completed solve back.
+
+The async client mirrors this — `await` the start, the result, and the cancel:
+
+```python
+async with AsyncNoneCap(api_key="nc_live_...") as nc:
+    handle = await nc.solves.start(type="hcaptcha", sitekey=sitekey, url=url)
+    print(handle.id)
+
+    # Either wait for the outcome ...
+    solve = await handle.result(timeout=120)
+    print(solve.token)
+
+    # ... or, on another handle, cancel it instead of awaiting:
+    other = await nc.solves.start(type="hcaptcha", sitekey=sitekey, url=url)
+    await other.cancel()
+```
+
+Cancelled solves are never charged, and a solve you simply abandon expires uncharged at the server deadline — nothing is billed unless a solve actually succeeds. So `cancel()` is for cleanup and early-stop, not cost protection.
+
 ## Handling failures
 
 Every error this library raises extends `NoneCapError`, so you can catch the whole family or pick out the one you care about.
@@ -103,6 +145,8 @@ nc.solve(
     url=url,
     proxy={"scheme": "http", "host": "1.2.3.4", "port": 8080, "username": "u", "password": "p"},
     # or: proxy="http://u:p@1.2.3.4:8080"
+    # scheme can be http, https, socks5, socks5h, or socks4 (default http)
+    # e.g. proxy="socks5://u:p@1.2.3.4:1080"
 )
 ```
 

{nonecap-0.1.0 → nonecap-0.2.0}/src/nonecap/__init__.py

@@ -7,7 +7,7 @@
 'P1_...'
 """
 
-from ._client import AsyncNoneCap, NoneCap
+from ._client import AsyncNoneCap, AsyncSolveHandle, NoneCap, SolveHandle
 from ._errors import (
     APIConnectionError,
     APIError,
@@ -40,6 +40,9 @@ __all__ = [
     # clients
     "NoneCap",
     "AsyncNoneCap",
+    # handles
+    "SolveHandle",
+    "AsyncSolveHandle",
     # types
     "Solve",
     "SolveError",

{nonecap-0.1.0 → nonecap-0.2.0}/src/nonecap/_client.py

@@ -15,6 +15,7 @@ pyright, and a runtime check backs it up for untyped callers.
 
 from __future__ import annotations
 
+import asyncio
 import time
 from collections.abc import AsyncIterator, Iterator
 from typing import (
@@ -31,6 +32,7 @@ from ._errors import (
     APIConnectionError,
     APIError,
     APITimeoutError,
+    ConflictError,
     SolveFailedError,
     SolveTimeoutError,
     ValidationError,
@@ -234,6 +236,68 @@ class Solves:
         )
         return Solve._from_dict(payload)
 
+    @overload
+    def start(
+        self,
+        *,
+        type: Literal["hcaptcha"],
+        sitekey: str,
+        url: str,
+        rqdata: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+    ) -> SolveHandle: ...
+
+    @overload
+    def start(
+        self,
+        *,
+        type: Literal["hcaptcha_enterprise"],
+        sitekey: str,
+        url: str,
+        rqdata: str,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+    ) -> SolveHandle: ...
+
+    def start(
+        self,
+        *,
+        type: SolveType,
+        sitekey: str,
+        url: str,
+        rqdata: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+    ) -> SolveHandle:
+        """Submit a solve and return a :class:`SolveHandle` without waiting.
+
+        The handle's ``id`` is populated immediately, so you can later
+        :meth:`SolveHandle.cancel` the solve or block on its outcome with
+        :meth:`SolveHandle.result`. Use this over :meth:`NoneCap.solve` when you
+        need to hold a reference you can cancel — for clean shutdown, freeing a
+        worker slot, or stopping early.
+        """
+        body = _build_solve_body(
+            type=type,
+            sitekey=sitekey,
+            url=url,
+            rqdata=rqdata,
+            user_agent=user_agent,
+            proxy=proxy,
+            webhook_url=webhook_url,
+        )
+        return self._start_from_body(body)
+
+    def _start_from_body(self, body: dict[str, Any]) -> SolveHandle:
+        """Shared by :meth:`start` and :meth:`NoneCap.solve`: POST the solve
+        (without long-polling) and wrap the pending resource in a handle."""
+        payload = self._client._request("POST", "/v1/solves", json=body)
+        return SolveHandle(self, Solve._from_dict(payload))
+
     def retrieve(self, solve_id: str, *, wait: Optional[int] = None) -> Solve:
         """Fetch a solve by id. Pass ``wait`` to long-poll until it finishes."""
         payload = self._client._request(
@@ -288,6 +352,81 @@ class Solves:
             cursor = page.data[-1].id
 
 
+class SolveHandle:
+    """A handle to a submitted solve, returned by :meth:`Solves.start`.
+
+    Like :class:`asyncio.Task`, this is a distinct object you hold onto — not
+    the result itself. ``id`` is available as soon as ``start()`` returns; call
+    :meth:`result` to block until the solve finishes, or :meth:`cancel` to stop
+    it early.
+    """
+
+    def __init__(self, solves: Solves, solve: Solve) -> None:
+        self.id: str = solve.id
+        """The solve's id, available immediately after ``start()``."""
+        self._solves = solves
+        self._solve = solve
+        self._settled: Optional[Solve] = solve if solve.is_terminal else None
+
+    def result(self, timeout: Optional[float] = None) -> Solve:
+        """Wait for the solve to finish and return it.
+
+        Long-polls under the hood until the solve is terminal, exactly like
+        :meth:`NoneCap.solve`. ``timeout`` is the overall budget in seconds
+        (defaults to ``DEFAULT_SOLVE_TIMEOUT``). Raises :class:`SolveTimeoutError`
+        if the budget elapses first, or :class:`SolveFailedError` if the solve
+        ends without a token.
+
+        Only a *terminal* outcome is memoized: once the solve settles, later
+        calls replay it without another request. A :class:`SolveTimeoutError` is
+        not cached, so a later call with a larger ``timeout`` resumes polling.
+        """
+        if self._settled is not None:
+            return self._result_from(self._settled)
+        budget = DEFAULT_SOLVE_TIMEOUT if timeout is None else timeout
+        deadline = time.monotonic() + budget
+        solve = self._solve
+        while not solve.is_terminal:
+            if time.monotonic() >= deadline:
+                raise SolveTimeoutError(
+                    f"Solve {solve.id} did not finish within {budget:g}s "
+                    f"(last status: {solve.status}).",
+                    solve_id=solve.id,
+                    solve=solve,
+                )
+            solve = self._solves.retrieve(solve.id, wait=_wait_seconds(deadline))
+            self._solve = solve
+        self._settled = solve
+        return self._result_from(solve)
+
+    def cancel(self) -> Solve:
+        """Cancel the solve and return its resulting state. Cancelled solves are
+        never charged. If the solve has already finished, the server replies 409;
+        that is swallowed and the solve's current state is returned instead, so
+        cancelling a completed solve is never an error.
+
+        A terminal result (including ``cancelled``) is memoized as the handle's
+        settled outcome, so a later :meth:`result` reflects it instead of polling
+        — ``cancelled`` is terminal-but-not-solved, so ``result()`` then raises
+        :class:`SolveFailedError`.
+        """
+        try:
+            solve = self._solves.cancel(self.id)
+        except ConflictError:
+            solve = self._solves.retrieve(self.id)
+        self._solve = solve
+        if solve.is_terminal:
+            self._settled = solve
+        return solve
+
+    @staticmethod
+    def _result_from(solve: Solve) -> Solve:
+        """Map a settled (terminal) solve to ``result()``'s return/raise."""
+        if solve.status != "solved":
+            raise SolveFailedError(solve)
+        return solve
+
+
 class NoneCap(_BaseClient):
     """The NoneCap API client (sync).
 
@@ -383,12 +522,14 @@ class NoneCap(_BaseClient):
         solve is terminal or ``timeout`` seconds elapse. Raises
         :class:`SolveFailedError` if the solve fails/expires/is cancelled, or
         :class:`SolveTimeoutError` on timeout.
+
+        This is sugar for ``solves.start(...).result(timeout)``; reach for
+        :meth:`Solves.start` directly when you need a handle you can cancel.
         """
-        deadline = time.monotonic() + timeout
         # Build the body directly rather than dispatching through the
-        # overloaded create(): the union-typed passthrough args defeat
-        # overload resolution, and the runtime rqdata check lives in
-        # _build_solve_body either way.
+        # overloaded start(): the union-typed passthrough args defeat overload
+        # resolution, and the runtime rqdata check lives in _build_solve_body
+        # either way.
         body = _build_solve_body(
             type=type,
             sitekey=sitekey,
@@ -398,21 +539,7 @@ class NoneCap(_BaseClient):
             proxy=proxy,
             webhook_url=webhook_url,
         )
-        wait = _wait_seconds(deadline)
-        payload = self._request(
-            "POST", "/v1/solves", params={"wait": wait}, json=body, wait=wait
-        )
-        solve = Solve._from_dict(payload)
-        while not solve.is_terminal:
-            if time.monotonic() >= deadline:
-                raise SolveTimeoutError(
-                    f"Solve {solve.id} did not finish within {timeout:g}s "
-                    f"(last status: {solve.status})."
-                )
-            solve = self.solves.retrieve(solve.id, wait=_wait_seconds(deadline))
-        if solve.status != "solved":
-            raise SolveFailedError(solve)
-        return solve
+        return self.solves._start_from_body(body).result(timeout)
 
     def me(self) -> Account:
         """Fetch your account, including the current credit balance."""
@@ -501,6 +628,68 @@ class AsyncSolves:
         )
         return Solve._from_dict(payload)
 
+    @overload
+    async def start(
+        self,
+        *,
+        type: Literal["hcaptcha"],
+        sitekey: str,
+        url: str,
+        rqdata: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+    ) -> AsyncSolveHandle: ...
+
+    @overload
+    async def start(
+        self,
+        *,
+        type: Literal["hcaptcha_enterprise"],
+        sitekey: str,
+        url: str,
+        rqdata: str,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+    ) -> AsyncSolveHandle: ...
+
+    async def start(
+        self,
+        *,
+        type: SolveType,
+        sitekey: str,
+        url: str,
+        rqdata: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        proxy: Union[Proxy, str, None] = None,
+        webhook_url: Optional[str] = None,
+    ) -> AsyncSolveHandle:
+        """Submit a solve and return an :class:`AsyncSolveHandle` without waiting.
+
+        The handle's ``id`` is populated immediately, so you can later
+        :meth:`AsyncSolveHandle.cancel` the solve or await its outcome with
+        :meth:`AsyncSolveHandle.result`. Use this over :meth:`AsyncNoneCap.solve`
+        when you need a handle you can cancel — for clean shutdown, freeing a
+        worker slot, or stopping early.
+        """
+        body = _build_solve_body(
+            type=type,
+            sitekey=sitekey,
+            url=url,
+            rqdata=rqdata,
+            user_agent=user_agent,
+            proxy=proxy,
+            webhook_url=webhook_url,
+        )
+        return await self._start_from_body(body)
+
+    async def _start_from_body(self, body: dict[str, Any]) -> AsyncSolveHandle:
+        """Shared by :meth:`start` and :meth:`AsyncNoneCap.solve`: POST the solve
+        (without long-polling) and wrap the pending resource in a handle."""
+        payload = await self._client._request("POST", "/v1/solves", json=body)
+        return AsyncSolveHandle(self, Solve._from_dict(payload))
+
     async def retrieve(self, solve_id: str, *, wait: Optional[int] = None) -> Solve:
         """Fetch a solve by id. Pass ``wait`` to long-poll until it finishes."""
         payload = await self._client._request(
@@ -558,6 +747,115 @@ class AsyncSolves:
             cursor = page.data[-1].id
 
 
+class AsyncSolveHandle:
+    """A handle to a submitted solve, returned by ``await`` :meth:`AsyncSolves.start`.
+
+    Like :class:`asyncio.Task`, this is a distinct object you hold onto — not
+    the result itself. ``id`` is available as soon as ``start()`` resolves;
+    ``await`` :meth:`result` to wait until the solve finishes, or ``await``
+    :meth:`cancel` to stop it early.
+    """
+
+    def __init__(self, solves: AsyncSolves, solve: Solve) -> None:
+        self.id: str = solve.id
+        """The solve's id, available immediately after ``start()``."""
+        self._solves = solves
+        self._solve = solve
+        self._settled: Optional[Solve] = solve if solve.is_terminal else None
+        self._inflight: Optional[asyncio.Future[Solve]] = None
+
+    async def result(self, timeout: Optional[float] = None) -> Solve:
+        """Wait for the solve to finish and return it.
+
+        Long-polls under the hood until the solve is terminal, exactly like
+        :meth:`AsyncNoneCap.solve`. ``timeout`` is the overall budget in seconds
+        (defaults to ``DEFAULT_SOLVE_TIMEOUT``). Raises :class:`SolveTimeoutError`
+        if the budget elapses first, or :class:`SolveFailedError` if the solve
+        ends without a token.
+
+        Only a *terminal* outcome is memoized: once the solve settles, later
+        calls replay it without another request. A :class:`SolveTimeoutError` is
+        not cached, so a later call with a larger ``timeout`` resumes polling.
+        Concurrent calls share one in-flight poll rather than each opening their
+        own long-poll connection.
+        """
+        if self._settled is not None:
+            return self._result_from(self._settled)
+        budget = DEFAULT_SOLVE_TIMEOUT if timeout is None else timeout
+        if self._inflight is None:
+            self._inflight = asyncio.ensure_future(self._poll(budget))
+        task = self._inflight
+        try:
+            solve = await task
+        except asyncio.CancelledError:
+            # cancel() cancels the shared poll once it has settled the handle;
+            # awaiters then replay the cached terminal outcome.
+            if task.cancelled() and self._settled is not None:
+                return self._result_from(self._settled)
+            if self._inflight is task:
+                self._inflight = None
+            raise
+        except SolveTimeoutError:
+            # Timeouts are retryable: drop the shared poll so a later call (with
+            # a larger budget) starts fresh instead of replaying the timeout.
+            if self._inflight is task:
+                self._inflight = None
+            raise
+        if self._inflight is task:
+            self._inflight = None
+        self._settled = solve
+        return self._result_from(solve)
+
+    async def _poll(self, budget: float) -> Solve:
+        """The shared long-poll loop. Returns a terminal solve or raises
+        :class:`SolveTimeoutError`; never caches (the caller settles)."""
+        deadline = time.monotonic() + budget
+        solve = self._solve
+        while not solve.is_terminal:
+            if time.monotonic() >= deadline:
+                raise SolveTimeoutError(
+                    f"Solve {solve.id} did not finish within {budget:g}s "
+                    f"(last status: {solve.status}).",
+                    solve_id=solve.id,
+                    solve=solve,
+                )
+            solve = await self._solves.retrieve(solve.id, wait=_wait_seconds(deadline))
+            self._solve = solve
+        return solve
+
+    async def cancel(self) -> Solve:
+        """Cancel the solve and return its resulting state. Cancelled solves are
+        never charged. If the solve has already finished, the server replies 409;
+        that is swallowed and the solve's current state is returned instead, so
+        cancelling a completed solve is never an error.
+
+        A terminal result (including ``cancelled``) is memoized as the handle's
+        settled outcome and any in-flight :meth:`result` poll is stopped, so an
+        awaiting or later ``result()`` settles to the cancelled solve instead of
+        polling on. ``cancelled`` is terminal-but-not-solved, so ``result()``
+        then raises :class:`SolveFailedError`.
+        """
+        try:
+            solve = await self._solves.cancel(self.id)
+        except ConflictError:
+            solve = await self._solves.retrieve(self.id)
+        self._solve = solve
+        if solve.is_terminal:
+            self._settled = solve
+            inflight = self._inflight
+            self._inflight = None
+            if inflight is not None and not inflight.done():
+                inflight.cancel()
+        return solve
+
+    @staticmethod
+    def _result_from(solve: Solve) -> Solve:
+        """Map a settled (terminal) solve to ``result()``'s return/raise."""
+        if solve.status != "solved":
+            raise SolveFailedError(solve)
+        return solve
+
+
 class AsyncNoneCap(_BaseClient):
     """The NoneCap API client (async).
 
@@ -651,10 +949,13 @@ class AsyncNoneCap(_BaseClient):
         solve is terminal or ``timeout`` seconds elapse. Raises
         :class:`SolveFailedError` if the solve fails/expires/is cancelled, or
         :class:`SolveTimeoutError` on timeout.
+
+        This is sugar for ``(await solves.start(...)).result(timeout)``; reach
+        for :meth:`AsyncSolves.start` directly when you need a handle you can
+        cancel.
         """
-        deadline = time.monotonic() + timeout
         # Same shape as the sync client: build the body directly instead of
-        # dispatching through the overloaded create() with union-typed args.
+        # dispatching through the overloaded start() with union-typed args.
         body = _build_solve_body(
             type=type,
             sitekey=sitekey,
@@ -664,21 +965,8 @@ class AsyncNoneCap(_BaseClient):
             proxy=proxy,
             webhook_url=webhook_url,
         )
-        wait = _wait_seconds(deadline)
-        payload = await self._request(
-            "POST", "/v1/solves", params={"wait": wait}, json=body, wait=wait
-        )
-        solve = Solve._from_dict(payload)
-        while not solve.is_terminal:
-            if time.monotonic() >= deadline:
-                raise SolveTimeoutError(
-                    f"Solve {solve.id} did not finish within {timeout:g}s "
-                    f"(last status: {solve.status})."
-                )
-            solve = await self.solves.retrieve(solve.id, wait=_wait_seconds(deadline))
-        if solve.status != "solved":
-            raise SolveFailedError(solve)
-        return solve
+        handle = await self.solves._start_from_body(body)
+        return await handle.result(timeout)
 
     async def me(self) -> Account:
         """Fetch your account, including the current credit balance."""

{nonecap-0.1.0 → nonecap-0.2.0}/src/nonecap/_errors.py

@@ -71,7 +71,26 @@ class APITimeoutError(APIConnectionError):
 
 
 class SolveTimeoutError(NoneCapError):
-    """Raised by ``solve()`` when the overall timeout elapses first."""
+    """Raised by ``solve()`` / ``SolveHandle.result()`` when the overall timeout
+    elapses before the solve reaches a terminal state.
+
+    When the timeout originates from waiting on a specific solve, ``solve_id`` is
+    the solve's id and ``solve`` is its last-known state (still non-terminal), so
+    you can retry or inspect the latest status. Both are ``None`` only if the
+    error was constructed without a solve in hand."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        solve_id: Optional[str] = None,
+        solve: Optional[Solve] = None,
+    ) -> None:
+        super().__init__(message)
+        self.solve_id = solve_id
+        """The id of the solve that did not finish in time, when known."""
+        self.solve = solve
+        """The last-known (non-terminal) solve at the moment of timeout, when known."""
 
 
 class SolveFailedError(NoneCapError):

{nonecap-0.1.0 → nonecap-0.2.0}/src/nonecap/_types.py

@@ -97,12 +97,14 @@ class Solve:
 class SolvePage:
     """One page of solves, newest first."""
 
+    object: str
     data: list[Solve]
     has_more: bool
 
     @classmethod
     def _from_dict(cls, payload: dict[str, Any]) -> SolvePage:
         return cls(
+            object=payload.get("object", "list"),
             data=[Solve._from_dict(item) for item in payload.get("data", [])],
             has_more=bool(payload.get("has_more", False)),
         )
@@ -112,6 +114,7 @@ class SolvePage:
 class Account:
     """Your account, including the current credit balance."""
 
+    object: str
     id: str
     email: str
     credits_balance: int
@@ -120,6 +123,7 @@ class Account:
     @classmethod
     def _from_dict(cls, data: dict[str, Any]) -> Account:
         return cls(
+            object=data.get("object", "account"),
             id=data["id"],
             email=data.get("email", ""),
             credits_balance=int(data.get("credits_balance", 0)),

nonecap-0.2.0/src/nonecap/_version.py

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

nonecap-0.2.0/tests/test_async_client.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+import pytest
+
+from nonecap import AsyncNoneCap, SolveFailedError, SolveTimeoutError, ValidationError
+
+from .conftest import Script, error_payload, solve_payload
+
+
+def client_for(script: Script) -> AsyncNoneCap:
+    return AsyncNoneCap(
+        api_key="nc_test",
+        http_client=httpx.AsyncClient(transport=script.transport),
+    )
+
+
+async def test_create_posts_with_bearer_auth() -> None:
+    script = Script((202, solve_payload()))
+    nc = client_for(script)
+    await nc.solves.create(type="hcaptcha", sitekey="sk", url="https://e.com")
+    request = script.requests[0]
+    assert request.method == "POST"
+    assert request.headers["Authorization"] == "Bearer nc_test"
+
+
+async def test_solve_polls_until_terminal() -> None:
+    script = Script(
+        (202, solve_payload(status="pending")),
+        (202, solve_payload(status="solving")),
+        (200, solve_payload(status="solved", token="TOK")),
+    )
+    nc = client_for(script)
+    solve = await nc.solve(type="hcaptcha", sitekey="sk", url="https://e.com")
+    assert solve.token == "TOK"
+    assert len(script.requests) == 3
+
+
+async def test_solve_failed_raises_with_solve_attached() -> None:
+    failed = solve_payload(status="failed", error={"code": "unsolvable", "message": "no"})
+    script = Script((200, failed))
+    nc = client_for(script)
+    with pytest.raises(SolveFailedError) as exc_info:
+        await nc.solve(type="hcaptcha", sitekey="sk", url="https://e.com")
+    assert exc_info.value.solve.status == "failed"
+
+
+async def test_solve_times_out() -> None:
+    script = Script((202, solve_payload(status="solving")))
+    nc = client_for(script)
+    with pytest.raises(SolveTimeoutError):
+        await nc.solve(type="hcaptcha", sitekey="sk", url="https://e.com", timeout=0)
+
+
+async def test_enterprise_without_rqdata_raises_locally() -> None:
+    script = Script((202, solve_payload()))
+    nc = client_for(script)
+    with pytest.raises(ValidationError):
+        await nc.solves.create(type="hcaptcha_enterprise", sitekey="sk", url="https://e.com")  # type: ignore[call-overload]
+    assert script.requests == []
+
+
+async def test_list_all_walks_pages() -> None:
+    page1 = {
+        "object": "list",
+        "data": [solve_payload(id="a"), solve_payload(id="b")],
+        "has_more": True,
+    }
+    page2 = {"object": "list", "data": [solve_payload(id="c")], "has_more": False}
+    script = Script((200, page1), (200, page2))
+    nc = client_for(script)
+    ids = [s.id async for s in nc.solves.list_all()]
+    assert ids == ["a", "b", "c"]
+    assert script.requests[1].url.params["starting_after"] == "b"
+
+
+async def test_me() -> None:
+    account = {
+        "object": "account",
+        "id": "u_1",
+        "email": "a@b.com",
+        "credits_balance": 7,
+        "created_at": "x",
+    }
+    script = Script((200, account))
+    nc = client_for(script)
+    me = await nc.me()
+    assert me.credits_balance == 7
+
+
+async def test_start_returns_handle_then_result_polls() -> None:
+    script = Script(
+        (202, solve_payload(status="pending")),
+        (200, solve_payload(status="solved", token="TOK")),
+    )
+    nc = client_for(script)
+    handle = await nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+    assert handle.id == "solve_1"
+    assert len(script.requests) == 1  # only the create POST
+    solve = await handle.result()
+    assert solve.token == "TOK"
+    assert len(script.requests) == 2
+
+
+async def test_result_is_cached_when_awaited_twice() -> None:
+    script = Script(
+        (202, solve_payload(status="pending")),
+        (200, solve_payload(status="solved", token="TOK")),
+    )
+    nc = client_for(script)
+    handle = await nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+    first = await handle.result()
+    count = len(script.requests)
+    second = await handle.result()
+    assert first is second
+    assert len(script.requests) == count
+
+
+async def test_handle_cancel_after_terminal_swallows_conflict() -> None:
+    script = Script(
+        (202, solve_payload(status="pending")),
+        (409, error_payload("conflict")),
+        (200, solve_payload(status="solved", token="TOK")),
+    )
+    nc = client_for(script)
+    handle = await nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+    solve = await handle.cancel()
+    assert solve.status == "solved"
+    assert script.requests[1].method == "DELETE"
+    assert script.requests[2].method == "GET"
+
+
+async def test_handle_result_times_out() -> None:
+    script = Script((202, solve_payload(status="solving")))
+    nc = client_for(script)
+    handle = await nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+    with pytest.raises(SolveTimeoutError):
+        await handle.result(timeout=0)
+
+
+async def test_timeout_carries_solve_id_and_solve() -> None:
+    script = Script((202, solve_payload(status="solving")))
+    nc = client_for(script)
+    handle = await nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+    with pytest.raises(SolveTimeoutError) as exc_info:
+        await handle.result(timeout=0)
+    assert exc_info.value.solve_id == "solve_1"
+    assert exc_info.value.solve is not None
+    assert exc_info.value.solve.status == "solving"
+
+
+async def test_timeout_is_not_cached_and_resumes() -> None:
+    script = Script(
+        (202, solve_payload(status="solving")),
+        (200, solve_payload(status="solved", token="TOK")),
+    )
+    nc = client_for(script)
+    handle = await nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+    with pytest.raises(SolveTimeoutError):
+        await handle.result(timeout=0)
+    assert len(script.requests) == 1  # the timeout never polled
+    solve = await handle.result(timeout=30)
+    assert solve.token == "TOK"
+    assert len(script.requests) == 2  # re-polled, did not replay the timeout
+
+
+async def test_concurrent_result_calls_share_one_poll() -> None:
+    script = Script(
+        (202, solve_payload(status="pending")),
+        (200, solve_payload(status="solved", token="TOK")),
+    )
+    nc = client_for(script)
+    handle = await nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+    first, second = await asyncio.gather(handle.result(), handle.result())
+    assert first is second  # both observe the same settled outcome
+    assert first.token == "TOK"
+    # one POST + exactly one shared GET poll, not two.
+    assert len(script.requests) == 2
+    assert sum(1 for r in script.requests if r.method == "GET") == 1
+
+
+async def test_cancel_then_result_settles_to_cancelled_without_polling() -> None:
+    script = Script(
+        (202, solve_payload(status="pending")),
+        (200, solve_payload(status="cancelled")),
+    )
+    nc = client_for(script)
+    handle = await nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+    await handle.cancel()
+    with pytest.raises(SolveFailedError) as exc_info:
+        await handle.result()
+    assert exc_info.value.solve.status == "cancelled"
+    assert len(script.requests) == 2  # POST + DELETE only
+
+
+class _GatedTransport(httpx.AsyncBaseTransport):
+    """Async transport whose GET polls block until ``release`` is set, so a
+    cancel() can land while a result() poll is genuinely in flight."""
+
+    def __init__(self) -> None:
+        self.release = asyncio.Event()
+        self.get_count = 0
+        self.requests: list[httpx.Request] = []
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        if request.method == "POST":
+            return httpx.Response(202, json=solve_payload(status="pending"))
+        if request.method == "DELETE":
+            return httpx.Response(200, json=solve_payload(status="cancelled"))
+        # GET poll: block so the test can interleave a cancel().
+        self.get_count += 1
+        await self.release.wait()
+        return httpx.Response(200, json=solve_payload(status="pending"))
+
+
+async def test_cancel_settles_a_result_already_awaiting() -> None:
+    transport = _GatedTransport()
+    nc = AsyncNoneCap(api_key="k", http_client=httpx.AsyncClient(transport=transport))
+    handle = await nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+    waiter: asyncio.Task[Any] = asyncio.create_task(handle.result(timeout=30))
+    # Let result() start polling and block inside the gated GET.
+    while transport.get_count == 0:
+        await asyncio.sleep(0)
+    cancelled = await handle.cancel()
+    assert cancelled.status == "cancelled"
+    # The already-awaiting result() settles to the cancelled (terminal) solve.
+    with pytest.raises(SolveFailedError) as exc_info:
+        await waiter
+    assert exc_info.value.solve.status == "cancelled"
+    transport.release.set()  # unblock any straggler so the client closes cleanly
+    await nc.close()
+
+
+async def test_async_context_manager_closes_owned_client() -> None:
+    async with AsyncNoneCap(api_key="k") as nc:
+        http = nc._http
+    assert http.is_closed

{nonecap-0.1.0 → nonecap-0.2.0}/tests/test_client.py

@@ -219,6 +219,129 @@ class TestSolveHelper:
             nc.solve(type="hcaptcha", sitekey="sk", url="https://e.com", timeout=0)
 
 
+class TestSolveHandle:
+    def test_start_returns_handle_with_id_without_polling(self) -> None:
+        script = Script((202, solve_payload(status="pending")))
+        nc = client_for(script)
+        handle = nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+        assert handle.id == "solve_1"
+        assert len(script.requests) == 1  # only the create POST
+        assert script.requests[0].method == "POST"
+
+    def test_result_polls_until_terminal(self) -> None:
+        script = Script(
+            (202, solve_payload(status="pending")),
+            (202, solve_payload(status="solving")),
+            (200, solve_payload(status="solved", token="TOK")),
+        )
+        nc = client_for(script)
+        handle = nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+        solve = handle.result()
+        assert solve.token == "TOK"
+        assert len(script.requests) == 3
+        assert script.requests[1].method == "GET"
+
+    def test_result_is_cached_when_called_twice(self) -> None:
+        script = Script(
+            (202, solve_payload(status="pending")),
+            (200, solve_payload(status="solved", token="TOK")),
+        )
+        nc = client_for(script)
+        handle = nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+        first = handle.result()
+        count_after_first = len(script.requests)
+        second = handle.result()
+        assert first is second  # same settled outcome, replayed
+        assert len(script.requests) == count_after_first  # no extra request
+
+    def test_result_raises_solve_failed(self) -> None:
+        script = Script(
+            (202, solve_payload(status="pending")),
+            (200, solve_payload(status="failed", error={"code": "x", "message": "no"})),
+        )
+        nc = client_for(script)
+        handle = nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+        with pytest.raises(SolveFailedError):
+            handle.result()
+
+    def test_result_times_out(self) -> None:
+        script = Script((202, solve_payload(status="solving")))
+        nc = client_for(script)
+        handle = nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+        with pytest.raises(SolveTimeoutError):
+            handle.result(timeout=0)
+
+    def test_timeout_carries_solve_id_and_solve(self) -> None:
+        script = Script((202, solve_payload(status="solving")))
+        nc = client_for(script)
+        handle = nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+        with pytest.raises(SolveTimeoutError) as exc_info:
+            handle.result(timeout=0)
+        assert exc_info.value.solve_id == "solve_1"
+        assert exc_info.value.solve is not None
+        assert exc_info.value.solve.status == "solving"
+
+    def test_timeout_is_not_cached_and_resumes(self) -> None:
+        # timeout=0 raises without polling; a later call resumes to terminal.
+        script = Script(
+            (202, solve_payload(status="solving")),
+            (200, solve_payload(status="solved", token="TOK")),
+        )
+        nc = client_for(script)
+        handle = nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+        with pytest.raises(SolveTimeoutError):
+            handle.result(timeout=0)
+        assert len(script.requests) == 1  # only the POST; the timeout never polled
+        solve = handle.result(timeout=30)
+        assert solve.token == "TOK"
+        assert len(script.requests) == 2  # re-polled, did not replay the timeout
+
+    def test_cancel_then_result_settles_to_cancelled_without_polling(self) -> None:
+        script = Script(
+            (202, solve_payload(status="pending")),
+            (200, solve_payload(status="cancelled")),
+        )
+        nc = client_for(script)
+        handle = nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+        handle.cancel()
+        with pytest.raises(SolveFailedError) as exc_info:
+            handle.result()
+        assert exc_info.value.solve.status == "cancelled"
+        assert len(script.requests) == 2  # POST + DELETE only, no extra poll
+
+    def test_cancel_deletes_and_returns_state(self) -> None:
+        script = Script(
+            (202, solve_payload(status="pending")),
+            (200, solve_payload(status="cancelled")),
+        )
+        nc = client_for(script)
+        handle = nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+        solve = handle.cancel()
+        assert solve.status == "cancelled"
+        assert script.requests[1].method == "DELETE"
+
+    def test_cancel_after_terminal_swallows_conflict(self) -> None:
+        script = Script(
+            (202, solve_payload(status="pending")),
+            (409, error_payload("conflict")),
+            (200, solve_payload(status="solved", token="TOK")),
+        )
+        nc = client_for(script)
+        handle = nc.solves.start(type="hcaptcha", sitekey="sk", url="https://e.com")
+        solve = handle.cancel()
+        assert solve.status == "solved"
+        assert script.requests[1].method == "DELETE"  # the 409
+        assert script.requests[2].method == "GET"  # the retrieve fallback
+
+    def test_enterprise_without_rqdata_raises_locally(self) -> None:
+        script = Script((202, solve_payload()))
+        nc = client_for(script)
+        with pytest.raises(ValidationError) as exc_info:
+            nc.solves.start(type="hcaptcha_enterprise", sitekey="sk", url="https://e.com")  # type: ignore[call-overload]  # noqa: E501
+        assert exc_info.value.param == "rqdata"
+        assert script.requests == []
+
+
 class TestLifecycle:
     def test_cancel_deletes(self) -> None:
         script = Script((200, solve_payload(status="cancelled")))

{nonecap-0.1.0 → nonecap-0.2.0}/tests/typing_assertions.py

@@ -10,7 +10,16 @@ the build.
 
 from __future__ import annotations
 
-from nonecap import AsyncNoneCap, NoneCap
+from typing import Optional
+
+from nonecap import (
+    AsyncNoneCap,
+    AsyncSolveHandle,
+    NoneCap,
+    Solve,
+    SolveHandle,
+    SolveTimeoutError,
+)
 
 nc = NoneCap(api_key="k")
 anc = AsyncNoneCap(api_key="k")
@@ -23,21 +32,41 @@ def positive_cases() -> None:
     # enterprise: rqdata provided.
     nc.solve(type="hcaptcha_enterprise", sitekey="s", url="u", rqdata="r")
     nc.solves.create(type="hcaptcha_enterprise", sitekey="s", url="u", rqdata="r")
+    # start() returns a handle; result()/cancel() return Solve.
+    handle: SolveHandle = nc.solves.start(type="hcaptcha", sitekey="s", url="u")
+    _id: str = handle.id
+    _r: Solve = handle.result()
+    _r2: Solve = handle.result(timeout=10.0)
+    _c: Solve = handle.cancel()
+    nc.solves.start(type="hcaptcha_enterprise", sitekey="s", url="u", rqdata="r")
 
 
 async def positive_cases_async() -> None:
     await anc.solve(type="hcaptcha", sitekey="s", url="u")
     await anc.solves.create(type="hcaptcha_enterprise", sitekey="s", url="u", rqdata="r")
+    handle: AsyncSolveHandle = await anc.solves.start(type="hcaptcha", sitekey="s", url="u")
+    _id: str = handle.id
+    _r: Solve = await handle.result()
+    _r2: Solve = await handle.result(timeout=10.0)
+    _c: Solve = await handle.cancel()
 
 
 def negative_cases() -> None:
     # Enterprise without rqdata must not type-check.
     nc.solve(type="hcaptcha_enterprise", sitekey="s", url="u")  # type: ignore[call-overload]
     nc.solves.create(type="hcaptcha_enterprise", sitekey="s", url="u")  # type: ignore[call-overload]
+    nc.solves.start(type="hcaptcha_enterprise", sitekey="s", url="u")  # type: ignore[call-overload]
     # Unknown captcha type must not type-check.
     nc.solve(type="recaptcha", sitekey="s", url="u")  # type: ignore[call-overload]
 
 
+def timeout_error_fields(err: SolveTimeoutError) -> None:
+    # SolveTimeoutError exposes the solve it timed out on.
+    _sid: Optional[str] = err.solve_id
+    _solve: Optional[Solve] = err.solve
+
+
 async def negative_cases_async() -> None:
     await anc.solve(type="hcaptcha_enterprise", sitekey="s", url="u")  # type: ignore[call-overload]
     await anc.solves.create(type="hcaptcha_enterprise", sitekey="s", url="u")  # type: ignore[call-overload]
+    await anc.solves.start(type="hcaptcha_enterprise", sitekey="s", url="u")  # type: ignore[call-overload]

nonecap-0.1.0/src/nonecap/_version.py

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

nonecap-0.1.0/tests/test_async_client.py

@@ -1,94 +0,0 @@
-from __future__ import annotations
-
-import httpx
-import pytest
-
-from nonecap import AsyncNoneCap, SolveFailedError, SolveTimeoutError, ValidationError
-
-from .conftest import Script, solve_payload
-
-
-def client_for(script: Script) -> AsyncNoneCap:
-    return AsyncNoneCap(
-        api_key="nc_test",
-        http_client=httpx.AsyncClient(transport=script.transport),
-    )
-
-
-async def test_create_posts_with_bearer_auth() -> None:
-    script = Script((202, solve_payload()))
-    nc = client_for(script)
-    await nc.solves.create(type="hcaptcha", sitekey="sk", url="https://e.com")
-    request = script.requests[0]
-    assert request.method == "POST"
-    assert request.headers["Authorization"] == "Bearer nc_test"
-
-
-async def test_solve_polls_until_terminal() -> None:
-    script = Script(
-        (202, solve_payload(status="pending")),
-        (202, solve_payload(status="solving")),
-        (200, solve_payload(status="solved", token="TOK")),
-    )
-    nc = client_for(script)
-    solve = await nc.solve(type="hcaptcha", sitekey="sk", url="https://e.com")
-    assert solve.token == "TOK"
-    assert len(script.requests) == 3
-
-
-async def test_solve_failed_raises_with_solve_attached() -> None:
-    failed = solve_payload(status="failed", error={"code": "unsolvable", "message": "no"})
-    script = Script((200, failed))
-    nc = client_for(script)
-    with pytest.raises(SolveFailedError) as exc_info:
-        await nc.solve(type="hcaptcha", sitekey="sk", url="https://e.com")
-    assert exc_info.value.solve.status == "failed"
-
-
-async def test_solve_times_out() -> None:
-    script = Script((202, solve_payload(status="solving")))
-    nc = client_for(script)
-    with pytest.raises(SolveTimeoutError):
-        await nc.solve(type="hcaptcha", sitekey="sk", url="https://e.com", timeout=0)
-
-
-async def test_enterprise_without_rqdata_raises_locally() -> None:
-    script = Script((202, solve_payload()))
-    nc = client_for(script)
-    with pytest.raises(ValidationError):
-        await nc.solves.create(type="hcaptcha_enterprise", sitekey="sk", url="https://e.com")  # type: ignore[call-overload]
-    assert script.requests == []
-
-
-async def test_list_all_walks_pages() -> None:
-    page1 = {
-        "object": "list",
-        "data": [solve_payload(id="a"), solve_payload(id="b")],
-        "has_more": True,
-    }
-    page2 = {"object": "list", "data": [solve_payload(id="c")], "has_more": False}
-    script = Script((200, page1), (200, page2))
-    nc = client_for(script)
-    ids = [s.id async for s in nc.solves.list_all()]
-    assert ids == ["a", "b", "c"]
-    assert script.requests[1].url.params["starting_after"] == "b"
-
-
-async def test_me() -> None:
-    account = {
-        "object": "account",
-        "id": "u_1",
-        "email": "a@b.com",
-        "credits_balance": 7,
-        "created_at": "x",
-    }
-    script = Script((200, account))
-    nc = client_for(script)
-    me = await nc.me()
-    assert me.credits_balance == 7
-
-
-async def test_async_context_manager_closes_owned_client() -> None:
-    async with AsyncNoneCap(api_key="k") as nc:
-        http = nc._http
-    assert http.is_closed