企业官网建设流程全解析

mypy-boto3-acm是专为 AWS Certificate Manager（ACM）生成的stubs-only 类型存根包：它不为运行时提供任何 AWS API 调用能力，而是为boto3的 ACM 客户端、分页器、等待器、字面量与请求/响应TypedDict形状提供完整的类型标注，让mypy、pyright与 IDE 补全可以静态捕获 ACM 代码中的字段拼写与结构错误。本文以仓库内维护的 mypy-boto3-acm 官方文档 为主体，系统讲解三种安装选型、核心类型化用法与常见误区，并结合 Context Hub 仓库的 CLI 实现（get.js、registry.js）说明如何按语言与版本获取该文档。读完本文，你将能够在 ACM 证书管理代码中完整落地类型安全，并理解存根包与运行时 SDK 的边界。

Golden Rule：存根只服务静态检查，运行时仍用 boto3

mypy-boto3-acm的定位极其明确：它是类型存根，不是运行时 SDK。真实的 ACM API 调用（证书申请、校验、导入、续期、吊销等）必须继续通过boto3的Session().client("acm")完成；存根包只是在编译期/编辑期为这些调用提供类型信息。正因如此，使用前需要先选定一种“类型化模式”：

• boto3-stubs[acm]：当你想让Session().client("acm")在 IDE、mypy、pyright中自动推断出类型时使用。它通过重载（overload）机制把 ACM 客户端类型自动关联到client("acm")调用上，无需手写任何注解。
• mypy-boto3-acm：当你只想要 ACM 专属的类型存根，并且愿意显式注解ACMClient、分页器、等待器、字面量（literals）与type_defs时使用。它是按服务拆分的独立包，体积最小、环境最干净。
• boto3-stubs-lite[acm]：当完整存根对 PyCharm 或内存受限环境过重时使用。lite 包更省内存，但上游明确指出它不提供session.client/resource的重载，因此无法自动推断客户端类型，需要显式标注。

选择逻辑可以概括为：追求零注解的“开箱即用”体验选boto3-stubs[acm]；追求最小安装面、接受显式注解选mypy-boto3-acm；PyCharm 在大型Literal重载下卡顿选boto3-stubs-lite[acm]。这份选型指南同样适用于仓库中其他服务级存根文档（参见 boto3-stubs 总指南），其中包含[essential]、[full]、按服务拆分安装等更细粒度的策略。

安装与版本对齐

存根包的签名必须与boto3的实际 API 保持一致，因此文档强烈建议将boto3与存根版本钉在一起安装。文档给出的推荐命令（对应boto3==1.42.3）：

# 推荐：自动类型发现 python -m pip install "boto3==1.42.3" "boto3-stubs[acm]==1.42.3" # 低内存选项 python -m pip install "boto3==1.42.3" "boto3-stubs-lite[acm]==1.42.3" # 独立 ACM 存根 python -m pip install "boto3==1.42.3" "mypy-boto3-acm==1.42.3"

使用uv或poetry时采用等价写法：

uv add "boto3==1.42.3" "boto3-stubs[acm]==1.42.3" poetry add "boto3==1.42.3" "boto3-stubs[acm]==1.42.3"

三点关键提示：

• boto3-stubs[acm]是最省事的选择，Session().client("acm")无需额外注解即可推断出ACMClient。
• boto3-stubs-lite[acm]在 PyCharm 处理大型Literal重载变慢时更安全。
• mypy-boto3-acm不替代boto3。如果只安装存根包而不安装boto3，类型检查可能通过，但运行时导入或 AWS 调用必然失败——这恰恰说明存根只解决“类型”问题，不解决“运行”问题。

认证与运行时配置

类型存根包不会改变运行时认证、重试、端点或权限行为，这些仍然由boto3与 AWS 标准凭据链负责。本地开发常用的环境变量包括：

• AWS_PROFILE
• AWS_DEFAULT_REGION
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_SESSION_TOKEN

典型本地配置：

export AWS_PROFILE="dev" export AWS_DEFAULT_REGION="us-east-1"

或使用共享配置与凭据文件：

aws configure

类型化客户端初始化（显式注解版本）：

from boto3.session import Session from mypy_boto3_acm import ACMClient session = Session(profile_name="dev", region_name="us-east-1") acm: ACMClient = session.client("acm")

需要特别指出的是：ACM 在 boto3 中是纯客户端型服务。AWS 文档描述的 ACM 客户端表面只包含一个分页器（list_certificates）和一个等待器（certificate_validated）；与 S3、IAM 不同，ACM 没有 boto3 的 resource 接口可供类型化，因此mypy-boto3-acm也不会提供 resource 类型。

