notify-tls-client 0.1.6__py3-none-any.whl → 2.0.0__py3-none-any.whl

notify_tls_client/__init__.py

@@ -1,2 +1,2 @@
-from .core.notifytlsclient import NotifyTLSClient
-from .tls_client import Session
+from .core.notifytlsclient import NotifyTLSClient
+from .tls_client import Session

notify_tls_client/config/__init__.py

@@ -0,0 +1,18 @@
+"""
+Módulo de configuração para NotifyTLSClient.
+
+Fornece classes de configuração especializadas para organizar
+os parâmetros do cliente TLS de forma mais limpa e reutilizável.
+"""
+
+from .rotation_config import RotationConfig
+from .recovery_config import RecoveryConfig
+from .client_config import ClientConfig
+from .client_configuration import ClientConfiguration
+
+__all__ = [
+    'RotationConfig',
+    'RecoveryConfig',
+    'ClientConfig',
+    'ClientConfiguration',
+]

notify_tls_client/config/client_config.py

@@ -0,0 +1,76 @@
+"""
+Configurações do cliente TLS (identifiers, headers, protocolos).
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from notify_tls_client.tls_client.settings import ClientIdentifiers
+
+
+@dataclass
+class ClientConfig:
+    """
+    Configurações relacionadas ao cliente TLS e fingerprinting.
+
+    Attributes:
+        client_identifiers: Lista de client identifiers para rotação.
+            Identifiers disponíveis incluem chrome_133, firefox_120, safari_17_0, etc.
+            Se apenas um identifier for fornecido, não haverá rotação.
+            Default: ["chrome_133"]
+
+        default_headers: Headers padrão a serem enviados em todas as requisições.
+            Pode ser sobrescrito por requisição individual.
+            Default: None (usa headers padrão do tls-client)
+
+        disable_http3: Se True, força o uso de HTTP/2 ou HTTP/1.1, desabilitando HTTP/3.
+            Útil para ambientes que não suportam QUIC.
+            Default: False
+
+        debug_mode: Se True, habilita logs de debug detalhados.
+            IMPORTANTE: Pode vazar informações sensíveis nos logs.
+            Default: False
+
+    Examples:
+        >>> # Configuração padrão
+        >>> config = ClientConfig()
+
+        >>> # Múltiplos identifiers para stealth
+        >>> config = ClientConfig(
+        ...     client_identifiers=["chrome_133", "firefox_120", "safari_17_0"]
+        ... )
+
+        >>> # Headers customizados
+        >>> config = ClientConfig(
+        ...     default_headers={
+        ...         "User-Agent": "Mozilla/5.0...",
+        ...         "Accept-Language": "pt-BR,pt;q=0.9"
+        ...     }
+        ... )
+
+        >>> # Forçar HTTP/2
+        >>> config = ClientConfig(disable_http3=True)
+    """
+
+    client_identifiers: list[ClientIdentifiers] = field(default_factory=lambda: ["chrome_133"])
+    default_headers: Optional[dict] = None
+    disable_http3: bool = False
+    debug_mode: bool = False
+
+    def __post_init__(self):
+        """Valida os parâmetros de configuração."""
+        if not self.client_identifiers:
+            raise ValueError("client_identifiers não pode ser vazio")
+
+        if len(self.client_identifiers) != len(set(self.client_identifiers)):
+            raise ValueError("client_identifiers contém duplicatas")
+
+        # Valida default_headers se fornecido
+        if self.default_headers is not None:
+            if not isinstance(self.default_headers, dict):
+                raise ValueError("default_headers deve ser um dicionário")
+
+            # Valida que keys são strings
+            for key in self.default_headers.keys():
+                if not isinstance(key, str):
+                    raise ValueError(f"Header key inválido: {key}. Deve ser string")

notify_tls_client/config/client_configuration.py

@@ -0,0 +1,237 @@
+"""
+Configuração completa do NotifyTLSClient com factory methods para casos de uso comuns.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from notify_tls_client.core.proxiesmanager import ProxiesManager
+from .rotation_config import RotationConfig
+from .recovery_config import RecoveryConfig
+from .client_config import ClientConfig
+
+
+@dataclass
+class ClientConfiguration:
+    """
+    Configuração completa para NotifyTLSClient.
+
+    Agrupa todas as configurações específicas em um único objeto para
+    simplificar a criação e reutilização de configurações.
+
+    Attributes:
+        proxies_manager: Gerenciador de proxies para rotação automática.
+            Default: None (sem proxies)
+
+        rotation: Configurações de rotação de proxies e client identifiers.
+            Default: RotationConfig com valores padrão
+
+        recovery: Configurações de recuperação automática.
+            Default: RecoveryConfig com valores padrão
+
+        client: Configurações do cliente TLS.
+            Default: ClientConfig com valores padrão
+
+    Examples:
+        >>> # Configuração padrão
+        >>> config = ClientConfiguration()
+
+        >>> # Configuração customizada
+        >>> config = ClientConfiguration(
+        ...     proxies_manager=ProxiesManager([...]),
+        ...     rotation=RotationConfig(requests_limit_same_proxy=10),
+        ...     recovery=RecoveryConfig(
+        ...         instantiate_new_client_on_forbidden_response=True,
+        ...         status_codes_to_forbidden_response_handle=[403, 429]
+        ...     ),
+        ...     client=ClientConfig(
+        ...         client_identifiers=["chrome_133", "firefox_120"]
+        ...     )
+        ... )
+
+        >>> # Usando factory method
+        >>> config = ClientConfiguration.aggressive(proxies_manager)
+    """
+
+    proxies_manager: Optional[ProxiesManager] = None
+    rotation: RotationConfig = field(default_factory=RotationConfig)
+    recovery: RecoveryConfig = field(default_factory=RecoveryConfig)
+    client: ClientConfig = field(default_factory=ClientConfig)
+
+    @classmethod
+    def aggressive(cls, proxies_manager: Optional[ProxiesManager] = None) -> 'ClientConfiguration':
+        """
+        Configuração agressiva: rotação rápida e recuperação automática completa.
+
+        Ideal para cenários de scraping intensivo onde detectar e contornar
+        bloqueios rapidamente é crítico.
+
+        Características:
+        - Troca proxy a cada 10 requisições
+        - Troca client identifier a cada 50 requisições
+        - Recuperação automática em erros e respostas proibidas
+        - Troca client identifier em respostas proibidas
+        - Monitora status codes 403, 429 e 503
+
+        Args:
+            proxies_manager: Gerenciador de proxies (obrigatório para rotação)
+
+        Returns:
+            ClientConfiguration configurado para modo agressivo
+
+        Example:
+            >>> tls = NotifyTLSClient(ClientConfiguration.aggressive(proxies))
+        """
+        return cls(
+            proxies_manager=proxies_manager,
+            rotation=RotationConfig(
+                requests_limit_same_proxy=10,
+                requests_limit_same_client_identifier=50,
+                random_tls_extension_order=True
+            ),
+            recovery=RecoveryConfig(
+                instantiate_new_client_on_forbidden_response=True,
+                instantiate_new_client_on_exception=True,
+                change_client_identifier_on_forbidden_response=True,
+                status_codes_to_forbidden_response_handle=[403, 429, 503]
+            ),
+            client=ClientConfig(
+                client_identifiers=["chrome_133", "firefox_120", "safari_17_0"]
+            )
+        )
+
+    @classmethod
+    def stealth(cls, proxies_manager: Optional[ProxiesManager] = None) -> 'ClientConfiguration':
+        """
+        Configuração stealth: foco em evitar detecção através de diversidade.
+
+        Ideal para cenários onde ser discreto é mais importante que velocidade,
+        utilizando múltiplos client identifiers e randomização.
+
+        Características:
+        - Múltiplos client identifiers (Chrome, Firefox, Safari, Edge)
+        - Ordem de extensões TLS randomizada
+        - Rotação moderada de proxies (100 requisições)
+        - Rotação de client identifier a cada 30 requisições
+        - Recuperação básica apenas para erros críticos
+
+        Args:
+            proxies_manager: Gerenciador de proxies (opcional mas recomendado)
+
+        Returns:
+            ClientConfiguration configurado para modo stealth
+
+        Example:
+            >>> tls = NotifyTLSClient(ClientConfiguration.stealth(proxies))
+        """
+        return cls(
+            proxies_manager=proxies_manager,
+            rotation=RotationConfig(
+                requests_limit_same_proxy=100,
+                requests_limit_same_client_identifier=30,
+                random_tls_extension_order=True
+            ),
+            recovery=RecoveryConfig(
+                instantiate_new_client_on_forbidden_response=False,
+                instantiate_new_client_on_exception=True,
+                change_client_identifier_on_forbidden_response=False,
+                status_codes_to_forbidden_response_handle=[403]
+            ),
+            client=ClientConfig(
+                client_identifiers=[
+                    "chrome_133",
+                    "firefox_120",
+                    "safari_17_0",
+                    "safari_ios_16_0"
+                ]
+            )
+        )
+
+    @classmethod
+    def simple(cls, proxies_manager: Optional[ProxiesManager] = None) -> 'ClientConfiguration':
+        """
+        Configuração simples: apenas rotação básica de proxies.
+
+        Ideal para uso geral onde não há necessidade de evasão agressiva,
+        mantendo a simplicidade e confiabilidade.
+
+        Características:
+        - Client identifier único (Chrome 133)
+        - Rotação de proxy padrão (1000 requisições)
+        - Sem rotação de client identifier
+        - Sem recuperação automática
+        - Monitora apenas status 403
+
+        Args:
+            proxies_manager: Gerenciador de proxies (opcional)
+
+        Returns:
+            ClientConfiguration configurado para modo simples
+
+        Example:
+            >>> tls = NotifyTLSClient(ClientConfiguration.simple())
+        """
+        return cls(
+            proxies_manager=proxies_manager,
+            rotation=RotationConfig(
+                requests_limit_same_proxy=1000,
+                requests_limit_same_client_identifier=-1,
+                random_tls_extension_order=False
+            ),
+            recovery=RecoveryConfig(
+                instantiate_new_client_on_forbidden_response=False,
+                instantiate_new_client_on_exception=False,
+                change_client_identifier_on_forbidden_response=False,
+                status_codes_to_forbidden_response_handle=[403]
+            ),
+            client=ClientConfig(
+                client_identifiers=["chrome_133"]
+            )
+        )
+
+    @classmethod
+    def mobile(cls, proxies_manager: Optional[ProxiesManager] = None, platform: str = "android") -> 'ClientConfiguration':
+        """
+        Configuração mobile: simula dispositivos móveis.
+
+        Ideal para APIs ou sites que têm comportamento diferente para mobile.
+
+        Características:
+        - Client identifiers mobile (Android ou iOS)
+        - Rotação moderada
+        - Recuperação automática em erros
+
+        Args:
+            proxies_manager: Gerenciador de proxies (opcional)
+            platform: "android" ou "ios"
+
+        Returns:
+            ClientConfiguration configurado para modo mobile
+
+        Example:
+            >>> tls = NotifyTLSClient(ClientConfiguration.mobile(platform="ios"))
+        """
+        if platform.lower() == "android":
+            identifiers = ["okhttp4_android_13", "okhttp4_android_12"]
+        elif platform.lower() == "ios":
+            identifiers = ["safari_ios_16_0", "safari_ios_15_6"]
+        else:
+            raise ValueError(f"Platform inválida: {platform}. Use 'android' ou 'ios'")
+
+        return cls(
+            proxies_manager=proxies_manager,
+            rotation=RotationConfig(
+                requests_limit_same_proxy=50,
+                requests_limit_same_client_identifier=100,
+                random_tls_extension_order=True
+            ),
+            recovery=RecoveryConfig(
+                instantiate_new_client_on_forbidden_response=True,
+                instantiate_new_client_on_exception=True,
+                change_client_identifier_on_forbidden_response=False,
+                status_codes_to_forbidden_response_handle=[403, 429]
+            ),
+            client=ClientConfig(
+                client_identifiers=identifiers
+            )
+        )

