Extract shared mixins, add documentation and examples for async support

- Extract _BaseClientMixin and _BaseJobMixin into _common.py to share
  init logic, payload builders, solution getters, and repr between
  sync and async clients
- Refactor AnticaptchaClient and AsyncAnticaptchaClient to inherit
  from shared mixins, reducing maintenance burden
- Add "Async Usage" section to README.md and docs/usage.rst
- Add async_client automodule to docs/api.rst
- Add CHANGELOG.rst entries for async support
- Add async example scripts (async_recaptcha_request.py, async_balance.py)
- Add "Framework :: AsyncIO" and "Topic :: Internet :: WWW/HTTP" classifiers
- Add "asyncio", "async", "httpx" keywords for PyPI discoverability

https://claude.ai/code/session_01Pimg4VAco2v4srPeZj44Zm

Author: claude

CHANGELOG.rst

@@ -7,6 +7,8 @@ Unreleased
 Added
 #####
 
+- Add ``AsyncAnticaptchaClient`` and ``AsyncJob`` for async/await usage with ``httpx`` (``pip install python-anticaptcha[async]``)
+- Add shared ``_BaseClientMixin`` and ``_BaseJobMixin`` to reduce duplication between sync and async clients
 - Add context manager support to ``AnticaptchaClient`` (``__enter__``, ``__exit__``, ``close``)
 - Add ``ANTICAPTCHA_API_KEY`` environment variable fallback for ``AnticaptchaClient``
 - Add ``Proxy`` frozen dataclass with ``parse_url()`` and ``to_kwargs()`` methods

README.md

@@ -20,6 +20,12 @@ Install as standard Python package using:
 pip install python-anticaptcha
 ```
 
+For async support (FastAPI, aiohttp, Starlette, etc.):
+
+```
+pip install python-anticaptcha[async]
+```
+
 ## Usage
 
 To use this library you need [Anticaptcha.com](http://getcaptchasolution.com/p9bwplkicx) API key.
@@ -42,6 +48,27 @@ with AnticaptchaClient(api_key) as client:
     job.join()
 ```
 
+### Async Usage
+
+For async frameworks, use `AsyncAnticaptchaClient` — the API mirrors the sync
+client but all methods are awaitable:
+
+```python
+from python_anticaptcha import AsyncAnticaptchaClient, NoCaptchaTaskProxylessTask
+
+api_key = '174faff8fbc769e94a5862391ecfd010'
+site_key = '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-'
+url = 'https://www.google.com/recaptcha/api2/demo'
+
+async with AsyncAnticaptchaClient(api_key) as client:
+    task = NoCaptchaTaskProxylessTask(url, site_key)
+    job = await client.create_task(task)
+    await job.join()
+    print(job.get_solution_response())
+```
+
+The full integration example is available in file `examples/async_recaptcha_request.py`.
+
 ### Solve recaptcha
 
 Example snippet for Recaptcha:

docs/api.rst

@@ -8,6 +8,13 @@ Base
    :members:
    :undoc-members:
 
+Async Client
+------------
+
+ .. automodule:: python_anticaptcha.async_client
+   :members:
+   :undoc-members:
+
 Exceptions
 ----------
 

docs/usage.rst

@@ -21,6 +21,32 @@ The client can be used as a context manager to ensure the underlying session is
         job = client.create_task(task)
         job.join()
 
+Async client
+############
+
+For async frameworks (FastAPI, aiohttp, Starlette), install with async support::
+
+    pip install python-anticaptcha[async]
+
+Then use ``AsyncAnticaptchaClient`` — the API mirrors the sync client but all
+methods are awaitable:
+
+.. code:: python
+
+    from python_anticaptcha import AsyncAnticaptchaClient, NoCaptchaTaskProxylessTask
+
+    api_key = '174faff8fbc769e94a5862391ecfd010'
+    site_key = '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-'
+    url = 'https://www.google.com/recaptcha/api2/demo'
+
+    async with AsyncAnticaptchaClient(api_key) as client:
+        task = NoCaptchaTaskProxylessTask(url, site_key)
+        job = await client.create_task(task)
+        await job.join()
+        print(job.get_solution_response())
+
+The full integration example is available in file ``examples/async_recaptcha_request.py``.
+
 Solve recaptcha
 ###############
 

examples/async_balance.py

@@ -0,0 +1,17 @@
+import asyncio
+from os import environ
+from pprint import pprint
+
+from python_anticaptcha import AsyncAnticaptchaClient
+
+api_key = environ["KEY"]
+
+
+async def process():
+    async with AsyncAnticaptchaClient(api_key) as client:
+        balance = await client.get_balance()
+        pprint(balance)
+
+
+if __name__ == "__main__":
+    asyncio.run(process())

examples/async_recaptcha_request.py

