v1.2.0

.github/workflows/build.yml

@@ -7,12 +7,16 @@ on:
       - '.github/workflows/build.yml'
       - 'src/**'
       - 'Makefile'
+      - 'pyproject.toml'
+      - 'uv.lock'
   pull_request:
     branches: [ "main", "release"]
     paths:
       - '.github/workflows/build.yml'
       - 'src/**'
       - 'Makefile'
+      - 'pyproject.toml'
+      - 'uv.lock'
 
 jobs:
   test_build:
@@ -24,10 +28,12 @@ jobs:
 
     steps:
     - uses: actions/checkout@v6
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v6
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v5
       with:
-        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
 
     - name: Local build checking
       run: make build

.github/workflows/build_sphinx.yml

@@ -15,13 +15,12 @@ jobs:
 
     steps:
       - uses: actions/checkout@v6
-      - name: Set up Python 3.11
-        uses: actions/setup-python@v6
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
         with:
-          python-version: 3.11.6
-
-      - name: Build docs requirements
-        run: pip install -r docs/requirements.txt
+          enable-cache: true
+      - name: Set up Python 3.11
+        run: uv python install 3.11
 
       - name: Build docs
         run: make doc

.github/workflows/install.yml

@@ -7,12 +7,16 @@ on:
       - '.github/workflows/install.yml'
       - 'src/**'
       - 'Makefile'
+      - 'pyproject.toml'
+      - 'uv.lock'
   pull_request:
     branches: [ "main", "release"]
     paths:
       - '.github/workflows/install.yml'
       - 'src/**'
       - 'Makefile'
+      - 'pyproject.toml'
+      - 'uv.lock'
 
 jobs:
   install:
@@ -24,13 +28,15 @@ jobs:
 
     steps:
     - uses: actions/checkout@v6
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v6
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v5
       with:
-        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
 
     - name: Local install checking
       run: make install
 
     - name: PYPI install checking
-      run: pip3 install python3-capsolver
+      run: uv pip install python3-capsolver

.github/workflows/lint.yml

@@ -7,14 +7,16 @@ on:
       - '.github/workflows/lint.yml'
       - 'src/**'
       - 'Makefile'
-      - 'requirements.style.txt'
+      - 'pyproject.toml'
+      - 'uv.lock'
   pull_request:
     branches: [ "main", "release"]
     paths:
       - '.github/workflows/lint.yml'
       - 'src/**'
       - 'Makefile'
-      - 'requirements.style.txt'
+      - 'pyproject.toml'
+      - 'uv.lock'
 
 jobs:
   lint:
@@ -28,15 +30,12 @@ jobs:
 
     steps:
     - uses: actions/checkout@v6
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v6
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v5
       with:
-        python-version: ${{ matrix.python-version }}
-
-    - name: Install dependencies
-      run: |
-        pip3 install --upgrade pip
-        pip3 install -r requirements.style.txt
+        enable-cache: true
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
 
     - name: Lint
       run: make lint

.github/workflows/sphinx.yml

@@ -15,13 +15,12 @@ jobs:
 
     steps:
       - uses: actions/checkout@v6
-      - name: Set up Python 3.11
-        uses: actions/setup-python@v6
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
         with:
-          python-version: 3.11.6
-
-      - name: Build docs requirements
-        run: pip install -r docs/requirements.txt
+          enable-cache: true
+      - name: Set up Python 3.11
+        run: uv python install 3.11
 
       - name: Build docs
         run: make doc

.github/workflows/test.yml

@@ -8,14 +8,16 @@ on:
       - 'src/**'
       - 'tests/**'
       - 'Makefile'
-      - 'requirements.test.txt'
+      - 'pyproject.toml'
+      - 'uv.lock'
   pull_request:
     branches: [ "main", "release"]
     paths:
       - '.github/workflows/test.yml'
       - 'src/**'
       - 'Makefile'
-      - 'requirements.test.txt'
+      - 'pyproject.toml'
+      - 'uv.lock'
   schedule:
     - cron: "5 0 * * 1"
 
@@ -31,15 +33,12 @@ jobs:
 
     steps:
       - uses: actions/checkout@v6
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
         with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Install dependencies
-        run: |
-          pip install --upgrade pip
-          pip install -U -r requirements.test.txt
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
 
       - name: Test
         run: make tests

Makefile

@@ -1,44 +1,42 @@
 .PHONY: install remove refactor lint build upload tests doc
 
 install:
-	pip3 install -e .
+	uv sync --all-groups
 
 remove:
 	pip uninstall python3_capsolver -y
 
-refactor:
-	black docs/
-	isort docs/
+refactor: install
+	uv run black docs/
+	uv run isort docs/
 
-	autoflake --in-place \
+	uv run autoflake --in-place \
 				--recursive \
 				--remove-unused-variables \
 				--remove-duplicate-keys \
 				--remove-all-unused-imports \
 				src/ tests/
-	black src/ tests/
-	isort src/ tests/
+	uv run black src/ tests/
+	uv run isort src/ tests/
 
-lint:
-	autoflake --in-place --recursive src/ --check
-	black src/ --check
-	isort src/ --check-only
+lint: install
+	uv run autoflake --in-place --recursive src/ --check
+	uv run black src/ --check
+	uv run isort src/ --check-only
 
 build:
