Add async support with AsyncAnticaptchaClient (#131)

* Add async support with AsyncAnticaptchaClient and AsyncJob

Add a new async_client module providing AsyncAnticaptchaClient and AsyncJob
classes that mirror the sync API but use httpx.AsyncClient and asyncio.sleep
for non-blocking operation in async frameworks (FastAPI, aiohttp, etc.).

This is a non-breaking change: the sync API is untouched, httpx remains an
optional dependency (pip install python-anticaptcha[async]), and the new
classes are lazily imported in __init__.py to avoid requiring httpx at
package import time.

https://claude.ai/code/session_01Pimg4VAco2v4srPeZj44Zm

* 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

* Balance sync and async as equal first-class citizens

- Rename base.py → sync_client.py for symmetry with async_client.py;
  add backward-compat base.py re-export shim
- Rename all sync example files with sync_ prefix to match async_ examples
- Rename test_base.py → test_sync_client.py
- Promote "Async Usage" to same heading level as sync in README and docs
- Add "Sync client" heading in docs/usage.rst for symmetry
- Rename "Base" → "Sync Client" in docs/api.rst
- Update __init__.py to import from sync_client instead of base
- All existing import paths preserved for backward compatibility

https://claude.ai/code/session_01Pimg4VAco2v4srPeZj44Zm

* Defer httpx ImportError to instantiation time for Sphinx compatibility

The module-level ImportError prevented Sphinx autodoc from importing
async_client when httpx is not installed. Now the module imports
successfully (setting httpx=None) and raises ImportError only when
AsyncAnticaptchaClient is instantiated without httpx.

https://claude.ai/code/session_01Pimg4VAco2v4srPeZj44Zm

* Fix CI: linter errors, mypy types, and add httpx to test deps

- Fix ruff import sorting in __init__.py, test_sync_client.py,
  test_async_client.py
- Fix ruff-format: async_client.py await parenthesization,
  string concatenation
- Fix mypy: add return type to __getattr__, add type:ignore for
  optional httpx import
- Add httpx to test dependencies so async tests work in CI
- Remove redundant explicit imports from base.py shim (covered by *)

https://claude.ai/code/session_01Pimg4VAco2v4srPeZj44Zm

* Fix E2E tests: update example imports to use sync_ prefix

The example files were renamed with sync_ prefix but test_examples.py
still imported them by their old names.

https://claude.ai/code/session_01Pimg4VAco2v4srPeZj44Zm

* Remove import aliases in test_examples.py, use sync_ prefixed names directly

https://claude.ai/code/session_01Pimg4VAco2v4srPeZj44Zm

* Add six to test dependencies

Required by funcaptcha and hcaptcha example tests.

https://claude.ai/code/session_01Pimg4VAco2v4srPeZj44Zm

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: ad-m

CHANGELOG.rst

@@ -7,6 +7,9 @@ Unreleased
 Added
 #####
 
+- Add ``AsyncAnticaptchaClient`` and ``AsyncJob`` for async/await usage with ``httpx`` (``pip install python-anticaptcha[async]``)
+- Rename ``base.py`` → ``sync_client.py`` for symmetry with ``async_client.py``; backward-compatible ``base.py`` shim preserved
+- Rename sync example files with ``sync_`` prefix to match ``async_`` examples
 - 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,29 @@ 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`.
+
+## Sync Usage
+
 ### Solve recaptcha
 
 Example snippet for Recaptcha:
@@ -60,7 +89,7 @@ job.join()
 print(job.get_solution_response())
 ```
 
-The full integration example is available in file `examples/recaptcha_request.py`.
+The full integration example is available in file `examples/sync_recaptcha_request.py`.
 
 If you process the same page many times, to increase reliability you can specify
 whether the captcha is visible or not. This parameter is not required, as the

docs/api.rst

@@ -1,10 +1,17 @@
 API
 ===
 
-Base
-----
+Sync Client
+-----------
 
- .. automodule:: python_anticaptcha.base
+ .. automodule:: python_anticaptcha.sync_client
+   :members:
+   :undoc-members:
+
+Async Client
+------------
+
+ .. automodule:: python_anticaptcha.async_client
    :members:
    :undoc-members:
 

docs/usage.rst

@@ -21,6 +21,35 @@ The client can be used as a context manager to ensure the underlying session is
         job = client.create_task(task)
         job.join()
 
+Async client
+############
+
+.. note::
+
+   Requires the ``async`` extra: ``pip install python-anticaptcha[async]``
+
+For async frameworks (FastAPI, aiohttp, Starlette) 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``.
+
+Sync client
+###########
+
 Solve recaptcha
 ###############
 
@@ -40,7 +69,7 @@ Example snippet for Recaptcha:
     job.join()
     print(job.get_solution_response())
 
-The full integration example is available in file ``examples/recaptcha_request.py``.
+The full integration example is available in file ``examples/sync_recaptcha_request.py``.
 
 If you process the same page many times, to increase reliability you can specify
 whether the captcha is visible or not. This parameter is not required, as the

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