Truststore

Warnings

• gotcha The `truststore.inject_into_ssl()` function must be called as early as possible in your application's lifecycle, before any `ssl.SSLContext` objects are created by other libraries (e.g., `requests`, `httpx`, `urllib3`). Contexts created before injection will not use the system trust store.
  Fix: Ensure `truststore.inject_into_ssl()` is one of the first lines of executable code in your main script or entry point.
• breaking Versions prior to 0.10.4 had a thread-safety issue when configuring the internal `ssl.SSLContext` object, potentially leading to incorrect behavior or crashes in multi-threaded applications.
  Fix: Upgrade to truststore 0.10.4 or higher to resolve the thread-safety bug. If unable to upgrade, avoid using truststore in multi-threaded contexts where `SSLContext` objects are frequently configured.
• gotcha Truststore requires Python 3.10 or newer. Attempting to install or use it on older Python versions will result in an `ImportError` or installation failure.
  Fix: Ensure your project's `requires_python` is set to `>=3.10` and your environment uses a compatible Python interpreter.
• gotcha `truststore.inject_into_ssl()` performs a global patch on the standard library's `ssl.SSLContext`. While this is often the desired behavior for broad adoption, be aware that it affects all subsequent `SSLContext` creations in the process.
  Fix: If granular control is needed, you can use `truststore.SSLContext` directly instead of `ssl.SSLContext` for specific connections, or `truststore.extract_from_ssl()` to temporarily revert the global patch.
• deprecated Error handling for unsupported macOS versions (10.7 or earlier) changed in v0.7.0. It now raises an `ImportError` instead of an `OSError` when the module isn't supported on a given macOS system.
  Fix: Update error handling code to catch `ImportError` when `truststore` is not supported on a given platform, instead of `OSError`.

Install

• pip install truststore Install truststore

Imports

• inject_into_ssl

  import truststore; truststore.inject_into_ssl()

• extract_from_ssl

  import truststore; truststore.extract_from_ssl()

  Used to revert the global patch applied by inject_into_ssl().
• SSLContext

  from truststore import SSLContext

  For explicit use, less common than global injection for most applications.

Quickstart

The most common way to use truststore is by calling `truststore.inject_into_ssl()` early in your application's execution. This globally patches `ssl.SSLContext`, causing libraries like `requests` and `httpx` to automatically use the system's trust store for certificate verification. This example demonstrates making a simple request with `requests` after injection.

import truststore
import requests

# Call inject_into_ssl() as early as possible in your application's lifecycle.
# This patches the default SSLContext used by many libraries (e.g., requests, httpx).
truststore.inject_into_ssl()

try:
    # requests will now use the system trust store for verification
    response = requests.get('https://www.google.com', timeout=5)
    response.raise_for_status()
    print(f"Successfully connected to Google: {response.status_code}")
except requests.exceptions.RequestException as e:
    print(f"Error connecting: {e}")