# 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)