wscraper/README.md

wscraper

wscraper, tracker bookmark / wishlist akışlarını ortak bir Python adapter katmanında toplayan çoklu tracker scraper paketidir. Bugünkü kullanım şekli iki parçalıdır:

• bin/wscraper/: Python paketinin kendisi, tracker adapter'ları ve CLI
• bin/wscraper-service/server.py: q-buffer backend'in HTTP ile konuştuğu host-side servis

q-buffer watcher akışı artık wscraper CLI'yi doğrudan Docker içinde spawn etmek yerine, host makinede çalışan wscraper-service üzerinden kullanır. Bunun ana nedeni scrapling + Playwright zincirinin tracker tarafında daha stabil çalışmasının host ortamında olmasıdır.

Desteklenen Tracker'lar

• happyfappy (hf)
• privatehd (phd)

Desteklenen ortak aksiyonlar:

• get-bookmarks
• download-torrent-files
• remove-bookmark

Mimari

wscraper paket yapısı artık tracker-registry tabanlıdır:

• src/wscraper/registry.py
  • desteklenen tracker adapter'larını kaydeder
• src/wscraper/types.py
  • ortak BookmarkItem, DownloadResult, TrackerAdapter tiplerini tanımlar
• src/wscraper/sites/happyfappy.py
  • HappyFappy adapter'ı
• src/wscraper/sites/privatehd.py
  • PrivateHD adapter'ı
• src/wscraper/cli.py
  • tüm tracker'lar için ortak CLI entrypoint

Bu sayede yeni tracker eklemek için mevcut CLI'yi kopyalamak yerine sadece yeni bir adapter yazmak yeterlidir.

Kurulum

macOS / Linux

cd bin/wscraper
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
scrapling install

Alternatif:

• python3.12 yoksa python3.11 veya python3.10 kullan
• scrapling install, Playwright/browser bağımlılıklarını kurar

Windows PowerShell

cd bin/wscraper
py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .
scrapling install

CLI Kullanımı

Genel form:

wscraper <tracker> --action <action> [opsiyonlar]

Bookmark / Wishlist Çekme

wscraper happyfappy --action get-bookmarks -c cookies.txt -o bookmarks.json
wscraper privatehd --action get-bookmarks -c cookies.txt -o bookmarks.json

İsteğe bağlı wishlist_url override:

wscraper privatehd --action get-bookmarks -c cookies.txt --wishlist-url "https://privatehd.to/bookmarks" -o bookmarks.json

Torrent Dosyası İndirme

wscraper happyfappy --action download-torrent-files \
  -c cookies.txt \
  -u "https://www.happyfappy.net/torrents.php?id=110178" \
  --title "Sample" \
  --image-url "https://example.com/poster.jpg" \
  -o torrent

wscraper privatehd --action download-torrent-files \
  -c cookies.txt \
  -u "https://privatehd.to/torrent/12345" \
  --download-url "https://privatehd.to/download.php?id=12345" \
  --title "Sample" \
  -o torrent

Bookmark Silme

wscraper happyfappy --action remove-bookmark \
  -c cookies.txt \
  -u "https://www.happyfappy.net/torrents.php?id=110178" \
  --title "Sample"

wscraper privatehd --action remove-bookmark \
  -c cookies.txt \
  -u "https://privatehd.to/torrent/12345" \
  --remove-token "bookmark-delete-token" \
  --title "Sample"

Kısa Alias'lar

wscraper hf -a gb -c cookies.txt -o bookmarks.json
wscraper phd -a gb -c cookies.txt -o bookmarks.json
wscraper hf -a dtf -c cookies.txt -u "https://www.happyfappy.net/torrents.php?id=110178" -o torrent
wscraper phd -a rb -c cookies.txt -u "https://privatehd.to/torrent/12345" --remove-token "token"

q-buffer ile Entegrasyon

q-buffer içinde watcher tarafı artık şu şekilde çalışır:

1. UI'dan watcher tanımlanır
2. q-buffer backend cookie'yi şifreli saklar
3. Docker içindeki server, host'taki wscraper-servicee HTTP çağrısı yapar
4. wscraper-service, wscraper adapter'ı ile bookmarkları çeker
5. yeni bookmark için torrent dosyasını indirir
6. q-buffer backend .torrent içeriğini alır ve qBittorrent'e yollar
7. başarılı import sonrası bookmark tracker tarafında kaldırılır

Bu yüzden wscraper tek başına bir CLI olmanın ötesinde artık q-buffer watcher entegrasyonunun backend scraping motorudur.

wscraper-service API

bin/wscraper-service/server.py şu endpoint'leri sunar:

• GET /health
• GET /trackers
• POST /bookmarks
• POST /download
• POST /remove-bookmark

Örnek POST /bookmarks payload:

{
  "tracker": "happyfappy",
  "cookie": "raw-cookie",
  "wishlistUrl": "optional-override"
}

Örnek POST /download payload:

{
  "tracker": "privatehd",
  "cookie": "raw-cookie",
  "wishlistUrl": "optional-override",
  "item": {
    "pageURL": "https://privatehd.to/torrent/12345",
    "title": "Example",
    "downloadURL": "https://privatehd.to/download.php?id=12345",
    "removeToken": "bookmark-token"
  }
}

q-buffer İlk Kurulumunda wscraper Nasıl Hazırlanır?

Bu adım özellikle önemlidir. q-buffer reposunda scraping logic bin/wscraper/ içindedir. Host servis ise bin/wscraper-service/server.py dosyasıdır. Yani:

• bin/wscraper/ yalnızca server.py değildir
• server.py, ayrı wscraper-service klasöründedir
• asıl tracker kodları bin/wscraper/src/wscraper/... altındadır

