企业网络的HTTP辅助库

概述

sema4ai_http -库提供在企业网络中使用MITM防火墙/代理进行出站流量时的HTTPS请求处理。

问题

• 现代防火墙需要跟踪出站流量以检测恶意软件
• 为了跟踪流量，SSL/TLS需要在防火墙/代理上终止
• 这意味着内部网络HTTPS需要单独的证书才能正常工作
• 这些证书通常使用操作系统特定的证书存储进行分发
• 像requests、urllib3、aiohttp等库尚未原生支持证书存储

👉 在企业网络中，未设置正确SSL上下文的HTTPS请求将失败，而且很难设置正确。

解决方案

每个出站HTTPS请求都需要正确的SSL上下文，但95%的HTTPS代码只是下载文件和简单的GET / POST调用，所以我们提供了一个辅助库。

我们使用truststore -库来访问证书存储，并使用urllib3以避免额外的依赖。

该库的关键特性包括

• 使用操作系统证书存储创建SSL上下文，并提供可选的SSL遗产重协商支持。   - 要使用SSL上下文与其他库，请参阅truststore用户指南
• 使用urllib3的HTTPS请求方法（GET、POST、PUT、PATCH、DELETE）
• 支持断点续传的文件下载，带有重试逻辑和错误处理。
• 支持将下载的文件设置为可执行。

使用示例

from pathlib import Path
from sema4ai_http import download_with_resume

url = "https://example.com/file.zip"
target = Path("/path/to/save/file.zip")

result = download_with_resume(url, target)

print(f"Download status: {result.status}")
print(f"File saved to: {result.path}")

文档

函数

1. HTTPS 请求函数

这些函数处理不同的 HTTPS 请求方法，并从 urllib3 返回响应

• get(url, **kwargs)：发送 GET 请求。
• post(url, **kwargs)：发送 POST 请求。
• put(url, **kwargs)：发送 PUT 请求。
• patch(url, **kwargs)：发送 PATCH 请求。
• delete(url, **kwargs)：发送 DELETE 请求。

2. 构建 SSL 上下文

build_ssl_context(protocol: int = None, *, enable_legacy_server_connect: bool = False) -> ssl.SSLContext**

此函数创建用于与 urllib3 请求一起使用的 SSL 上下文，该请求使用 truststore 库。它还支持启用 SSL 旧版协商连接。

参数

• protocol：要使用的 SSL 协议。
• enable_legacy_server_connect：启用对旧版服务器的支持。

返回：具有适当配置的 SSL 上下文。

3. 带有断点续传支持的文件下载

download_with_resume(url: str, target: str | Path, **kwargs) -> DownloadResult**

从 URL 下载文件，支持断点续传中断的下载。此函数在失败的情况下也可以多次重试下载，并在标记为完成之前确保文件被完整下载。

参数

• url：要下载的文件的 URL。
• target：文件应保存的目标路径。
• headers：请求的可选标头。
• make_executable：是否使文件可执行。
• chunk_size：要下载的数据块的大小。
• poll_manager：要使用的 urllib3.PoolManager 实例。
• max_retries：下载的最大重试次数。
• timeout：请求的超时时间。
• wait_interval：重试之间的等待时间。
• overwrite_existing：是否覆盖现有文件。
• resume_from_existing_part_file：是否从现有部分文件继续下载。默认为 True。

返回：包含下载状态和文件路径的 DownloadResult 对象。

4. 部分文件存在

partial_file_exists(target: str | Path) -> bool**

一个辅助函数，用于检查给定目标路径是否存在部分下载的文件。

参数

• target：要检查现有部分文件的文件路径。

返回：一个布尔值，指示是否存在部分文件。

类

文件下载结果类

DownloadResult

一个 NamedTuple，用于存储下载操作的结果。它包含

• status：下载的最终状态（来自 DownloadStatus 枚举）。
• path：下载文件的路径。

依赖项

此存储库使用以下外部库

• urllib3：用于发送 HTTPS 请求。
• truststore：用于创建和管理 SSL 上下文。