核心用法

类型化 ACM 客户端

不写任何存根相关注解、仅靠boto3-stubs[acm]重载时，代码与原生 boto3 完全一致：

from boto3.session import Session from mypy_boto3_acm import ACMClient acm: ACMClient = Session(region_name="us-east-1").client("acm") response = acm.list_certificates(CertificateStatuses=["ISSUED"]) for cert in response["CertificateSummaryList"]: print(cert["CertificateArn"], cert.get("DomainName"))

response["CertificateSummaryList"]中的每个元素都是类型化的CertificateSummaryTypeDef，cert["CertificateArn"]与cert.get("DomainName")的字段名和类型都能被静态检查器验证——拼错字段会在编辑期立即报错，而不是等 AWS 返回ValidationException。

类型化分页器（Paginator）

AWS 为 ACM 文档化了唯一的分页器：list_certificates。分页器通过get_paginator获取，类型同样来自存根包：

from boto3.session import Session from mypy_boto3_acm import ACMClient from mypy_boto3_acm.paginator import ListCertificatesPaginator acm: ACMClient = Session(region_name="us-east-1").client("acm") paginator: ListCertificatesPaginator = acm.get_paginator("list_certificates") for page in paginator.paginate(CertificateStatuses=["ISSUED"]): for cert in page["CertificateSummaryList"]: print(cert["CertificateArn"])

注意paginate()返回的是迭代器，每个page对应一页分页结果，其结构（如CertificateSummaryList）由ListCertificatesPaginator的签名约束。

类型化等待器（Waiter）

ACM 唯一的等待器是certificate_validated，用于等待证书完成验证（例如 DNS 验证记录生效）：

from boto3.session import Session from mypy_boto3_acm import ACMClient from mypy_boto3_acm.waiter import CertificateValidatedWaiter acm: ACMClient = Session(region_name="us-east-1").client("acm") waiter: CertificateValidatedWaiter = acm.get_waiter("certificate_validated") waiter.wait( CertificateArn="arn:aws:acm:us-east-1:123456789012:certificate/...", WaiterConfig={"Delay": 60, "MaxAttempts": 30}, )

CertificateArn必须是 ACM 证书 ARN（示例中的123456789012需替换为你的 AWS 账号 ID）。WaiterConfig控制轮询节奏：Delay为每次轮询间隔秒数，MaxAttempts为最大尝试次数，两者均由waiter.wait的WaiterConfigTypeDef类型化约束，传入非法键会在静态检查阶段被发现。

用 type_defs 显式构造请求形状

在辅助函数中希望显式构造请求/响应结构时，使用type_defs中的TypedDict：

from mypy_boto3_acm.type_defs import RequestCertificateRequestTypeDef, TagTypeDef tags: list[TagTypeDef] = [ {"Key": "service", "Value": "payments"}, ] request: RequestCertificateRequestTypeDef = { "DomainName": "api.example.com", "ValidationMethod": "DNS", "SubjectAlternativeNames": ["www.example.com"], "Tags": tags, }

这段代码演示了申请证书（RequestCertificate）的请求结构：DomainName为主域名，ValidationMethod为验证方式，SubjectAlternativeNames为 SAN 附加域名，Tags为证书标签。由于type_defs全部是TypedDict，多余键、缺失必填键、错误值类型都会在类型检查时暴露。

用 literals 约束取值

对于枚举型字段，使用literals模块中的字面量类型获得“填写即校验”的体验：

from mypy_boto3_acm.literals import CertificateStatusType, ValidationMethodType status: CertificateStatusType = "ISSUED" validation_method: ValidationMethodType = "DNS"

CertificateStatusType约束证书状态（如PENDING_VALIDATION、ISSUED、INACTIVE、EXPIRED、VALIDATION_TIMED_OUT、REVOKED、FAILED等），ValidationMethodType约束验证方式（EMAIL/DNS）。如果写出"issud"之类的拼写错误，mypy与pyright会直接报出“非法字面量”错误。

用 TYPE_CHECKING 隔离开发期存根

如果生产镜像不希望携带存根包，可以将存根导入放在类型检查分支中，运行时回退到object，以规避 PyPI 文档中记录的一个已知pylint告警：

from typing import TYPE_CHECKING from boto3.session import Session if TYPE_CHECKING: from mypy_boto3_acm import ACMClient else: ACMClient = object acm = Session(region_name="us-east-1").client("acm") typed_acm: "ACMClient" = acm

