captcha-router 0.1.2

Reusable captcha router with pluggable solver providers.

captcha-router

Reusable captcha router with pluggable providers.

Install

pip install .

Publish automation (GitHub Actions)

1. Configure Trusted Publishers in PyPI:

• Production: workflow /.github/workflows/publish.yml, environment pypi
• Test: workflow /.github/workflows/publish-testpypi.yml, environment testpypi

2. Bump version in pyproject.toml and commit.
3. For TestPyPI (release candidate), tag with -rc:

git tag v0.1.1-rc1
git push origin v0.1.1-rc1

4. For production PyPI, push a stable tag:

git tag v0.1.1
git push origin v0.1.1

Publish on version change

The workflow /.github/workflows/publish-on-version-change.yml is active for pushes to main when pyproject.toml changes.

Default behavior:

• Push to main with a changed project.version in pyproject.toml -> publishes to PyPI.
• If pyproject.toml changed but version did not change -> publish is skipped.

Manual behavior:

• You can still run the workflow manually from GitHub Actions and choose testpypi or pypi.

Supported providers

• anticaptcha (alias: anti-captcha)
• 2captcha (alias: twocaptcha)

Router methods

• CaptchaRouter.list_providers(): returns all registered provider names and aliases.
• CaptchaRouter.list_provider_capabilities(include_aliases=False): returns provider -> supported captcha kinds.
• CaptchaRouter.get_supported_task_kinds(provider_name): returns supported captcha kinds for one provider.
• CaptchaRouter.list_supported_task_kinds(): returns union of captcha kinds across providers.
• CaptchaRouter.get_solver(provider_name=None, api_key=None, **kwargs): creates a solver instance and uses env fallbacks when api_key is omitted.

Usage

1) Create a solver

from captcha_router import CaptchaRouter

solver = CaptchaRouter.get_solver(provider_name="anticaptcha", api_key="YOUR_KEY")

2) Solve a task

import asyncio
from captcha_router import CaptchaRouter, CaptchaTaskSpec


async def main():
    solver = CaptchaRouter.get_solver(provider_name="anticaptcha", api_key="YOUR_KEY")
    try:
        result = await solver.solve_task(
            CaptchaTaskSpec(
                kind="recaptcha_v2",
                params={
                    "website_url": "https://example.com",
                    "site_key": "SITE_KEY_HERE",
                },
            )
        )
        print(result.status, result.token, result.error)
    finally:
        await solver.close()


asyncio.run(main())

3) Inspect capabilities

from captcha_router import CaptchaRouter

print(CaptchaRouter.list_providers())
print(CaptchaRouter.list_provider_capabilities())