示例工程【免费下载链接】python-docs-samplesCode samples used on cloud.google.com项目地址https://gitcode.com/GitHub_Trending/py/python-docs-samples点击查看免费下载本篇指南以 python-docs-samples 仓库的 CONTRIBUTING.md 为骨架系统讲解为 Google Cloud Python 代码样例仓库提交贡献的完整链路从提交 Issue、签署贡献者许可协议CLA、搭建多版本 Python 开发环境到遵循 AUTHORING_GUIDE.md 编写可复制运行的样例与配套测试再通过 nox 或 Docker 在本地验证最终经双人评审合并。读完本文你将掌握该仓库对样例代码在风格、类型注解、依赖管理、Region Tag、测试策略等方面的全部硬性要求能够独立提交一份质量达标、一次过审的 Pull Request。一、贡献流程总览七步走通一个 Patchpython-docs-samples 欢迎任何形式的代码补丁Patches are always welcome!但流程上有明确的先后顺序。仓库在 CONTRIBUTING.md 中给出了完整步骤先提交 Issue如果你要新增一个代码样例或对现有样例做大范围修改必须先提交一个描述变更内容的 Issue在社区/维护者层面先讨论确认方向等待仓库 Owner 响应仓库 Owner 会及时回复。若几天内没有动静可以主动联系 Issue 上指派的 Owner 追问签署 CLA变更方案被接受后如果还没签过贡献者许可协议需要先完成 CLA 签署见下文第二节Fork 并开发测试Fork 本仓库开发并测试代码。所有样例都必须附带测试具体要求见 AUTHORING_GUIDE.md贴合既有风格确保代码风格与所在样例目录的既有代码保持一致补齐单元测试为代码准备一套完整、全部通过的单元测试提交 Pull Request提交 PR等待评审与合并。从源码结构看该仓库包含appengine、bigquery、storage、functions、generative_ai等上百个按 Google Cloud 服务划分的顶层目录每个目录下都同时存在*.py样例、requirements.txt与*_test.py例如 storage/samples/snippets 下的acl_test.py、quickstart_test.py、iam_test.py等这套样例 依赖 测试三位一体的结构正是上述流程的产物。二、Contributor License Agreements贡献前的法律门槛在仓库接受任何代码之前必须跨越贡献者许可协议CLA这道法律关卡。仓库区分两种签署场景个人 CLAIndividual CLA如果你是以个人身份编写原始代码并且确信自己拥有这些代码的知识产权签署个人 CLA 即可公司 CLACorporate CLA如果你所在的公司希望允许你代表公司贡献代码则需由公司签署公司级 CLA。签署方式为在对应 CLA 页面填写并回传仓库收到已签署的 CLA 后才会开始接受你的 Pull Request。这属于贡献环节的硬性前置条件未签署 CLA 的 PR 将无法被合并。三、搭建本地开发环境多版本 Python 并行管理样例开发者与普通使用者最大的区别在于需要同时管理多个 Python 版本因为仓库要求样例兼容多个解释器版本。仓库为此提供了专门的 MAC_SETUP.mdMac 环境指南其核心思路是用pyenvpyenv-virtualenv实现多版本共存# 1. 安装 pyenvmacOS 上建议先装 HomebrewCatalina 10.15.x 需确保 Homebrew 2.1.13 brew update brew install pyenv # 2. 安装 pyenv-virtualenv 插件 brew install pyenv-virtualenv # 3. 将初始化脚本追加到 ~/.bashrcZSH 同样适用 eval $(pyenv init -) eval $(pyenv virtualenv-init -) # 4. 重载 shell source ~/.bashrcLinux 或 macOS 用户均可使用 pyenv 管理 Python 版本安装每个次要版本minor version对应的最新补丁版本即可。关于仓库要求的具体版本范围见下文Python 版本支持小节。四、样例编写规范AUTHORING_GUIDE 的硬性要求[C]ONTRIBUTING.md 明确指示编写、测试和贡献样例的全部细节见 AUTHORING_GUIDE.md。这份近千行的指南是仓库对样例代码的宪法核心目标有三个可复制粘贴即运行Copy-paste-runnable、用代码教学Teach through code、符合 Python 惯例Idiomatic。以下分点拆解其硬性规定。4.1 文件夹位置Folder Location样例的存放位置由所在仓库决定python-docs-samples 仓库样例应放在与所用 Google Cloud 服务/API 对应的顶层目录下。例如 Composer 相关样例放composer/下App Engine Standard 样例放appengine/standard/App Engine Flex 样例放appengine/flexible/概念相关的样例进一步归入子目录客户端库仓库library repositories样例放在库仓库的顶层samples/目录下快速入门类样例quickstart用于演示如何快速上手某服务/API 的样例应放在名为quickstart的目录中仓库中大量存在如 datastore/cloud-client/quickstart.py 即被指南点名作为 License Header 的示例。4.2 Python 版本支持指南明确要求样例支持Python 3.9、3.10、3.11、3.12、3.13若所用 API/服务有特殊版本要求则按 API 要求执行。这与 noxfile-template.py 中的ALL_VERSIONS [3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14]定义相互呼应——具体测试哪些版本由各目录的 noxfile_config.py 中的ignored_versions决定。4.3 License Header 与 ShebangLicense Header所有源码文件必须以 Apache 2.0 许可头开头参见仓库 LICENSE 中的应用说明典型样式可参考 datastore/cloud-client/quickstart.pyShebang仅当样例是命令行应用时首行才写#!/usr/bin/env python并用空行与正文分隔Web 应用与测试文件一律不写 shebang。4.4 编码风格PEP 8 Google Python Style样例代码需遵循 [PEP 8] 与 Google Python Style Guide并接受 flake8 自动化检查。仓库在 noxfile-template.py 中固化了一套FLAKE8_COMMON_ARGS具体包括忽略规则ANN101self 缺类型注解、ANN102、E121、E123、E126、E203、E226、E24、E266、E501行过长、E704、W503、W504、I202关键阈值--max-complexity20、--max-line-length88、--import-order-stylegoogle排除目录.nox、.cache、env、lib、generated_pb2、*_pb2.py、*_pb2_grpc.py。同时仓库推荐使用 Black 统一格式化默认 noxfile 提供了blackensession 供一键调用见第六节命令Owlbot 自动化工具会在新 PR 上自动运行blackensession。若使用 pylint样例不要求满足其默认设置中超出 PEP 8 范围的告警如参数过多局部变量过多。此外指南强调样例应自包含、可自上而下通读、尽量自文档化优先使用描述性名称如upload_file、list_resource_records优先函数而非类减少间接层偏向命令式编程。4.5 导入 Google Cloud 库的规范写法统一采用从google.cloud导入版本化模块的风格例如from google.cloud import texttospeech_v1 client texttospeech_v1.TextToSpeechClient() audio_config texttospeech_v1.AudioConfig( audio_encodingtexttospeech_v1.AudioEncoding.MP3 )所有常用客户端和类型都暴露在版本化模块如texttospeech_v1之下。4.6 GAPIC 请求对象的创建方式GAPIC 库由 proto 定义经生成器生成API 消息统一以proto-plus消息类暴露。指南强烈推荐两种创建方式并明确不推荐字典构造方式一构造函数直接实例化推荐from google.cloud import tasks_v2 task tasks_v2.Task( http_requesttasks_v2.HttpRequest( http_methodtasks_v2.HttpMethod.POST, urlhttps://pubsub.googleapis.com/v1/projects/my-project/topics/testtopic:publish, bodyb..., oauth_tokentasks_v2.OAuthToken( service_account_emailmy-svc-acctmy-project.iam.gserviceaccount.com ) ) )方式二空对象 逐属性赋值http_request tasks_v2.HttpRequest() http_request.http_method tasks_v2.HttpMethod.POST http_request.url https://pubsub.googleapis.com/... task tasks_v2.Task() task.http_request http_request方式三不推荐字典构造——难以利用类型检查IDE 无法提供智能提示。4.7 函数与类型注解顶层函数应使用描述性参数名并附简洁 docstring。类型注解按 PEP 484 书写def adder(a: int, b: int) - int: return a b类型注解通过flake8-annotations强制检查启用开关是各目录noxfile_config.py中的enforce_type_hints字段默认模板为False仓库根目录 noxfile_config.py 为True——新样例必须带类型注解存量样例逐步补齐。4.8datetime必须带时区凡使用 protobuf 的库无时区的 datetime 转 protobuf 时间戳可能产生意外行为因此一律创建带时区对象import datetime now datetime.datetime.now(tzdatetime.timezone.utc)4.9 README 与依赖声明每个样例需有README.md说明安装、配置与运行方式涉及创建 GCP 项目/资源的步骤应链接到 Google Cloud 官方文档以避免重复维护每个样例必须提供requirements.txt所有依赖固定到具体版本Flask1.1.1 PyMySQL0.9.3 SQLAlchemy1.3.12测试依赖如 pytest与运行时依赖不同时放入单独的requirements-test.txt。仓库中绝大多数目录都遵循这一约定例如 dlp/snippets、secretmanager/snippets 下均有这两个文件。4.10 Region Tags供文档直接内嵌的代码标记Region Tag 是源码中以[START region_tag]/[END region_tag]包裹的注释块圈定可被复制进 REPL 直接运行的核心样例逻辑用于将代码直接集成到 Google Cloud 官方文档。规范要求置于 License Header 之后对运行样例至关重要的 import 应包含在 Region Tag 内纯命令行辅助的 import如sys放在外面。例如 storagecontrol/hierarchical-namespace 目录下的样例即以[START example_storage_control_create_folder]形式标注。五、测试规范样例必须带测试且必须是系统测试Tests are required for all samples——这是贡献的底线。指南对测试提出了非常具体的策略要求。5.1 测试风格与结构只用 pytest使用 pytest 风格与普通assert禁用unittest风格及assertX方法仓库根目录的 pytest.ini 已配置-v --tbnative与norecursedirs排除项Arrange, Act, Assert 三段式先创建并配置被测组件避免嵌套重可读性再执行被测代码最后用assert校验结果测试间相互独立、顺序无关并支持并行执行可在requirements-test.txt中加入pytest-parallel或pytest-xdist开启并行。5.2 外部资源与临时资源测试应尽量运行在线上生产版云 API 与资源上以便发现上游破坏性变更对外部资源强烈反对打 mock必须预先存在的外部资源如 Cloud SQL 实例通过环境变量传入资源内部的特定数据则由测试在 Arrange 阶段创建、结束前清理临时资源命名需带 UUID 保证唯一并在测试完成后显式删除推荐在 pytest fixture 中用finally确保清理必然执行。命名示例如下glossary_id ftest-glossary-{uuid.uuid4()} encrypted_disk_name ftest-disk-{uuid.uuid4().hex[:5]}5.3 避免无限循环与重试gRPC 长时运行操作LRO的result()调用必须传 timeout 参数例如operation.result(60)60 秒后抛错严禁无参等待必要时用pytest.mark.flaky(max_runs3, min_passes1)标记易抖动测试所有 RPC 都可能抖动新版google-cloud客户端通常自动重试旧版 api-client 不会需用google.api_core.retry.Retry装饰器默认重试瞬时错误或使用backoff库指数退避。5.4 控制台输出与 list 方法过滤样例若打印输出测试应捕获 stdout 到文件校验输出包含关键信息而非语法位置测试list类方法时优先使用filter/filter_参数收窄结果集如按时间戳过滤日志或用page_size限制分页大小避免列出全量资源拖慢测试。六、运行测试的两条路nox 与 Docker6.1 环境变量准备系统测试前提由于所有测试都是使用真实资源的系统测试运行前需要一个已启用结算的 Google Cloud 项目并按 testing/test-env.tmpl.sh 设置所需环境变量cp testing/test-env.tmpl.sh testing/test-env.sh editor testing/test-env.sh # 修改 GOOGLE_CLOUD_PROJECT 等值 source testing/test-env.sh # 导出环境变量6.2 方式一nox推荐更快nox 是仓库测试的统一管理器负责跑 flake8 静态检查、多版本 pytest、README 生成等。使用步骤全局安装pip install nox将 noxfile-template.py 复制为项目目录下的noxfile.pycp noxfile-template.py PATH/TO/YOUR/PROJECT/noxfile.py cd PATH/TO/YOUR/PROJECT/说明nox 只检测noxfile_config.py所在目录的tests/目录以及同目录下*_test.py/test_*.py命名的文件参见 noxfile-template.py 的 glob 逻辑。常用命令nox -s lint # 仅跑风格检查flake8 nox -s blacken # 用 Black 格式化当前目录 .py 文件 nox -s py-3.10 # 用指定 Python 版本跑测试 nox -s py-3.10 -- snippets_test.py # 只跑指定测试文件 nox -s py-3.10 -- snippets_test.py::test_list_blobs # 只跑指定测试用例模板中的pysession 会按ALL_VERSIONS逐版本执行被ignored_versions排除的版本直接skip见 noxfile-template.pypytest 由_session_tests统一驱动自动安装requirements.txt与requirements-test.txt存在时附带--only-binary :all存在constraints.txt时追加-c约束。lintsession 还会根据enforce_type_hints决定是否安装flake8-annotations。6.3noxfile_config.py定制测试行为各目录可通过 noxfile_config.py 覆盖模板中的TEST_CONFIG支持ignored_versions跳过特定 Python 版本的测试enforce_type_hints是否强制类型注解检查gcloud_project_env指定用于测试的 GCP 项目环境变量键默认GOOGLE_CLOUD_PROJECT可改为BUILD_SPECIFIC_GCLOUD_PROJECT以使用 CI 专属项目pip_version_override固定 pip 版本envs向测试注入额外环境变量禁止放密钥。6.4 方式二Docker贴近 CI配置更省安装 Docker 后使用仓库脚本 scripts/run_tests_local.shcd cdn ../scripts/run_tests_local.sh . # 运行默认 sessionslint 各 Python 版本 ../scripts/run_tests_local.sh . lint # 只运行 lint若测试需要服务账号将 JSON 密钥放到testing/service-account.jsonmacOS 上需先用brew install coreutils安装coreutils。这种方式同样可用于模拟 CI 环境。七、环境变量与 Secrets密钥只走 Secret Manager新增普通环境变量若目录无noxfile_config.py先复制仓库根的 noxfile_config.py将变量加入TEST_CONFIG_OVERRIDE[envs]字典例如{DJANGO_SETTINGS_MODULE: mysite.settings}新增密钥类变量Secrets密钥统一托管在 Cloud Secret Manager 中修改流程为在 PR 中把新环境变量加入 testing/test-env.tmpl.sh运行 scripts/decrypt-secrets.sh 拉取解密后的testing/test-env.sh将新变量写入testing/test-env.sh运行 scripts/encrypt-secrets.sh 加密回传 Secret Manager。八、代码评审双人把关后合并满足上述全部条件后PR 需要两名评审人批准才能合入 main第一位是所贡献产品领域的CODEOWNER部分产品有多位 CODEOWNER 可选可手动改派更熟悉该工作的队友第二位是仓库 Owner负责把关对仓库整体健康有害的问题技术债、测试抖动等。两人都会被自动指派若仓库 Owner 评审人一两天内无响应且不在休假可以友好提醒若评审人休假可用blunderbuss: assign标签改派新评审人。这一双保险机制保证了单个样例的领域正确性与仓库整体的长期可维护性。九、调试手段贡献者可以正常使用 Python 调试器import pdb; pdb.set_trace()Python 3.7或breakpoint()3.7IntelliJ、VSCode 等 IDE 的断点调试同样适用。十、FAQ 速览有没有标杆样例可参考有。仓库官方推荐以 Storage 客户端样例storage/cloud-client作为编写样例与测试的参照客户端库在哪各 Google Cloud 服务的 Python 客户端库位于googleapis组织的python-API仓库中每个仓库对应一个库如google-cloud-bigquery样例放哪见 4.1 文件夹位置规则谁评审我的 PR自动指派给仓库的 python-samples-reviewers 团队可用blunderbuss: assign改派。结语一份合格的 python-docs-samples 贡献本质上要同时满足三套约束流程约束Issue 先行、签署 CLA、双人评审、编写约束固定版本依赖、Region Tag、类型注解、flake8/Black 风格、测试约束pytest 系统测试、UUID 临时资源、LRO 超时与 RPC 重试。把握住 CONTRIBUTING.md 与 AUTHORING_GUIDE.md 这两份文档再配合 noxfile-template.py 与 noxfile_config.py 的本地验证闭环你的下一个 PR 就能以最快速度、最少返工通过评审。赞分享示例工程【免费下载链接】python-docs-samplesCode samples used on cloud.google.com项目地址https://gitcode.com/GitHub_Trending/py/python-docs-samples点击查看免费下载相关推荐python-docs-samples 实战指南在本地配置、运行并测试 Google Cloud Python 示例代码python docs samples 实战指南在本地配置、运行并测试 Google Cloud Python 示例代码 本指南以 python docs s示例工程青龙面板API实战4类高频操作替代重复点击青龙面板API实战4类高频操作替代重复点击 青龙面板QingLong是一个定时任务管理平台支持 Python、JavaScript、Shell 脚本的定任务调度后端前端python-docs-samples 的 Python 示例编写指南从代码规范、GAPIC 对象构造到 nox 自动化测试的完整实践python docs samples 的 Python 示例编写指南从代码规范、GAPIC 对象构造到 nox 自动化测试的完整实践 python docs示例工程上一篇如何用nMigen构建复杂数字硬件从入门到精通的完整教程下一篇如何快速上手rofi-emoji5分钟学会在Linux中高效插入表情符号创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考