captchakings 1.0.0__tar.gz

captchakings-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CaptchaKings
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

captchakings-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include examples *.py

captchakings-1.0.0/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: captchakings
+Version: 1.0.0
+Summary: Official Python client for CaptchaKings API
+Home-page: https://captchakings.com
+Author: CaptchaKings
+Author-email: support@captchakings.com
+Project-URL: Documentation, https://captchakings.com?section=documentation
+Project-URL: Source, https://captchakings.com
+Project-URL: Bug Reports, https://captchakings.com
+Keywords: captcha,ocr,captcha-solver,captchakings,api-client
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# CaptchaKings Python Library
+
+[![Python Version](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Official Python client library for [CaptchaKings API](https://captchakings.com) - Fast, accurate, and affordable CAPTCHA solving service.
+
+## ✨ Features
+
+- 🚀 **Simple & Clean API** - Just 2 lines of code to solve CAPTCHAs
+- 🔄 **Automatic Retry** - Built-in retry logic for failed requests
+- 🛡️ **Type Hints** - Full type annotations for better IDE support
+- ⚡ **Fast & Reliable** - Optimized for performance
+- 🎯 **Error Handling** - Custom exceptions for different error types
+- 📦 **Zero Configuration** - Works out of the box
+
+## 📦 Installation
+
+### From Source (Local Development)
+
+```bash
+cd captchakings-python
+pip install -e .
+```
+
+### Requirements
+
+- Python 3.6 or higher
+- `requests` library (automatically installed)
+
+## 🚀 Quick Start
+
+```python
+from captchakings import CaptchaKings
+
+# Initialize client
+client = CaptchaKings('ck_your_api_key_here')
+
+# Solve CAPTCHA
+result = client.solve('captcha.jpg')
+
+print(f"Solved: {result['prediction']}")
+print(f"Confidence: {result['confidence']}")
+print(f"Credits Remaining: {result['credits_remaining']}")
+```
+
+That's it! Just 3 lines of code. 🎉
+
+## 📖 Usage Examples
+
+### Basic Usage
+
+```python
+from captchakings import CaptchaKings
+
+client = CaptchaKings('ck_your_api_key')
+result = client.solve('path/to/captcha.jpg')
+
+if result:
+    print(f"✅ CAPTCHA Solved: {result['prediction']}")
+    print(f"Confidence: {result['confidence']}")
+    print(f"Credits Remaining: {result['credits_remaining']}")
+```
+
+### With Automatic Retry
+
+```python
+from captchakings import CaptchaKings
+
+client = CaptchaKings('ck_your_api_key')
+
+# Automatically retry up to 5 times with 2 second delay
+result = client.solve_with_retry(
+    'captcha.jpg',
+    max_retries=5,
+    retry_delay=2
+)
+
+print(f"Solved: {result['prediction']}")
+```
+
+### Error Handling
+
+```python
+from captchakings import CaptchaKings
+from captchakings.exceptions import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidImageError,
+    APIError
+)
+
+client = CaptchaKings('ck_your_api_key')
+
+try:
+    result = client.solve('captcha.jpg')
+    print(f"Solved: {result['prediction']}")
+    
+except AuthenticationError:
+    print("❌ Invalid API key")
+except InsufficientCreditsError:
+    print("❌ Not enough credits")
+except InvalidImageError:
+    print("❌ Invalid image file")
+except APIError as e:
+    print(f"❌ API Error: {e}")
+```
+
+### Using Context Manager
+
+```python
+from captchakings import CaptchaKings
+
+# Automatically closes session after use
+with CaptchaKings('ck_your_api_key') as client:
+    result = client.solve('captcha.jpg')
+    print(f"Solved: {result['prediction']}")
+```
+
+### Processing Multiple CAPTCHAs
+
+```python
+from captchakings import CaptchaKings
+import os
+
+client = CaptchaKings('ck_your_api_key')
+
+captcha_folder = 'captchas/'
+for filename in os.listdir(captcha_folder):
+    if filename.endswith(('.jpg', '.png', '.jpeg')):
+        filepath = os.path.join(captcha_folder, filename)
+        
+        try:
+            result = client.solve(filepath)
+            print(f"{filename}: {result['prediction']}")
+        except Exception as e:
+            print(f"{filename}: Error - {e}")
+```
+
+## 🎯 API Reference
+
+### CaptchaKings Class
+
+#### `__init__(api_key, base_url='https://captchakings.com/api/process.php')`
+
+Initialize the client.
+
+**Parameters:**
+- `api_key` (str): Your CaptchaKings API key
+- `base_url` (str, optional): API endpoint URL
+
+#### `solve(image_path, timeout=30)`
+
+Solve a CAPTCHA from an image file.
+
+**Parameters:**
+- `image_path` (str): Path to CAPTCHA image file
+- `timeout` (int, optional): Request timeout in seconds (default: 30)
+
+**Returns:**
+- `dict`: Response containing:
+  - `prediction` (str): Solved CAPTCHA text
+  - `confidence` (float): Prediction confidence score
+  - `process_time` (float): Processing time in seconds
+  - `credits_deducted` (int): Credits used for this request
+  - `credits_remaining` (int): Remaining credits in account
+  - `plan` (str): Your current plan name
+
+**Raises:**
+- `InvalidImageError`: Image file not found or invalid
+- `AuthenticationError`: Invalid API key
+- `InsufficientCreditsError`: Not enough credits
+- `TimeoutError`: Request timeout
+- `NetworkError`: Connection error
+- `APIError`: Other API errors
+
+#### `solve_with_retry(image_path, max_retries=3, retry_delay=2, timeout=30)`
+
+Solve CAPTCHA with automatic retry on transient failures.
+
+**Parameters:**
+- `image_path` (str): Path to CAPTCHA image file
+- `max_retries` (int, optional): Maximum retry attempts (default: 3)
+- `retry_delay` (int, optional): Delay between retries in seconds (default: 2)
+- `timeout` (int, optional): Request timeout in seconds (default: 30)
+
+**Returns:**
+- Same as `solve()` method
+
+## 🎨 Response Format
+
+```python
+{
+    'prediction': 'ABC123',           # Solved CAPTCHA text
+    'confidence': 0.98,               # Confidence score (0-1)
+    'process_time': 0.234,            # Processing time in seconds
+    'credits_deducted': 1,            # Credits used
+    'credits_remaining': 9999,        # Remaining credits
+    'plan': 'Professional'            # Your plan name
+}
+```
+
+## ⚠️ Exception Types
+
+- `CaptchaKingsException` - Base exception class
+- `APIError` - General API errors
+- `AuthenticationError` - Invalid API key
+- `InsufficientCreditsError` - Not enough credits
+- `InvalidImageError` - Invalid or missing image file
+- `TimeoutError` - Request timeout
+- `NetworkError` - Network connection error
+
+## 🔑 Getting API Key
+
+1. Visit [CaptchaKings.com](https://captchakings.com)
+2. Register for an account
+3. Go to Dashboard
+4. Copy your API key (starts with `ck_`)
+
+## 💡 Tips
+
+1. **Use context manager** - Ensures proper session cleanup
+2. **Enable retry logic** - For better reliability
+3. **Handle exceptions** - For robust error handling
+4. **Batch processing** - Reuse the same client instance
+
+## 📚 More Examples
+
+Check the `examples/` folder for more usage examples:
+
+- `basic_usage.py` - Simple CAPTCHA solving
+- `advanced_usage.py` - Advanced features and error handling
+- `batch_processing.py` - Process multiple CAPTCHAs
+
+## 🤝 Support
+
+- **Website**: [captchakings.com](https://captchakings.com)
+- **Documentation**: [captchakings.com/docs](https://captchakings.com?section=documentation)
+- **Email**: support@captchakings.com
+
+## 📄 License
+
+MIT License - see LICENSE file for details
+
+## 🌟 Why CaptchaKings?
+
+- ✅ **High Accuracy** - 99%+ success rate
+- ✅ **Fast Processing** - < 1 second average response time
+- ✅ **Affordable Pricing** - Starting from $1/1000 solves
+- ✅ **24/7 Support** - Always here to help
+- ✅ **No Setup Required** - Start in seconds
+
+---
+
+Made with ❤️ by [CaptchaKings](https://captchakings.com)

captchakings-1.0.0/README.md

@@ -0,0 +1,255 @@
+# CaptchaKings Python Library
+
+[![Python Version](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Official Python client library for [CaptchaKings API](https://captchakings.com) - Fast, accurate, and affordable CAPTCHA solving service.
+
+## ✨ Features
+
+- 🚀 **Simple & Clean API** - Just 2 lines of code to solve CAPTCHAs
+- 🔄 **Automatic Retry** - Built-in retry logic for failed requests
+- 🛡️ **Type Hints** - Full type annotations for better IDE support
+- ⚡ **Fast & Reliable** - Optimized for performance
+- 🎯 **Error Handling** - Custom exceptions for different error types
+- 📦 **Zero Configuration** - Works out of the box
+
+## 📦 Installation
+
+### From Source (Local Development)
+
+```bash
+cd captchakings-python
+pip install -e .
+```
+
+### Requirements
+
+- Python 3.6 or higher
+- `requests` library (automatically installed)
+
+## 🚀 Quick Start
+
+```python
+from captchakings import CaptchaKings
+
+# Initialize client
+client = CaptchaKings('ck_your_api_key_here')
+
+# Solve CAPTCHA
+result = client.solve('captcha.jpg')
+
+print(f"Solved: {result['prediction']}")
+print(f"Confidence: {result['confidence']}")
+print(f"Credits Remaining: {result['credits_remaining']}")
+```
+
+That's it! Just 3 lines of code. 🎉
+
+## 📖 Usage Examples
+
+### Basic Usage
+
+```python
+from captchakings import CaptchaKings
+
+client = CaptchaKings('ck_your_api_key')
+result = client.solve('path/to/captcha.jpg')
+
+if result:
+    print(f"✅ CAPTCHA Solved: {result['prediction']}")
+    print(f"Confidence: {result['confidence']}")
+    print(f"Credits Remaining: {result['credits_remaining']}")
+```
+
+### With Automatic Retry
+
+```python
+from captchakings import CaptchaKings
+
+client = CaptchaKings('ck_your_api_key')
+
+# Automatically retry up to 5 times with 2 second delay
+result = client.solve_with_retry(
+    'captcha.jpg',
+    max_retries=5,
+    retry_delay=2
+)
+
+print(f"Solved: {result['prediction']}")
+```
+
+### Error Handling
+
+```python
+from captchakings import CaptchaKings
+from captchakings.exceptions import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidImageError,
+    APIError
+)
+
+client = CaptchaKings('ck_your_api_key')
+
+try:
+    result = client.solve('captcha.jpg')
+    print(f"Solved: {result['prediction']}")
+    
+except AuthenticationError:
+    print("❌ Invalid API key")
+except InsufficientCreditsError:
+    print("❌ Not enough credits")
+except InvalidImageError:
+    print("❌ Invalid image file")
+except APIError as e:
+    print(f"❌ API Error: {e}")
+```
+
+### Using Context Manager
+
+```python
+from captchakings import CaptchaKings
+
+# Automatically closes session after use
+with CaptchaKings('ck_your_api_key') as client:
+    result = client.solve('captcha.jpg')
+    print(f"Solved: {result['prediction']}")
+```
+
+### Processing Multiple CAPTCHAs
+
+```python
+from captchakings import CaptchaKings
+import os
+
+client = CaptchaKings('ck_your_api_key')
+
+captcha_folder = 'captchas/'
+for filename in os.listdir(captcha_folder):
+    if filename.endswith(('.jpg', '.png', '.jpeg')):
+        filepath = os.path.join(captcha_folder, filename)
+        
+        try:
+            result = client.solve(filepath)
+            print(f"{filename}: {result['prediction']}")
+        except Exception as e:
+            print(f"{filename}: Error - {e}")
+```
+
+## 🎯 API Reference
+
+### CaptchaKings Class
+
+#### `__init__(api_key, base_url='https://captchakings.com/api/process.php')`
+
+Initialize the client.
+
+**Parameters:**
+- `api_key` (str): Your CaptchaKings API key
+- `base_url` (str, optional): API endpoint URL
+
+#### `solve(image_path, timeout=30)`
+
+Solve a CAPTCHA from an image file.
+
+**Parameters:**
+- `image_path` (str): Path to CAPTCHA image file
+- `timeout` (int, optional): Request timeout in seconds (default: 30)
+
+**Returns:**
+- `dict`: Response containing:
+  - `prediction` (str): Solved CAPTCHA text
+  - `confidence` (float): Prediction confidence score
+  - `process_time` (float): Processing time in seconds
+  - `credits_deducted` (int): Credits used for this request
+  - `credits_remaining` (int): Remaining credits in account
+  - `plan` (str): Your current plan name
+
+**Raises:**
+- `InvalidImageError`: Image file not found or invalid
+- `AuthenticationError`: Invalid API key
+- `InsufficientCreditsError`: Not enough credits
+- `TimeoutError`: Request timeout
+- `NetworkError`: Connection error
+- `APIError`: Other API errors
+
+#### `solve_with_retry(image_path, max_retries=3, retry_delay=2, timeout=30)`
+
+Solve CAPTCHA with automatic retry on transient failures.
+
+**Parameters:**
+- `image_path` (str): Path to CAPTCHA image file
+- `max_retries` (int, optional): Maximum retry attempts (default: 3)
+- `retry_delay` (int, optional): Delay between retries in seconds (default: 2)
+- `timeout` (int, optional): Request timeout in seconds (default: 30)
+
+**Returns:**
+- Same as `solve()` method
+
+## 🎨 Response Format
+
+```python
+{
+    'prediction': 'ABC123',           # Solved CAPTCHA text
+    'confidence': 0.98,               # Confidence score (0-1)
+    'process_time': 0.234,            # Processing time in seconds
+    'credits_deducted': 1,            # Credits used
+    'credits_remaining': 9999,        # Remaining credits
+    'plan': 'Professional'            # Your plan name
+}
+```
+
+## ⚠️ Exception Types
+
+- `CaptchaKingsException` - Base exception class
+- `APIError` - General API errors
+- `AuthenticationError` - Invalid API key
+- `InsufficientCreditsError` - Not enough credits
+- `InvalidImageError` - Invalid or missing image file
+- `TimeoutError` - Request timeout
+- `NetworkError` - Network connection error
+
+## 🔑 Getting API Key
+
+1. Visit [CaptchaKings.com](https://captchakings.com)
+2. Register for an account
+3. Go to Dashboard
+4. Copy your API key (starts with `ck_`)
+
+## 💡 Tips
+
+1. **Use context manager** - Ensures proper session cleanup
+2. **Enable retry logic** - For better reliability
+3. **Handle exceptions** - For robust error handling
+4. **Batch processing** - Reuse the same client instance
+
+## 📚 More Examples
+
+Check the `examples/` folder for more usage examples:
+
+- `basic_usage.py` - Simple CAPTCHA solving
+- `advanced_usage.py` - Advanced features and error handling
+- `batch_processing.py` - Process multiple CAPTCHAs
+
+## 🤝 Support
+
+- **Website**: [captchakings.com](https://captchakings.com)
+- **Documentation**: [captchakings.com/docs](https://captchakings.com?section=documentation)
+- **Email**: support@captchakings.com
+
+## 📄 License
+
+MIT License - see LICENSE file for details
+
+## 🌟 Why CaptchaKings?
+
+- ✅ **High Accuracy** - 99%+ success rate
+- ✅ **Fast Processing** - < 1 second average response time
+- ✅ **Affordable Pricing** - Starting from $1/1000 solves
+- ✅ **24/7 Support** - Always here to help
+- ✅ **No Setup Required** - Start in seconds
+
+---
+
+Made with ❤️ by [CaptchaKings](https://captchakings.com)

captchakings-1.0.0/captchakings/__init__.py

@@ -0,0 +1,37 @@
+"""
+CaptchaKings Python Library
+
+Simple and powerful Python client for CaptchaKings API.
+
+Example:
+    >>> from captchakings import CaptchaKings
+    >>> client = CaptchaKings('ck_your_api_key')
+    >>> result = client.solve('captcha.jpg')
+    >>> print(result['prediction'])
+"""
+
+__version__ = '1.0.0'
+__author__ = 'CaptchaKings'
+__license__ = 'MIT'
+
+from .client import CaptchaKings
+from .exceptions import (
+    CaptchaKingsException,
+    APIError,
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidImageError,
+    TimeoutError,
+    NetworkError
+)
+
+__all__ = [
+    'CaptchaKings',
+    'CaptchaKingsException',
+    'APIError',
+    'AuthenticationError',
+    'InsufficientCreditsError',
+    'InvalidImageError',
+    'TimeoutError',
+    'NetworkError'
+]