此模式的关键在于：TYPE_CHECKING分支在运行期不会执行，存根包因此无需安装进生产环境；而类型检查器仍然能看到ACMClient的真实定义，保证typed_acm的类型安全。这正是“存根是开发期依赖”理念的标准落地写法。

工具链说明

• 上游文档声明boto3-stubs[acm]支持 VSCode、PyCharm、Emacs、Sublime Text，以及mypy与pyright两个主流类型检查器。
• PyCharm 在处理Literal重载时可能变慢。若遇到卡顿，上游建议改用boto3-stubs-lite，或关闭 PyCharm 内置类型检查器，单独运行mypy/pyright作为 CI 与编辑期校验。
• 独立mypy-boto3-acm包的适用场景是“只想装 ACM 类型”。但此时工厂函数与辅助函数应显式返回ACMClient、分页器、等待器或type_defs类型，而不是依赖boto3-stubs的重载推断——因为独立存根包不提供session.client("acm")的重载。

常见误区清单

• 不要把mypy-boto3-acm当成运行时 SDK：真实的 AWS 调用仍然需要boto3。
• 不要随意让boto3与存根版本错位：本包紧跟对应的 boto3 版本线，签名需要对齐，预测性优先时务必一起钉版本。
• 不要指望 lite 包自动推断Session().client("acm")：lite 缺少重载，必须显式添加ACMClient注解。
• 不要在代码中导入带连字符的包名：Python 导入根使用下划线，即mypy_boto3_acm。
• 不要期待类型化的 ACM resource 接口：ACM 只通过 client + 一个分页器 + 一个等待器 + literals +type_defs暴露。
• 不要假设类型存根能校验 AWS 凭据、IAM 权限、区域可用性或证书状态：它们只改善静态类型，任何运行时约束仍需 AWS 侧保障。

版本敏感说明

• PyPI 上mypy-boto3-acm 1.42.3标注为 2025 年 12 月 4 日发布，本文档记录版本即为1.42.3（元数据见 DOC.md 头部）。
• 托管文档站点可能领先于已发布的 PyPI 包：文档记录的生成命令曾对应boto3==1.42.61，而 PyPI 仍发布1.42.3。当二者不一致时，以已安装的包版本与 PyPI 元数据为准，它是精确兼容性的权威来源。
• PyPI 声明本包由mypy-boto3-builder 8.12.0生成。
• 根据维护者仓库针对boto3-stubs的迁移指引，新一代types-boto3系列包改用types_boto3_<service>导入根，而非mypy_boto3_<service>。若团队迁移到该新系列，需同步更新所有导入语句。

在 Context Hub 中按语言与版本获取本文档

本文档是 Context Hub 仓库内维护的“版本化、语言化”内容：它位于 content/aws/docs/mypy-boto3-acm/python/DOC.md，是 ACM 存根包的Python 语言变体。Context Hub 的定位是给编码 Agent 提供经过整理的版本化文档，避免 Agent 幻觉化 API——README 中给出的工作流是“搜索、获取、使用”：chub search查找相关文档，chub get <id> --lang py获取对应语言变体（参见 README.md）。

从 CLI 源码可以看到这套机制的实现细节：chub get命令会调用 registry.js 的resolveDocPath按语言与版本解析出具体路径（如content/aws/docs/mypy-boto3-acm/python/DOC.md），语言别名（py→python等）由 normalize.js 归一化，随后由 get.js 的fetchEntries加载正文并输出。这意味着：当本仓库的 ACM 存根文档更新时，Agent 通过chub get拉取到的始终是与当前仓库一致的最新版本，且可与其他服务（如 boto3-stubs 总指南、ACM JavaScript 变体）形成互补，构成完整的 ACM 编程参考面。

结语与官方来源

mypy-boto3-acm的核心理念可总结为一句话：类型存根把 AWS API 的“形状知识”前置到编译期，让证书管理代码的常见错误在写代码时就暴露。无论你选择boto3-stubs[acm]的零注解体验、mypy-boto3-acm的最小独立安装，还是boto3-stubs-lite[acm]的低内存方案，都需要始终牢记存根与boto3的边界，并保持版本对齐。

本指南对应的上游官方来源包括：PyPI 包页面（mypy-boto3-acm）、维护者文档站点（youtype.github.io/boto3_stubs_docs/mypy_boto3_acm/）、AWS ACM boto3 参考（docs.aws.amazon.com/boto3/latest/reference/services/acm.html）以及维护者仓库（youtype/types-boto3）。本文基于的仓库内权威版本为 content/aws/docs/mypy-boto3-acm/python/DOC.md，版本与兼容性细节以已安装包与 PyPI 元数据为准。