Grabber

Utilities to extract media from supported sources and publish to Telegram/Telegraph.

Quick Start

Install dependencies:

uv sync --dev

Configure environment in .env (at minimum):

BOT_TOKEN
TELEGRAPH_TOKEN
SHORT_NAME
AUTHOR_NAME
AUTHOR_URL

Show supported entities:

uv run grabber -a

Run (CLI)

Example:

uv run grabber --publish --channel @your_channel --sources "https://example.com/post"

Send plain text to a channel:

uv run grabber --channel @your_channel --text "Some text"

Print unread Picazor album notification URLs:

uv run grabber --notifications picazor --number 10

Print profile URLs for the first unread Picazor album notifications scanned:

uv run grabber --notifications picazor --number 10 --profiles

Print Fapello feed image URLs:

uv run grabber --notifications fapello --number 10

Print unique Fapello profile URLs from the feed:

uv run grabber --notifications fapello --number 10 --profile

Search Fapello models:

uv run grabber --search fapello --query peachyxeena

Fapello notification/search modes and Picazor notification mode need these .env values from authenticated browser sessions:

FAPELLO_USER_ID=
FAPELLO_HASH=
PICAZOR_SESSION_TOKEN=
PICAZOR_CF_CLEARANCE=
PICAZOR_CSRF_TOKEN=
PICAZOR_LOCALE=en

Post text into a thread (discussion group):

uv run grabber --channel @your_channel --thread-id 123 --text "Some text in thread"

If --thread-id is omitted, grabber prints the resolved thread id so you can reuse it:

uv run grabber --channel @your_channel --text "Some text"

Output:

Text sent to @your_channel
Resolved thread id for reuse: --thread-id 123

Run Interactive Bot

uv run python -m grabber.core.bot.interactive_bot

Then use /post, select channel, and send source URLs.

Run Web UI

The web interface is served in two services:

web-api: FastAPI backend (session-protected endpoints)
web-ui: React dashboard

Setup

Add web environment variables:

WEB_UI_PASSWORD=your-strong-password
WEB_SESSION_SECRET=a-long-random-string
WEB_SESSION_TTL_SECONDS=86400

Start the stack:

docker compose up --build web-api web-ui

Open http://<your-vps-ip>:8888 (or map another public port in docker-compose.yml).
Log in with WEB_UI_PASSWORD. After login:

Enter one or more URLs and target channel
Optionally enable tag mode/video mode
Send plain text by checking Post text only
Optionally provide a thread id (--thread-id) for text replies/comments

Notes:

The channel list is pulled from the existing bot CHANNELS mapping (src/grabber/core/settings.py).
Entity list comes from QUERY_MAPPING.
API routes are exposed under /api/* and proxied by the UI.

Pornhub Video-to-Channel

Single-video Pornhub URLs are supported for direct Telegram delivery.

Requirements

A target channel is mandatory (--channel in CLI or bot channel picker).
yt_dlp must be available in the runtime environment.
PORNHUB_COOKIES_FILE_PATH must point to a valid Netscape-format cookies file.

Add to .env:

PORNHUB_COOKIES_FILE_PATH=/absolute/path/to/pornhub_cookies.txt

Supported Pornhub hosts

pornhub.com
www.pornhub.com
m.pornhub.com

CLI example

uv run grabber \
  --publish \
  --channel -1003835153909 \
  --sources "https://www.pornhub.com/view_video.php?viewkey=ph5abc123"

Note: CLI --channel must be a Telegram username/ID (for example @channel_name or -100...), not the interactive bot display label.

Delivery behavior

Chooses the best format expected to fit Telegram Bot API upload limits (<= 50MB).
If the selected media is oversized, it sends a link message fallback to the channel.
If --channel is missing, Pornhub execution fails fast with an explicit error.
If PORNHUB_COOKIES_FILE_PATH is missing/invalid, execution fails fast.
Checkpoint dedupe is applied, and successful sends are committed.

Troubleshooting

PORNHUB_COOKIES_FILE_PATH is required...
- Set PORNHUB_COOKIES_FILE_PATH in .env.
...does not exist or is not a file
- Fix the path and permissions for the cookies file.
yt_dlp is required to process Pornhub sources
- Install dependencies in the same runtime where grabber executes.
ERROR: [PornHub] ... Unable to extract title
- The adapter now auto-falls back to HTML media parsing when yt_dlp metadata extraction fails.
- If it still fails, refresh/export cookies again and update yt-dlp in your runtime.
Oversized media warnings
- Expected behavior; the source falls back to link delivery.

Metadata

Release files for grabberlib2 0.39.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for grabberlib2 0.39.1
File	Size	Uploaded
grabberlib2-0.39.1.tar.gz	189.0 kB	Sep 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for grabberlib2 0.39.1
File	Interpreter	ABI	Platform	Reset
grabberlib2-0.39.1-py3-none-any.whl 382.7 kB Sep 15, 2026	Python 3	none	any	Details

Total release size: 571.8 kB

Release files / grabberlib2-0.39.1.tar.gz

Download URL	grabberlib2-0.39.1.tar.gz
Size	189.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`1c8d846465948d945d84e4ed63a3d0e218d933beb926e1297ffdcfb7237cd745`
BLAKE2b-256 checksum How to use checksums	`bc2b23c9f50bbc8c602b59fb00790b48fdbd06c766ad556e35350c8ea20e9c00`
Upload date	Sep 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / grabberlib2-0.39.1-py3-none-any.whl

Download URL	grabberlib2-0.39.1-py3-none-any.whl
Size	382.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`301c572785247cbc7517bfd4d8ce45c37df04aa026c502afa83eefde24a273f8`
BLAKE2b-256 checksum How to use checksums	`f025f5b751a083e82e0c148e6a2ade605b604b389fc428e7d3cba34a3a6d7a12`
Upload date	Sep 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`