Skip to content

Commit b2cef44

Browse files
AndreiDrangAndreiDrang
committed
Add hierarchical AGENTS.md knowledge base
1 parent 42d9619 commit b2cef44

4 files changed

Lines changed: 172 additions & 0 deletions

File tree

‎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

‎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

‎src/python3_anticaptcha/core/AGENTS.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Core Module
2+
3+
## OVERVIEW
4+
Shared utilities: base classes, enums, HTTP instruments, serialization.
5+
6+
## WHERE TO LOOK
7+
| Component | File |
8+
|-----------|------|
9+
| Base classes | base.py - CaptchaParams, CaptchaResponse |
10+
| Enums | enum.py - CaptchaTypeEnm, ProxyTypeEnm, ResponseStatusEnm, SaveFormatsEnm |
11+
| HTTP sync | captcha_instrument.py - SynchronousInstrument |
12+
| HTTP async | captcha_instrument.py - AsyncInstrument |
13+
| Serialization | serializer.py - msgspec.Struct configs |
14+
15+
## CONVENTIONS
16+
- All params classes inherit CaptchaParams
17+
- All response classes inherit CaptchaResponse
18+
- msgspec.Struct for fast serialization
19+
- HTTP instruments handle session lifecycle
20+
21+
## ANTI-PATTERNS
22+
- `verify=False` in sio_captcha_instrument.py:32 - INTENTIONAL, don't "fix"
23+
- Don't add new enums without updating parent package

‎tests/AGENTS.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Tests
2+
3+
## OVERVIEW
4+
pytest + pytest-asyncio with mock server responses.
5+
6+
## WHERE TO LOOK
7+
| Task | Location |
8+
|------|----------|
9+
| Test patterns | tests/*.py |
10+
| Mock responses | tests/static/responses.py |
11+
| Fixtures | Conftest in each test file |
12+
13+
## CONVENTIONS
14+
- asyncio_mode = auto (pytest.ini)
15+
- API_KEY from env or mock
16+
- Each captcha type has dedicated test file
17+
- Mock server responses in static/responses.py
18+
19+
## COMMANDS
20+
```bash
21+
pytest # Run all tests
22+
pytest -k recaptcha # Run specific tests
23+
make tests # pytest + coverage
24+
```

0 commit comments

Comments
 (0)