Metadata-Version: 2.4
Name: toolcenter
Version: 1.1.0
Summary: Official Python SDK for ToolCenter's web automation and utility APIs
Home-page: https://github.com/toolcenter-dev/sdk-python
Author: ToolCenter
Author-email: ToolCenter <hello@toolcenter.dev>
Maintainer-email: ToolCenter <hello@toolcenter.dev>
License: MIT License
        
        Copyright (c) 2024 ToolCenter
        
        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.
Project-URL: Homepage, https://toolcenter.dev
Project-URL: Documentation, https://toolcenter.dev/docs
Project-URL: Repository, https://github.com/toolcenter-dev/sdk-python
Project-URL: Bug Reports, https://github.com/toolcenter-dev/sdk-python/issues
Project-URL: Changelog, https://github.com/toolcenter-dev/sdk-python/blob/main/CHANGELOG.md
Keywords: api,web,screenshot,pdf,qr,automation,toolcenter
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# ToolCenter Python SDK

[![PyPI version](https://badge.fury.io/py/toolcenter.svg)](https://badge.fury.io/py/toolcenter)
[![Python version](https://img.shields.io/pypi/pyversions/toolcenter.svg)](https://pypi.org/project/toolcenter/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official Python SDK for ToolCenter's web automation and utility APIs. Take screenshots, generate PDFs, create QR codes, extract metadata, and access 20+ other web-related tools through a simple Python interface.

## Installation

```bash
pip install toolcenter
```

## Quick Start

```python
from toolcenter import ToolCenter

# Initialize client with your API key
tc = ToolCenter('your-api-key')

# Take a screenshot
result = tc.screenshot(url='https://example.com', width=1920, format='png')

# Generate a PDF
pdf_result = tc.pdf(url='https://example.com', format='A4')

# Create a QR code
qr_result = tc.qr(data='https://example.com', size=300)
```

## Authentication

Get your API key from [ToolCenter Dashboard](https://toolcenter.dev/dashboard) and initialize the client:

```python
from toolcenter import ToolCenter

tc = ToolCenter('your-api-key')

# Or with custom base URL
tc = ToolCenter('your-api-key', base_url='https://api.toolcenter.dev')
```

## Core Features

### Screenshots

Capture high-quality webpage screenshots:

```python
# Basic screenshot
result = tc.screenshot(url='https://example.com')

# Full page screenshot with custom dimensions
result = tc.screenshot(
    url='https://example.com',
    width=1920,
    height=1080,
    full_page=True,
    format='png'
)

# Mobile device emulation
result = tc.screenshot(
    url='https://example.com',
    device='iPhone 12',
    wait_for='#content'
)
```

### PDF Generation

Convert webpages to PDF documents:

```python
# Basic PDF
result = tc.pdf(url='https://example.com')

# Custom format and options
result = tc.pdf(
    url='https://example.com',
    format='A4',
    landscape=True,
    print_background=True,
    margin={'top': '1in', 'bottom': '1in'}
)
```

### QR Codes

Generate QR codes for any data:

```python
# Basic QR code
result = tc.qr(data='https://example.com')

# Custom size and format
result = tc.qr(
    data='Hello World!',
    size=500,
    format='svg',
    error_correction='H'
)
```

### Metadata Extraction

Extract rich metadata from websites:

```python
# Extract all metadata
result = tc.metadata(url='https://example.com')

# Include specific data types
result = tc.metadata(
    url='https://example.com',
    include_og=True,
    include_twitter=True,
    include_schema=True
)
```

## Available Methods

### Web Content
- `screenshot(**kwargs)` - Capture webpage screenshots
- `pdf(**kwargs)` - Generate PDFs from webpages  
- `html_to_image(**kwargs)` - Convert HTML to image
- `metadata(**kwargs)` - Extract webpage metadata
- `og_image(**kwargs)` - Get Open Graph images
- `link_preview(**kwargs)` - Generate rich link previews
- `favicon(**kwargs)` - Extract website favicons

### Image Processing
- `watermark(**kwargs)` - Add watermarks to images
- `compress(**kwargs)` - Compress and optimize images
- `colors(**kwargs)` - Extract dominant colors
- `placeholder(**kwargs)` - Generate placeholder images

### Utilities
- `qr(**kwargs)` - Generate QR codes
- `status(**kwargs)` - Check website status
- `dns(**kwargs)` - Perform DNS lookups
- `ssl(**kwargs)` - Check SSL certificates
- `whois(**kwargs)` - WHOIS domain lookups
- `tech_stack(**kwargs)` - Detect website technologies

### Bulk Operations
- `bulk_screenshot(urls, **kwargs)` - Screenshot multiple URLs
- `bulk_pdf(urls, **kwargs)` - Generate PDFs for multiple URLs
- `bulk_metadata(urls, **kwargs)` - Extract metadata from multiple URLs

### Account
- `usage()` - Get API usage statistics

## Error Handling

The SDK includes custom exception classes for different error types:

```python
from toolcenter import ToolCenter, ToolCenterError, AuthenticationError, RateLimitError

tc = ToolCenter('your-api-key')

try:
    result = tc.screenshot(url='https://example.com')
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit exceeded")
except ToolCenterError as e:
    print(f"API error: {e}")
```

## Bulk Operations

Process multiple URLs efficiently:

```python
# Screenshot multiple websites
urls = [
    'https://example.com',
    'https://github.com',
    'https://stackoverflow.com'
]

results = tc.bulk_screenshot(urls, width=1920, format='png')

for url, result in results.items():
    if result['success']:
        print(f"Screenshot saved for {url}")
    else:
        print(f"Error for {url}: {result['error']}")
```

## Advanced Usage

### Custom Configuration

```python
# Custom timeout and retry settings
tc = ToolCenter(
    api_key='your-api-key',
    base_url='https://toolcenter.dev'
)

# Screenshot with advanced options
result = tc.screenshot(
    url='https://example.com',
    width=1920,
    height=1080,
    full_page=False,
    wait_for='#main-content',
    delay=2000,  # 2 second delay
    device='Desktop'
)
```

### Response Format

All methods return a dictionary with the following structure:

```python
{
    "success": True,
    "data": {
        "url": "https://generated-content-url.com/image.png",
        "size": 156789,
        "format": "png",
        "width": 1920,
        "height": 1080
    },
    "usage": {
        "credits_used": 1,
        "remaining": 999
    }
}
```

## Requirements

- Python 3.8+
- requests >= 2.20.0

## Documentation

For complete API documentation and advanced usage examples, visit:
- [API Documentation](https://toolcenter.dev/docs)
- [Python SDK Examples](https://toolcenter.dev/docs/sdks/python)

## Support

- **Issues**: [GitHub Issues](https://github.com/toolcenter-dev/sdk-python/issues)  
- **Email**: hello@toolcenter.dev
- **Documentation**: https://toolcenter.dev/docs

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Made with ❤️ by [ToolCenter](https://toolcenter.dev)
