pingrabber 0.1.7__tar.gz

pingrabber-0.1.7/MANIFEST.in

@@ -0,0 +1 @@
+include requirements.txt

pingrabber-0.1.7/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,226 @@
+# 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/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"