PyInfra 3.8.0

PyInfra 3.8.0 发布说明

Big release with a lot of fixes and improvements across the board! We’re also switching to full semver (so .0 on the 3.8.0) for this release and others going forward. Thank you to all contributors!

这是一个包含全面修复和改进的大型版本！从本次发布开始，我们将全面采用语义化版本控制（SemVer），因此版本号定为 3.8.0。感谢所有贡献者！

Core (核心)

api.command: fix make_formatted_string_command adding unwanted spaces between format args (#1610) (@wowi42) 修复 make_formatted_string_command 在格式化参数间添加多余空格的问题 (#1610) (@wowi42)
api: decouple core API from click by introducing pluggable output functions (#1616) (@wowi42) 通过引入可插拔的输出函数，将核心 API 与 click 解耦 (#1616) (@wowi42)

Operations/facts (操作与事实)

operations: expand quoting of user inputs to prevent command injection (#1576) (@wowi42) 扩展用户输入的引用处理，以防止命令注入 (#1576) (@wowi42)
facts.selinux.FileContext: handle missing SELinux context (#1581) (@wowi42) 处理缺失 SELinux 上下文的情况 (#1581) (@wowi42)
facts.systemd: ensure that user-mode systemd facts do not fail if user manager is not available (#1604) (@martenlienen) 确保当用户管理器不可用时，用户模式的 systemd 事实不会失败 (#1604) (@martenlienen)
facts.apt.AptSources: add deb822 format support (#1465) (@maisim) 增加对 deb822 格式的支持 (#1465) (@maisim)
operations.files: expand diff output (#1552) (@gwelch-contegix) 扩展 diff 输出内容 (#1552) (@gwelch-contegix)
facts.server: add Ports fact returning all listening ports (#1637) (@wowi42) 新增 Ports 事实，返回所有监听端口 (#1637) (@wowi42)
facts.choco: remove invalid shell_executable on ChocoPackages (#1598) (@wowi42) 移除 ChocoPackages 上无效的 shell_executable (#1598) (@wowi42)
operations.git.repo: add depth support (#1656) (@bsaussay) 增加深度（depth）支持 (#1656) (@bsaussay)
operations.docker: add extra parameters (#1593) (@wowi42) 增加额外参数 (#1593) (@wowi42)
operations.selinux.port: fix a bug where the op would not find existing labels if sepolicy command was missing from the host (#1654) (@yacoob) 修复当主机缺少 sepolicy 命令时，操作无法找到现有标签的 Bug (#1654) (@yacoob)
operations.server.reboot: survive dead SSH session during askpass cleanup (#1665) (@wowi42) 在 askpass 清理期间，即使 SSH 会话中断也能正常运行 (#1665) (@wowi42)
facts.docker: add version, container, image, network detail facts (#1668) (@wowi42) 新增版本、容器、镜像、网络详细信息事实 (#1668) (@wowi42)
facts.server: add AuthorizedKeys, make user_authorized_keys idempotent (#1670) (@wowi42) 新增 AuthorizedKeys，使 user_authorized_keys 具备幂等性 (#1670) (@wowi42)
facts.crontab: match full crontab(5) env var syntax (#1678) (@wowi42) 匹配完整的 crontab(5) 环境变量语法 (#1678) (@wowi42)
operations.files: add limit_rate to cap download bandwidth (#1681) (@wowi42) 新增 limit_rate 以限制下载带宽 (#1681) (@wowi42)
operations.files: add files.unarchive (#1631) (@wowi42) 新增 files.unarchive 操作 (#1631) (@wowi42)
operations.docker: add support for custom command (#1625) (@EricDriussi) 增加对自定义命令的支持 (#1625) (@EricDriussi)
facts.{yum,dnf,zypper}: add filename field to each repository entry (#1684) (@wowi42) 为每个仓库条目添加 filename 字段 (#1684) (@wowi42)
operations.server: dispatch BSD rc.d before sysvinit in server.service (#1685) (@wowi42) 在 server.service 中，优先调度 BSD rc.d 而非 sysvinit (#1685) (@wowi42)
operations.files.download: reconcile mode/user/group on existing files (#1687) (@wowi42) 协调现有文件的模式/用户/组权限 (#1687) (@wowi42)

Connectors (连接器)

connectors.ssh: fix parsing of SSH config file comments (#1574) (@wowi42) 修复 SSH 配置文件注释的解析问题 (#1574) (@wowi42)
connectors: use gevent.subprocess in util for macOS + Python 3.13 compatibility (#1653) (@Yaminyam) 在 util 中使用 gevent.subprocess 以兼容 macOS 和 Python 3.13 (#1653) (@Yaminyam)
connectors: show askpass generation errors (#1628) (@matthijskooijman) 显示 askpass 生成错误 (#1628) (@matthijskooijman)
connectors.ssh: honor ConnectTimeout through ProxyJump (#1679) (@wowi42) 通过 ProxyJump 时遵循 ConnectTimeout 设置 (#1679) (@wowi42)

Docs/meta (文档与元数据)

docs: facts.opkg, operations.opkg - add note about Openwrt switch to apk (#1595) (@morrison12) 添加关于 Openwrt 切换至 apk 的说明 (#1595) (@morrison12)
docs: fix extra trailing comma in operation argument lists (#1596) (@morrison12) 修复操作参数列表中多余的尾随逗号 (#1596) (@morrison12)
docs: fix missing keyword-only args in operations documentation (#1600) (@morrison12) 修复操作文档中缺失的仅关键字参数 (#1600) (@morrison12)
docs: fix generate_operations_docs.py and add docs build to CI (#1614) (@wowi42) 修复 generate_operations_docs.py 并将文档构建加入 CI (#1614) (@wowi42)
docs: operations.files - clarify template vars use (#1615) (@EricDriussi) 明确模板变量的使用说明 (#1615) (@EricDriussi)
docs: update Python version requirements (#1627) (@pascal-cm) 更新 Python 版本要求 (#1627) (@pascal-cm)
docs: generate fact/operation docs for modules (vs files) (#1606) (@morrison12) 为模块（而非文件）生成事实/操作文档 (#1606) (@morrison12)
docs: clarify group_data/ is file-inventory only (#1696) (@wowi42) 明确 group_data/ 仅用于文件清单 (#1696) (@wowi42)

Other (其他)

facts+operations: add GpgKeyrings fact and gpg.* operations (#1460) (@maisim) 新增 GpgKeyrings 事实和 gpg.* 操作 (#1460) (@maisim)
dependencies/paramiko: support paramiko v4, remove DSS key support (#1525) (@5long) 支持 paramiko v4，移除 DSS 密钥支持 (#1525) (@5long)
operations.server.mount: fix not detecting already-mounted devices (#1611) (@wowi42) 修复无法检测已挂载设备的问题 (#1611) (@wowi42)
facts+operations: add uv support (#1500) (@morrison12) 增加对 uv 的支持 (#1500) (@morrison12)
meta,api: lazy load fact and operation modules (#1609) (@Dexmachi) 延迟加载事实和操作模块 (#1609) (@Dexmachi)
facts,operations: migrate shlex.quote to StringCommand + QuoteString everywhere (#1617) (@wowi42) 全面迁移 shlex.quote 至 StringCommand + QuoteString (#1617) (@wowi42)
operations+facts: server.Processes fact and server.kill operation (#1583) (@wowi42) 新增 server.Processes 事实和 server.kill 操作 (#1583) (@wowi42)
arguments: add dzdo support for privilege escalation, including CLI options and configuration (#1633) (@guinuxbr) 增加 dzdo 权限提升支持，包括 CLI 选项和配置 (#1633) (@guinuxbr)
zfs: return an empty dict if zfs/zpool commands are not available (#1650) (@yacoob) 若 zfs/zpool 命令不可用，则返回空字典 (#1650) (@yacoob)
meta,ci: make ruff checks in ci+dev-lint.sh consistent progress: finish spinner as soon as possible (#1657) (@matthijskooijman) 使 ci+dev-lint.sh 中的 ruff 检查进度保持一致：尽快结束加载动画 (#1657) (@matthijskooijman)
feat: support SSH IdentityAgent config directive (#1630) (@wowi42) 支持 SSH IdentityAgent 配置指令 (#1630) (@wowi42)
security: quote untrusted values in command construction across connectors, operations, and util (#1664) (@wowi42) 在连接器、操作和工具的命令构建中对不可信值进行引用处理 (#1664) (@wowi42)
ci: upgrade default Python to 3.14 (#1667) (@wowi42) 将默认 Python 升级至 3.14 (#1667) (@wowi42)
fix: Add timeout support in FunctionCommand (#1663) (@Tbruno25) 为 FunctionCommand 增加超时支持 (#1663) (@Tbruno25)
feat: add config.INHERIT_ENV to pass local process env vars to all op… (#1677) (@maisim) 新增 config.INHERIT_ENV 以将本地进程环境变量传递给所有操作 (#1677) (@maisim)
Add support for using AI coding agents (#1672) (@DonDebonair) 增加对 AI 编码代理的支持 (#1672) (@DonDebonair)
fix(cli): exclude imports from group data (#1676) (@wowi42) 从组数据中排除导入项 (#1676) (@wowi42)
fix: scripts/generate_facts_docs: add canonical-name label for re-exported facts (#1686) (@wowi42) 为重新导出的事实添加规范名称标签 (#1686) (@wowi42)
fix(operations.git): don’t pull when already up to date (#1690) (@wowi42) 当已是最新状态时不再执行 pull (#1690) (@wowi42)
feat(facts): add requires_command guard sentinel and check_preconditions() hook (@maisim) 新增 requires_command 守卫哨兵和 check_preconditions() 钩子 (@maisim)
feat(facts.zfs): add check_preconditions for ZfsDatasets and update command method (@maisim) 为 ZfsDatasets 添加 check_preconditions 并更新命令方法 (@maisim)
feat(operations.docker): add login/logout operations (#1694) (@wowi42) 新增 login/logout 操作 (#1694) (@wowi42)
feat(operations.docker): add compose operation (#1693) (@wowi42) 新增 compose 操作 (#1693) (@wowi42)
feat(operations.docker): add build operation (#1695) (@wowi42) 新增 build 操作 (#1695) (@wowi42)
operations/facts: modernize apt.key to replace deprecated apt-key command (@maisim) 现代化 apt.key 以替换已弃用的 apt-key 命令 (@maisim)
chore: make Claude use modern type hints (#1692) (@DonDebonair) 使 Claude 使用现代类型提示 (#1692) (@DonDebonair)
feat(apt): add purge option to apt.packages (closes #1698) (#1702) (@mvanhorn) 为 apt.packages 增加 purge 选项 (#1702) (@mvanhorn)
fix(facts): add semicolons to TmpDir shell script for sh -c compatibility (#1703) (@wucm6) 为 TmpDir shell 脚本添加分号，以兼容 sh -c (#1703) (@wucm6)