notify-tls-client 2.1.0
Cliente HTTP avançado com TLS fingerprinting, rotação automática de proxies e recuperação inteligente para web scraping profissional
License: MIT
Requires Python: >=3.12
Keywords: tls-client, http-client, web-scraping, proxy-rotation, tls-fingerprinting, browser-emulation, http2, http3, requests, automation

# 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**