-	pip3 install --upgrade build setuptools
-	python3 -m build
+	uv build
 
 upload:
-	pip3 install twine wheel setuptools build
-	twine upload dist/*
+	uv publish
 
 tests: install
-	coverage run --rcfile=.coveragerc -m pytest --verbose --showlocals --disable-warnings \
+	uv run coverage run --rcfile=.coveragerc -m pytest --verbose --showlocals --disable-warnings \
 	tests/ && \
-	coverage report --precision=3 --sort=cover --skip-empty --show-missing && \
-	coverage html --precision=3 --skip-empty -d coverage/html/ && \
-	coverage xml -o coverage/coverage.xml
+	uv run coverage report --precision=3 --sort=cover --skip-empty --show-missing && \
+	uv run coverage html --precision=3 --skip-empty -d coverage/html/ && \
+	uv run coverage xml -o coverage/coverage.xml
 
 doc: install
 	cd docs/ && \
-	make html -e
+	uv run --group docs make html -e

README.md

@@ -25,6 +25,13 @@ Tested on UNIX based OS.
 
 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.
 
+## Features
+- **Sync & Async Support**: Full support for both synchronous (`requests`) and asynchronous (`aiohttp`) operations.
+- **Type Safety**: Enums for captcha types and response statuses.
+- **Resilience**: Built-in retries using `tenacity`.
+- **Performance**: High-speed JSON serialization with `msgspec`.
+- **Coverage**: Supports ReCaptcha (V2/V3), Cloudflare, DataDome, GeeTest, MtCaptcha, AWS WAF, Yandex, and ImageToText.
+
 ## How to install?
 
 We recommend using the latest version of Python. `python3-capsolver` supports Python 3.7+.
@@ -37,8 +44,74 @@ pip install python3-capsolver
 
 ## How to use?
 
-Is described in the [documentation-website](https://andreidrang.github.io/python3-capsolver/).
+Detailed documentation is available on the [website](https://andreidrang.github.io/python3-capsolver/).
+
+### Quick Start
+
+#### Synchronous Example (ImageToText)
+```python
+from python3_capsolver.image_to_text import ImageToText
+
+# 1. Initialize with API Key
+solver = ImageToText(api_key="YOUR_API_KEY")
+
+# 2. Solve
+result = solver.captcha_handler(
+    task_payload={
+        "body": "base64_encoded_image_string"
+    }
+)
+
+# 3. Check result
+if result["errorId"] == 0:
+    print("Solution:", result["solution"])
+else:
+    print("Error:", result["errorCode"])
+```
+
+#### Asynchronous Example (ReCaptcha)
+```python
+import asyncio
+from python3_capsolver.recaptcha import ReCaptcha
+from python3_capsolver.core.enum import CaptchaTypeEnm
+
+async def main():
+    # 1. Initialize
+    solver = ReCaptcha(
+        api_key="YOUR_API_KEY", 
+        captcha_type=CaptchaTypeEnm.ReCaptchaV2TaskProxyLess
+    )
+
+    # 2. Solve
+    result = await solver.aio_captcha_handler(
+        task_payload={
+            "websiteURL": "https://example.com",
+            "websiteKey": "SITE_KEY"
+        }
+    )
+
+    print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
 
+## Supported Captcha Types
+- **ReCaptcha**: V2 (Task/Enterprise), V3 (Task/Enterprise)
+- **HCaptcha**: Task, Enterprise
+- **Cloudflare**: Turnstile
+- **GeeTest**: V3, V4
+- **DataDome**: Slider
+- **MtCaptcha**
+- **AWS WAF**
+- **Yandex SmartCaptcha**
+- **ImageToText**: General image CAPTCHAs
+
+## Documentation & Context (For LLMs)
+- **Project Structure**: See `AGENTS.md` in root and subdirectories for internal architecture.
+- **Entry Points**: `src/python3_capsolver/*.py` contains service-specific classes (e.g., `ReCaptcha`, `HCaptcha`).
+- **Core Logic**: `src/python3_capsolver/core/base.py` handles the API communication loop.
+- **Enums**: Use `python3_capsolver.core.enum` for type-safe parameters.
 
 ## How to test?
 

pyproject.toml

@@ -103,3 +103,18 @@ Documentation = "https://andreidrang.github.io/python3-capsolver/"
 Repository = "https://github.com/AndreiDrang/python3-capsolver"
 Issues = "https://github.com/AndreiDrang/python3-capsolver/issues"
 Changelog = "https://github.com/AndreiDrang/python3-capsolver/releases"
+
+[dependency-groups]
+dev = [
+    "autoflake>=2.3.1",
+    "black>=24.8.0",
+    "coverage>=7.6.1",
+    "isort>=5.13.2",
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.24.0",
+]
+docs = [
+    "myst-parser>=3.0.1",
+    "pallets-sphinx-themes>=2.3.0",
+    "sphinx>=7.1.2",
+]

src/python3_capsolver/__version__.py

@@ -1 +1 @@
-__version__ = "1.1.1"
+__version__ = "1.2.0"