webshotr

WebShotr 📸

A simple, fast, and elegant website screenshot tool built with Python and Playwright.

✨ Features

• 🚀 Fast and Reliable - Built on Playwright for robust browser automation
• 🌐 Multi-Browser Support - Chromium, Firefox, and WebKit
• 📱 Mobile Screenshots - Capture mobile viewport screenshots
• 📄 Full Page Capture - Take full-page screenshots beyond the viewport
• 🎯 Element Selection - Screenshot specific elements using CSS selectors
• 📁 Batch Processing - Process multiple URLs from command line or file
• ⚙️ Configurable - Extensive customization options
• 💻 CLI & API - Use from command line or integrate into Python projects
• 🎨 Beautiful CLI - Elegant command-line interface with colored output

🛠️ Installation

Prerequisites

• Python 3.7+
• pip

Install WebShotr

pip install webshotr

Install Playwright Browsers

After installing WebShotr, you need to install the browser binaries:

playwright install

🚀 Quick Start

Command Line Usage

Take a screenshot of a website:

webshotr https://example.com

See the beautiful banner and help:

webshotr

Python API Usage

from webshotr import WebShotr

# Create WebShotr instance
snap = WebShotr()

# Take a screenshot
snap.screenshot("https://example.com", "screenshot.png")

📖 Usage Examples

CLI Examples

Single Website

# Basic screenshot
webshotr https://example.com

# Custom output path
webshotr https://example.com --output my-screenshot.png

# Full page screenshot
webshotr https://example.com --full-page --output fullpage.png

Mobile Screenshots

# Mobile viewport
webshotr https://example.com --mobile --output mobile.png

# Custom mobile dimensions
webshotr https://example.com --width 375 --height 812 --output iphone.png

Multiple Websites

# Multiple URLs
webshotr https://google.com https://github.com --output screenshots/

# From file
webshotr --list-file urls.txt --output screenshots/

Advanced Options

# Custom browser, quality, and delay
webshotr https://example.com \
  --browser firefox \
  --quality 90 \
  --delay 3 \
  --timeout 30

# Screenshot specific element
webshotr https://example.com \
  --element "#main-content" \
  --output element.png

# Use configuration file
webshotr https://example.com --config config.json

Python API Examples

Basic Usage

from webshotr import WebShotr, screenshot

# Quick function
screenshot("https://example.com", "output.png")

# With options
screenshot("https://example.com", "output.png", 
          full_page=True, mobile=True)

Advanced Usage

from webshotr import WebShotr

# Create instance with custom settings
snap = WebShotr(
    width=1920,
    height=1080,
    browser_type="firefox",
    headless=True
)

# Take screenshots
snap.screenshot("https://example.com", "desktop.png")
snap.screenshot("https://example.com", "mobile.png", mobile=True)

# Multiple URLs
urls = ["https://google.com", "https://github.com"]
results = snap.screenshot_multiple(urls, "screenshots/")
print(f"Saved {len(results)} screenshots")

Async Usage

import asyncio
from webshotr import WebShotr

async def take_screenshots():
    async with WebShotr() as snap:
        # Async screenshot
        result = await snap.screenshot_async(
            "https://example.com", 
            "async-screenshot.png"
        )
        print(f"Screenshot saved: {result}")

# Run async function
asyncio.run(take_screenshots())

⚙️ Configuration

Command Line Options

Option	Description	Default
--output, -o	Output file path or directory	Auto-generated
--width, -w	Viewport width	1280
--height, -h	Viewport height	720
--full-page, -f	Capture full page	False
--mobile, -m	Use mobile viewport	False
--quality, -q	JPEG quality (1-100)	Auto
--delay, -d	Delay before screenshot (seconds)	0
--element, -e	CSS selector for specific element	None
--browser, -b	Browser engine (chromium/firefox/webkit)	chromium
--user-agent, -ua	Custom user agent string	Auto
--timeout, -t	Page load timeout (seconds)	30
--headless/--no-headless	Run in headless mode	True
--list-file, -l	File containing list of URLs	None
--config, -c	JSON configuration file	None
--verbose, -v	Verbose output	False

Configuration File

Create a config.json file:

{
  "width": 1920,
  "height": 1080,
  "headless": true,
  "timeout": 30000,
  "browser_type": "chromium",
  "user_agent": "Mozilla/5.0 (compatible; WebShotr/1.0)"
}

Use it with:

webshotr https://example.com --config config.json

URL List File

Create a urls.txt file:

https://example.com
https://google.com
# This is a comment
https://github.com

Use it with:

webshotr --list-file urls.txt --output screenshots/

🐍 API Reference

WebShotr Class

WebShotr(
    width: int = 1280,
    height: int = 720,
    headless: bool = True,
    timeout: int = 30000,
    browser_type: str = "chromium",
    user_agent: Optional[str] = None
)

Methods

• screenshot(url, output=None, **kwargs) - Take a screenshot
• screenshot_multiple(urls, output_dir="screenshots", **kwargs) - Multiple screenshots
• screenshot_async(url, output=None, **kwargs) - Async screenshot
• screenshot_multiple_async(urls, output_dir="screenshots", **kwargs) - Async multiple

Convenience Functions

from webshotr import screenshot, screenshot_multiple

# Quick screenshot
screenshot("https://example.com", "output.png")

# Multiple screenshots
screenshot_multiple(urls, "screenshots/")

🔧 Development

Setup Development Environment

# Clone the repository
git clone https://github.com/abderrahimghazali/webshotr.git
cd webshotr

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Install development dependencies
pip install pytest pytest-asyncio flake8

# Install Playwright browsers
playwright install

Running Tests

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_cli.py -v

# Run with coverage
pytest tests/ --cov=webshotr

Code Style

# Check code style
flake8 webshotr/ tests/

# Format code (if you have black installed)
black webshotr/ tests/

📝 Requirements

• Python 3.7+
• playwright >= 1.40.0
• Pillow >= 9.0.0
• click >= 8.0.0
• aiofiles >= 22.0.0

🤝 Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

🙏 Acknowledgments

• Built with Playwright for reliable browser automation
• Inspired by the need for a simple, elegant screenshot tool
• Thanks to all contributors and users

📬 Support

• 🐛 Report Issues
• 💡 Feature Requests

Made with ❤️ by AbderrahimGHAZALI