Skip to content

Commit 29d7830

Browse files
AndreiDrangAndreiDrang
authored
Merge pull request #235 from AndreiDrang/main
Upd libs and readme
2 parents 045ea74 + 276bf97 commit 29d7830

File tree

11 files changed

+560
-39
lines changed

11 files changed

+560
-39
lines changed

‎.github/workflows/build.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ jobs:
2020
strategy:
2121
fail-fast: false
2222
matrix:
23-
python-version: ["3.9", "3.10", "3.11", "3.12"]
23+
python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
2424

2525
steps:
2626
- uses: actions/checkout@v3

‎AGENTS.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# PROJECT KNOWLEDGE BASE
2+
3+
**Generated:** 2026-02-15
4+
**Commit:** 3a0e55c
5+
**Branch:** master
6+
7+
## OVERVIEW
8+
Python client for AntiCaptcha service API. Supports 12 captcha types with sync/async handlers using msgspec for serialization.
9+
10+
## STRUCTURE
11+
```
12+
python3-anticaptcha/
13+
├── src/python3_anticaptcha/ # Main package
14+
│ ├── core/ # Shared: base classes, enums, serializer
15+
│ ├── recaptcha_v2.py # Individual captcha modules
16+
│ ├── recaptcha_v3.py
17+
│ └── ... # 10 more captcha types
18+
├── tests/ # pytest + asyncio
19+
├── docs/ # Sphinx documentation
20+
├── Makefile # Build/test/lint commands
21+
└── .github/workflows/ # 5 CI workflows (test, install, lint, build, sphinx)
22+
```
23+
24+
## WHERE TO LOOK
25+
| Task | Location | Notes |
26+
|------|----------|-------|
27+
| Add new captcha type | `src/python3_anticaptcha/` | Copy existing module pattern |
28+
| Base classes | `core/base.py` | CaptchaParams, CaptchaResponse |
29+
| Enums | `core/enum.py` | CaptchaTypeEnm, ProxyTypeEnm, ResponseStatusEnm |
30+
| HTTP handling | `core/captcha_instrument.py` | SynchronousInstrument, AsyncInstrument |
31+
| Serialization | `core/serializer.py` | msgspec.Struct base |
32+
| Config | `config.py` | API key, urls |
33+
| Tests | `tests/` | pytest-asyncio, mock server |
34+
| CI | `.github/workflows/` | 5 separate workflows |
35+
36+
## CODE MAP
37+
38+
| Symbol | Type | Location | Role |
39+
|--------|------|----------|------|
40+
| ReCaptchaV2 | Class | recaptcha_v2.py | Google reCAPTCHA v2 |
41+
| ReCaptchaV3 | Class | recaptcha_v3.py | Google reCAPTCHA v3 |
42+
| ImageToText | Class | image_to_text.py | Text from image |
43+
| FunCaptcha | Class | funcaptcha.py | Arkose Labs |
44+
| GeeTest | Class | geetest.py | GeeTest captcha |
45+
| Turnstile | Class | turnstile.py | Cloudflare Turnstile |
46+
| FriendlyCaptcha | Class | friendly_captcha.py | FriendlyCaptcha |
47+
| Prosopo | Class | prosopo.py | Prosopo captcha |
48+
| AmazonWAF | Class | amazon_waf.py | Amazon WAF captcha |
49+
| CustomTask | Class | custom_task.py | Custom task template |
50+
| Control | Class | control.py | Balance/status |
51+
| CaptchaParams | Base | core/base.py | Parent for all params |
52+
| CaptchaResponse | Base | core/base.py | Parent for responses |
53+
| SynchronousInstrument | Class | core/captcha_instrument.py | Sync HTTP client |
54+
| AsyncInstrument | Class | core/captcha_instrument.py | Async HTTP client |
55+
56+
## CONVENTIONS
57+
- **Format**: Black + isort (120 char, py310 target)
58+
- **Imports**: isort with black profile, length_sort
59+
- **Docstrings**: Google-style (Args/Returns/Examples/Notes)
60+
- **Serialization**: msgspec.Struct with type annotations
61+
- **Type hints**: Union[X,Y], Optional[X] syntax (not |)
62+
- **Async**: All captcha classes have `captcha_handler()` sync + `aio_captcha_handler()` async
63+
64+
## ANTI-PATTERNS (THIS PROJECT)
65+
- **SSL**: `verify=False` in sio_captcha_instrument.py:32 - INTENTIONAL for proxy support, suppresses urllib3 warnings
66+
- **apiDomain**: DO NOT use in ReCaptcha - deprecated by AntiCaptcha
67+
- **Proxy restrictions**: Never use hostnames, transparent proxies, local networks (192.*.*, 10.*.*, 127.*.*)
68+
- **Exceptions**: Only ValueError raised - no custom exception hierarchy
69+
- **Bare except**: Used in some cleanup - avoid expanding
70+
71+
## COMMANDS
72+
```bash
73+
make tests # pytest + coverage
74+
make lint # autoflake/black/isort --check
75+
make build # python3 -m build
76+
make doc # sphinx-build
77+
make upload # twine upload dist/*
78+
```
79+
80+
## NOTES
81+
- API_KEY required as env var or constructor param
82+
- Tests use mock server (tests.static.responses)
83+
- Manual PyPI upload (make upload) - no auto-publish
84+
- Docs deploy only on release branch

