Skip to content

Commit d4b3f65

Browse files
AndreiDrangAndreiDrang
authored
Merge pull request #165 from AndreiDrang/main
v1.2.0
2 parents 27c5b7c + 22f393a commit d4b3f65

19 files changed

Lines changed: 3716 additions & 80 deletions

‎.github/workflows/build.yml‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,16 @@ on:
77
- '.github/workflows/build.yml'
88
- 'src/**'
99
- 'Makefile'
10+
- 'pyproject.toml'
11+
- 'uv.lock'
1012
pull_request:
1113
branches: [ "main", "release"]
1214
paths:
1315
- '.github/workflows/build.yml'
1416
- 'src/**'
1517
- 'Makefile'
18+
- 'pyproject.toml'
19+
- 'uv.lock'
1620

1721
jobs:
1822
test_build:
@@ -24,10 +28,12 @@ jobs:
2428

2529
steps:
2630
- uses: actions/checkout@v6
27-
- name: Set up Python ${{ matrix.python-version }}
28-
uses: actions/setup-python@v6
31+
- name: Set up uv
32+
uses: astral-sh/setup-uv@v5
2933
with:
30-
python-version: ${{ matrix.python-version }}
34+
enable-cache: true
35+
- name: Set up Python ${{ matrix.python-version }}
36+
run: uv python install ${{ matrix.python-version }}
3137

3238
- name: Local build checking
3339
run: make build

‎.github/workflows/build_sphinx.yml‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,12 @@ jobs:
1515

1616
steps:
1717
- uses: actions/checkout@v6
18-
- name: Set up Python 3.11
19-
uses: actions/setup-python@v6
18+
- name: Set up uv
19+
uses: astral-sh/setup-uv@v5
2020
with:
21-
python-version: 3.11.6
22-
23-
- name: Build docs requirements
24-
run: pip install -r docs/requirements.txt
21+
enable-cache: true
22+
- name: Set up Python 3.11
23+
run: uv python install 3.11
2524

2625
- name: Build docs
2726
run: make doc

‎.github/workflows/install.yml‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,16 @@ on:
77
- '.github/workflows/install.yml'
88
- 'src/**'
99
- 'Makefile'
10+
- 'pyproject.toml'
11+
- 'uv.lock'
1012
pull_request:
1113
branches: [ "main", "release"]
1214
paths:
1315
- '.github/workflows/install.yml'
1416
- 'src/**'
1517
- 'Makefile'
18+
- 'pyproject.toml'
19+
- 'uv.lock'
1620

1721
jobs:
1822
install:
@@ -24,13 +28,15 @@ jobs:
2428

2529
steps:
2630
- uses: actions/checkout@v6
27-
- name: Set up Python ${{ matrix.python-version }}
28-
uses: actions/setup-python@v6
31+
- name: Set up uv
32+
uses: astral-sh/setup-uv@v5
2933
with:
30-
python-version: ${{ matrix.python-version }}
34+
enable-cache: true
35+
- name: Set up Python ${{ matrix.python-version }}
36+
run: uv python install ${{ matrix.python-version }}
3137

3238
- name: Local install checking
3339
run: make install
3440

3541
- name: PYPI install checking
36-
run: pip3 install python3-capsolver
42+
run: uv pip install python3-capsolver

‎.github/workflows/lint.yml‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,16 @@ on:
77
- '.github/workflows/lint.yml'
88
- 'src/**'
99
- 'Makefile'
10-
- 'requirements.style.txt'
10+
- 'pyproject.toml'
11+
- 'uv.lock'
1112
pull_request:
1213
branches: [ "main", "release"]
1314
paths:
1415
- '.github/workflows/lint.yml'
1516
- 'src/**'
1617
- 'Makefile'
17-
- 'requirements.style.txt'
18+
- 'pyproject.toml'
19+
- 'uv.lock'
1820

1921
jobs:
2022
lint:
@@ -28,15 +30,12 @@ jobs:
2830

2931
steps:
3032
- uses: actions/checkout@v6
31-
- name: Set up Python ${{ matrix.python-version }}
32-
uses: actions/setup-python@v6
33+
- name: Set up uv
34+
uses: astral-sh/setup-uv@v5
3335
with:
34-
python-version: ${{ matrix.python-version }}
35-
36-
- name: Install dependencies
37-
run: |
38-
pip3 install --upgrade pip
39-
pip3 install -r requirements.style.txt
36+
enable-cache: true
37+
- name: Set up Python ${{ matrix.python-version }}
38+
run: uv python install ${{ matrix.python-version }}
4039

