captchakings 1.0.0__py3-none-any.whl

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'
+]

captchakings/client.py

@@ -0,0 +1,189 @@
+"""
+CaptchaKings API Client
+"""
+
+import requests
+import os
+import time
+from typing import Dict, Optional, Union
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidImageError,
+    TimeoutError as CKTimeoutError,
+    NetworkError
+)
+
+class CaptchaKings:
+    """
+    CaptchaKings API Client
+    
+    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'])
+    """
+    
+    def __init__(self, api_key: str, base_url: str = 'https://captchakings.com/api/process.php'):
+        """
+        Initialize CaptchaKings client
+        
+        Args:
+            api_key: Your CaptchaKings API key
+            base_url: API endpoint URL (default: official API)
+        """
+        if not api_key:
+            raise ValueError("API key is required")
+        
+        self.api_key = api_key
+        self.base_url = base_url
+        self._session = requests.Session()
+        self._session.headers.update({
+            'Authorization': f'Bearer {api_key}'
+        })
+    
+    def solve(self, image_path: str, timeout: int = 30) -> Dict:
+        """
+        Solve CAPTCHA from image file
+        
+        Args:
+            image_path: Path to CAPTCHA image file
+            timeout: Request timeout in seconds (default: 30)
+            
+        Returns:
+            dict: Response with prediction and credits info
+            
+        Raises:
+            InvalidImageError: If image file not found or invalid
+            AuthenticationError: If API key is invalid
+            InsufficientCreditsError: If not enough credits
+            APIError: For other API errors
+            
+        Example:
+            >>> result = client.solve('captcha.jpg')
+            >>> print(f"Solved: {result['prediction']}")
+            >>> print(f"Credits: {result['credits_remaining']}")
+        """
+        if not os.path.exists(image_path):
+            raise InvalidImageError(f"Image file not found: {image_path}")
+        
+        try:
+            with open(image_path, 'rb') as f:
+                files = {
+                    'captcha': ('captcha.jpg', f, 'image/jpeg')
+                }
+                
+                response = self._session.post(
+                    self.base_url,
+                    files=files,
+                    timeout=timeout
+                )
+            
+            data = response.json()
+            
+            if response.status_code == 200 and data.get('success'):
+                return {
+                    'prediction': data['data']['prediction'],
+                    'confidence': data['data']['confidence'],
+                    'process_time': data['data']['process_time'],
+                    'credits_deducted': data['credits']['credits_deducted'],
+                    'credits_remaining': data['credits']['credits_remaining'],
+                    'plan': data['credits']['plan']
+                }
+            else:
+                self._handle_error(response.status_code, data)
+                
+        except requests.exceptions.Timeout:
+            raise CKTimeoutError(f"Request timeout after {timeout} seconds")
+        except requests.exceptions.ConnectionError as e:
+            raise NetworkError(f"Connection error: {str(e)}")
+        except requests.exceptions.RequestException as e:
+            raise APIError(f"Request error: {str(e)}")
+        except (ValueError, KeyError) as e:
+            raise APIError(f"Invalid response format: {str(e)}")
+        except IOError as e:
+            raise InvalidImageError(f"Error reading image file: {str(e)}")
+    
+    def solve_with_retry(self, image_path: str, max_retries: int = 3, 
+                        retry_delay: int = 2, timeout: int = 30) -> Dict:
+        """
+        Solve CAPTCHA with automatic retry on failure
+        
+        Args:
+            image_path: Path to CAPTCHA image file
+            max_retries: Maximum number of retry attempts (default: 3)
+            retry_delay: Delay between retries in seconds (default: 2)
+            timeout: Request timeout in seconds (default: 30)
+            
+        Returns:
+            dict: Response with prediction and credits info
+            
+        Raises:
+            Same as solve() method
+            
+        Example:
+            >>> result = client.solve_with_retry('captcha.jpg', max_retries=5)
+        """
+        last_error = None
+        
+        for attempt in range(max_retries):
+            try:
+                return self.solve(image_path, timeout)
+            except (AuthenticationError, InsufficientCreditsError, InvalidImageError):
+                raise
+            except Exception as e:
+                last_error = e
+                if attempt < max_retries - 1:
+                    time.sleep(retry_delay)
+        
+        raise last_error
+    
+    def get_balance(self) -> Dict:
+        """
+        Get account balance and plan information
+        
+        Returns:
+            dict: Balance information
+            
+        Note:
+            This method sends a test request to get balance info
+        """
+        test_image_path = os.path.join(os.path.dirname(__file__), 'test.jpg')
+        
+        try:
+            result = self.solve(test_image_path)
+            return {
+                'credits_remaining': result['credits_remaining'],
+                'plan': result['plan']
+            }
+        except Exception:
+            raise APIError("Could not retrieve balance information")
+    
+    def _handle_error(self, status_code: int, data: Dict):
+        """Handle API error responses"""
+        error_msg = data.get('error', 'Unknown error')
+        
+        if status_code == 401 or 'Invalid API key' in error_msg:
+            raise AuthenticationError(error_msg)
+        elif status_code == 402 or 'Insufficient credits' in error_msg:
+            raise InsufficientCreditsError(error_msg)
+        elif status_code == 400 or 'Invalid image' in error_msg:
+            raise InvalidImageError(error_msg)
+        else:
+            raise APIError(f"API error: {error_msg}")
+    
+    def close(self):
+        """Close the session"""
+        self._session.close()
+    
+    def __enter__(self):
+        """Context manager entry"""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit"""
+        self.close()

captchakings/exceptions.py

@@ -0,0 +1,31 @@
+"""
+CaptchaKings API Exceptions
+"""
+
+class CaptchaKingsException(Exception):
+    """Base exception for CaptchaKings API"""
+    pass
+
+class APIError(CaptchaKingsException):
+    """API request error"""
+    pass
+
+class AuthenticationError(CaptchaKingsException):
+    """Invalid API key or authentication failed"""
+    pass
+
+class InsufficientCreditsError(CaptchaKingsException):
+    """Not enough credits to process request"""
+    pass
+
+class InvalidImageError(CaptchaKingsException):
+    """Invalid or corrupted image file"""
+    pass
+
+class TimeoutError(CaptchaKingsException):
+    """Request timeout"""
+    pass
+
+class NetworkError(CaptchaKingsException):
+    """Network connection error"""
+    pass

captchakings-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+captchakings/__init__.py,sha256=mgXzghjPRmVra9ZBE4cm15zUkbszFAK-m9Kfkp4RK4c,769
+captchakings/client.py,sha256=FXBQDPmEO9Kd9LvTjaEFuFKpZr92E4po47uFqBo2f9A,6491
+captchakings/exceptions.py,sha256=gEg2YyZdWhBoWaPS4GPnJHDlKaDgeV6lfE1XCdp5JlY,700
+captchakings-1.0.0.dist-info/licenses/LICENSE,sha256=pbtrBRDwqQPp3x4iWRUI070lnIOuaGTvt0_ldws_aS8,1069
+captchakings-1.0.0.dist-info/METADATA,sha256=a21ftJTv5oGDMD-UzLBEMRYMgPj5CRxTocmjMy5nee0,8614
+captchakings-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+captchakings-1.0.0.dist-info/top_level.txt,sha256=IkIvMDQ-vA_9dcJjzymjeDYs8XObiVLGRTiGL6m_-fc,13
+captchakings-1.0.0.dist-info/RECORD,,

captchakings-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

captchakings-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+captchakings