notify-tls-client 2.0.0__tar.gz → 2.0.1__tar.gz

notify_tls_client-2.0.1/PKG-INFO

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: notify-tls-client
+Version: 2.0.1
+Summary: Cliente HTTP avançado com TLS fingerprinting, rotação automática de proxies e recuperação inteligente para web scraping profissional
+Author-email: Jeferson Albara <jeferson.albara@example.com>
+Maintainer-email: Jeferson Albara <jeferson.albara@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/jefersonAlbara/notify-tls-client
+Project-URL: Documentation, https://github.com/jefersonAlbara/notify-tls-client#readme
+Project-URL: Repository, https://github.com/jefersonAlbara/notify-tls-client
+Project-URL: Issues, https://github.com/jefersonAlbara/notify-tls-client/issues
+Project-URL: Changelog, https://github.com/jefersonAlbara/notify-tls-client/blob/main/CHANGELOG.md
+Keywords: tls-client,http-client,web-scraping,proxy-rotation,tls-fingerprinting,browser-emulation,http2,http3,requests,automation
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: dataclasses-json>=0.6.0
+Requires-Dist: typing-extensions>=4.8.0
+Requires-Dist: orjson>=3.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# Notify TLS Client
+
+[![PyPI version](https://badge.fury.io/py/notify-tls-client.svg)](https://badge.fury.io/py/notify-tls-client)
+[![Python Version](https://img.shields.io/pypi/pyversions/notify-tls-client.svg)](https://pypi.org/project/notify-tls-client/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Cliente HTTP avançado em Python com suporte a TLS/SSL customizado, fingerprinting de navegadores e rotação automática de proxies. Construído sobre a biblioteca `tls-client` com funcionalidades adicionais para web scraping e automação resiliente.
+
+## 🚀 Características Principais
+
+- **Fingerprinting TLS Avançado**: Emula múltiplos navegadores (Chrome, Firefox, Safari, Edge, Mobile)
+- **Rotação Automática**: Proxies e client identifiers com políticas configuráveis
+- **Recuperação Automática**: Reconexão inteligente em erros e respostas proibidas
+- **Thread-Safe**: Uso seguro em ambientes multi-threaded
+- **Configuração Modular**: Sistema de configuração baseado em objetos reutilizáveis
+- **Presets Prontos**: Configurações pré-definidas para casos de uso comuns
+- **HTTP/3 Support**: Suporte opcional a QUIC/HTTP3
+
+## 📦 Instalação
+
+```bash
+pip install notify-tls-client
+```
+
+### Requisitos
+
+- Python >= 3.12
+- Sistema operacional: Windows, macOS, Linux (x86_64, ARM64)
+
+## 🎯 Quick Start
+
+### Uso Básico
+
+```python
+from notify_tls_client import NotifyTLSClient
+
+# Cliente com configuração padrão
+client = NotifyTLSClient()
+
+# Fazer requisição
+response = client.get("https://api.example.com/data")
+print(response.status_code)
+print(response.json())
+```
+
+### Usando Presets (Recomendado)
+
+```python
+from notify_tls_client import NotifyTLSClient
+from notify_tls_client.config import ClientConfiguration
+from notify_tls_client.core.proxiesmanager import ProxiesManagerLoader
+
+# Carregar proxies
+proxies = ProxiesManagerLoader().from_txt("proxies.txt")
+
+# Preset para scraping agressivo
+config = ClientConfiguration.aggressive(proxies)
+client = NotifyTLSClient(config)
+
+# Fazer múltiplas requisições
+for i in range(100):
+    response = client.get("https://example.com/api/endpoint")
+    print(f"Request {i}: {response.status_code}")
+```
+
+### Configuração Customizada
+
+```python
+from notify_tls_client import NotifyTLSClient
+from notify_tls_client.config import (
+    ClientConfiguration,
+    RotationConfig,
+    RecoveryConfig,
+    ClientConfig
+)
+
+config = ClientConfiguration(
+    proxies_manager=proxies,
+    rotation=RotationConfig(
+        requests_limit_same_proxy=50,
+        requests_limit_same_client_identifier=200,
+        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"],
+        disable_http3=False,
+        debug_mode=False
+    )
+)
+
+client = NotifyTLSClient(config)
+```
+
+## 📚 Presets Disponíveis
+
+### Simple
+Uso básico com rotação de proxies padrão.
+```python
+config = ClientConfiguration.simple(proxies)
+```
+
+### Aggressive
+Para scraping intensivo com recuperação automática completa.
+```python
+config = ClientConfiguration.aggressive(proxies)
+```
+- Troca proxy a cada 10 requisições
+- Troca client identifier a cada 50 requisições
+- Recuperação automática em erros e 403/429/503
+- Múltiplos client identifiers
+
+### Stealth
+Foco em evitar detecção através de diversidade.
+```python
+config = ClientConfiguration.stealth(proxies)
+```
+- 4 client identifiers diferentes
+- Ordem de extensões TLS randomizada
+- Rotação moderada (100 req/proxy)
+
+### Mobile
+Simula dispositivos móveis.
+```python
+# Android
+config = ClientConfiguration.mobile(proxies, platform="android")
+
+# iOS
+config = ClientConfiguration.mobile(proxies, platform="ios")
+```
+
+## 🔧 Funcionalidades Avançadas
+
+### Rotação de Proxies
+
+```python
+from notify_tls_client.core.proxiesmanager import ProxiesManagerLoader
+
+# Carregar de arquivo
+proxies = ProxiesManagerLoader().from_txt("proxies.txt")
+
+# Formato do arquivo (um por linha):
+# host:port
+# host:port:username:password
+# http://username:password@host:port
+```
+
+### Client Identifiers Suportados
+
+**Desktop:**
+- Chrome: `chrome_133`, `chrome_131`, `chrome_120`, etc.
+- Firefox: `firefox_120`, `firefox_117`, `firefox_110`, etc.
+- Safari: `safari_17_0`, `safari_16_0`, etc.
+- Edge, Opera
+
+**Mobile:**
+- Android: `okhttp4_android_13`, `okhttp4_android_12`, etc.
+- iOS: `safari_ios_16_0`, `safari_ios_15_6`, etc.
+
+### Recuperação Automática
+
+```python
+config = ClientConfiguration(
+    recovery=RecoveryConfig(
+        # Criar nova sessão em respostas proibidas
+        instantiate_new_client_on_forbidden_response=True,
+
+        # Criar nova sessão em exceções
+        instantiate_new_client_on_exception=True,
+
+        # Trocar identifier em respostas proibidas
+        change_client_identifier_on_forbidden_response=True,
+
+        # Status codes que acionam recuperação
+        status_codes_to_forbidden_response_handle=[403, 429, 503]
+    )
+)
+```
+
+### Headers Customizados
+
+```python
+config = ClientConfiguration(
+    client=ClientConfig(
+        default_headers={
+            "User-Agent": "Mozilla/5.0...",
+            "Accept-Language": "pt-BR,pt;q=0.9",
+            "Custom-Header": "value"
+        }
+    )
+)
+
+# Ou por requisição
+response = client.get(
+    "https://example.com",
+    headers={"Authorization": "Bearer token"}
+)
+```
+
+### Cookies
+
+```python
+# Obter todos os cookies
+cookies = client.get_cookies()
+
+# Obter cookie específico
+value = client.get_cookie_by_name("session_id")
+
+# Definir cookie
+client.set_cookie("name", "value")
+```
+
+## 🔒 Thread Safety
+
+A biblioteca é thread-safe e pode ser usada em ambientes multi-threaded:
+
+```python
+import concurrent.futures
+
+client = NotifyTLSClient(ClientConfiguration.aggressive(proxies))
+
+def make_request(url):
+    return client.get(url)
+
+with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
+    urls = ["https://example.com"] * 100
+    results = list(executor.map(make_request, urls))
+```
+
+## 📊 Logging
+
+```python
+import logging
+
+# Habilitar logs de debug
+logging.basicConfig(level=logging.DEBUG)
+
+# Ou configurar apenas para notify_tls_client
+logger = logging.getLogger("notify_tls_client")
+logger.setLevel(logging.DEBUG)
+```
+
+## 🛠️ Métodos HTTP Suportados
+
+```python
+# GET
+response = client.get(url, params={"key": "value"})
+
+# POST
+response = client.post(url, json={"data": "value"})
+response = client.post(url, data="form data")
+
+# PUT
+response = client.put(url, json={"data": "value"})
+
+# PATCH
+response = client.patch(url, json={"data": "value"})
+
+# DELETE
+response = client.delete(url)
+```
+
+## 📖 Documentação Completa
+
+Para documentação detalhada sobre arquitetura, componentes internos e exemplos avançados, consulte:
+- [CLAUDE.md](CLAUDE.md) - Guia completo de desenvolvimento
+- [examples/](examples/) - Exemplos de código
+
+## 🤝 Contribuindo
+
+Contribuições são bem-vindas! Por favor, leia [CONTRIBUTING.md](CONTRIBUTING.md) para detalhes sobre nosso código de conduta e processo de submissão de pull requests.
+
+## 📝 Changelog
+
+Veja [CHANGELOG.md](CHANGELOG.md) para histórico de versões e mudanças.
+
+## 📄 Licença
+
+Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.
+
+## ⚠️ Aviso Legal
+
+Esta biblioteca é fornecida apenas para fins educacionais e de pesquisa. O uso desta ferramenta para violar termos de serviço de websites, realizar scraping não autorizado ou qualquer atividade ilegal é de sua responsabilidade. Os desenvolvedores não se responsabilizam pelo uso indevido desta biblioteca.
+
+## 🙏 Agradecimentos
+
+- [tls-client](https://github.com/bogdanfinn/tls-client) - Biblioteca Go subjacente para TLS fingerprinting
+- Comunidade Python por ferramentas e bibliotecas incríveis
+
+## 📞 Suporte
+
+- **Issues**: [GitHub Issues](https://github.com/jefersonAlbara/notify-tls-client/issues)
+- **Discussões**: [GitHub Discussions](https://github.com/jefersonAlbara/notify-tls-client/discussions)
+
+---
+
+**Desenvolvido com ❤️ para a comunidade Python**

notify_tls_client-2.0.1/README.md

@@ -0,0 +1,302 @@
+# Notify TLS Client
+
+[![PyPI version](https://badge.fury.io/py/notify-tls-client.svg)](https://badge.fury.io/py/notify-tls-client)
+[![Python Version](https://img.shields.io/pypi/pyversions/notify-tls-client.svg)](https://pypi.org/project/notify-tls-client/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Cliente HTTP avançado em Python com suporte a TLS/SSL customizado, fingerprinting de navegadores e rotação automática de proxies. Construído sobre a biblioteca `tls-client` com funcionalidades adicionais para web scraping e automação resiliente.
+
+## 🚀 Características Principais
+
+- **Fingerprinting TLS Avançado**: Emula múltiplos navegadores (Chrome, Firefox, Safari, Edge, Mobile)
+- **Rotação Automática**: Proxies e client identifiers com políticas configuráveis
+- **Recuperação Automática**: Reconexão inteligente em erros e respostas proibidas
+- **Thread-Safe**: Uso seguro em ambientes multi-threaded
+- **Configuração Modular**: Sistema de configuração baseado em objetos reutilizáveis
+- **Presets Prontos**: Configurações pré-definidas para casos de uso comuns
+- **HTTP/3 Support**: Suporte opcional a QUIC/HTTP3
+
+## 📦 Instalação
+
+```bash
+pip install notify-tls-client
+```
+
+### Requisitos
+
+- Python >= 3.12
+- Sistema operacional: Windows, macOS, Linux (x86_64, ARM64)
+
+## 🎯 Quick Start
+
+### Uso Básico
+
+```python
+from notify_tls_client import NotifyTLSClient
+
+# Cliente com configuração padrão
+client = NotifyTLSClient()
+
+# Fazer requisição
+response = client.get("https://api.example.com/data")
+print(response.status_code)
+print(response.json())
+```
+
+### Usando Presets (Recomendado)
+
+```python
+from notify_tls_client import NotifyTLSClient
+from notify_tls_client.config import ClientConfiguration
+from notify_tls_client.core.proxiesmanager import ProxiesManagerLoader
+
+# Carregar proxies
+proxies = ProxiesManagerLoader().from_txt("proxies.txt")
+
+# Preset para scraping agressivo
+config = ClientConfiguration.aggressive(proxies)
+client = NotifyTLSClient(config)
+
+# Fazer múltiplas requisições
+for i in range(100):
+    response = client.get("https://example.com/api/endpoint")
+    print(f"Request {i}: {response.status_code}")
+```
+
+### Configuração Customizada
+
+```python
+from notify_tls_client import NotifyTLSClient
+from notify_tls_client.config import (
+    ClientConfiguration,
+    RotationConfig,
+    RecoveryConfig,
+    ClientConfig
+)
+
+config = ClientConfiguration(
+    proxies_manager=proxies,
+    rotation=RotationConfig(
+        requests_limit_same_proxy=50,
+        requests_limit_same_client_identifier=200,
+        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"],
+        disable_http3=False,
+        debug_mode=False
+    )
+)
+
+client = NotifyTLSClient(config)
+```
+
+## 📚 Presets Disponíveis
+
+### Simple
+Uso básico com rotação de proxies padrão.
+```python
+config = ClientConfiguration.simple(proxies)
+```
+
+### Aggressive
+Para scraping intensivo com recuperação automática completa.
+```python
+config = ClientConfiguration.aggressive(proxies)
+```
+- Troca proxy a cada 10 requisições
+- Troca client identifier a cada 50 requisições
+- Recuperação automática em erros e 403/429/503
+- Múltiplos client identifiers
+
+### Stealth
+Foco em evitar detecção através de diversidade.
+```python
+config = ClientConfiguration.stealth(proxies)
+```
+- 4 client identifiers diferentes
+- Ordem de extensões TLS randomizada
+- Rotação moderada (100 req/proxy)
+
+### Mobile
+Simula dispositivos móveis.
+```python
+# Android
+config = ClientConfiguration.mobile(proxies, platform="android")
+
+# iOS
+config = ClientConfiguration.mobile(proxies, platform="ios")
+```
+
+## 🔧 Funcionalidades Avançadas
+
+### Rotação de Proxies
+
+```python
+from notify_tls_client.core.proxiesmanager import ProxiesManagerLoader
+
+# Carregar de arquivo
+proxies = ProxiesManagerLoader().from_txt("proxies.txt")
+
+# Formato do arquivo (um por linha):
+# host:port
+# host:port:username:password
+# http://username:password@host:port
+```
+
+### Client Identifiers Suportados
+
+**Desktop:**
+- Chrome: `chrome_133`, `chrome_131`, `chrome_120`, etc.
+- Firefox: `firefox_120`, `firefox_117`, `firefox_110`, etc.
+- Safari: `safari_17_0`, `safari_16_0`, etc.
+- Edge, Opera
+
+**Mobile:**
+- Android: `okhttp4_android_13`, `okhttp4_android_12`, etc.
+- iOS: `safari_ios_16_0`, `safari_ios_15_6`, etc.
+
+### Recuperação Automática
+
+```python
+config = ClientConfiguration(
+    recovery=RecoveryConfig(
+        # Criar nova sessão em respostas proibidas
+        instantiate_new_client_on_forbidden_response=True,
+
+        # Criar nova sessão em exceções
+        instantiate_new_client_on_exception=True,
+
+        # Trocar identifier em respostas proibidas
+        change_client_identifier_on_forbidden_response=True,
+
+        # Status codes que acionam recuperação
+        status_codes_to_forbidden_response_handle=[403, 429, 503]
+    )
+)
+```
+
+### Headers Customizados
+
+```python
+config = ClientConfiguration(
+    client=ClientConfig(
+        default_headers={
+            "User-Agent": "Mozilla/5.0...",
+            "Accept-Language": "pt-BR,pt;q=0.9",
+            "Custom-Header": "value"
+        }
+    )
+)
+
+# Ou por requisição
+response = client.get(
+    "https://example.com",
+    headers={"Authorization": "Bearer token"}
+)
+```
+
+### Cookies
+
+```python
+# Obter todos os cookies
+cookies = client.get_cookies()
+
+# Obter cookie específico
+value = client.get_cookie_by_name("session_id")
+
+# Definir cookie
+client.set_cookie("name", "value")
+```
+
+## 🔒 Thread Safety
+
+A biblioteca é thread-safe e pode ser usada em ambientes multi-threaded:
+
+```python
+import concurrent.futures
+
+client = NotifyTLSClient(ClientConfiguration.aggressive(proxies))
+
+def make_request(url):
+    return client.get(url)
+
+with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
+    urls = ["https://example.com"] * 100
+    results = list(executor.map(make_request, urls))
+```
+
+## 📊 Logging
+
+```python
+import logging
+
+# Habilitar logs de debug
+logging.basicConfig(level=logging.DEBUG)
+
+# Ou configurar apenas para notify_tls_client
+logger = logging.getLogger("notify_tls_client")
+logger.setLevel(logging.DEBUG)
+```
+
+## 🛠️ Métodos HTTP Suportados
+
+```python
+# GET
+response = client.get(url, params={"key": "value"})
+
+# POST
+response = client.post(url, json={"data": "value"})
+response = client.post(url, data="form data")
+
+# PUT
+response = client.put(url, json={"data": "value"})
+
+# PATCH
+response = client.patch(url, json={"data": "value"})
+
+# DELETE
+response = client.delete(url)
+```
+
+## 📖 Documentação Completa
+
+Para documentação detalhada sobre arquitetura, componentes internos e exemplos avançados, consulte:
+- [CLAUDE.md](CLAUDE.md) - Guia completo de desenvolvimento
+- [examples/](examples/) - Exemplos de código
+
+## 🤝 Contribuindo
+
+Contribuições são bem-vindas! Por favor, leia [CONTRIBUTING.md](CONTRIBUTING.md) para detalhes sobre nosso código de conduta e processo de submissão de pull requests.
+
+## 📝 Changelog
+
+Veja [CHANGELOG.md](CHANGELOG.md) para histórico de versões e mudanças.
+
+## 📄 Licença
+
+Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.
+
+## ⚠️ Aviso Legal
+
+Esta biblioteca é fornecida apenas para fins educacionais e de pesquisa. O uso desta ferramenta para violar termos de serviço de websites, realizar scraping não autorizado ou qualquer atividade ilegal é de sua responsabilidade. Os desenvolvedores não se responsabilizam pelo uso indevido desta biblioteca.
+
+## 🙏 Agradecimentos
+
+- [tls-client](https://github.com/bogdanfinn/tls-client) - Biblioteca Go subjacente para TLS fingerprinting
+- Comunidade Python por ferramentas e bibliotecas incríveis
+
+## 📞 Suporte
+
+- **Issues**: [GitHub Issues](https://github.com/jefersonAlbara/notify-tls-client/issues)
+- **Discussões**: [GitHub Discussions](https://github.com/jefersonAlbara/notify-tls-client/discussions)
+
+---
+
+**Desenvolvido com ❤️ para a comunidade Python**

{notify_tls_client-2.0.0 → notify_tls_client-2.0.1}/notify_tls_client/config/recovery_config.py

@@ -44,10 +44,15 @@ class 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])
+    status_codes_to_forbidden_response_handle: tuple[int, ...] = field(default_factory=lambda: (403,))
 
     def __post_init__(self):
         """Valida os parâmetros de configuração."""
+        # Converter lista para tuple se necessário (compatibilidade)
+        if isinstance(self.status_codes_to_forbidden_response_handle, list):
+            object.__setattr__(self, 'status_codes_to_forbidden_response_handle',
+                             tuple(self.status_codes_to_forbidden_response_handle))
+
         if not self.status_codes_to_forbidden_response_handle:
             raise ValueError("status_codes_to_forbidden_response_handle não pode ser vazio")