TLS Requests

The tls_requests.Client class is the primary interface for making synchronous HTTP requests. It is functionally equivalent to requests.Session from the requests library.

Using a Client is recommended over top-level functions (like tls_requests.get()) because it:

• Performance: Reuses underlying TLS sessions and network connections.
• State Management: Automatically manages cookies and authentication across multiple requests.
• Consistency: Applies shared headers, proxies, and timeouts to every request made with that client instance.

import tls_requests

with tls_requests.Client() as client:
    response = client.get("https://httpbin.org/get")
    print(response.status_code)

When providing headers or cookies at both the Client level and the individual request level, they are merged. If a conflict exists, the request-level values override the client-level values.

import tls_requests

client_headers = {'X-Auth': 'client'}
request_headers = {'X-Custom': 'request'}

with tls_requests.Client(headers=client_headers) as client:
    response = client.get("https://httpbin.org/get", headers=request_headers)
    # Resulting headers will contain both 'X-Auth': 'client' and 'X-Custom': 'request'
    print(response.request.headers['X-Auth'])  # 'client'
    print(response.request.headers['X-Custom'])  # 'request'

For complex authentication schemes, subclass tls_requests.Auth and implement the build_auth method. The build_auth method must accept a tls_requests.Request object and return the modified tls_requests.Request object. This is the recommended way to create reusable authentication classes.

import tls_requests

class BearerAuth(tls_requests.Auth):
    def __init__(self, token):
        self.token = token

    def build_auth(self, request: tls_requests.Request) -> tls_requests.Request:
        request.headers["Authorization"] = f"Bearer {self.token}"
        return request

You can emulate specific browser TLS fingerprints by providing a client_identifier to the request methods. This spoofing is handled automatically at the protocol level, allowing you to bypass fingerprint-based detection.

By default, tls_requests uses the chrome_133 profile. If no identifier is provided, the library uses this default configuration.

import tls_requests

# Using the default profile (chrome_133)
response = tls_requests.get("https://httpbin.org/get")

# Using a specific profile
response = tls_requests.get("https://httpbin.org/get", client_identifier="firefox_132")

When working with proxies in tls_requests, keep the following in mind:

• Global vs. Per-Request: Proxies are typically set on the Client instance, but you can also pass a proxy argument to individual request methods (e.g., client.get(url, proxy=...)) to override the client default.
• HTTPS Support: Both HTTP and SOCKS5 proxies correctly handle HTTPS traffic (HTTP proxies use the CONNECT method).
• Format: The proxy parameter expects a valid string. If you use a Proxy object from tls_requests.models, it will be automatically converted to the required string format.

If your environment has restricted internet access or you require a specific version of the underlying tls-client library, you can trigger the download manually using TLSLibrary.download(). This is useful for ensuring the binary is present before your main application logic runs.

from tls_requests import TLSLibrary

# Download a specific version
TLSLibrary.download(version='1.13.1')

The AsyncClient provides full support for asynchronous HTTP requests, making it suitable for high-concurrency workloads and integration with frameworks like FastAPI. It mirrors the synchronous Client API but requires the await keyword for all network operations.

To use it, wrap your logic in an async function and use the async with context manager to ensure TLS sessions are properly closed.

import asyncio
import tls_requests

async def main():
    async with tls_requests.AsyncClient() as client:
        response = await client.get("https://httpbin.org/get")
        print(f"Status: {response.status_code}")
        print(f"Data: {response.json()}")

if __name__ == "__main__":
    asyncio.run(main())

You can define hooks at the moment of creation by passing a hooks dictionary to the tls_requests.Client or tls_requests.AsyncClient constructor. The dictionary keys must be 'request' or 'response', and the values must be lists of callable functions.

import tls_requests

def log_request(request):
    pass

def log_response(response):
    pass

def raise_on_4xx_5xx(response):
    response.raise_for_status()

client = tls_requests.Client(hooks={
    'request': [log_request],
    'response': [log_response, raise_on_4xx_5xx],
})

You can modify hooks after a client has been initialized by accessing the .hooks property. You can add specific event hooks, update them, or replace the entire dictionary.

import tls_requests

def log_request(request):
    pass

def log_response(response):
    pass

def raise_on_4xx_5xx(response):
    response.raise_for_status()

client = tls_requests.Client()

# Add a request hook
client.hooks['request'] = [log_request]

# Add a response hook
client.hooks['response'] = [log_response]

# Completely replace hooks
client.hooks = {
    'request': [log_request],
    'response': [raise_on_4xx_5xx],
}