Initial commit: ScraperGuard v1.0 — scraper reliability framework

Author: mostafam-dev

.dockerignore

@@ -0,0 +1,11 @@
+__pycache__
+*.pyc
+.git
+.github
+tests/
+*.egg-info
+dist/
+build/
+.pytest_cache
+.mypy_cache
+.ruff_cache

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest --tb=short -q
+      - run: ruff check src/
+      - run: mypy src/scraperguard/ --ignore-missing-imports
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/
+      - run: ruff format --check src/

.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing / Coverage
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Runtime artifacts
+*.db
+*.sqlite
+*.sqlite3
+
+# ScraperGuard local artifacts
+scraperguard.db
+scraperguard.yaml
+_dump/
+
+# Logs
+*.log
+
+# Environment
+.env
+.env.local

.python-version

@@ -0,0 +1 @@
+3.13

CONTRIBUTING.md

@@ -0,0 +1,111 @@
+# Contributing to ScraperGuard
+
+Thanks for your interest in contributing to ScraperGuard!
+
+## Development Setup
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/mostafam-dev/scraperguard.git
+cd scraperguard
+```
+
+2. Install in development mode:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Or with uv:
+
+```bash
+uv sync --extra dev
+```
+
+3. Verify the installation:
+
+```bash
+pytest
+scraperguard --help
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=scraperguard --cov-report=term-missing
+
+# Run a specific test file
+pytest tests/test_health.py
+
+# Run tests matching a pattern
+pytest -k "test_schema"
+```
+
+## Code Style
+
+We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```bash
+# Check for lint errors
+ruff check src/ tests/
+
+# Auto-fix lint errors
+ruff check --fix src/ tests/
+
+# Format code
+ruff format src/ tests/
+```
+
+Configuration is in `pyproject.toml` under `[tool.ruff]`.
+
+## Type Checking
+
+We use [mypy](https://mypy.readthedocs.io/) for static type checking:
+
+```bash
+mypy src/scraperguard/
+```
+
+Configuration is in `pyproject.toml` under `[tool.mypy]`.
+
+## Submitting Changes
+
+1. Fork the repository and create a feature branch:
+
+```bash
+git checkout -b feature/my-feature
+```
+
+2. Make your changes, ensuring:
+   - All tests pass (`pytest`)
+   - Code is formatted (`ruff format`)
+   - No lint errors (`ruff check`)
+   - Types check cleanly (`mypy src/scraperguard/`)
+
+3. Write tests for new functionality.
+
+4. Commit with a clear message describing the change.
+
+5. Open a pull request against the `main` branch.
+
+## Project Structure
+
+```
+src/scraperguard/       # Main package source
+tests/                  # Test suite (mirrors src/ structure)
+examples/               # Working examples and configs
+docs/                   # Documentation
+```
+
+## Reporting Issues
+
+Please open an issue on GitHub with:
+- A clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Python version and OS

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY pyproject.toml .
+COPY src/ src/
+
+RUN pip install --no-cache-dir ".[api]"
+
+EXPOSE 8000
+
+CMD ["scraperguard", "serve", "--host", "0.0.0.0", "--port", "8000"]

Makefile

@@ -0,0 +1,19 @@
+.PHONY: test lint format typecheck docker-build docker-run
+
+test:
+	pytest --tb=short -q
+
+lint:
+	ruff check src/
+
+format:
+	ruff format src/
+
+typecheck:
+	mypy src/scraperguard/ --ignore-missing-imports
+
+docker-build:
+	docker build -t scraperguard .
+
+docker-run:
+	docker-compose up -d