pingrabber 0.1.7__py3-none-any.whl

pingrabber/__init__.py

@@ -0,0 +1,24 @@
+"""
+pingrabber
+==========
+
+Thư viện đơn giản giúp cào (scrape) ảnh chất lượng cao từ một board
+Pinterest công khai thông qua RSS feed của Pinterest.
+
+Cách dùng nhanh:
+
+    import pingrabber
+
+    # Tải ảnh từ board hoặc pin đơn lẻ (tự nhận diện loại URL)
+    pingrabber.download("https://www.pinterest.com/username/boardname/")
+
+    # Tìm theo từ khóa, lấy link ảnh raw (không tải file về máy)
+    links = pingrabber.search("thiên nhiên")
+
+"""
+
+from .core import PinGrabber, download, search
+
+__all__ = ["PinGrabber", "download", "search"]
+
+__version__ = "0.1.7"

pingrabber/core.py

@@ -0,0 +1,749 @@
+"""
+pingrabber.core
+~~~~~~~~~~~~~~~~
+
+Logic chính: tải ảnh chất lượng cao từ Pinterest, hỗ trợ 2 dạng URL:
+
+    1. URL BOARD (pinterest.com/<user>/<board>/):
+       Lấy RSS feed của board, phân tích bằng BeautifulSoup để tìm các
+       liên kết ảnh, sau đó tải ảnh gốc (chất lượng cao nhất) về máy.
+
+    2. URL PIN ĐƠN LẺ (pinterest.com/pin/<id>/):
+       Pin lẻ không có RSS feed riêng, nên thư viện sẽ fetch trực tiếp
+       trang HTML của pin và lấy ảnh từ thẻ <meta property="og:image">.
+
+Hàm `download()` / `PinGrabber.download()` tự động nhận diện loại URL
+và xử lý phù hợp, người dùng không cần phân biệt thủ công.
+
+Ghi chú kỹ thuật:
+    Pinterest cung cấp RSS feed công khai cho mỗi board theo dạng:
+        https://www.pinterest.com/<user>/<board>.rss
+
+    Mỗi <item> trong feed chứa một đoạn HTML (trong <description>) có thẻ
+    <img src="..."> trỏ tới ảnh thumbnail. URL ảnh thumbnail thường có dạng:
+        https://i.pinimg.com/236x/xx/xx/xx/xxxxxxx.jpg
+
+    Để lấy ảnh gốc (kích thước lớn nhất), ta thay thế phần kích thước
+    (ví dụ "236x") bằng "originals".
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+import random
+import logging
+from typing import List, Optional
+from urllib.parse import urlparse
+
+import requests
+from bs4 import BeautifulSoup
+
+# `ddgs` (trước đây là `duckduckgo-search`) là dependency TÙY CHỌN, chỉ dùng
+# cho tính năng search() theo từ khóa. Nếu chưa cài, search() sẽ tự động
+# rơi về phương án dự phòng dùng requests + BeautifulSoup thuần.
+try:
+    from ddgs import DDGS  # package mới, khuyến nghị
+    _HAS_DDGS = True
+except ImportError:
+    try:
+        from duckduckgo_search import DDGS  # tên package cũ, vẫn còn trên PyPI
+        _HAS_DDGS = True
+    except ImportError:
+        DDGS = None
+        _HAS_DDGS = False
+
+logger = logging.getLogger("pingrabber")
+logging.basicConfig(level=logging.INFO, format="[%(levelname)s] %(message)s")
+
+# Danh sách User-Agent thật để xoay vòng, giảm khả năng bị nhận diện là bot
+# khi gọi đến công cụ tìm kiếm (search engine thường nhạy với UA hơn Pinterest).
+USER_AGENTS = [
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 "
+    "(KHTML, like Gecko) Version/17.4 Safari/605.1.15",
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:125.0) "
+    "Gecko/20100101 Firefox/125.0",
+    "Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) "
+    "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Mobile/15E148 Safari/604.1",
+]
+
+# User-Agent mặc định dùng cho các request tải ảnh/RSS (ổn định, không cần xoay)
+DEFAULT_HEADERS = {
+    "User-Agent": USER_AGENTS[0],
+}
+
+
+def _random_search_headers() -> dict:
+    """Tạo header ngẫu nhiên (User-Agent + Accept-Language) cho mỗi lần search,
+    giúp giảm khả năng bị nhận diện và chặn theo pattern cố định."""
+    return {
+        "User-Agent": random.choice(USER_AGENTS),
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": random.choice(["en-US,en;q=0.9", "vi-VN,vi;q=0.9,en;q=0.8"]),
+    }
+
+# Regex để tìm URL ảnh i.pinimg.com bên trong đoạn HTML mô tả của RSS item
+IMG_URL_PATTERN = re.compile(
+    r"https?://i\.pinimg\.com/[^\s\"'<>]+\.(?:jpg|jpeg|png|gif|webp)",
+    re.IGNORECASE,
+)
+
+# Các kích thước thumbnail phổ biến mà Pinterest dùng trong URL ảnh,
+# cần thay bằng "originals" để lấy ảnh gốc chất lượng cao nhất.
+THUMBNAIL_SIZE_PATTERN = re.compile(
+    r"/(\d+x(?:\d+)?|originals)/", re.IGNORECASE
+)
+
+# Nhận diện URL pin đơn lẻ, ví dụ: pinterest.com/pin/119134352618387326/
+SINGLE_PIN_PATTERN = re.compile(r"^/pin/(\d+)", re.IGNORECASE)
+
+# Danh sách công cụ tìm kiếm để thử lần lượt (fallback) khi một engine bị
+# chặn hoặc trả lỗi. Mỗi engine có format URL kết quả khác nhau nên cần
+# parser riêng (xem hàm _parse_search_results).
+SEARCH_ENGINES = [
+    {
+        "name": "duckduckgo_html",
+        "url": "https://html.duckduckgo.com/html/",
+        "param": "q",
+    },
+    {
+        "name": "duckduckgo_lite",
+        "url": "https://lite.duckduckgo.com/lite/",
+        "param": "q",
+    },
+    {
+        "name": "bing",
+        "url": "https://www.bing.com/search",
+        "param": "q",
+    },    
+    {
+        "name": "brave",
+        "url": "https://search.brave.com/search",
+        "param": "q",
+    },
+    {
+        "name": "yandex_lite",
+        "url": "https://yandex.com", # Bản Lite của Yandex Nga, HTML siêu nhẹ, ít check bot
+        "param": "text",
+    },
+    {
+        "name": "yahoo",
+        "url": "https://yahoo.com", # HTML lỏng lẻo giống Bing, quét rất mượt
+        "param": "p",
+    },
+    {
+        "name": "ecosia",
+        "url": "https://ecosia.org", # Sử dụng lõi Bing nhưng hệ thống lọc bot lỏng hơn
+        "param": "q",
+    },
+    {
+        "name": "qwant_lite",
+        "url": "https://qwant.com", # Phiên bản không JavaScript của công cụ tìm kiếm Pháp
+        "param": "q",
+    },
+    {
+        "name": "mojeek",
+        "url": "https://mojeek.com", # Bộ máy độc lập hoàn toàn, không có hệ thống chống bot gắt gao
+        "param": "q",
+    },
+    {
+        "name": "gibiru",
+        "url": "https://gibiru.com", # Trang tìm kiếm ẩn danh, cấu trúc HTML thô sơ
+        "param": "q",
+    },
+    {
+        "name": "ask",
+        "url": "https://ask.com", # Trang tìm kiếm lâu đời, máy chủ lọc bot rất yếu
+        "param": "q",
+    },
+    {
+        "name": "seznam",
+        "url": "https://seznam.cz", # Công cụ tìm kiếm nội địa của Séc, bot cào thoải mái
+        "param": "q",
+    }
+]
+
+
+# Regex nhận diện URL board hợp lệ trong kết quả tìm kiếm:
+# pinterest.com/<user>/<board>/ nhưng KHÔNG phải /pin/..., /search/..., /explore/...
+BOARD_URL_PATTERN = re.compile(
+    r"^https?://(?:[a-z]{2,3}\.)?pinterest\.[a-z.]+/"
+    r"(?!pin/|search/|explore/|today/)([\w.\-%]+)/([\w.\-%]+)/?$",
+    re.IGNORECASE,
+)
+
+
+class PinGrabberError(Exception):
+    """Lỗi tùy biến cho thư viện pingrabber."""
+
+
+class PinGrabber:
+    """Đối tượng chính để cào và tải ảnh từ một board Pinterest."""
+
+    def __init__(self, timeout: int = 15, session: Optional[requests.Session] = None):
+        self.timeout = timeout
+        self.session = session or requests.Session()
+        self.session.headers.update(DEFAULT_HEADERS)
+
+    # ------------------------------------------------------------------ #
+    # Tiện ích: kiểm tra URL là pin đơn lẻ hay board
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def is_single_pin_url(url: str) -> bool:
+        """Trả về True nếu URL có dạng pinterest.com/pin/<id>/ (pin đơn lẻ)."""
+        parsed = urlparse(url)
+        return bool(SINGLE_PIN_PATTERN.match(parsed.path))
+
+    # ------------------------------------------------------------------ #
+    # TÌM KIẾM THEO TỪ KHÓA
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _extract_bing_real_url(href: str) -> Optional[str]:
+        """Bing thường bọc link thật trong link redirect dạng base64
+        (tham số 'u', tiền tố 'a1' + base64 của URL thật). Hàm này giải mã
+        ra URL thật nếu có, ngược lại trả về href gốc không đổi."""
+        import base64
+        from urllib.parse import urlparse as _urlparse, parse_qs
+
+        parsed = _urlparse(href)
+        qs = parse_qs(parsed.query)
+        if "u" in qs:
+            raw = qs["u"][0]
+            if raw.startswith("a1"):
+                raw = raw[2:]
+            # Bing dùng base64 URL-safe, có thể thiếu padding '='
+            padding = "=" * (-len(raw) % 4)
+            try:
+                decoded = base64.urlsafe_b64decode(raw + padding).decode("utf-8", errors="ignore")
+                return decoded
+            except (ValueError, UnicodeDecodeError):
+                return href
+        return href
+
+    def _parse_search_results(self, engine_name: str, html: str) -> List[str]:
+        """Phân tích HTML kết quả tìm kiếm để lấy danh sách URL board hợp lệ.
+        Mỗi engine có cấu trúc HTML khác nhau nên xử lý link hơi khác nhau."""
+        soup = BeautifulSoup(html, "html.parser")
+        board_urls: List[str] = []
+
+        for link in soup.find_all("a", href=True):
+            href = link["href"]
+
+            if engine_name == "bing":
+                href = self._extract_bing_real_url(href) or href
+
+            match = BOARD_URL_PATTERN.match(href)
+            if match:
+                normalized = href.split("?")[0].rstrip("/") + "/"
+                if normalized not in board_urls:
+                    board_urls.append(normalized)
+
+        return board_urls
+
+    def _find_boards_via_ddgs(self, keyword: str, max_results: int = 5) -> List[str]:
+        """
+        Tìm board bằng package `ddgs` (trước đây là `duckduckgo-search`).
+
+        Ưu điểm so với cách tự gọi requests:
+            - Package được cộng đồng duy trì, tự xử lý header/cookie giống
+              trình duyệt thật hơn, tỷ lệ bị chặn thấp hơn.
+            - Hỗ trợ proxy (http/https/socks5) ngay trong constructor, đây
+              là cách hiệu quả nhất để né chặn theo IP nếu bạn có proxy.
+            - Tự động thử nhiều backend bên trong (DuckDuckGo, Bing, Google...).
+
+        Trả về [] nếu ddgs chưa được cài, hoặc nếu gọi thất bại (lỗi sẽ
+        được log lại, không raise, để find_boards() có thể rơi về fallback).
+        """
+        if not _HAS_DDGS:
+            return []
+
+        query = f"site:pinterest.com {keyword}"
+        try:
+            ddgs = DDGS(timeout=self.timeout)
+            try:
+                raw_results = ddgs.text(query, max_results=max_results * 3)
+            finally:
+                # Một số phiên bản DDGS hỗ trợ context manager / .close(),
+                # đóng lại nếu có để giải phóng kết nối HTTP.
+                close_fn = getattr(ddgs, "close", None)
+                if callable(close_fn):
+                    close_fn()
+        except Exception as exc:  # noqa: BLE001 - ddgs có thể raise nhiều loại lỗi riêng
+            logger.warning("  [ddgs] Gọi thất bại: %s", exc)
+            return []
+
+        board_urls: List[str] = []
+        for item in raw_results or []:
+            # Tùy phiên bản, key có thể là "href" hoặc "url"
+            href = item.get("href") or item.get("url") or ""
+            if not href:
+                continue
+            match = BOARD_URL_PATTERN.match(href)
+            if match:
+                normalized = href.split("?")[0].rstrip("/") + "/"
+                if normalized not in board_urls:
+                    board_urls.append(normalized)
+
+        return board_urls[:max_results]
+
+    def _find_boards_via_requests(
+        self,
+        keyword: str,
+        max_results: int = 5,
+        max_retries: int = 2,
+        delay_seconds: float = 1.5,
+    ) -> List[str]:
+        """
+        Phương án DỰ PHÒNG: tự gọi requests đến nhiều search engine, dùng khi
+        package `ddgs` chưa được cài hoặc gọi thất bại. Có xoay User-Agent,
+        retry, và fallback giữa nhiều engine (DuckDuckGo HTML/Lite, Bing).
+        """
+        query = f"site:pinterest.com {keyword}"
+        last_error: Optional[Exception] = None
+
+        for engine in SEARCH_ENGINES:
+            for attempt in range(1, max_retries + 1):
+                try:
+                    headers = _random_search_headers()
+                    resp = self.session.get(
+                        engine["url"],
+                        params={engine["param"]: query},
+                        headers=headers,
+                        timeout=self.timeout,
+                    )
+
+                    if resp.status_code in (403, 429):
+                        logger.warning(
+                            "  [%s] Bị chặn (HTTP %d), thử lại lần %d/%d...",
+                            engine["name"], resp.status_code, attempt, max_retries,
+                        )
+                        time.sleep(delay_seconds + random.uniform(0, 1.5))
+                        continue
+
+                    resp.raise_for_status()
+
+                    board_urls = self._parse_search_results(engine["name"], resp.text)
+                    if board_urls:
+                        logger.info(
+                            "  [%s] Tìm thấy %d board.", engine["name"], len(board_urls)
+                        )
+                        return board_urls[:max_results]
+
+                    logger.info("  [%s] Không có kết quả phù hợp, thử engine khác.", engine["name"])
+                    break  # Engine trả về OK nhưng không có board -> chuyển engine khác
+
+                except requests.RequestException as exc:
+                    last_error = exc
+                    logger.warning(
+                        "  [%s] Lỗi request (lần %d/%d): %s",
+                        engine["name"], attempt, max_retries, exc,
+                    )
+                    time.sleep(delay_seconds + random.uniform(0, 1.5))
+
+            # Nghỉ một chút trước khi chuyển sang engine kế tiếp
+            time.sleep(delay_seconds)
+
+        if last_error:
+            logger.error(
+                "Tất cả công cụ tìm kiếm đều thất bại. Lỗi cuối: %s. "
+                "Mạng của bạn có thể đang bị chặn truy cập search engine — "
+                "hãy thử lại sau, đổi mạng/VPN, hoặc tự tìm board qua trình "
+                "duyệt rồi dùng download(url_board) trực tiếp.",
+                last_error,
+            )
+        return []
+
+    def find_boards(
+        self,
+        keyword: str,
+        max_results: int = 5,
+        max_retries: int = 2,
+        delay_seconds: float = 1.5,
+    ) -> List[str]:
+        """
+        Tìm các URL board Pinterest liên quan đến từ khóa.
+
+        Thứ tự ưu tiên:
+            1. Dùng package `ddgs` (khuyến nghị) nếu đã cài — package này
+               được cộng đồng duy trì, tự xử lý giả lập trình duyệt tốt
+               hơn và hỗ trợ proxy, nên tỷ lệ bị chặn thấp hơn nhiều.
+            2. Nếu chưa cài `ddgs` hoặc gọi thất bại, tự động rơi về
+               phương án dự phòng: gọi requests trực tiếp đến nhiều search
+               engine (DuckDuckGo HTML/Lite, Bing), có xoay User-Agent,
+               retry và delay giữa các lần thử.
+
+        Để dùng phương án 1 (khuyến nghị), cài thêm:
+            pip install ddgs
+
+        Lưu ý: đây KHÔNG phải tìm kiếm trực tiếp trong Pinterest (trang đó
+        cần JS render nên requests không đọc được), mà là dùng index của
+        công cụ tìm kiếm để tìm ra các board công khai liên quan. Kết quả
+        có thể rỗng tùy theo IP/mạng của bạn — nếu vậy, hãy tự tìm board
+        qua trình duyệt và dùng download(url_board) trực tiếp.
+
+        Trả về danh sách URL board (đã loại trùng), tối đa max_results.
+        """
+        if _HAS_DDGS:
+            logger.info("Đang tìm board qua package ddgs...")
+            board_urls = self._find_boards_via_ddgs(keyword, max_results=max_results)
+            if board_urls:
+                logger.info("  [ddgs] Tìm thấy %d board.", len(board_urls))
+                return board_urls
+            logger.info("  [ddgs] Không có kết quả, chuyển sang phương án dự phòng (requests).")
+        else:
+            logger.info(
+                "Package 'ddgs' chưa được cài (pip install ddgs) — "
+                "dùng phương án dự phòng qua requests."
+            )
+
+        return self._find_boards_via_requests(
+            keyword,
+            max_results=max_results,
+            max_retries=max_retries,
+            delay_seconds=delay_seconds,
+        )
+
+    def search(
+        self,
+        keyword: str,
+        max_boards: int = 3,
+        max_images_per_board: int = 25,
+        max_retries: int = 2,
+        delay_seconds: float = 1.5,
+    ) -> List[str]:
+        """
+        Tìm board liên quan đến từ khóa, rồi tự động lấy danh sách URL ảnh
+        gốc (chất lượng cao) từ các board đó. KHÔNG tải ảnh về máy, chỉ
+        trả về danh sách link raw để bạn tự quyết định dùng tiếp.
+
+        Ví dụ:
+            import pingrabber
+            links = pingrabber.search("thiên nhiên")
+            print(links)  # ['https://i.pinimg.com/originals/.../a.jpg', ...]
+
+        Args:
+            keyword: từ khóa tìm kiếm, ví dụ "thiên nhiên", "nature".
+            max_boards: số board tối đa sẽ quét qua.
+            max_images_per_board: số ảnh tối đa lấy từ mỗi board.
+            max_retries: số lần thử lại mỗi search engine nếu bị chặn/lỗi.
+            delay_seconds: thời gian nghỉ cơ bản (giây) giữa các lần thử,
+                giúp giảm khả năng bị search engine chặn vì gọi quá nhanh.
+
+        Trả về danh sách URL ảnh gốc (string), rỗng nếu không tìm được gì.
+        Nếu trả về rỗng, kiểm tra log WARNING/ERROR để biết nguyên nhân cụ
+        thể (bị chặn, hết engine, hay không có board liên quan).
+        """
+        logger.info("Đang tìm board liên quan đến từ khóa: %s", keyword)
+        board_urls = self.find_boards(
+            keyword,
+            max_results=max_boards,
+            max_retries=max_retries,
+            delay_seconds=delay_seconds,
+        )
+
+        if not board_urls:
+            logger.warning(
+                "Không tìm thấy board nào liên quan đến: %s. "
+                "Nếu log phía trên cho thấy lỗi 403/429 ở tất cả engine, "
+                "khả năng cao mạng/IP của bạn đang bị search engine chặn.",
+                keyword,
+            )
+            return []
+
+        logger.info("Tìm thấy %d board, đang lấy ảnh...", len(board_urls))
+
+        all_image_urls: List[str] = []
+        for board_url in board_urls:
+            try:
+                rss_url = self.build_rss_url(board_url)
+                rss_content = self.fetch_rss(rss_url)
+                image_urls = self.extract_image_urls(rss_content)[:max_images_per_board]
+                logger.info("  + %s -> %d ảnh", board_url, len(image_urls))
+                for url in image_urls:
+                    if url not in all_image_urls:
+                        all_image_urls.append(url)
+                # Delay nhẹ giữa các board để tránh gửi request quá dồn dập
+                time.sleep(delay_seconds * 0.5)
+            except PinGrabberError as exc:
+                logger.error("  Lỗi khi xử lý board %s: %s", board_url, exc)
+
+        logger.info("Hoàn tất. Tổng cộng %d link ảnh raw.", len(all_image_urls))
+        return all_image_urls
+
+    # ------------------------------------------------------------------ #
+    # Bước 1: Chuyển URL board thường -> URL RSS feed
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def build_rss_url(board_url: str) -> str:
+        """
+        Chuyển một URL board Pinterest thông thường thành URL RSS feed.
+
+        Ví dụ:
+            https://www.pinterest.com/username/boardname/
+            -> https://www.pinterest.com/username/boardname.rss
+        """
+        parsed = urlparse(board_url)
+        if "pinterest." not in parsed.netloc:
+            raise PinGrabberError(f"URL không hợp lệ, không phải Pinterest: {board_url}")
+
+        path = parsed.path.strip("/")
+        if not path:
+            raise PinGrabberError(f"Không tìm thấy đường dẫn board trong URL: {board_url}")
+
+        if path.endswith(".rss"):
+            rss_path = path
+        else:
+            rss_path = f"{path}.rss"
+
+        return f"https://{parsed.netloc}/{rss_path}"
+
+    # ------------------------------------------------------------------ #
+    # Bước 2: Lấy nội dung RSS feed
+    # ------------------------------------------------------------------ #
+    def fetch_rss(self, rss_url: str) -> str:
+        """Gửi request lấy nội dung RSS feed (dạng XML/text)."""
+        try:
+            resp = self.session.get(rss_url, timeout=self.timeout)
+            resp.raise_for_status()
+        except requests.RequestException as exc:
+            raise PinGrabberError(f"Không thể tải RSS feed: {rss_url} ({exc})") from exc
+        return resp.text
+
+    # ------------------------------------------------------------------ #
+    # Bước 3: Parse RSS bằng BeautifulSoup -> lấy danh sách URL ảnh gốc
+    # ------------------------------------------------------------------ #
+    def extract_image_urls(self, rss_content: str) -> List[str]:
+        """
+        Dùng BeautifulSoup để parse XML của RSS feed, lấy tất cả thẻ <img>
+        nằm trong mỗi <item><description>, rồi nâng cấp URL thumbnail
+        thành URL ảnh gốc ("originals").
+        """
+        soup = BeautifulSoup(rss_content, "lxml-xml")
+        items = soup.find_all("item")
+
+        if not items:
+            # Một số feed có thể không parse đúng theo "lxml-xml" (hiếm),
+            # thử lại bằng parser HTML mặc định như phương án dự phòng.
+            soup = BeautifulSoup(rss_content, "html.parser")
+            items = soup.find_all("item")
+
+        image_urls: List[str] = []
+
+        for item in items:
+            description = item.find("description")
+            if not description or not description.text:
+                continue
+
+            # description chứa HTML dạng escape, parse tiếp lần 2
+            desc_soup = BeautifulSoup(description.text, "html.parser")
+            img_tags = desc_soup.find_all("img")
+
+            for img in img_tags:
+                src = img.get("src")
+                if not src:
+                    continue
+                original_url = self._to_original_quality(src)
+                if original_url not in image_urls:
+                    image_urls.append(original_url)
+
+            # Phòng trường hợp ảnh nằm trong text thay vì thẻ <img>
+            for match in IMG_URL_PATTERN.findall(description.text):
+                original_url = self._to_original_quality(match)
+                if original_url not in image_urls:
+                    image_urls.append(original_url)
+
+        return image_urls
+
+    @staticmethod
+    def _to_original_quality(image_url: str) -> str:
+        """Thay phần kích thước thumbnail (vd: 236x) bằng 'originals'."""
+        return THUMBNAIL_SIZE_PATTERN.sub("/originals/", image_url, count=1)
+
+    # ------------------------------------------------------------------ #
+    # Xử lý PIN ĐƠN LẺ (không có RSS, phải fetch trực tiếp trang HTML)
+    # ------------------------------------------------------------------ #
+    def fetch_pin_page(self, pin_url: str) -> str:
+        """Tải nội dung HTML của trang pin đơn lẻ."""
+        try:
+            resp = self.session.get(pin_url, timeout=self.timeout)
+            resp.raise_for_status()
+        except requests.RequestException as exc:
+            raise PinGrabberError(f"Không thể tải trang pin: {pin_url} ({exc})") from exc
+        return resp.text
+
+    def extract_single_pin_image(self, html_content: str) -> Optional[str]:
+        """
+        Dùng BeautifulSoup để tìm ảnh chính của một pin đơn lẻ.
+
+        Pinterest nhúng ảnh chính của pin vào thẻ:
+            <meta property="og:image" content="https://i.pinimg.com/originals/...">
+        Đây thường đã là ảnh chất lượng gốc, không cần nâng cấp thêm.
+        Nếu không tìm thấy, thử phương án dự phòng là quét toàn bộ HTML
+        bằng regex để tìm URL ảnh i.pinimg.com.
+        """
+        soup = BeautifulSoup(html_content, "html.parser")
+
+        og_image = soup.find("meta", property="og:image")
+        if og_image and og_image.get("content"):
+            return self._to_original_quality(og_image["content"])
+
+        # Phương án dự phòng: quét toàn bộ HTML tìm URL ảnh pinimg.com
+        matches = IMG_URL_PATTERN.findall(html_content)
+        if matches:
+            return self._to_original_quality(matches[0])
+
+        return None
+
+    def download_single_pin(self, pin_url: str, output_dir: str = "downloads") -> List[str]:
+        """
+        Tải ảnh từ một URL pin đơn lẻ, ví dụ:
+            https://www.pinterest.com/pin/119134352618387326/
+
+        Trả về danh sách đường dẫn file đã lưu (rỗng nếu không tìm thấy ảnh).
+        """
+        os.makedirs(output_dir, exist_ok=True)
+
+        logger.info("Đang tải trang pin: %s", pin_url)
+        html_content = self.fetch_pin_page(pin_url)
+
+        image_url = self.extract_single_pin_image(html_content)
+        if not image_url:
+            logger.warning("Không tìm thấy ảnh nào trong pin: %s", pin_url)
+            return []
+
+        try:
+            path = self.download_image(image_url, output_dir)
+            logger.info("Đã tải: %s", path)
+            return [path]
+        except PinGrabberError as exc:
+            logger.error("Lỗi tải ảnh: %s", exc)
+            return []
+
+    # ------------------------------------------------------------------ #
+    # Bước 4: Tải ảnh về máy
+    # ------------------------------------------------------------------ #
+    def download_image(self, image_url: str, output_dir: str) -> str:
+        """Tải một ảnh về thư mục output_dir, trả về đường dẫn file đã lưu."""
+        filename = os.path.basename(urlparse(image_url).path) or "image.jpg"
+        filepath = os.path.join(output_dir, filename)
+
+        try:
+            resp = self.session.get(image_url, timeout=self.timeout, stream=True)
+            resp.raise_for_status()
+        except requests.RequestException as exc:
+            raise PinGrabberError(f"Không thể tải ảnh: {image_url} ({exc})") from exc
+
+        with open(filepath, "wb") as f:
+            for chunk in resp.iter_content(chunk_size=8192):
+                if chunk:
+                    f.write(chunk)
+
+        return filepath
+
+    # ------------------------------------------------------------------ #
+    # Hàm tổng hợp: từ URL board -> tải toàn bộ ảnh gốc về máy
+    # ------------------------------------------------------------------ #
+    def download(self, url: str, output_dir: str = "downloads") -> List[str]:
+        """
+        Quy trình đầy đủ, tự động nhận diện loại URL:
+
+            - Nếu là URL pin đơn lẻ (pinterest.com/pin/<id>/):
+                fetch trực tiếp trang HTML -> lấy ảnh từ og:image -> tải về.
+            - Nếu là URL board (pinterest.com/username/boardname/):
+                1. Tạo URL RSS từ URL board.
+                2. Tải nội dung RSS.
+                3. Trích xuất danh sách URL ảnh gốc chất lượng cao.
+                4. Tải toàn bộ ảnh về output_dir.
+
+        Trả về danh sách đường dẫn các file ảnh đã lưu thành công.
+        """
+        if self.is_single_pin_url(url):
+            logger.info("Phát hiện URL pin đơn lẻ, chuyển sang chế độ tải pin lẻ.")
+            return self.download_single_pin(url, output_dir=output_dir)
+
+        os.makedirs(output_dir, exist_ok=True)
+
+        rss_url = self.build_rss_url(url)
+        logger.info("Đang lấy RSS feed: %s", rss_url)
+
+        rss_content = self.fetch_rss(rss_url)
+        image_urls = self.extract_image_urls(rss_content)
+
+        if not image_urls:
+            logger.warning("Không tìm thấy ảnh nào trong board: %s", url)
+            return []
+
+        logger.info("Tìm thấy %d ảnh. Bắt đầu tải...", len(image_urls))
+
+        saved_paths: List[str] = []
+        for index, img_url in enumerate(image_urls, start=1):
+            try:
+                path = self.download_image(img_url, output_dir)
+                saved_paths.append(path)
+                logger.info("(%d/%d) Đã tải: %s", index, len(image_urls), path)
+            except PinGrabberError as exc:
+                logger.error("(%d/%d) Lỗi tải ảnh: %s", index, len(image_urls), exc)
+
+        logger.info("Hoàn tất. Đã tải %d/%d ảnh.", len(saved_paths), len(image_urls))
+        return saved_paths
+
+
+# ---------------------------------------------------------------------- #
+# Hàm shortcut cấp module để dùng nhanh: pingrabber.download(url)
+# ---------------------------------------------------------------------- #
+def download(url: str, output_dir: str = "downloads", timeout: int = 15) -> List[str]:
+    """
+    Hàm tiện ích nhanh, không cần khởi tạo PinGrabber thủ công.
+    Tự động nhận diện URL là board hay pin đơn lẻ và xử lý phù hợp.
+
+    Ví dụ:
+        import pingrabber
+
+        # Board
+        pingrabber.download("https://www.pinterest.com/username/boardname/")
+
+        # Pin đơn lẻ
+        pingrabber.download("https://www.pinterest.com/pin/119134352618387326/")
+    """
+    grabber = PinGrabber(timeout=timeout)
+    return grabber.download(url, output_dir=output_dir)
+
+
+def search(
+    keyword: str,
+    max_boards: int = 3,
+    max_images_per_board: int = 25,
+    max_retries: int = 2,
+    delay_seconds: float = 1.5,
+    timeout: int = 15,
+) -> List[str]:
+    """
+    Hàm tiện ích nhanh: tìm board liên quan đến từ khóa và trả về danh sách
+    link ảnh raw (chất lượng gốc), không tải file về máy.
+
+    Tự động xoay User-Agent, thử lại (retry) và chuyển đổi giữa nhiều
+    công cụ tìm kiếm (DuckDuckGo, Bing) nếu bị chặn.
+
+    Ví dụ:
+        import pingrabber
+
+        links = pingrabber.search("thiên nhiên")
+        for url in links:
+            print(url)
+
+        # Tăng số lần thử lại và thời gian nghỉ nếu mạng dễ bị chặn
+        links = pingrabber.search("nature", max_retries=4, delay_seconds=3)
+    """
+    grabber = PinGrabber(timeout=timeout)
+    return grabber.search(
+        keyword,
+        max_boards=max_boards,
+        max_images_per_board=max_images_per_board,
+        max_retries=max_retries,
+        delay_seconds=delay_seconds,
+    )

pingrabber-0.1.7.dist-info/METADATA

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: pingrabber
+Version: 0.1.7
+Summary: A lightweight Python library that scrapes high-quality images from any public Pinterest board using the official RSS feed
+Home-page: https://github.com/VVui-blip/pin_grabber
+Author: VVui-blip
+Author-email: VVui-blip <vuv54581@gmail.com>
+Maintainer-email: VVui-blip <vuv54581@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/VVui-blip/image-data-scraping-resource-pack-from-Pinterest-
+Project-URL: Repository, https://github.com/VVui-blip/image-data-scraping-resource-pack-from-Pinterest-.git
+Project-URL: Issues, https://github.com/VVui-blip/image-data-scraping-resource-pack-from-Pinterest-/issues
+Project-URL: Documentation, https://github.com/VVui-blip/image-data-scraping-resource-pack-from-Pinterest-/blob/main/README.md
+Keywords: pinterest,scraper,image-downloader,rss,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: beautifulsoup4>=4.9.0
+Requires-Dist: lxml>=4.6.0
+Provides-Extra: search
+Requires-Dist: ddgs>=1.0.0; extra == "search"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# PinGrabber
+
+[![PyPI version](https://img.shields.io/badge/pypi-v0.1.0-blue)](https://pypi.org/project/pingrabber/)
+[![Python 3.7+](https://img.shields.io/badge/python-3.7+-green.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**PinGrabber** is a lightweight Python library that scrapes high‑quality images from any public Pinterest board using the official RSS feed provided by Pinterest. It extracts the original, full‑resolution images and downloads them to your local machine with minimal effort.
+
+![Pinterest Banner](https://www.logo.wine/a/logo/Pinterest/Pinterest-Icon-White-Dark-Background-Logo.wine.svg)
+
+> **Important** – Use this tool only with public boards and for personal or educational purposes. Always respect Pinterest’s [Terms of Service](https://www.pinterest.com/terms/) and the copyright of image authors.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Advanced Usage](#advanced-usage)
+- [How It Works](#how-it-works)
+- [Project Structure](#project-structure)
+- [Dependencies](#dependencies)
+- [License](#license)
+
+---
+
+## Features
+
+- Simple shortcut function – download an entire board or a single pin with one line of code.
+- Automatic conversion of thumbnail URLs to original high‑resolution images.
+- Customizable output directory.
+- Both high‑level wrapper and low‑level class for fine‑grained control.
+- Keyword search that returns raw image URLs without downloading.
+- Built with `requests`, `BeautifulSoup`, and `lxml` for fast and reliable parsing.
+
+---
+
+## Installation
+
+You can install PinGrabber directly from the GitHub repository:
+
+```bash
+pip install git+https://github.com/VVui-blip/image-data-scraping-resource-pack-from-Pinterest-.git
+```
+
+Alternatively, if you have the source code locally:
+
+```bash
+pip install -r requirements.txt
+pip install .
+```
+
+The required dependencies (requests, beautifulsoup4, lxml) will be installed automatically.
+
+Optional dependency for better keyword search
+
+For a more robust and stable keyword search, we recommend installing the ddgs package (community‑maintained, formerly duckduckgo-search):
+
+```bash
+pip install ddgs
+```
+
+Or install it together with PinGrabber:
+
+```bash
+pip install .[search]
+```
+
+ddgs provides a more reliable way to query search engines (DuckDuckGo, Bing, Google, etc.) and supports proxy configuration right in the code. Without ddgs, the search() function will fall back to direct requests calls to search engines, which are more prone to blocking.
+
+---
+
+## Quick Start
+
+pingrabber.download(url) automatically detects whether the given URL is a board or a single pin and handles it accordingly – you don't need to differentiate manually.
+
+Download all images from a board
+
+```python
+import pingrabber
+
+pingrabber.download("https://www.pinterest.com/username/boardname/")
+```
+
+Download a single pin
+
+```python
+import pingrabber
+
+pingrabber.download("https://www.pinterest.com/pin/119134352618387326/")
+```
+
+To save images to a custom directory:
+
+```python
+import pingrabber
+
+pingrabber.download(
+    "https://www.pinterest.com/username/boardname/",
+    output_dir="my_pinterest_images"
+)
+```
+
+Search images by keyword (returns raw links, no download)
+
+```python
+import pingrabber
+
+links = pingrabber.search("nature")
+for url in links:
+    print(url)
+```
+
+This function does not download any images – it only returns a list of high‑quality raw image URLs. You can preview them, filter, or download them manually with requests if needed.
+
+How it works: search() tries multiple search engines (DuckDuckGo HTML, DuckDuckGo Lite, Bing) using the site:pinterest.com <keyword> query. It rotates user‑agents, retries, and adds delays between attempts to reduce the chance of being blocked. If one engine fails (403/429), it automatically switches to the next. It does not scrape Pinterest’s search page directly, because that page requires JavaScript rendering which requests cannot handle.
+
+Customise the number of boards to scan, images per board, retries, and delay:
+
+```python
+links = pingrabber.search(
+    "nature",
+    max_boards=5,
+    max_images_per_board=10,
+    max_retries=3,
+    delay_seconds=2.5
+)
+```
+
+If search() always returns empty: check the logged WARNING/ERROR messages. If you see 403/429 errors for all fallback engines, your network/IP is likely being rate‑limited by the search engines (common on cloud servers, VPNs, or IPs that have sent many requests). In that case:
+
+· Install ddgs if you haven’t (pip install ddgs) – this is the most significant improvement.
+· If ddgs is installed but still returns nothing, try using a proxy directly with the package:
+  ```python
+  from ddgs import DDGS
+  with DDGS(proxy="socks5://127.0.0.1:9050", timeout=15) as ddgs:
+      results = ddgs.text("site:pinterest.com nature", max_results=5)
+      print(results)
+  ```
+  If that returns results, you can initialise PinGrabber with a similarly proxied session, or simply use the found board URLs with download().
+· Increase max_retries and delay_seconds (this only affects the fallback method).
+· Try a different network/VPN.
+· Alternatively, use the most reliable approach: find a board manually through your browser and call pingrabber.download(board_url) directly – this does not depend on search engines and is always stable.
+
+---
+
+## Advanced Usage
+
+For more control, use the PinGrabber class:
+
+```python
+from pingrabber import PinGrabber
+
+grabber = PinGrabber(timeout=30)
+
+# Download all original images
+saved_files = grabber.download(
+    "https://www.pinterest.com/username/boardname/",
+    output_dir="high_res_pins"
+)
+
+print(f"Downloaded {len(saved_files)} images")
+```
+
+If you only need the image URLs (without downloading):
+
+```python
+from pingrabber import PinGrabber
+
+grabber = PinGrabber()
+rss_url = grabber.build_rss_url("https://www.pinterest.com/username/boardname/")
+rss_content = grabber.fetch_rss(rss_url)
+image_urls = grabber.extract_image_urls(rss_content)
+
+for url in image_urls:
+    print(url)
+```
+
+---
+
+## How It Works
+
+1. Board/Pin URL to RSS Feed – The provided URL is converted to an RSS feed URL (appending .rss for boards, or using the pin’s RSS endpoint).
+2. Fetch RSS – The RSS content is retrieved via a requests GET request.
+3. Parse and Extract – BeautifulSoup with the lxml parser extracts all <img> tags inside the RSS items.
+4. Upgrade to Original – Thumbnail URLs (e.g., 236x) are transformed into originals URLs to fetch the highest available quality.
+5. Download – Each image is downloaded and saved to the specified output directory with a unique filename.
+
+---
+
+## Project Structure
+
+```
+pin_grabber/
+├── pingrabber/
+│   ├── __init__.py          # Package entry point
+│   └── core.py              # Main logic (PinGrabber class + helper functions)
+├── requirements.txt         # Python dependencies
+├── README.md                # This file
+├── setup.py                 # Packaging configuration
+└── LICENSE                  # MIT License
+```
+
+---
+
+## Dependencies
+
+· Python 3.7+
+· requests – HTTP requests.
+· beautifulsoup4 – HTML/XML parsing.
+· lxml – Fast XML/HTML parser.
+
+All dependencies are listed in requirements.txt and will be installed when using pip install . or the Git install command.
+
+---
+
+## License
+
+This project is released under the MIT License. See the LICENSE file for details.
+
+Disclaimer: This tool is provided “as is”. You are solely responsible for ensuring that your usage complies with Pinterest’s Terms of Service and applicable copyright laws.
+
+---
+
+Built with attention for developers who need a quick, clean Pinterest image scraper.

pingrabber-0.1.7.dist-info/RECORD

@@ -0,0 +1,7 @@
+pingrabber/__init__.py,sha256=3cNX-r8mewlRs5OPu5Kd8IG7yJFOvbqvodGX9Gun6yw,624
+pingrabber/core.py,sha256=HqbwyfUpQIjXu3f0xFFzldC_VnHYvfkdTLoHvMRJRE4,31453
+pingrabber-0.1.7.dist-info/METADATA,sha256=VN4rHDng8fPo5FGYrNpYPhoAJ86GnFV8l0jqNPxxGvA,9851
+pingrabber-0.1.7.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pingrabber-0.1.7.dist-info/entry_points.txt,sha256=Q3icyZV7pv0xwDk69vA8nIN-cJN2083fYF714gVj8Eo,51
+pingrabber-0.1.7.dist-info/top_level.txt,sha256=inAN9tNeeGLwL32Yn9wucNDQqIZWuExlW6wb02X2e48,11
+pingrabber-0.1.7.dist-info/RECORD,,

pingrabber-0.1.7.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pingrabber-0.1.7.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pingrabber = pingrabber.cli:main

pingrabber-0.1.7.dist-info/top_level.txt

@@ -0,0 +1 @@
+pingrabber