‎README.md‎

Lines changed: 122 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,153 @@
11
# python3-anticaptcha
22

3-
[![AntiCaptcha.png](https://s.vyjava.xyz/files/2024/12-December/17/b18528fc/AntiCaptcha.png)](https://vyjava.xyz/dashboard/image/b18528fc-8572-4167-9d2f-abaacf4e1053)
4-
5-
<hr>
6-
73
[![PyPI version](https://badge.fury.io/py/python3-anticaptcha.svg)](https://badge.fury.io/py/python3-anticaptcha)
84
[![Python versions](https://img.shields.io/pypi/pyversions/python3-anticaptcha.svg?logo=python&logoColor=FBE072)](https://badge.fury.io/py/python3-anticaptcha)
95
[![Downloads](https://static.pepy.tech/badge/python3-anticaptcha/month)](https://pepy.tech/project/python3-anticaptcha)
106
[![Static Badge](https://img.shields.io/badge/docs-Sphinx-green?label=Documentation&labelColor=gray)](https://andreidrang.github.io/python3-anticaptcha/)
11-
12-
[![Code Climate](https://codeclimate.com/github/AndreiDrang/python3-anticaptcha/badges/gpa.svg)](https://codeclimate.com/github/AndreiDrang/python3-anticaptcha)
13-
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/7f49780f2edb48d4b133833887c850e8)](https://www.codacy.com/gh/AndreiDrang/python3-anticaptcha/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=AndreiDrang/python3-anticaptcha&amp;utm_campaign=Badge_Grade)
14-
[![codecov](https://codecov.io/gh/AndreiDrang/python3-anticaptcha/branch/main/graph/badge.svg?token=W92nfZY6Tz)](https://codecov.io/gh/AndreiDrang/python3-anticaptcha)
15-
16-
[![Sphinx docs](https://github.com/AndreiDrang/python3-anticaptcha/actions/workflows/sphinx.yml/badge.svg?branch=release)](https://github.com/AndreiDrang/python3-anticaptcha/actions/workflows/sphinx.yml)
17-
[![Building](https://github.com/AndreiDrang/python3-anticaptcha/actions/workflows/build.yml/badge.svg)](https://github.com/AndreiDrang/python3-anticaptcha/actions/workflows/build.yml)
18-
[![Installation check](https://github.com/AndreiDrang/python3-anticaptcha/actions/workflows/install.yml/badge.svg?branch=main)](https://github.com/AndreiDrang/python3-anticaptcha/actions/workflows/install.yml)
197
[![Test](https://github.com/AndreiDrang/python3-anticaptcha/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/AndreiDrang/python3-anticaptcha/actions/workflows/test.yml)
208
[![Lint](https://github.com/AndreiDrang/python3-anticaptcha/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/AndreiDrang/python3-anticaptcha/actions/workflows/lint.yml)
219

10+
Python 3 client library for [AntiCaptcha](https://getcaptchasolution.com/vchfpctqyz) service - solve reCAPTCHA, hCaptcha, image captchas, and more programmatically.
2211

23-
Python 3 library for [AntiCaptcha](https://getcaptchasolution.com/vchfpctqyz) service API.
12+
## Why use this library?
2413

25-
The library is intended for software developers and is used to work with the [AntiCaptcha](https://getcaptchasolution.com/vchfpctqyz) service API.
26-
Tested on UNIX based OS.
14+
AntiCaptcha is a paid captcha solving service. This library provides a clean Python interface to:
15+
- Submit captchas to AntiCaptcha's worker network
16+
- Poll for results automatically
17+
- Handle proxy rotation for high-volume requests
18+
- Support both synchronous and asynchronous workflows
2719

28-
Love Rust? Me too! Check AntiCaptcha API binding for Rust - [Rust-AntiCaptcha crate](https://crates.io/crates/rust-anticaptcha).
20+
## Supported Captcha Types
2921

30-
## How to install?
22+
| Type | Class | Use Case |
23+
|------|-------|----------|
24+
| reCAPTCHA v2 | `ReCaptchaV2` | Google reCAPTCHA V2 checkbox/invisible |
25+
| reCAPTCHA v3 | `ReCaptchaV3` | Google reCAPTCHA V3 score-based |
26+
| Image Captcha | `ImageToText` | Classic text-from-image captchas |
27+
| Image Coordinates | `ImageToCoordinates` | Click-on-image captchas |
28+
| FunCaptcha | `FunCaptcha` | Arkose Labs (formerly FunCaptcha) |
29+
| GeeTest | `GeeTest` | Chinese GeeTest captcha |
30+
| Turnstile | `Turnstile` | Cloudflare Turnstile |
31+
| FriendlyCaptcha | `FriendlyCaptcha` | FriendlyCaptcha puzzles |
32+
| Prosopo | `Prosopo` | Prosopo captcha |
33+
| Amazon WAF | `AmazonWAF` | AWS WAF Captcha |
3134

32-
We recommend using the latest version of Python. `python3-anticaptcha` supports Python 3.7+.
35+
## Quick Start
3336

34-
#### pip
37+
### 1. Install
3538

3639
```bash
3740
pip install python3-anticaptcha
3841
```
3942

43+
### 2. Get Your API Key
4044

41-
## How to test?
45+
1. Log into [AntiCaptcha](https://getcaptchasolution.com/vchfpctqyzclients/settings/apisetup)
46+
2. Copy your API key from the "Setup" section
4247

43-
1. You need set ``API_KEY`` in your environment(get this value from you account).
44-
2. Run command ``make tests``, from root directory.
48+
### 3. Solve a reCAPTCHA
4549

46-
### Additional info
47-
1. [Library usage examples && Docs](https://andreidrang.github.io/python3-anticaptcha/)
48-
2. [AntiCaptcha errors list](https://getcaptchasolution.com/vchfpctqyzapidoc/errors)
50+
```python
51+
from python3_anticaptcha import ReCaptchaV2
52+
from python3_anticaptcha.core.enum import CaptchaTypeEnm
4953

54+
# Basic usage (no proxy)
55+
result = ReCaptchaV2(
56+
api_key="YOUR_API_KEY",
57+
captcha_type=CaptchaTypeEnm.RecaptchaV2TaskProxyless,
58+
websiteURL="https://example.com/page-with-captcha",
59+
websiteKey="6LeIxAKTAAAAAJ309xRj9YBN2aaaaaaaaa", # sitekey from the page
60+
).captcha_handler()
61+
62+
print(result["solution"]["gRecaptchaResponse"])
63+
```
64+
65+
### 4. Solve with Proxy
66+
67+
```python
68+
from python3_anticaptcha import ReCaptchaV2
69+
from python3_anticaptcha.core.enum import CaptchaTypeEnm, ProxyTypeEnm
70+
71+
result = ReCaptchaV2(
72+
api_key="YOUR_API_KEY",
73+
captcha_type=CaptchaTypeEnm.RecaptchaV2Task,
74+
websiteURL="https://example.com/page-with-captcha",
75+
websiteKey="6LeIxAKTAAAAAJ309xRj9YBN2aaaaaaaaa",
76+
proxyType=ProxyTypeEnm.HTTP,
77+
proxyAddress="123.45.67.89",
78+
proxyPort=8080,
79+
proxyLogin="proxy_user",
80+
proxyPassword="proxy_pass",
81+
userAgent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
82+
).captcha_handler()
83+
```
5084

51-
### How to get API Key to work with the library
52-
1. On the page - https://getcaptchasolution.com/vchfpctqyzclients/settings/apisetup
53-
2. Find it: [![img.png](https://s.vyjava.xyz/files/2024/12-December/17/5d6a902c/img.png)](https://vyjava.xyz/dashboard/image/5d6a902c-6997-47dd-af2a-734bde9bd1fb)
85+
### 5. Async Usage
5486

55-
### Contacts
87+
```python
88+
import asyncio
89+
from python3_anticaptcha import ReCaptchaV2
90+
from python3_anticaptcha.core.enum import CaptchaTypeEnm
5691

57-
If you have any questions, please send a message to the [Telegram](https://t.me/pythoncaptcha) chat room.
92+
async def solve():
93+
result = await ReCaptchaV2(
94+
api_key="YOUR_API_KEY",
95+
captcha_type=CaptchaTypeEnm.RecaptchaV2TaskProxyless,
96+
websiteURL="https://example.com/page-with-captcha",
97+
websiteKey="6LeIxAKTAAAAAJ309xRj9YBN2aaaaaaaaa",
98+
).aio_captcha_handler()
99+
return result
100+
101+
result = asyncio.run(solve())
102+
```
103+
104+
## Environment Variable
105+
106+
Set `API_KEY` to avoid passing it in code:
107+
108+
```bash
109+
export API_KEY="your_api_key_here"
110+
```
111+
112+
```python
113+
# Now you can omit api_key parameter
114+
from python3_anticaptcha import ImageToText
115+
116+
result = ImageToText(captcha_file="captcha.png").captcha_handler()
117+
```
118+
119+
## Configuration Options
120+
121+
All captcha classes support these common parameters:
122+
123+
| Parameter | Type | Description |
124+
|-----------|------|-------------|
125+
| `api_key` | str | Your AntiCaptcha API key (or set `API_KEY` env var) |
126+
| `sleep_time` | int | Seconds between result polls (default: 10) |
127+
128+
## Documentation
129+
130+
- [Full Documentation](https://andreidrang.github.io/python3-anticaptcha/) - Detailed API reference
131+
- [AntiCaptcha Errors](https://getcaptchasolution.com/vchfpctqyzapidoc/errors) - Error code meanings
132+
133+
## Development
134+
135+
```bash
136+
# Run tests
137+
make tests
138+
139+
# Run linters
140+
make lint
141+
142+
# Build package
143+
make build
144+
```
58145

59-
Or email python-captcha@pm.me
146+
## Contacts
60147

61-
<hr>
148+
- Telegram: [pythoncaptcha](https://t.me/pythoncaptcha)
149+
- Email: python-captcha@pm.me
62150

63-
## 💰 Sponsorship
151+
---
64152

65-
This project is supported by [TokenBel.info](https://dashboard.tokenbel.info/?utm_source=pypi), which helps maintain its development and acts as a sponsor.
66-
TokenBel is an information platform for investing in tokens, providing analytics, financial data, and market insights.
153+
Love Rust? Check out [Rust-AntiCaptcha](https://crates.io/crates/rust-anticaptcha) - same API for Rust projects.

‎docs/requirements.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
sphinx==8.3.0
1+
sphinx==9.1.0
22
pallets_sphinx_themes==2.3.0
3-
myst-parser==4.0.1
3+
myst-parser==5.0.0

‎pyproject.toml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,8 @@ classifiers = [
7676
"Programming Language :: Python :: 3.10",
7777
"Programming Language :: Python :: 3.11",
7878
"Programming Language :: Python :: 3.12",
79+
"Programming Language :: Python :: 3.13",
80+
"Programming Language :: Python :: 3.14",
7981
"Framework :: AsyncIO",
8082
"Operating System :: Unix",
8183
"Operating System :: Microsoft :: Windows",
@@ -84,7 +86,7 @@ classifiers = [
8486
dependencies = [
8587
"requests>=2.21.0",
8688
"aiohttp>=3.9.2",
87-
"msgspec>=0.18,<0.20",
89+
"msgspec>=0.18,<0.21",
8890
"tenacity>=8,<10"
8991
]
9092

‎src/python3_anticaptcha/AGENTS.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# python3_anticaptcha Package
2+
3+
## OVERVIEW
4+
Main package - 12 captcha handler classes with sync/async API.
5+
6+
## STRUCTURE
7+
```
8+
python3_anticaptcha/
9+
├── __init__.py # Exports version only
10+
├── config.py # API URLs, key handling
11+
├── core/ # Shared utilities (see core/AGENTS.md)
12+
├── recaptcha_v2.py # Captcha type modules
13+
├── recaptcha_v3.py
14+
├── image_to_text.py
15+
├── funcaptcha.py
16+
├── geetest.py
17+
├── turnstile.py
18+
├── friendly_captcha.py
19+
├── prosopo.py
20+
├── amazon_waf.py
21+
├── custom_task.py
22+
└── control.py
23+
```
24+
25+
## WHERE TO LOOK
26+
| Task | Location |
27+
|------|----------|
28+
| Add captcha type | Copy existing module, register in CaptchaTypeEnm |
29+
| Modify HTTP client | `core/captcha_instrument.py` |
30+
| Change serialization | `core/serializer.py` |
31+
| Add enum | `core/enum.py` |
32+
33+
## CONVENTIONS
34+
- Each captcha module: one class with `captcha_handler()` + `aio_captcha_handler()`
35+
- Inherit from `CaptchaParams` (core/base.py)
36+
- Params passed as constructor kwargs
37+
- Return `CaptchaResponse` subclass
38+
39+
## ANTI-PATTERNS
40+
- Don't add to `__init__.py` exports - users import directly
41+
- Don't modify core enums without updating all handlers

0 commit comments

Comments
 (0)