FloPy开发者指南从运行测试套件到提交新Package的7步开发工作流【免费下载链接】flopyA Python package to create, run, and post-process MODFLOW-based models.项目地址: https://gitcode.com/gh_mirrors/fl/flopyFloPy是一个用于创建、运行和后处理 MODFLOW 系列地下水模拟模型的 Python 工具包。这篇指南面向首次参与 FloPy 开发的新手用 7 个步骤带你完成完整的开发工作流搭建开发环境、运行测试套件、调试失败测试、按规范提交代码直到亲手为 FloPy 添加一个全新的 MODFLOW 6 Package让你快速上手这个水文模拟开源项目。7步开发工作流总览步骤内容关键文件/工具1️⃣克隆仓库安装开发环境pyproject.toml、etc/environment.yml2️⃣获取 MODFLOW 可执行文件get-modflow命令3️⃣运行测试套件autotest/、pytest4️⃣用 markers 做快速冒烟测试autotest/pytest.ini5️⃣编写并调试新测试modflow-devtoolsfixtures6️⃣Lint 规范提交 提交 PRCONTRIBUTING.md7️⃣用代码生成工具提交新 Packagedocs/mf6_dev_guide.md第1步一键搭建 FloPy 开发环境 ️开发 FloPy 需要三样东西Git、Python ≥ 3.11和MODFLOW 可执行文件。先克隆仓库并安装开发依赖需要 clone 时仓库地址是 https://link.gitcode.com/i/87dc35a02e9200fe847278d3b4061824git clone https://link.gitcode.com/i/87dc35a02e9200fe847278d3b4061824 cd flopy pip install -e .[optional] # 以可编辑模式安装 可选依赖 pip install --group dev # 安装 test、lint、docs 等开发依赖组-e参数以可编辑模式安装改完代码立即生效是迭代开发的推荐姿势dev依赖组定义在 pyproject.toml 的[dependency-groups]段落中一次性装齐测试与 Lint 所需的一切如果你习惯 Conda也可以直接执行conda env create -f etc/environment.yml再conda activate flopy最后补一句pip install -e .。第2步快速获取 MODFLOW 可执行文件 FloPy 的测试会真实调用 MODFLOW 系列模型的可执行程序来跑数值算例所以这一步不能省。最省事的方式是用项目自带的下载工具get-modflow该命令会自动下载并安装所需的全部 MODFLOW 可执行文件详细说明见 flopy/utils/get_modflow.py。手动安装的同学可以把官方可执行文件包解压到任意目录再将该目录加入系统PATH。 小贴士部分测试会调用 GitHub API 下载数据需要在 autotest/ 目录下创建一个.env文件写入GITHUB_TOKEN你的令牌pytest-dotenv插件会自动加载它。.env已被 Git 忽略不会误提交。第3步运行完整测试套件 FloPy 的所有测试都集中在 autotest/ 目录中必须在该目录下执行 pytestcd autotest pytest -v test_conftest.py # 跑单个测试脚本 pytest -v -k export # 按名称模式筛选测试 pytest -v -n auto # 并行跑全部测试利用全部CPU核心全量测试包含回归测试、基准测试和示例脚本视机器性能大约需要30 分钟到 1 小时。测试套件依赖modflow-devtools包提供共享 fixtures如果遇到与测试内容无关的报错优先尝试更新到最新版modflow-devtools。第4步用 markers 秒选测试子集 ⚡写代码期间不可能每次都跑全量测试。pytest的 markers 机制帮你精确筛选可用 markers 定义在 autotest/pytest.iniMarker含义示例用法slow跑不完几秒钟的慢测试pytest -m not slow只跑快速测试example示例脚本、教程、Notebookpytest -m not example排除示例regression对比多个模型版本结果的回归测试组合布尔表达式自由筛选最高效的组合是内置的冒烟测试快捷开关一分钟内完成pytest -v -n auto -S-S即--smoke等价于not slow and not example and not regression。按项目约定单个超过 1~2 秒的新测试都应标记为slow以保护冒烟测试的快速迭代能力。第5步编写与调试新测试 编写测试时记住三条约定命名要有信息量测试文件和函数名应清晰表达被测对象相关测试放在同一文件不要互相踩脚测试套件是并行执行的新测试请使用modflow-devtools提供的临时目录 fixtures如function_tmpdir避免访问其他测试的工作空间调试失败测试测试输出默认会自动清理加--keep 目录即可保留现场——pytest test_export.py --keep exports_scratchVS Code 用户只需在settings.json中设置python.testing.cwd: ${workspaceFolder}/autotest等四项配置即可在 IDE 里交互式断点调试测试详见 DEVELOPER.md 的 Debugging tests in VS Code 章节。第6步Lint、规范提交并发起 PR ✅提交代码前在项目根目录运行格式化检查PR 必须通过 CI 的 lint 任务ruff check . ruff format .然后按项目的提交信息规范提交格式为type(scope): subject例如fix(mf6): correct wel package option parsing。type 只能是feat/fix/docs/test/refactor/perf/style/ci八种之一每行不超过 100 字符——这些提交信息会被自动汇总成发布说明所以写清楚很重要。分支与合并策略详见 CONTRIBUTING.md从develop分支切出特性分支开发完成后向flopy:develop发起 Pull Request项目遵循 git flowdevelop负责日常开发master只保留最新稳定版状态开发 PR 通常以 squash 方式合入涉及功能弃用时要遵守弃用策略至少保留 1 年或 2 个非补丁版本使用DeprecationWarning并在消息中注明弃用版本号。第7步提交一个全新的 MODFLOW 6 Package FloPy 的 flopy/mf6/ 模块有一个秘密武器大部分 MODFLOW 6 源码是由 DFN定义文件自动生成的你几乎不需要手写 Package 类。阅读 docs/mf6_dev_guide.md 了解 MFStructure 元数据体系与MFPackage类层次确保安装了codegen可选依赖Jinja2modflow-devtools运行代码生成脚本它会自动下载 DFN 文件并用 Jinja 模板生成源码python -m flopy.mf6.utils.generate_classes --ref develop生成结果输出到 flopy/mf6/modflow/ 目录每个 DFN 定义文件通常 1 对 1 映射成一个源文件和组件类。如果你新增的 Package 尚未进入 MODFLOW 6 官方 DFN就需要参照现有模块如mfgwfdrn.py排水包手动编写MFPackage子类。新 Package 同样要遵循第 5 步的测试约定在autotest/下新增test_*.py文件用示例数据跑通数值结果后再走第 6 步的提交流程。写在最后 掌握这套7 步开发工作流后你就具备了参与 FloPy 开发的完整能力前 4 步保证你能快速验证任何改动第 5、6 步让测试与代码规范成为习惯第 7 步则带你走进 MODFLOW 6 模块的代码生成体系完成从跑通测试到贡献新 Package的跨越。核心参考资料再汇总一次开发环境与测试详解DEVELOPER.md贡献流程与提交规范CONTRIBUTING.mdMF6 模块底层原理docs/mf6_dev_guide.md测试配置autotest/pytest.ini祝你在 FloPy 的地下水世界里开发愉快【免费下载链接】flopyA Python package to create, run, and post-process MODFLOW-based models.项目地址: https://gitcode.com/gh_mirrors/fl/flopy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考