ndg-httpsclient: Enhanced HTTPS with PyOpenSSL

Warnings

• breaking Support for Python 2.6 and Python 3.3 was dropped in version 0.5.1. Users on these End-of-Life Python versions must use an older `ndg-httpsclient` version or upgrade their Python environment.
  Fix: Upgrade Python to a supported version (e.g., Python 3.6+) or pin `ndg-httpsclient<0.5.1`.
• gotcha ndg-httpsclient primarily enhances Python's lower-level `httplib`/`urllib2` (Python 2) or `http.client`/`urllib.request` (Python 3) modules with PyOpenSSL. It is not a general-purpose HTTP client like `requests` and requires understanding of the underlying standard library modules for effective use. It's often used in scenarios needing fine-grained SSL/TLS control.
  Fix: Understand that this library is a low-level enhancement for specific SSL/TLS requirements, not a replacement for higher-level HTTP client libraries.
• gotcha Version 0.4.2 introduced a bug in the `ndg.httpsclient.utils.open_url` function (a duplicate open call). This bug was fixed in version 0.4.3. Importantly, this specific bug *did not affect* the core `httplib` and `urllib2` interfaces that the package patches, only the higher-level `open_url` utility.
  Fix: If relying on `ndg.httpsclient.utils.open_url`, ensure you are on version 0.4.3 or higher.
• deprecated While `ndg-httpsclient` provides Python 3 compatibility, the standard library modules it enhances (`urllib.request`, `http.client`) are often superseded by higher-level, more user-friendly libraries like `requests` for general-purpose HTTP communication. This library remains relevant for niche applications requiring deep PyOpenSSL integration.
  Fix: For most new HTTP-related projects, consider `requests`. Use `ndg-httpsclient` when explicit PyOpenSSL control or compatibility with existing standard library code is a strict requirement.

Install

• pip install ndg-httpsclient Install latest version

Imports

• open_url

  from ndg.httpsclient.utils import open_url

• ServerSSLCertVerification

  from ndg.httpsclient.ssl_peer_verification import ServerSSLCertVerification

• SubjectAlternativeNameMatcher

  from ndg.httpsclient.ssl_peer_verification import SubjectAlternativeNameMatcher

Quickstart

This quickstart demonstrates using `ndg-httpsclient`'s `open_url` utility to make an HTTPS request. This function internally leverages the PyOpenSSL-enhanced `HTTPSHandler` that the library integrates into Python's standard HTTP client modules. For more advanced use, like client certificate authentication or custom CA bundles, additional arguments can be passed to `open_url`.

import sys
import ssl
# PyOpenSSL is a dependency that ndg-httpsclient leverages
from OpenSSL import SSL

# ndg-httpsclient patches these modules, so they should benefit from its enhancements
if sys.version_info[0] >= 3:
    import urllib.request as request_mod
    import http.client as http_client_mod
else:
    import urllib2 as request_mod
    import httplib as http_client_mod

# The primary utility for direct use is open_url
from ndg.httpsclient.utils import open_url

# For this example, we'll try a common HTTPS URL.
# In a real-world scenario, you might pass specific client certificates (c, k)
# or a custom CA bundle (ca) for peer verification.
target_url = "https://www.google.com"

print(f"Attempting to connect to {target_url} using ndg-httpsclient's open_url...")

try:
    # open_url utilizes the PyOpenSSL-backed HTTPS handling provided by ndg-httpsclient
    # For more robust verification, you'd provide `ca='path/to/ca-bundle.pem'`
    response = open_url(target_url)

    print(f"Connection successful!")
    print(f"HTTP Status Code: {response.getcode()}")
    print(f"Content-Type: {response.info()['Content-Type']}")
    # Read and decode a small part of the content to demonstrate success
    # Do not read full content for quickstart to avoid large output
    content_snippet = response.read(200).decode('utf-8', errors='ignore')
    print(f"Partial Content: {content_snippet}...")

except SSL.Error as e:
    print(f"SSL Error during connection: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")