@@ -0,0 +1,40 @@
+import asyncio
+import re
+from os import environ
+
+import httpx
+
+from python_anticaptcha import AsyncAnticaptchaClient, NoCaptchaTaskProxylessTask
+
+api_key = environ["KEY"]
+site_key_pattern = 'data-sitekey="(.+?)"'
+url = "https://www.google.com/recaptcha/api2/demo?invisible=false"
+EXPECTED_RESULT = "Verification Success... Hooray!"
+
+
+async def get_form_html(session: httpx.AsyncClient) -> str:
+    return (await session.get(url)).text
+
+
+async def get_token(client: AsyncAnticaptchaClient, form_html: str) -> str:
+    site_key = re.search(site_key_pattern, form_html).group(1)
+    task = NoCaptchaTaskProxylessTask(website_url=url, website_key=site_key)
+    job = await client.create_task(task)
+    await job.join()
+    return job.get_solution_response()
+
+
+async def form_submit(session: httpx.AsyncClient, token: str) -> str:
+    return (await session.post(url, data={"g-recaptcha-response": token})).text
+
+
+async def process():
+    async with AsyncAnticaptchaClient(api_key) as client, httpx.AsyncClient() as session:
+        html = await get_form_html(session)
+        token = await get_token(client, html)
+        return await form_submit(session, token)
+
+
+if __name__ == "__main__":
+    result = asyncio.run(process())
+    assert "Verification Success... Hooray!" in result

pyproject.toml

@@ -10,7 +10,7 @@ license = "MIT"
 requires-python = ">=3.9"
 dependencies = ["requests"]
 dynamic = ["version"]
-keywords = ["recaptcha", "captcha", "development"]
+keywords = ["recaptcha", "captcha", "development", "asyncio", "async", "httpx"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -21,6 +21,8 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Framework :: AsyncIO",
+    "Topic :: Internet :: WWW/HTTP",
 ]
 
 [project.urls]

python_anticaptcha/_common.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+from urllib.parse import urlparse
+
+from .exceptions import AnticaptchaException
+from .tasks import BaseTask
+
+SOFT_ID = 847
+SLEEP_EVERY_CHECK_FINISHED = 3
+MAXIMUM_JOIN_TIME = 60 * 5
+
+
+class _BaseClientMixin:
+    CREATE_TASK_URL = "/createTask"
+    TASK_RESULT_URL = "/getTaskResult"
+    BALANCE_URL = "/getBalance"
+    REPORT_IMAGE_URL = "/reportIncorrectImageCaptcha"
+    REPORT_RECAPTCHA_URL = "/reportIncorrectRecaptcha"
+    APP_STAT_URL = "/getAppStats"
+    SOFT_ID = SOFT_ID
+    language_pool = "en"
+    response_timeout = 5
+
+    def _init_client(
+        self, client_key: str | None, language_pool: str, host: str, use_ssl: bool,
+    ) -> None:
+        self.client_key = client_key or os.environ.get("ANTICAPTCHA_API_KEY")
+        if not self.client_key:
+            raise AnticaptchaException(
+                None,
+                "CONFIG_ERROR",
+                "API key required. Pass client_key or set ANTICAPTCHA_API_KEY env var.",
+            )
+        self.language_pool = language_pool
+        self.base_url = "{proto}://{host}/".format(
+            proto="https" if use_ssl else "http", host=host
+        )
+
+    def _build_create_task_request(self, task: BaseTask) -> dict[str, Any]:
+        return {
+            "clientKey": self.client_key,
+            "task": task.serialize(),
+            "softId": self.SOFT_ID,
+            "languagePool": self.language_pool,
+        }
+
+    def _build_key_request(self, **extra: Any) -> dict[str, Any]:
+        return {"clientKey": self.client_key, **extra}
+
+    def _process_check_response(
+        self, response: dict[str, Any], client_ip: str | None = None,
+    ) -> None:
+        if response.get("errorId", False) == 11 and client_ip:
+            response[
+                "errorDescription"
+            ] = "{} Your missing IP address is probably {}.".format(
+                response["errorDescription"], client_ip
+            )
+        if response.get("errorId", False):
+            raise AnticaptchaException(
+                response["errorId"], response["errorCode"], response["errorDescription"]
+            )
+
+    def _repr_client(self, class_name: str) -> str:
+        host = urlparse(self.base_url).hostname or self.base_url
+        return f"<{class_name} host={host!r}>"
+
+
+class _BaseJobMixin:
+    client = None
+    task_id = None
+    _last_result = None
+
+    def get_solution_response(self) -> str:  # Recaptcha
+        return self._last_result["solution"]["gRecaptchaResponse"]
+
+    def get_solution(self) -> dict[str, Any]:
+        return self._last_result["solution"]
+
+    def get_token_response(self) -> str:  # Funcaptcha
+        return self._last_result["solution"]["token"]
+
+    def get_answers(self) -> dict[str, str]:
+        return self._last_result["solution"]["answers"]
+
+    def get_captcha_text(self) -> str:  # Image
+        return self._last_result["solution"]["text"]
+
+    def get_cells_numbers(self) -> list[int]:
+        return self._last_result["solution"]["cellNumbers"]
+
+    def _repr_job(self, class_name: str) -> str:
+        status = self._last_result.get("status") if self._last_result else None
+        if status:
+            return f"<{class_name} task_id={self.task_id} status={status!r}>"
+        return f"<{class_name} task_id={self.task_id}>"