İlk kurulum için önerilen yol:

1. repo root'ta .env.example dosyasını .env olarak kopyala
2. .env içinde watcher servis ayarlarını gözden geçir:
   • WSCRAPER_SERVICE_BASE_URL
   • WSCRAPER_SERVICE_TOKEN
   • WSCRAPER_SERVICE_HOST
   • WSCRAPER_SERVICE_PORT
   • WSCRAPER_SERVICE_PYTHON_BIN
3. repo root'ta şu komutu çalıştır:

./scripts/bootstrap.sh --dev-mode

Bu script:

• Docker web ve server servislerini up --build ile kaldırır
• host'ta .runtime/wscraper-service/.venv oluşturur
• scrapling[fetchers] kurar
• scrapling install çalıştırır
• bin/wscraper-service/server.py servis sürecini başlatır

Kurulum daha önce tamamsa script aynı işlemleri baştan yapmaz; sadece eksikleri tamamlar.

Testler

wscraper içinde canlı sistemlere karşı çalışan pytest tabanlı e2e testleri vardır. Bunlar varsayılan olarak kapalıdır; yalnızca açıkça etkinleştirildiğinde çalışırlar.

Test dosyaları:

• tests/e2e/test_happyfappy_live.py
• tests/e2e/test_privatehd_live.py
• tests/e2e/_helpers.py

Testleri Etkinleştirme

Tüm live testler için:

export WSCRAPER_E2E=1

Bu değişken yoksa veya 1 değilse, e2e testleri skip olur.

HappyFappy Live Testleri

Mevcut test kapsamı:

• get-bookmarks
• download-torrent-files

Kullanılan env değişkenleri:

• WSCRAPER_COOKIE_FILE
• WSCRAPER_TEST_TORRENT_URL

Örnek:

export WSCRAPER_E2E=1
export WSCRAPER_COOKIE_FILE=/absolute/path/to/happyfappy-cookies.txt
export WSCRAPER_TEST_TORRENT_URL="https://www.happyfappy.net/torrents.php?id=110178"
pytest tests/e2e/test_happyfappy_live.py -m e2e -s

PrivateHD Live Testleri

PrivateHD için eklenen test kapsamı:

• get-bookmarks
• download-torrent-files
• remove-bookmark

Kullanılan env değişkenleri:

• WSCRAPER_PRIVATEHD_COOKIE_FILE
• WSCRAPER_PRIVATEHD_WISHLIST_URL
• WSCRAPER_PRIVATEHD_TEST_TORRENT_URL
• WSCRAPER_PRIVATEHD_TEST_DOWNLOAD_URL
• WSCRAPER_PRIVATEHD_TEST_REMOVE_URL
• WSCRAPER_PRIVATEHD_TEST_REMOVE_TOKEN

Fallback kuralı:

• WSCRAPER_PRIVATEHD_COOKIE_FILE yoksa WSCRAPER_COOKIE_FILE kullanılır

Örnek:

export WSCRAPER_E2E=1
export WSCRAPER_PRIVATEHD_COOKIE_FILE=/absolute/path/to/privatehd-cookies.txt
export WSCRAPER_PRIVATEHD_WISHLIST_URL="https://privatehd.to/profile/blackdockers/wishlist"
export WSCRAPER_PRIVATEHD_TEST_TORRENT_URL="https://privatehd.to/torrent/12345-example"
export WSCRAPER_PRIVATEHD_TEST_DOWNLOAD_URL="https://privatehd.to/download/torrent/12345.example.torrent"
pytest tests/e2e/test_privatehd_live.py -m e2e -s

remove-bookmark Testi Hakkında

PrivateHD remove-bookmark testi gerçek wishlist kaydını sildiği için özellikle dikkatli kullanılmalıdır.

Bu test:

• yalnızca WSCRAPER_PRIVATEHD_TEST_REMOVE_URL ve WSCRAPER_PRIVATEHD_TEST_REMOVE_TOKEN verilirse çalışır
• aksi halde güvenli şekilde skip olur

Örnek:

export WSCRAPER_E2E=1
export WSCRAPER_PRIVATEHD_COOKIE_FILE=/absolute/path/to/privatehd-cookies.txt
export WSCRAPER_PRIVATEHD_WISHLIST_URL="https://privatehd.to/profile/blackdockers/wishlist"
export WSCRAPER_PRIVATEHD_TEST_REMOVE_URL="https://privatehd.to/torrent/12345-example"
export WSCRAPER_PRIVATEHD_TEST_REMOVE_TOKEN="467471"
pytest tests/e2e/test_privatehd_live.py -m e2e -s -k remove

Notlar

• Bu testler gerçek tracker hesaplarına ve geçerli cookie'lere ihtiyaç duyar
• remove-bookmark testi mutasyon yapar; test datası bilinçli seçilmelidir
• tests/e2e/_helpers.py, tüm tracker live testlerinde ortak CLI çalıştırma ve loglama yardımcılarını içerir

Dizin Yapısı

bin/
├── wscraper/
│   ├── README.md
│   ├── pyproject.toml
│   ├── setup.py
│   └── src/
│       └── wscraper/
│           ├── cli.py
│           ├── registry.py
│           ├── types.py
│           └── sites/
│               ├── happyfappy.py
│               └── privatehd.py
└── wscraper-service/
    └── server.py

Notlar

• Cookie hem raw string hem Netscape cookie file formatında verilebilir
• Tracker metadata alanları (backgroundImage, downloadURL, removeToken, size, seeders, leechers) adapter tarafından normalize edilir
• q-buffer tarafında image proxy, watcher item cache ve qBittorrent enrichment katmanları bu scraper çıktısını kullanır