{"id":29422131,"url":"https://github.com/abderrahimghazali/webshotr","last_synced_at":"2025-07-12T04:02:22.288Z","repository":{"id":298005610,"uuid":"998538178","full_name":"abderrahimghazali/webshotr","owner":"abderrahimghazali","description":"📸 A simple, fast, and elegant website screenshot tool built with Python and Playwright. Take full-page screenshots, mobile viewports, batch processing, and more with a beautiful CLI interface.","archived":false,"fork":false,"pushed_at":"2025-06-10T12:49:02.000Z","size":35,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-11T02:58:43.900Z","etag":null,"topics":["browser-automation","image-capture","playwright","python","screenshot","screenshot-tool","web","web-scraping","website"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/webshotr/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abderrahimghazali.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"abderrahimghazali","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"abderrahimghazali","thanks_dev":null,"custom":null}},"created_at":"2025-06-08T20:25:39.000Z","updated_at":"2025-06-23T13:54:29.000Z","dependencies_parsed_at":"2025-06-08T22:25:56.011Z","dependency_job_id":"b49fccb1-4948-4eda-a32c-59e85ef13727","html_url":"https://github.com/abderrahimghazali/webshotr","commit_stats":null,"previous_names":["abderrahimghazali/websnap"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/abderrahimghazali/webshotr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abderrahimghazali%2Fwebshotr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abderrahimghazali%2Fwebshotr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abderrahimghazali%2Fwebshotr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abderrahimghazali%2Fwebshotr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abderrahimghazali","download_url":"https://codeload.github.com/abderrahimghazali/webshotr/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abderrahimghazali%2Fwebshotr/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264935250,"owners_count":23685493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser-automation","image-capture","playwright","python","screenshot","screenshot-tool","web","web-scraping","website"],"created_at":"2025-07-12T04:02:14.639Z","updated_at":"2025-07-12T04:02:22.252Z","avatar_url":"https://github.com/abderrahimghazali.png","language":"Python","funding_links":["https://github.com/sponsors/abderrahimghazali","https://buymeacoffee.com/abderrahimghazali"],"categories":[],"sub_categories":[],"readme":"# WebShotr 📸\n\nA simple, fast, and elegant website screenshot tool built with Python and Playwright.\n\n![WebShotr Logo](https://i.imgur.com/9AsVEfZ.png)\n\n## ✨ Features\n\n- 🚀 **Fast and Reliable** - Built on Playwright for robust browser automation\n- 🌐 **Multi-Browser Support** - Chromium, Firefox, and WebKit\n- 📱 **Mobile Screenshots** - Capture mobile viewport screenshots\n- 📄 **Full Page Capture** - Take full-page screenshots beyond the viewport\n- 🎯 **Element Selection** - Screenshot specific elements using CSS selectors\n- 📁 **Batch Processing** - Process multiple URLs from command line or file\n- ⚙️ **Configurable** - Extensive customization options\n- 💻 **CLI \u0026 API** - Use from command line or integrate into Python projects\n- 🎨 **Beautiful CLI** - Elegant command-line interface with colored output\n\n## 🛠️ Installation\n\n### Prerequisites\n\n- Python 3.7+\n- pip\n\n### Install WebShotr\n\n```bash\npip install webshotr\n```\n\n### Install Playwright Browsers\n\nAfter installing WebShotr, you need to install the browser binaries:\n\n```bash\nplaywright install\n```\n\n## 🚀 Quick Start\n\n### Command Line Usage\n\nTake a screenshot of a website:\n\n```bash\nwebshotr https://example.com\n```\n\nSee the beautiful banner and help:\n\n```bash\nwebshotr\n```\n\n### Python API Usage\n\n```python\nfrom webshotr import WebShotr\n\n# Create WebShotr instance\nsnap = WebShotr()\n\n# Take a screenshot\nsnap.screenshot(\"https://example.com\", \"screenshot.png\")\n```\n\n## 📖 Usage Examples\n\n### CLI Examples\n\n#### Single Website\n\n```bash\n# Basic screenshot\nwebshotr https://example.com\n\n# Custom output path\nwebshotr https://example.com --output my-screenshot.png\n\n# Full page screenshot\nwebshotr https://example.com --full-page --output fullpage.png\n```\n\n#### Mobile Screenshots\n\n```bash\n# Mobile viewport\nwebshotr https://example.com --mobile --output mobile.png\n\n# Custom mobile dimensions\nwebshotr https://example.com --width 375 --height 812 --output iphone.png\n```\n\n#### Multiple Websites\n\n```bash\n# Multiple URLs\nwebshotr https://google.com https://github.com --output screenshots/\n\n# From file\nwebshotr --list-file urls.txt --output screenshots/\n```\n\n#### Advanced Options\n\n```bash\n# Custom browser, quality, and delay\nwebshotr https://example.com \\\n  --browser firefox \\\n  --quality 90 \\\n  --delay 3 \\\n  --timeout 30\n\n# Screenshot specific element\nwebshotr https://example.com \\\n  --element \"#main-content\" \\\n  --output element.png\n\n# Use configuration file\nwebshotr https://example.com --config config.json\n```\n\n### Python API Examples\n\n#### Basic Usage\n\n```python\nfrom webshotr import WebShotr, screenshot\n\n# Quick function\nscreenshot(\"https://example.com\", \"output.png\")\n\n# With options\nscreenshot(\"https://example.com\", \"output.png\", \n          full_page=True, mobile=True)\n```\n\n#### Advanced Usage\n\n```python\nfrom webshotr import WebShotr\n\n# Create instance with custom settings\nsnap = WebShotr(\n    width=1920,\n    height=1080,\n    browser_type=\"firefox\",\n    headless=True\n)\n\n# Take screenshots\nsnap.screenshot(\"https://example.com\", \"desktop.png\")\nsnap.screenshot(\"https://example.com\", \"mobile.png\", mobile=True)\n\n# Multiple URLs\nurls = [\"https://google.com\", \"https://github.com\"]\nresults = snap.screenshot_multiple(urls, \"screenshots/\")\nprint(f\"Saved {len(results)} screenshots\")\n```\n\n#### Async Usage\n\n```python\nimport asyncio\nfrom webshotr import WebShotr\n\nasync def take_screenshots():\n    async with WebShotr() as snap:\n        # Async screenshot\n        result = await snap.screenshot_async(\n            \"https://example.com\", \n            \"async-screenshot.png\"\n        )\n        print(f\"Screenshot saved: {result}\")\n\n# Run async function\nasyncio.run(take_screenshots())\n```\n\n## ⚙️ Configuration\n\n### Command Line Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--output, -o` | Output file path or directory | Auto-generated |\n| `--width, -w` | Viewport width | 1280 |\n| `--height, -h` | Viewport height | 720 |\n| `--full-page, -f` | Capture full page | False |\n| `--mobile, -m` | Use mobile viewport | False |\n| `--quality, -q` | JPEG quality (1-100) | Auto |\n| `--delay, -d` | Delay before screenshot (seconds) | 0 |\n| `--element, -e` | CSS selector for specific element | None |\n| `--browser, -b` | Browser engine (chromium/firefox/webkit) | chromium |\n| `--user-agent, -ua` | Custom user agent string | Auto |\n| `--timeout, -t` | Page load timeout (seconds) | 30 |\n| `--headless/--no-headless` | Run in headless mode | True |\n| `--list-file, -l` | File containing list of URLs | None |\n| `--config, -c` | JSON configuration file | None |\n| `--verbose, -v` | Verbose output | False |\n\n### Configuration File\n\nCreate a `config.json` file:\n\n```json\n{\n  \"width\": 1920,\n  \"height\": 1080,\n  \"headless\": true,\n  \"timeout\": 30000,\n  \"browser_type\": \"chromium\",\n  \"user_agent\": \"Mozilla/5.0 (compatible; WebShotr/1.0)\"\n}\n```\n\nUse it with:\n\n```bash\nwebshotr https://example.com --config config.json\n```\n\n### URL List File\n\nCreate a `urls.txt` file:\n\n```\nhttps://example.com\nhttps://google.com\n# This is a comment\nhttps://github.com\n```\n\nUse it with:\n\n```bash\nwebshotr --list-file urls.txt --output screenshots/\n```\n\n## 🐍 API Reference\n\n### WebShotr Class\n\n```python\nWebShotr(\n    width: int = 1280,\n    height: int = 720,\n    headless: bool = True,\n    timeout: int = 30000,\n    browser_type: str = \"chromium\",\n    user_agent: Optional[str] = None\n)\n```\n\n#### Methods\n\n- `screenshot(url, output=None, **kwargs)` - Take a screenshot\n- `screenshot_multiple(urls, output_dir=\"screenshots\", **kwargs)` - Multiple screenshots\n- `screenshot_async(url, output=None, **kwargs)` - Async screenshot\n- `screenshot_multiple_async(urls, output_dir=\"screenshots\", **kwargs)` - Async multiple\n\n### Convenience Functions\n\n```python\nfrom webshotr import screenshot, screenshot_multiple\n\n# Quick screenshot\nscreenshot(\"https://example.com\", \"output.png\")\n\n# Multiple screenshots\nscreenshot_multiple(urls, \"screenshots/\")\n```\n\n## 🔧 Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/abderrahimghazali/webshotr.git\ncd webshotr\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e .\n\n# Install development dependencies\npip install pytest pytest-asyncio flake8\n\n# Install Playwright browsers\nplaywright install\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest tests/ -v\n\n# Run specific test file\npytest tests/test_cli.py -v\n\n# Run with coverage\npytest tests/ --cov=webshotr\n```\n\n### Code Style\n\n```bash\n# Check code style\nflake8 webshotr/ tests/\n\n# Format code (if you have black installed)\nblack webshotr/ tests/\n```\n\n## 📝 Requirements\n\n- Python 3.7+\n- playwright \u003e= 1.40.0\n- Pillow \u003e= 9.0.0\n- click \u003e= 8.0.0\n- aiofiles \u003e= 22.0.0\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 🙏 Acknowledgments\n\n- Built with [Playwright](https://playwright.dev/) for reliable browser automation\n- Inspired by the need for a simple, elegant screenshot tool\n- Thanks to all contributors and users\n\n## 📬 Support\n\n- 🐛 [Report Issues](https://github.com/abderrahimghazali/webshotr/issues)\n- 💡 [Feature Requests](https://github.com/abderrahimghazali/webshotr/issues)\n\n---\n\nMade with ❤️ by [AbderrahimGHAZALI](https://github.com/abderrahimghazali) \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabderrahimghazali%2Fwebshotr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabderrahimghazali%2Fwebshotr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabderrahimghazali%2Fwebshotr/lists"}