rnet 3.0.0rc11__cp314-cp314t-manylinux_2_34_armv7l.whl

rnet/emulation.py

@@ -0,0 +1,200 @@
+"""
+This module provides functionality for emulating various browsers and HTTP clients
+to bypass detection and fingerprinting. It supports emulating Chrome, Firefox, Edge,
+Safari, Opera, and OkHttp clients across different operating systems and versions.
+
+The emulation system modifies HTTP/2 settings, TLS fingerprints, and request headers
+to match the behavior of real browsers and clients, making requests appear more
+authentic and less likely to be blocked by anti-bot systems.
+"""
+
+from enum import Enum, auto
+from typing import final
+
+__all__ = ["Emulation", "EmulationOS", "EmulationOption"]
+
+
+@final
+class Emulation(Enum):
+    r"""
+    An emulation.
+    """
+
+    # Chrome versions
+    Chrome100 = auto()
+    Chrome101 = auto()
+    Chrome104 = auto()
+    Chrome105 = auto()
+    Chrome106 = auto()
+    Chrome107 = auto()
+    Chrome108 = auto()
+    Chrome109 = auto()
+    Chrome110 = auto()
+    Chrome114 = auto()
+    Chrome116 = auto()
+    Chrome117 = auto()
+    Chrome118 = auto()
+    Chrome119 = auto()
+    Chrome120 = auto()
+    Chrome123 = auto()
+    Chrome124 = auto()
+    Chrome126 = auto()
+    Chrome127 = auto()
+    Chrome128 = auto()
+    Chrome129 = auto()
+    Chrome130 = auto()
+    Chrome131 = auto()
+    Chrome132 = auto()
+    Chrome133 = auto()
+    Chrome134 = auto()
+    Chrome135 = auto()
+    Chrome136 = auto()
+    Chrome137 = auto()
+    Chrome138 = auto()
+    Chrome139 = auto()
+    Chrome140 = auto()
+    Chrome141 = auto()
+    Chrome142 = auto()
+
+    # Microsoft Edge versions
+    Edge101 = auto()
+    Edge122 = auto()
+    Edge127 = auto()
+    Edge131 = auto()
+    Edge134 = auto()
+
+    # Firefox versions
+    Firefox109 = auto()
+    Firefox117 = auto()
+    Firefox128 = auto()
+    Firefox133 = auto()
+    Firefox135 = auto()
+    FirefoxPrivate135 = auto()
+    FirefoxAndroid135 = auto()
+    Firefox136 = auto()
+    FirefoxPrivate136 = auto()
+    Firefox139 = auto()
+    Firefox142 = auto()
+    Firefox143 = auto()
+
+    # Safari versions
+    SafariIos17_2 = auto()
+    SafariIos17_4_1 = auto()
+    SafariIos16_5 = auto()
+    Safari15_3 = auto()
+    Safari15_5 = auto()
+    Safari15_6_1 = auto()
+    Safari16 = auto()
+    Safari16_5 = auto()
+    Safari17_0 = auto()
+    Safari17_2_1 = auto()
+    Safari17_4_1 = auto()
+    Safari17_5 = auto()
+    Safari18 = auto()
+    SafariIPad18 = auto()
+    Safari18_2 = auto()
+    Safari18_3 = auto()
+    Safari18_3_1 = auto()
+    SafariIos18_1_1 = auto()
+    Safari18_5 = auto()
+    Safari26 = auto()
+    SafariIos26 = auto()
+    SafariIPad26 = auto()
+
+    # OkHttp versions
+    OkHttp3_9 = auto()
+    OkHttp3_11 = auto()
+    OkHttp3_13 = auto()
+    OkHttp3_14 = auto()
+    OkHttp4_9 = auto()
+    OkHttp4_10 = auto()
+    OkHttp4_12 = auto()
+    OkHttp5 = auto()
+
+    # Opera versions
+    Opera116 = auto()
+    Opera117 = auto()
+    Opera118 = auto()
+    Opera119 = auto()
+
+
+@final
+class EmulationOS(Enum):
+    """
+    Operating systems that can be emulated.
+
+    This enum defines the operating systems that can be combined with
+    browser emulations to create more specific fingerprints.
+    """
+
+    Windows = auto()  # Windows (any version)
+    MacOS = auto()  # macOS (any version)
+    Linux = auto()  # Linux (any distribution)
+    Android = auto()  # Android (mobile)
+    IOS = auto()  # iOS (iPhone/iPad)
+
+
+@final
+class EmulationOption:
+    """
+    Configuration options for browser and client emulation.
+
+    This class allows fine-grained control over emulation behavior,
+    including the ability to disable specific features or combine
+    browser types with specific operating systems.
+    """
+
+    def __init__(
+        self,
+        emulation: Emulation,
+        emulation_os: EmulationOS | None = None,
+        skip_http2: bool | None = None,
+        skip_headers: bool | None = None,
+    ) -> None:
+        """
+        Create a new emulation configuration.
+
+        Args:
+            emulation: The browser/client type to emulate
+            emulation_os: The operating system to emulate (optional)
+            skip_http2: Whether to disable HTTP/2 emulation (default: False)
+            skip_headers: Whether to skip default browser headers (default: False)
+
+        Returns:
+            A configured EmulationOption instance
+
+        Example:
+            ```python
+            # Basic Chrome emulation
+            option = EmulationOption(Emulation.Chrome137)
+
+            # Chrome on Windows with HTTP/2 disabled
+            option = EmulationOption(
+                emulation=Emulation.Chrome137,
+                emulation_os=EmulationOS.Windows,
+                skip_http2=True
+            )
+            ```
+        """
+        ...
+
+    @staticmethod
+    def random() -> "EmulationOption":
+        """
+        Generate a random emulation configuration.
+
+        This method creates a randomized emulation setup using a random
+        browser/client type and operating system combination. Useful for
+        scenarios where you want to vary your fingerprint across requests.
+
+        Returns:
+            A randomly configured EmulationOption instance
+
+        Example:
+            ```python
+            # Use different random emulation for each client
+            client1 = rnet.Client(emulation=EmulationOption.random())
+            client2 = rnet.Client(emulation=EmulationOption.random())
+            ```
+        """
+        ...

