docs: privatehd ve q-buffer entegrasyonunu belge
This commit is contained in:
271
README.md
271
README.md
@@ -1,131 +1,254 @@
|
|||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="logo-v2.png" alt="wscraper logo" width="240" height=/>
|
<img src="logo-v2.png" alt="wscraper logo" width="240" />
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<a href="https://gitea.wisecolt-panda.net/wisecolt/Bookmark-Tracker">
|
<a href="https://gitea.wisecolt-panda.net/wisecolt/Bookmark-Tracker">
|
||||||
<img src="https://img.shields.io/badge/Gitea-Repository-609926?logo=gitea&logoColor=white" alt="Gitea">
|
<img src="https://img.shields.io/badge/Gitea-Repository-609926?logo=gitea&logoColor=white" alt="Gitea">
|
||||||
</a>
|
</a>
|
||||||
<img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python">
|
<img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python">
|
||||||
<img src="https://img.shields.io/badge/E2E_Tests-enabled-22c55e?logo=pytest&logoColor=white" alt="E2E Tests">
|
<img src="https://img.shields.io/badge/Trackers-HappyFappy%20%7C%20PrivateHD-0A7B83" alt="Trackers">
|
||||||
<img src="https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-1f6feb" alt="Platform">
|
<img src="https://img.shields.io/badge/Runtime-scrapling%20%2B%20Playwright-1f6feb" alt="Runtime">
|
||||||
<img src="https://img.shields.io/badge/Layout-src%2F%20package-0A7B83" alt="Layout">
|
|
||||||
</p>
|
</p>
|
||||||
HappyFappy için komutlar paketlenmiş `wscraper` CLI üzerinden çalışır. Proje çoklu site desteği için `src/` paket yapısına göre düzenlenmiştir.
|
|
||||||
|
|
||||||
## 1) Repo Clone
|
# wscraper
|
||||||
|
|
||||||
```bash
|
`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:
|
||||||
git clone <REPO_URL>
|
|
||||||
cd <REPO_FOLDER>
|
|
||||||
```
|
|
||||||
|
|
||||||
## 2) Kurulum
|
- `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
|
### macOS / Linux
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python3 -m venv .venv
|
cd bin/wscraper
|
||||||
|
python3.12 -m venv .venv
|
||||||
source .venv/bin/activate
|
source .venv/bin/activate
|
||||||
python -m pip install -U pip
|
python -m pip install -U pip
|
||||||
python -m pip install -e .
|
python -m pip install -e .
|
||||||
scrapling install
|
scrapling install
|
||||||
```
|
```
|
||||||
|
|
||||||
### Windows (PowerShell)
|
Alternatif:
|
||||||
|
|
||||||
|
- `python3.12` yoksa `python3.11` veya `python3.10` kullan
|
||||||
|
- `scrapling install`, Playwright/browser bağımlılıklarını kurar
|
||||||
|
|
||||||
|
### Windows PowerShell
|
||||||
|
|
||||||
```powershell
|
```powershell
|
||||||
py -3.11 -m venv .venv
|
cd bin/wscraper
|
||||||
|
py -3.12 -m venv .venv
|
||||||
.venv\Scripts\Activate.ps1
|
.venv\Scripts\Activate.ps1
|
||||||
python -m pip install -U pip
|
python -m pip install -U pip
|
||||||
python -m pip install -e .
|
python -m pip install -e .
|
||||||
scrapling install
|
scrapling install
|
||||||
```
|
```
|
||||||
|
|
||||||
### Windows (CMD)
|
## CLI Kullanımı
|
||||||
|
|
||||||
```bat
|
Genel form:
|
||||||
py -3.11 -m venv .venv
|
|
||||||
.venv\Scripts\activate.bat
|
```bash
|
||||||
python -m pip install -U pip
|
wscraper <tracker> --action <action> [opsiyonlar]
|
||||||
python -m pip install -e .
|
|
||||||
scrapling install
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Not: Ortamı aktive ettikten sonra komutlar `wscraper ...` olarak kullanılabilir. İstersen `python -m wscraper ...` da kullanabilirsin.
|
### Bookmark / Wishlist Çekme
|
||||||
|
|
||||||
## 3) HappyFappy Komutları
|
|
||||||
|
|
||||||
### Bookmarks Çekme
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
wscraper happyfappy --action get-bookmarks -c cookies.txt -o bookmarks.json
|
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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
wscraper privatehd --action get-bookmarks -c cookies.txt --wishlist-url "https://privatehd.to/bookmarks" -o bookmarks.json
|
||||||
```
|
```
|
||||||
|
|
||||||
### Torrent Dosyası İndirme
|
### Torrent Dosyası İndirme
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
wscraper happyfappy --action download-torrent-files -u "https://www.happyfappy.net/torrents.php?id=110178" -c cookies.txt -o torrent
|
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
|
||||||
```
|
```
|
||||||
|
|
||||||
### Torrent İndir + Bookmark Kaldır
|
|
||||||
|
|
||||||
`--rm-bookmark` (kisa alias: `-rmb`) flag'i verildiginde, torrent dosyasi basariyla indirildikten sonra ayni torrent detay sayfasindaki bookmark remove mekanizmasi dinamik olarak bulunur ve tetiklenir.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
wscraper happyfappy --action download-torrent-files --rm-bookmark -u "https://www.happyfappy.net/torrents.php?id=110178" -c cookies.txt -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
|
||||||
```
|
```
|
||||||
|
|
||||||
Davranis kurallari:
|
### Bookmark Silme
|
||||||
|
|
||||||
- Torrent indirme basarisizsa bookmark silme adimina gecilmez.
|
```bash
|
||||||
- `--rm-bookmark` verilmis ve bookmark silme basarisizsa komut `exit code 1` ile biter.
|
wscraper happyfappy --action remove-bookmark \
|
||||||
- `--rm-bookmark` verilmemisse yalnizca indirme akisi calisir.
|
-c cookies.txt \
|
||||||
|
-u "https://www.happyfappy.net/torrents.php?id=110178" \
|
||||||
Bookmark remove tespiti tek bir sabit HTML selector'ine bagli degildir:
|
--title "Sample"
|
||||||
|
```
|
||||||
- oncelik `onclick`/event sinyalleri (or. `Unbookmark(...)`)
|
|
||||||
- `id/class/href` icinde bookmark semantigi
|
```bash
|
||||||
- remove/delete/unbookmark benzeri metin ve attribute sinyalleri
|
wscraper privatehd --action remove-bookmark \
|
||||||
- torrent id ile iliskili kontrol eslestirmesi
|
-c cookies.txt \
|
||||||
|
-u "https://privatehd.to/torrent/12345" \
|
||||||
## 4) Kısa Alias Kullanımı
|
--remove-token "bookmark-delete-token" \
|
||||||
|
--title "Sample"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Kısa Alias'lar
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# site alias: hf
|
|
||||||
# action alias: gb (get-bookmarks), dtf (download-torrent-files)
|
|
||||||
wscraper hf -a gb -c cookies.txt -o bookmarks.json
|
wscraper hf -a gb -c cookies.txt -o bookmarks.json
|
||||||
wscraper hf -a dtf -u "https://www.happyfappy.net/torrents.php?id=110178" -c cookies.txt -o torrent
|
wscraper phd -a gb -c cookies.txt -o bookmarks.json
|
||||||
wscraper hf -a dtf --rm-bookmark -u "https://www.happyfappy.net/torrents.php?id=110178" -c cookies.txt -o torrent
|
wscraper hf -a dtf -c cookies.txt -u "https://www.happyfappy.net/torrents.php?id=110178" -o torrent
|
||||||
wscraper hf -a dtf -rmb -u "https://www.happyfappy.net/torrents.php?id=110178" -c cookies.txt -o torrent
|
wscraper phd -a rb -c cookies.txt -u "https://privatehd.to/torrent/12345" --remove-token "token"
|
||||||
```
|
```
|
||||||
|
|
||||||
## 5) Proje Dizini
|
## 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-service`e 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:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"tracker": "happyfappy",
|
||||||
|
"cookie": "raw-cookie",
|
||||||
|
"wishlistUrl": "optional-override"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Örnek `POST /download` payload:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./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.
|
||||||
|
|
||||||
|
## Dizin Yapısı
|
||||||
|
|
||||||
```text
|
```text
|
||||||
.
|
bin/
|
||||||
├── pyproject.toml
|
├── wscraper/
|
||||||
├── requirements.txt
|
│ ├── README.md
|
||||||
├── src/
|
│ ├── pyproject.toml
|
||||||
|
│ ├── setup.py
|
||||||
|
│ └── src/
|
||||||
│ └── wscraper/
|
│ └── wscraper/
|
||||||
│ ├── __init__.py
|
|
||||||
│ ├── __main__.py
|
|
||||||
│ ├── cli.py
|
│ ├── cli.py
|
||||||
|
│ ├── registry.py
|
||||||
|
│ ├── types.py
|
||||||
│ └── sites/
|
│ └── sites/
|
||||||
│ ├── __init__.py
|
│ ├── happyfappy.py
|
||||||
│ └── happyfappy.py
|
│ └── privatehd.py
|
||||||
└── README.md
|
└── wscraper-service/
|
||||||
|
└── server.py
|
||||||
```
|
```
|
||||||
|
|
||||||
## 6) E2E Test (Canli)
|
## Notlar
|
||||||
|
|
||||||
Bu testler gercek siteye istek atar ve link/selector kirilmalarini yakalamayi hedefler.
|
- 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
|
||||||
```bash
|
- `q-buffer` tarafında image proxy, watcher item cache ve qBittorrent enrichment katmanları bu scraper çıktısını kullanır
|
||||||
python -m pip install -e ".[test]"
|
|
||||||
WSCRAPER_E2E=1 pytest -m e2e -s -vv --color=yes
|
|
||||||
```
|
|
||||||
|
|
||||||
Opsiyonel degiskenler:
|
|
||||||
|
|
||||||
- `WSCRAPER_COOKIE_FILE` (varsayilan: `cookies.txt`)
|
|
||||||
- `WSCRAPER_TEST_TORRENT_URL` (varsayilan: `https://www.happyfappy.net/torrents.php?id=110178`)
|
|
||||||
|
|||||||
Reference in New Issue
Block a user