Skip to content

Commit 8151060

Browse files
OpenCodeAndreiDrang
OpenCode
authored and
AndreiDrang
committed
docs: rewrite README with improved structure and examples
Restructure documentation to be more approachable for new users: - Clean up badge section, remove broken images - Add 'What is this?' section explaining the library purpose - Add Quick Start guide with install, API key, and usage examples - Add supported CAPTCHA types table - Add service switching examples - Simplify testing section - Update changelog with recent versions Stats: - 1 file changed - +104/-41 lines
1 parent f8f3803 commit 8151060

1 file changed

Lines changed: 116 additions & 41 deletions

File tree

‎README.md‎

Lines changed: 116 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,145 @@
11
# python-rucaptcha
22

3-
[![RuCaptchaHigh.png](https://s.vyjava.xyz/files/2024/12-December/17/45247a56/RuCaptchaHigh.png)](https://vyjava.xyz/dashboard/image/45247a56-3332-48ee-8df8-fc95bcfc52f0)
4-
5-
<hr>
6-
73
[![PyPI version](https://badge.fury.io/py/python-rucaptcha.svg)](https://badge.fury.io/py/python-rucaptcha)
84
[![Python versions](https://img.shields.io/pypi/pyversions/python-rucaptcha.svg?logo=python&logoColor=FBE072)](https://badge.fury.io/py/python-rucaptcha)
95
[![Downloads](https://static.pepy.tech/badge/python-rucaptcha/month)](https://pepy.tech/project/python-rucaptcha)
10-
[![Static Badge](https://img.shields.io/badge/docs-Sphinx-green?label=Documentation&labelColor=gray)](https://andreidrang.github.io/python-rucaptcha/)
6+
[![Documentation](https://img.shields.io/badge/docs-Sphinx-green)](https://andreidrang.github.io/python-rucaptcha/)
117

12-
[![Maintainability](https://api.codeclimate.com/v1/badges/aec93bb04a277cf0dde9/maintainability)](https://codeclimate.com/github/AndreiDrang/python-rucaptcha/maintainability)
13-
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/b4087362bd024b088b358b3e10e7a62f)](https://www.codacy.com/gh/AndreiDrang/python-rucaptcha/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=AndreiDrang/python-rucaptcha&amp;utm_campaign=Badge_Grade)
14-
[![codecov](https://codecov.io/gh/AndreiDrang/python-rucaptcha/branch/master/graph/badge.svg?token=doybTUCfbD)](https://codecov.io/gh/AndreiDrang/python-rucaptcha)
8+
**Python 3.9+ library to solve CAPTCHAs automatically using RuCaptcha, 2Captcha, or DeathByCaptcha services.**
159

16-
[![Sphinx docs](https://github.com/AndreiDrang/python-rucaptcha/actions/workflows/sphinx.yml/badge.svg?branch=release)](https://github.com/AndreiDrang/python-rucaptcha/actions/workflows/sphinx.yml)
17-
[![Build](https://github.com/AndreiDrang/python-rucaptcha/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/AndreiDrang/python-rucaptcha/actions/workflows/build.yml)
18-
[![Installation](https://github.com/AndreiDrang/python-rucaptcha/actions/workflows/install.yml/badge.svg?branch=master)](https://github.com/AndreiDrang/python-rucaptcha/actions/workflows/install.yml)
19-
[![Tests](https://github.com/AndreiDrang/python-rucaptcha/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/AndreiDrang/python-rucaptcha/actions/workflows/test.yml)
20-
[![Lint](https://github.com/AndreiDrang/python-rucaptcha/actions/workflows/lint.yml/badge.svg?branch=master)](https://github.com/AndreiDrang/python-rucaptcha/actions/workflows/lint.yml)
10+
## What is this?
2111

22-
Python3 library for [RuCaptcha](https://rucaptcha.com/?from=4170435) and [2Captcha](https://2captcha.com/?from=4170435) service API.
12+
This library automates CAPTCHA solving by connecting to third-party services. When your code encounters a CAPTCHA, python-rucaptcha sends it to the service, waits for a human to solve it, and returns the solution to your application.
2313

24-
Tested on UNIX based OS.
14+
**Supports 30+ CAPTCHA types:**
15+
- reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile
16+
- Image captchas, Audio captchas
17+
- GeeTest, KeyCaptcha, Amazon WAF, Tencent
18+
- And many more...
2519

26-
The library is intended for software developers and is used to work with the [RuCaptcha](https://rucaptcha.com/?from=4170435) and [2Captcha](https://2captcha.com/?from=4170435) service API.
20+
## Quick Start
2721

28-
Support of the service [Death By Captcha](https://deathbycaptcha.com?refid=1237267242) is integrated into this library, more information in the library documentation or in the [service docs](https://deathbycaptcha.com/api/2captcha?refid=1237267242).
22+
### 1. Install
23+
24+
```bash
25+
pip install python-rucaptcha
26+
```
2927

30-
Application in [RuCaptcha software](https://rucaptcha.com/software/python-rucaptcha) and [2Captcha software](https://2captcha.com/software/python-rucaptcha).
28+
### 2. Get an API Key
3129

32-
## How to install?
30+
Sign up at [RuCaptcha](https://rucaptcha.com) or [2Captcha](https://2captcha.com), then copy your API key from the dashboard.
3331

34-
### pip
32+
### 3. Solve a CAPTCHA
3533

36-
```bash
37-
pip install python-rucaptcha
34+
```python
35+
from python_rucaptcha import HCaptcha
36+
37+
# Your API key
38+
key = "your_api_key_here"
39+
40+
# Solve hCaptcha
41+
result = HCaptcha(aptcha_key=key).captcha_handler(site_url="https://example.com", site_key="abc123")
42+
43+
if result['code'] == 0:
44+
print(f"Solved! Token: {result['token']}")
45+
else:
46+
print(f"Error: {result['message']}")
47+
```
48+
49+
### Solving Different CAPTCHA Types
50+
51+
**reCAPTCHA v2:**
52+
```python
53+
from python_rucaptcha import ReCaptcha
54+
55+
result = ReCaptcha(api_key).captcha_handler(
56+
site_url="https://example.com",
57+
site_key="your_site_key"
58+
)
3859
```
3960

61+
**Image CAPTCHA:**
62+
```python
63+
from python_rucaptcha import ImageCaptcha
4064

41-
## How to use?
65+
result = ImageCaptcha(api_key).captcha_handler(
66+
image_link="https://example.com/captcha.jpg"
67+
)
68+
```
69+
70+
**Using async:**
71+
```python
72+
import asyncio
73+
from python_rucaptcha import HCaptcha
74+
75+
async def solve():
76+
result = await HCaptcha(api_key).aio_captcha_handler(
77+
site_url="https://example.com",
78+
site_key="abc123"
79+
)
80+
return result
81+
82+
token = asyncio.run(solve())
83+
```
84+
85+
## Supported CAPTCHA Types
86+
87+
| CAPTCHA | Module | Description |
88+
|---------|--------|-------------|
89+
| reCAPTCHA v2/v3 | `ReCaptcha` | Google reCAPTCHA |
90+
| hCaptcha | `HCaptcha` | hCaptcha challenge |
91+
| Cloudflare Turnstile | `Turnstile` | Cloudflare protection |
92+
| Image | `ImageCaptcha` | Type the text from image |
93+
| Audio | `AudioCaptcha` | Listen and type audio |
94+
| GeeTest | `GeeTest` | Chinese geetest puzzles |
95+
| KeyCaptcha | `KeyCaptcha` | KeyCAPTCHA service |
96+
| Amazon WAF | `AmazonWaf` | AWS WAF challenge |
97+
| Grid | `GridCaptcha` | Select grid cells |
98+
| Coordinates | `CoordinatesCaptcha` | Click on coordinates |
99+
| And 20+ more | ... | See [full docs](https://andreidrang.github.io/python-rucaptcha/) |
100+
101+
## Switching Services
42102

43-
Is described in the [documentation-website](https://andreidrang.github.io/python-rucaptcha/).
103+
Use the same code with different services:
44104

45-
## How to test?
105+
```python
106+
from python_rucaptcha import HCaptcha
107+
from python_rucaptcha.core.enums import ServiceEnm
46108

47-
1. You need set ``RUCAPTCHA_KEY`` in your environment(get this value from you account).
48-
2. Run command ``make tests``, from root directory.
109+
# Use 2Captcha (default)
110+
result = HCaptcha("2captcha_key").captcha_handler(...)
49111

112+
# Use RuCaptcha
113+
result = HCaptcha("rucaptcha_key", service_type=ServiceEnm.RuCaptcha).captcha_handler(...)
114+
115+
# Use DeathByCaptcha
116+
result = HCaptcha("dbc_user:dbc_pass", service_type=ServiceEnm.DeathByCaptcha).captcha_handler(...)
117+
```
118+
119+
## Testing
120+
121+
```bash
122+
# Set your API key
123+
export RUCAPTCHA_KEY="your_key_here"
124+
125+
# Run tests
126+
make tests
127+
```
50128

51-
### Changelog
129+
## Documentation
52130

53-
For full changelog info check - [Releases page](https://github.com/AndreiDrang/python-rucaptcha/releases).
131+
For advanced usage, configuration options, and all CAPTCHA types, see the [full documentation](https://andreidrang.github.io/python-rucaptcha/).
54132

55-
- v.6.0 - Library refactoring. Stop using `pydantic`, start using `msgspec`. Move to API v2. Drop Python 3.8 support. More details at [Releases page](https://github.com/AndreiDrang/python-rucaptcha/releases).
56-
- v.5.3 - Added support for [Death By Captcha](https://www.deathbycaptcha.com?refid=1237267242) and other services by changing `service_type` and `url_request` \ `url_response` parameters.
57-
- v.5.2 - Added Audio captcha method.
58-
- v.5.1 - Check [releases page](https://github.com/AndreiDrang/python-rucaptcha/releases).
59-
- v.5.0 - Added AmazonWAF captcha method.
60-
- v.4.2 - Added [Yandex Smart Captcha](https://rucaptcha.com/api-rucaptcha#yandex).
133+
## Support
61134

62-
### Get API Key to work with the library
63-
1. On the page - https://rucaptcha.com/enterpage
64-
2. Find it: [![img.png](https://s.vyjava.xyz/files/2024/12-December/17/ac679557/img.png)](https://vyjava.xyz/dashboard/image/ac679557-f3cc-402f-bf95-6c45d252a2ef)
135+
- **Telegram:** [pythoncaptcha](https://t.me/pythoncaptcha)
136+
- **Email:** python-captcha@pm.me
137+
- **Issues:** [GitHub Issues](https://github.com/AndreiDrang/python-rucaptcha/issues)
65138

66-
### Contacts
139+
## Changelog
67140

68-
If you have any questions, please send a message to the [Telegram](https://t.me/pythoncaptcha) chat room.
141+
See [Releases](https://github.com/AndreiDrang/python-rucaptcha/releases) for full changelog.
69142

70-
Or email python-captcha@pm.me
143+
- **v6.0** - Refactored to use msgspec (faster), API v2, dropped Python 3.8
144+
- **v5.3** - Added DeathByCaptcha support
145+
- **v5.2** - Added audio CAPTCHA solving

0 commit comments

Comments
 (0)