TLS Client

Warnings

• gotcha Failing to explicitly call `session.close()` can lead to significant memory leaks, especially in long-running applications or when making many requests. Version 1.0.0 introduced the `close` function to address this.
  Fix: Always call `session.close()` when the session is no longer needed, or use the `Session` object within a `with` statement if context manager support is available in a future version.
• gotcha While `client_identifier` helps mimic TLS fingerprints, it may not automatically set the `User-Agent` header. For full browser-like behavior and to bypass some bot detection, manually specify a `User-Agent` header in your requests.
  Fix: Include a `User-Agent` header in your request dictionary, e.g., `headers={'User-Agent': '...'}`.
• gotcha Certificate pinning, added in version 1.0.1, requires pre-generating pins using a separate GoLang tool (`hpkp-pins`). Misconfiguration or failure to provide valid pins can lead to connection failures, as it rigorously validates server certificates.
  Fix: Carefully follow the documentation for generating and implementing certificate pins. Ensure you pin multiple certificates (current, backup, and CA) to prevent breakage during certificate rotation.
• gotcha Older versions (pre-1.0.0) of `tls-client` had known bugs related to cookie handling (e.g., duplicate cookies, issues with auto-redirects). Using outdated versions might lead to unexpected behavior in stateful interactions. [cite: GitHub releases]
  Fix: Upgrade to the latest version of `tls-client` (1.0.0 or newer) to benefit from fixes in cookie management and other areas.
• gotcha Connections might fail if the underlying system's OpenSSL library or Python environment does not support modern TLS protocols (like TLS 1.2 or 1.3), as many servers deprecate older, insecure versions like TLS 1.0/1.1.
  Fix: Ensure your operating system and Python environment are up-to-date, with OpenSSL versions that support TLS 1.2+ (ideally 1.1.1 or newer for TLS 1.3).
• gotcha Some users have reported memory or connection issues that could be mitigated by forcing HTTP/1.1 instead of HTTP/2. This may indicate specific server or environmental compatibility challenges with the underlying GoLang library's HTTP/2 implementation.
  Fix: If experiencing unusual memory usage or connection issues, try initializing the session with `force_http1=True`: `tls_client.Session(..., force_http1=True)`.

Install

• pip install tls-client Install latest version

Imports

• Session

  import tls_client
  session = tls_client.Session()

  The primary class is `Session` and is accessed directly from the `tls_client` module, not from a subcommand or differently named class.

Quickstart

This quickstart demonstrates how to create a TLS client session, configure it to mimic a specific browser (Chrome 120), make a GET request to a URL with appropriate headers, and ensure the session is properly closed to avoid resource leaks.

import tls_client
import os

# Initialize a TLS client session mimicking Chrome 120
session = tls_client.Session(
    client_identifier="chrome120", 
    random_tls_extension_order=True,
    proxy=os.environ.get('TLS_PROXY', '') # Optional: load proxy from environment variable
)

try:
    # Make a GET request with browser-like headers
    response = session.get(
        "https://www.example.com/",
        headers={
            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
            "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7",
            "Accept-Language": "en-US,en;q=0.9",
            "Accept-Encoding": "gzip, deflate, br"
        },
        timeout_seconds=30
    )

    print(f"Status Code: {response.status_code}")
    print(f"Response Body (first 200 chars): {response.text[:200]}")
except Exception as e:
    print(f"An error occurred: {e}")
finally:
    session.close() # Crucial for releasing resources and preventing memory leaks