NullGazeX 2.1.0__py3-none-any.whl

nullgaze/__init__.py

@@ -0,0 +1,168 @@
+"""
+NullGazeX — High-speed content retrieval with DPI bypass and TLS impersonation.
+
+Provides two engines:
+  - ImageDownloader   — download images through any firewall/protection
+  - PageScraper       — scrape any page content undetected
+"""
+
+from .downloader import ImageDownloader
+from .scraper import PageScraper
+from .exceptions import (
+    NullGazeError,
+    DownloadFailedError,
+    InvalidURLError,
+    ScrapeError,
+    BlockedError,
+)
+
+__version__ = "2.1.0"
+
+# ------------------------------------------------------------------
+# Image downloading (convenience)
+# ------------------------------------------------------------------
+def download_image(
+    url: str,
+    output_path: str,
+    verbose: bool = False,
+    headers: dict = None,
+    race_timeout: float = 4.0,
+) -> str:
+    """
+    Convenience wrapper to download a single image.
+
+    All bypass strategies are raced in parallel — the fastest wins.
+    """
+    downloader = ImageDownloader(verbose=verbose)
+    return downloader.download(
+        url, output_path, headers=headers, race_timeout=race_timeout
+    )
+
+
+def download_images(
+    targets: list,
+    max_workers: int = 20,
+    verbose: bool = False,
+    headers: dict = None,
+    race_timeout: float = 4.0,
+    adaptive_delay: bool = True,
+) -> list:
+    """
+    Download multiple images concurrently with adaptive anti-blocking delays.
+    """
+    downloader = ImageDownloader(verbose=verbose)
+    return downloader.download_bulk(
+        targets,
+        max_workers=max_workers,
+        headers=headers,
+        race_timeout=race_timeout,
+        adaptive_delay=adaptive_delay,
+    )
+
+
+# ------------------------------------------------------------------
+# Page scraping (convenience)
+# ------------------------------------------------------------------
+def scrape_page(
+    url: str,
+    headers: dict = None,
+    verbose: bool = False,
+    race_timeout: float = 5.0,
+) -> str:
+    """
+    Scrape a page and return raw HTML.
+
+    Uses the same DPI-bypass proxy + rotating TLS fingerprints
+    that power the image downloader.  Undetectable by robot tests.
+    """
+    scraper = PageScraper(verbose=verbose)
+    return scraper.scrape(url, headers=headers, race_timeout=race_timeout)
+
+
+def scrape_text(
+    url: str,
+    headers: dict = None,
+    verbose: bool = False,
+    race_timeout: float = 5.0,
+) -> str:
+    """Scrape a page and return clean plain-text content."""
+    scraper = PageScraper(verbose=verbose)
+    return scraper.scrape_text(url, headers=headers, race_timeout=race_timeout)
+
+
+def scrape_title(
+    url: str,
+    headers: dict = None,
+    verbose: bool = False,
+    race_timeout: float = 5.0,
+) -> str:
+    """Scrape a page and return its <title> text."""
+    scraper = PageScraper(verbose=verbose)
+    return scraper.scrape_title(url, headers=headers, race_timeout=race_timeout)
+
+
+def scrape_json(
+    url: str,
+    headers: dict = None,
+    verbose: bool = False,
+    race_timeout: float = 5.0,
+):
+    """Scrape a JSON endpoint and return the parsed Python object."""
+    scraper = PageScraper(verbose=verbose)
+    return scraper.scrape_json(url, headers=headers, race_timeout=race_timeout)
+
+
+def scrape_bulk(
+    urls: list,
+    max_workers: int = 15,
+    headers: dict = None,
+    verbose: bool = False,
+    race_timeout: float = 5.0,
+    adaptive_delay: bool = True,
+) -> list:
+    """Scrape multiple URLs in parallel."""
+    scraper = PageScraper(verbose=verbose)
+    return scraper.scrape_bulk(
+        urls,
+        max_workers=max_workers,
+        headers=headers,
+        race_timeout=race_timeout,
+        adaptive_delay=adaptive_delay,
+    )
+
+
+# ------------------------------------------------------------------
+# Engine pre-warming
+# ------------------------------------------------------------------
+def engine_prewarm():
+    """
+    Pre-start the shared DPI-bypass proxy so the first real request
+    hits a hot path (sub-100ms).
+    """
+    BaseEngine = ImageDownloader.__bases__[0]
+    BaseEngine.prewarm()
+
+
+# Public API surface
+__all__ = [
+    # Classes
+    "ImageDownloader",
+    "PageScraper",
+    # Image functions
+    "download_image",
+    "download_images",
+    # Scraping functions
+    "scrape_page",
+    "scrape_text",
+    "scrape_title",
+    "scrape_json",
+    "scrape_bulk",
+    # Utility
+    "engine_prewarm",
+    # Exceptions
+    "NullGazeError",
+    "DownloadFailedError",
+    "InvalidURLError",
+    "ScrapeError",
+    "BlockedError",
+]