notify_tls_client/config/recovery_config.py

@@ -0,0 +1,66 @@
+"""
+Configurações de recuperação automática em caso de erros e respostas proibidas.
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class RecoveryConfig:
+    """
+    Configurações para controlar o comportamento de recuperação automática.
+
+    Attributes:
+        instantiate_new_client_on_forbidden_response: Se True, cria uma nova sessão TLS
+            quando receber um status code configurado como "proibido".
+            Default: False
+
+        instantiate_new_client_on_exception: Se True, cria uma nova sessão TLS
+            quando ocorrer uma exceção durante a requisição.
+            Default: False
+
+        change_client_identifier_on_forbidden_response: Se True, além de criar uma nova
+            sessão, também troca o client identifier quando receber resposta proibida.
+            Requer instantiate_new_client_on_forbidden_response=True para ter efeito.
+            Default: False
+
+        status_codes_to_forbidden_response_handle: Lista de status codes HTTP que devem
+            acionar os mecanismos de recuperação automática.
+            Default: [403]
+
+    Examples:
+        >>> # Recuperação agressiva
+        >>> config = RecoveryConfig(
+        ...     instantiate_new_client_on_forbidden_response=True,
+        ...     instantiate_new_client_on_exception=True,
+        ...     change_client_identifier_on_forbidden_response=True,
+        ...     status_codes_to_forbidden_response_handle=[403, 429, 503]
+        ... )
+
+        >>> # Sem recuperação automática
+        >>> config = RecoveryConfig()
+    """
+
+    instantiate_new_client_on_forbidden_response: bool = False
+    instantiate_new_client_on_exception: bool = False
+    change_client_identifier_on_forbidden_response: bool = False
+    status_codes_to_forbidden_response_handle: list[int] = field(default_factory=lambda: [403])
+
+    def __post_init__(self):
+        """Valida os parâmetros de configuração."""
+        if not self.status_codes_to_forbidden_response_handle:
+            raise ValueError("status_codes_to_forbidden_response_handle não pode ser vazio")
+
+        for code in self.status_codes_to_forbidden_response_handle:
+            if not isinstance(code, int) or code < 100 or code > 599:
+                raise ValueError(f"Status code inválido: {code}. Deve estar entre 100 e 599")
+
+        # Aviso sobre configuração inconsistente
+        if self.change_client_identifier_on_forbidden_response and not self.instantiate_new_client_on_forbidden_response:
+            import warnings
+            warnings.warn(
+                "change_client_identifier_on_forbidden_response=True não terá efeito "
+                "porque instantiate_new_client_on_forbidden_response=False. "
+                "Considere habilitar ambos.",
+                UserWarning
+            )

notify_tls_client/config/rotation_config.py

@@ -0,0 +1,56 @@
+"""
+Configurações de rotação de proxies e client identifiers.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class RotationConfig:
+    """
+    Configurações para controlar a rotação automática de proxies e client identifiers.
+
+    Attributes:
+        requests_limit_same_proxy: Número máximo de requisições com o mesmo proxy.
+            Use -1 para desabilitar rotação automática por limite.
+            Default: 1000
+
+        requests_limit_same_client_identifier: Número máximo de requisições com o mesmo
+            client identifier. Use -1 para desabilitar rotação automática por limite.
+            Default: -1 (desabilitado)
+
+        random_tls_extension_order: Se True, randomiza a ordem das extensões TLS
+            para dificultar fingerprinting.
+            Default: True
+
+    Examples:
+        >>> # Rotação agressiva
+        >>> config = RotationConfig(
+        ...     requests_limit_same_proxy=10,
+        ...     requests_limit_same_client_identifier=50
+        ... )
+
+        >>> # Sem rotação automática
+        >>> config = RotationConfig(
+        ...     requests_limit_same_proxy=-1,
+        ...     requests_limit_same_client_identifier=-1
+        ... )
+    """
+
+    requests_limit_same_proxy: int = 1000
+    requests_limit_same_client_identifier: int = -1
+    random_tls_extension_order: bool = True
+
+    def __post_init__(self):
+        """Valida os parâmetros de configuração."""
+        if self.requests_limit_same_proxy < -1:
+            raise ValueError("requests_limit_same_proxy deve ser >= -1")
+
+        if self.requests_limit_same_client_identifier < -1:
+            raise ValueError("requests_limit_same_client_identifier deve ser >= -1")
+
+        if self.requests_limit_same_proxy == 0:
+            raise ValueError("requests_limit_same_proxy não pode ser 0 (use -1 para desabilitar)")
+
+        if self.requests_limit_same_client_identifier == 0:
+            raise ValueError("requests_limit_same_client_identifier não pode ser 0 (use -1 para desabilitar)")

notify_tls_client/core/client/__init__.py

@@ -1,6 +1 @@
-from .decorators import (
-    increment_requests_decorator,
-    handle_forbidden_requests_decorator,
-    print_request_infos_decorator,
-    change_state_decorator,
-    handle_exception_requests_decorator)
+from .decorators import (request_guard_decorator)