rnet/exceptions.py

@@ -0,0 +1,224 @@
+"""
+HTTP Client Exceptions
+
+This module defines all exceptions that can be raised by the rnet HTTP client.
+The exceptions are organized into logical categories based on their cause and
+severity, making it easier to handle specific types of errors appropriately.
+"""
+
+__all__ = [
+    "DNSResolverError",
+    "TlsError",
+    "ConnectionError",
+    "ConnectionResetError",
+    "BodyError",
+    "BuilderError",
+    "DecodingError",
+    "StatusError",
+    "RequestError",
+    "RedirectError",
+    "UpgradeError",
+    "WebSocketError",
+    "URLParseError",
+    "TimeoutError",
+]
+
+# ========================================
+# Network and System-Level Errors
+# ========================================
+
+
+class RustPanic(Exception):
+    r"""
+    A panic occurred in the underlying Rust code.
+    """
+
+
+class DNSResolverError(RuntimeError):
+    r"""
+    An error occurred while resolving a DNS name.
+
+    This exception is raised when the DNS resolver fails to resolve
+    a hostname to an IP address. This is typically due to network
+    issues, invalid hostnames, or DNS server problems.
+
+    Since this is a system-level issue that usually cannot be resolved
+    by retrying the request, it inherits from RuntimeError.
+    """
+
+
+class TlsError(Exception):
+    r"""
+    An error occurred in the TLS security layer.
+
+    This exception covers TLS/SSL related issues such as:
+    - Certificate verification failures
+    - TLS handshake failures
+    - Protocol version mismatches
+    - Cipher suite negotiations
+    """
+
+
+class ConnectionError(Exception):
+    r"""
+    An error occurred while establishing a connection.
+
+    This exception is raised when the client cannot establish a
+    TCP connection to the remote server. Common causes include:
+    - Server is unreachable
+    - Port is closed or blocked
+    - Network connectivity issues
+    - Firewall blocking the connection
+    """
+
+
+class ConnectionResetError(Exception):
+    r"""
+    The connection was reset by the remote peer.
+
+    This exception occurs when an established connection is
+    unexpectedly closed by the remote server. This can happen
+    due to server overload, network issues, or server-side
+    connection limits.
+    """
+
+
+# ========================================
+# Request/Response Processing Errors
+# ========================================
+
+
+class BodyError(Exception):
+    r"""
+    An error occurred while processing the body of a request or response.
+
+    This exception covers issues with reading, writing, or processing
+    HTTP message bodies, including:
+    - Invalid content encoding
+    - Incomplete body data
+    - Body size limit exceeded
+    """
+
+
+class BuilderError(Exception):
+    r"""
+    An error occurred while building a request or response.
+
+    This exception is raised when there are issues constructing
+    HTTP requests or responses, such as:
+    - Invalid header combinations
+    - Malformed request parameters
+    - Configuration conflicts
+    """
+
+
+class DecodingError(Exception):
+    r"""
+    An error occurred while decoding a response.
+
+    This exception covers failures in decoding response content,
+    including:
+    - Character encoding issues (UTF-8, Latin-1, etc.)
+    - Compression decompression failures (gzip, deflate, etc.)
+    - Content format parsing errors
+    """
+
+
+class StatusError(Exception):
+    r"""
+    An error occurred while processing the status code of a response.
+
+    This exception is typically raised for HTTP error status codes
+    (4xx, 5xx) when automatic error handling is enabled, or when
+    there are issues interpreting the status line.
+    """
+
+
+class RequestError(Exception):
+    r"""
+    An error occurred while making a request.
+
+    This is a general exception for request-related issues that
+    don't fit into more specific categories. It covers various
+    problems during the request lifecycle.
+    """
+
+
+# ========================================
+# HTTP Protocol and Navigation Errors
+# ========================================
+
+
+class RedirectError(Exception):
+    r"""
+    An error occurred while following a redirect.
+
+    This exception is raised when there are issues with HTTP
+    redirects, such as:
+    - Too many redirects (redirect loop)
+    - Invalid redirect location
+    - Cross-protocol redirects when not allowed
+    - Redirect limit exceeded
+    """
+
+
+class UpgradeError(Exception):
+    r"""
+    An error occurred while upgrading a connection.
+
+    This exception covers failures when upgrading HTTP connections
+    to other protocols, such as:
+    - WebSocket upgrade failures
+    - HTTP/2 upgrade issues
+    - Protocol negotiation errors
+    """
+
+
+class WebSocketError(Exception):
+    r"""
+    An error occurred while handling a WebSocket connection.
+
+    This exception covers WebSocket-specific issues including:
+    - WebSocket handshake failures
+    - Frame parsing errors
+    - Connection state violations
+    - Message sending/receiving errors
+    """
+
+
+# ========================================
+# Parsing and Validation Errors
+# ========================================
+
+
+class URLParseError(Exception):
+    r"""
+    An error occurred while parsing a URL.
+
+    This exception is raised when a provided URL cannot be parsed
+    or is malformed. Common issues include:
+    - Invalid URL schemes
+    - Malformed hostnames or ports
+    - Invalid characters in URL components
+    - Missing required URL components
+    """
+
+
+# ========================================
+# Timeout Errors
+# ========================================
+
+
+class TimeoutError(Exception):
+    r"""
+    A timeout occurred while waiting for a response.
+
+    This exception is raised when operations exceed their configured
+    time limits, including:
+    - Connection timeout (time to establish connection)
+    - Read timeout (time to receive response)
+    - Total request timeout (entire request lifecycle)
+
+    Timeouts can often be resolved by increasing timeout values
+    or retrying the request.
+    """