4140
- name: Lint
4241
run: make lint

‎.github/workflows/sphinx.yml‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,12 @@ jobs:
1515

1616
steps:
1717
- uses: actions/checkout@v6
18-
- name: Set up Python 3.11
19-
uses: actions/setup-python@v6
18+
- name: Set up uv
19+
uses: astral-sh/setup-uv@v5
2020
with:
21-
python-version: 3.11.6
22-
23-
- name: Build docs requirements
24-
run: pip install -r docs/requirements.txt
21+
enable-cache: true
22+
- name: Set up Python 3.11
23+
run: uv python install 3.11
2524

2625
- name: Build docs
2726
run: make doc

‎.github/workflows/test.yml‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,16 @@ on:
88
- 'src/**'
99
- 'tests/**'
1010
- 'Makefile'
11-
- 'requirements.test.txt'
11+
- 'pyproject.toml'
12+
- 'uv.lock'
1213
pull_request:
1314
branches: [ "main", "release"]
1415
paths:
1516
- '.github/workflows/test.yml'
1617
- 'src/**'
1718
- 'Makefile'
18-
- 'requirements.test.txt'
19+
- 'pyproject.toml'
20+
- 'uv.lock'
1921
schedule:
2022
- cron: "5 0 * * 1"
2123

@@ -31,15 +33,12 @@ jobs:
3133

3234
steps:
3335
- uses: actions/checkout@v6
34-
- name: Set up Python ${{ matrix.python-version }}
35-
uses: actions/setup-python@v6
36+
- name: Set up uv
37+
uses: astral-sh/setup-uv@v5
3638
with:
37-
python-version: ${{ matrix.python-version }}
38-
39-
- name: Install dependencies
40-
run: |
41-
pip install --upgrade pip
42-
pip install -U -r requirements.test.txt
39+
enable-cache: true
40+
- name: Set up Python ${{ matrix.python-version }}
41+
run: uv python install ${{ matrix.python-version }}
4342

4443
- name: Test
4544
run: make tests

‎Makefile‎

Lines changed: 18 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,42 @@
11
.PHONY: install remove refactor lint build upload tests doc
22

33
install:
4-
pip3 install -e .
4+
uv sync --all-groups
55

66
remove:
77
pip uninstall python3_capsolver -y
88

9-
refactor:
10-
black docs/
11-
isort docs/
9+
refactor: install
10+
uv run black docs/
11+
uv run isort docs/
1212

13-
autoflake --in-place \
13+
uv run autoflake --in-place \
1414
--recursive \
1515
--remove-unused-variables \
1616
--remove-duplicate-keys \
1717
--remove-all-unused-imports \
1818
src/ tests/
19-
black src/ tests/
20-
isort src/ tests/
19+
uv run black src/ tests/
20+
uv run isort src/ tests/
2121

22-
lint:
23-
autoflake --in-place --recursive src/ --check
24-
black src/ --check
25-
isort src/ --check-only
22+
lint: install
23+
uv run autoflake --in-place --recursive src/ --check
24+
uv run black src/ --check
25+
uv run isort src/ --check-only
2626

2727
build:
28-
pip3 install --upgrade build setuptools
29-
python3 -m build
28+
uv build
3029

