perplexity-webui-scraper 0.3.4__py3-none-any.whl → 0.3.6__py3-none-any.whl

perplexity_webui_scraper/enums.py

@@ -1,4 +1,6 @@
-"""Enums for Perplexity WebUI Scraper configuration options."""
+"""
+Enums for Perplexity WebUI Scraper configuration options.
+"""
 
 from __future__ import annotations
 
@@ -6,70 +8,140 @@ from enum import Enum
 
 
 class CitationMode(str, Enum):
-    """Citation formatting modes for response text.
+    """
+    Citation formatting modes for response text.
 
     Controls how citation markers (e.g., [1], [2]) are formatted in the response.
     """
 
     DEFAULT = "default"
-    """Keep original Perplexity citation format (e.g., 'This is a citation[1]')."""
+    """
+    Keep original Perplexity citation format (e.g., 'This is a citation[1]').
+    """
 
     MARKDOWN = "markdown"
-    """Convert citations to markdown links (e.g., 'This is a citation[1](https://example.com)')."""
+    """
+    Convert citations to markdown links (e.g., 'This is a citation[1](https://example.com)').
+    """
 
     CLEAN = "clean"
-    """Remove all citation markers (e.g., 'This is a citation')."""
+    """
+    Remove all citation markers (e.g., 'This is a citation').
+    """
 
 
 class SearchFocus(str, Enum):
-    """Search focus types that control the type of search performed.
+    """
+    Search focus types that control the type of search performed.
 
     Determines whether to search the web or focus on writing tasks.
     """
 
     WEB = "internet"
-    """Search the web for information. Best for factual queries and research."""
+    """
+    Search the web for information. Best for factual queries and research.
+    """
 
     WRITING = "writing"
-    """Focus on writing tasks. Best for creative writing, editing, and text generation."""
+    """
+    Focus on writing tasks. Best for creative writing, editing, and text generation.
+    """
 
 
 class SourceFocus(str, Enum):
-    """Source focus types that control which sources to prioritize.
+    """
+    Source focus types that control which sources to prioritize.
 
     Can be combined (e.g., [SourceFocus.WEB, SourceFocus.ACADEMIC]) for multi-source searches.
     """
 
     WEB = "web"
-    """Search across the entire internet. General web search."""
+    """
+    Search across the entire internet. General web search.
+    """
 
     ACADEMIC = "scholar"
-    """Search academic papers and scholarly articles (Google Scholar, etc.)."""
+    """
+    Search academic papers and scholarly articles (Google Scholar, etc.).
+    """
 
     SOCIAL = "social"
-    """Search social media for discussions and opinions (Reddit, Twitter, etc.)."""
+    """
+    Search social media for discussions and opinions (Reddit, Twitter, etc.).
+    """
 
     FINANCE = "edgar"
-    """Search SEC EDGAR filings for financial and corporate documents."""
+    """
+    Search SEC EDGAR filings for financial and corporate documents.
+    """
 
 
 class TimeRange(str, Enum):
-    """Time range filters for search results.
+    """
+    Time range filters for search results.
 
     Controls how recent the sources should be.
     """
 
     ALL = ""
-    """Include sources from all time. No time restriction."""
+    """
+    Include sources from all time. No time restriction.
+    """
 
     TODAY = "DAY"
-    """Include only sources from today (last 24 hours)."""
+    """
+    Include only sources from today (last 24 hours).
+    """
 
     LAST_WEEK = "WEEK"
-    """Include sources from the last 7 days."""
+    """
+    Include sources from the last 7 days.
+    """
 
     LAST_MONTH = "MONTH"
-    """Include sources from the last 30 days."""
+    """
+    Include sources from the last 30 days.
+    """
 
     LAST_YEAR = "YEAR"
-    """Include sources from the last 365 days."""
+    """
+    Include sources from the last 365 days.
+    """
+
+
+class LogLevel(str, Enum):
+    """
+    Logging level configuration.
+
+    Controls the verbosity of logging output. DISABLED is the default.
+    """
+
+    DISABLED = "DISABLED"
+    """
+    Completely disable all logging output. This is the default.
+    """
+
+    DEBUG = "DEBUG"
+    """
+    Show all messages including internal debug information.
+    """
+
+    INFO = "INFO"
+    """
+    Show informational messages, warnings, and errors.
+    """
+
+    WARNING = "WARNING"
+    """
+    Show only warnings and errors.
+    """
+
+    ERROR = "ERROR"
+    """
+    Show only error messages.
+    """
+
+    CRITICAL = "CRITICAL"
+    """
+    Show only critical/fatal errors.
+    """

perplexity_webui_scraper/exceptions.py

@@ -1,8 +1,23 @@
-"""Custom exceptions for Perplexity WebUI Scraper."""
+"""
+Custom exceptions for Perplexity WebUI Scraper.
+"""
 
 from __future__ import annotations
 
 
+__all__: list[str] = [
+    "AuthenticationError",
+    "CloudflareBlockError",
+    "FileUploadError",
+    "FileValidationError",
+    "PerplexityError",
+    "RateLimitError",
+    "ResearchClarifyingQuestionsError",
+    "ResponseParsingError",
+    "StreamingError",
+]
+
+
 class PerplexityError(Exception):
     """Base exception for all Perplexity-related errors."""
 
@@ -34,6 +49,25 @@ class RateLimitError(PerplexityError):
         )
 
 
+class CloudflareBlockError(PerplexityError):
+    """
+    Raised when Cloudflare blocks the request with a challenge page.
+
+    This typically means the request triggered Cloudflare's bot detection.
+    The client will automatically retry with fingerprint rotation, but if
+    this exception is raised, all retry attempts have failed.
+    """
+
+    def __init__(self, message: str | None = None) -> None:
+        super().__init__(
+            message
+            or "Cloudflare challenge detected. The request was blocked by Cloudflare's "
+            "bot protection. Try waiting a few minutes before retrying, or obtain a "
+            "fresh session token.",
+            status_code=403,
+        )
+
+
 class FileUploadError(PerplexityError):
     """Raised when file upload fails."""
 
@@ -48,3 +82,45 @@ class FileValidationError(PerplexityError):
     def __init__(self, file_path: str, reason: str) -> None:
         self.file_path = file_path
         super().__init__(f"File validation failed for '{file_path}': {reason}")
+
+
+class ResearchClarifyingQuestionsError(PerplexityError):
+    """
+    Raised when Research mode requires clarifying questions.
+
+    This library does not support programmatic interaction with clarifying questions.
+    Consider rephrasing your query to be more specific.
+
+    Attributes:
+        questions: List of clarifying questions from the API.
+    """
+
+    def __init__(self, questions: list[str]) -> None:
+        self.questions = questions
+        questions_text = "\n".join(f"  - {q}" for q in questions) if questions else "  (no questions provided)"
+
+        super().__init__(
+            f"Research mode is asking clarifying questions:\n{questions_text}\n\n"
+            "Programmatic interaction with clarifying questions is not supported. "
+            "Please rephrase your query to be more specific."
+        )
+
+
+class ResponseParsingError(PerplexityError):
+    """
+    Raised when the API response cannot be parsed.
+
+    Attributes:
+        raw_data: The raw data that failed to parse.
+    """
+
+    def __init__(self, message: str, raw_data: str | None = None) -> None:
+        self.raw_data = raw_data
+        super().__init__(f"Failed to parse API response: {message}")
+
+
+class StreamingError(PerplexityError):
+    """Raised when an error occurs during streaming."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(f"Streaming error: {message}")