3130
upload:
32-
pip3 install twine wheel setuptools build
33-
twine upload dist/*
31+
uv publish
3432

3533
tests: install
36-
coverage run --rcfile=.coveragerc -m pytest --verbose --showlocals --disable-warnings \
34+
uv run coverage run --rcfile=.coveragerc -m pytest --verbose --showlocals --disable-warnings \
3735
tests/ && \
38-
coverage report --precision=3 --sort=cover --skip-empty --show-missing && \
39-
coverage html --precision=3 --skip-empty -d coverage/html/ && \
40-
coverage xml -o coverage/coverage.xml
36+
uv run coverage report --precision=3 --sort=cover --skip-empty --show-missing && \
37+
uv run coverage html --precision=3 --skip-empty -d coverage/html/ && \
38+
uv run coverage xml -o coverage/coverage.xml
4139

4240
doc: install
4341
cd docs/ && \
44-
make html -e
42+
uv run --group docs make html -e

‎README.md‎

Lines changed: 74 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,13 @@ Tested on UNIX based OS.
2525

2626
The library is intended for software developers and is used to work with the [Capsolver](https://dashboard.capsolver.com/passport/register?inviteCode=kQTn-tG07Jb1) service API.
2727

28+
## Features
29+
- **Sync & Async Support**: Full support for both synchronous (`requests`) and asynchronous (`aiohttp`) operations.
30+
- **Type Safety**: Enums for captcha types and response statuses.
31+
- **Resilience**: Built-in retries using `tenacity`.
32+
- **Performance**: High-speed JSON serialization with `msgspec`.
33+
- **Coverage**: Supports ReCaptcha (V2/V3), Cloudflare, DataDome, GeeTest, MtCaptcha, AWS WAF, Yandex, and ImageToText.
34+
2835
## How to install?
2936

3037
We recommend using the latest version of Python. `python3-capsolver` supports Python 3.7+.
@@ -37,8 +44,74 @@ pip install python3-capsolver
3744

3845
## How to use?
3946

40-
Is described in the [documentation-website](https://andreidrang.github.io/python3-capsolver/).
47+
Detailed documentation is available on the [website](https://andreidrang.github.io/python3-capsolver/).
48+
49+
### Quick Start
50+
51+
#### Synchronous Example (ImageToText)
52+
```python
53+
from python3_capsolver.image_to_text import ImageToText
54+
55+
# 1. Initialize with API Key
56+
solver = ImageToText(api_key="YOUR_API_KEY")
57+
58+
# 2. Solve
59+
result = solver.captcha_handler(
60+
task_payload={
61+
"body": "base64_encoded_image_string"
62+
}
63+
)
64+
65+
# 3. Check result
66+
if result["errorId"] == 0:
67+
print("Solution:", result["solution"])
68+
else:
69+
print("Error:", result["errorCode"])
70+
```
71+
72+
#### Asynchronous Example (ReCaptcha)
73+
```python
74+
import asyncio
75+
from python3_capsolver.recaptcha import ReCaptcha
76+
from python3_capsolver.core.enum import CaptchaTypeEnm
77+
78+
async def main():
79+
# 1. Initialize
80+
solver = ReCaptcha(
81+
api_key="YOUR_API_KEY",
82+
captcha_type=CaptchaTypeEnm.ReCaptchaV2TaskProxyLess
83+
)
84+
85+
# 2. Solve
86+
result = await solver.aio_captcha_handler(
87+
task_payload={
88+
"websiteURL": "https://example.com",
89+
"websiteKey": "SITE_KEY"
90+
}
91+
)
92+
93+
print(result)
94+
95+
if __name__ == "__main__":
96+
asyncio.run(main())
97+
```
4198

99+
## Supported Captcha Types
100+
- **ReCaptcha**: V2 (Task/Enterprise), V3 (Task/Enterprise)
101+
- **HCaptcha**: Task, Enterprise
102+
- **Cloudflare**: Turnstile
103+
- **GeeTest**: V3, V4
104+
- **DataDome**: Slider
105+
- **MtCaptcha**
106+
- **AWS WAF**
107+
- **Yandex SmartCaptcha**
108+
- **ImageToText**: General image CAPTCHAs
109+
110+
## Documentation & Context (For LLMs)
111+
- **Project Structure**: See `AGENTS.md` in root and subdirectories for internal architecture.
112+
- **Entry Points**: `src/python3_capsolver/*.py` contains service-specific classes (e.g., `ReCaptcha`, `HCaptcha`).
113+
- **Core Logic**: `src/python3_capsolver/core/base.py` handles the API communication loop.
114+
- **Enums**: Use `python3_capsolver.core.enum` for type-safe parameters.
42115

43116
## How to test?
44117

‎docs/requirements.txt‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎pyproject.toml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,3 +103,18 @@ Documentation = "https://andreidrang.github.io/python3-capsolver/"
103103
Repository = "https://github.com/AndreiDrang/python3-capsolver"
104104
Issues = "https://github.com/AndreiDrang/python3-capsolver/issues"
105105
Changelog = "https://github.com/AndreiDrang/python3-capsolver/releases"
106+
107+
[dependency-groups]
108+
dev = [
109+
"autoflake>=2.3.1",
110+
"black>=24.8.0",
111+
"coverage>=7.6.1",
112+
"isort>=5.13.2",
113+
"pytest>=8.3.5",
114+
"pytest-asyncio>=0.24.0",
115+
]
116+
docs = [
117+
"myst-parser>=3.0.1",
118+
"pallets-sphinx-themes>=2.3.0",
119+
"sphinx>=7.1.2",
120+
]

0 commit comments

Comments
 (0)