From 11f6f7969706fd03e68ff37ef064736443d64404 Mon Sep 17 00:00:00 2001 From: Roland Dobai Date: Wed, 24 Jun 2026 11:36:33 +0200 Subject: [PATCH] docs: Improve the Python contribution guide --- docs/en/contribute/index.rst | 2 ++ docs/en/contribute/style-guide.rst | 22 ++++++++++++++++++++++ docs/zh_CN/contribute/index.rst | 2 ++ docs/zh_CN/contribute/style-guide.rst | 22 ++++++++++++++++++++++ 4 files changed, 48 insertions(+) diff --git a/docs/en/contribute/index.rst b/docs/en/contribute/index.rst index 4e2a120775d..af23bd747cc 100644 --- a/docs/en/contribute/index.rst +++ b/docs/en/contribute/index.rst @@ -19,6 +19,8 @@ Before sending us a Pull Request, please consider this list of points: * Does any new code conform to the ESP-IDF :doc:`Style Guide `? +* If your contribution adds or changes Python tooling, does it follow the :ref:`Python Code Style ` and reuse shared helpers from ``esp-pylib`` where applicable? + * Have you installed the :doc:`pre-commit hook ` for ESP-IDF project? * Does the code documentation follow requirements in :doc:`documenting-code`? diff --git a/docs/en/contribute/style-guide.rst b/docs/en/contribute/style-guide.rst index 7c33244c4e5..f5fb0b56887 100644 --- a/docs/en/contribute/style-guide.rst +++ b/docs/en/contribute/style-guide.rst @@ -487,6 +487,28 @@ CMake Code Style - For globally scoped variables, use uppercase (``WITH_UNDERSCORES``). - Otherwise follow the defaults of the cmake-lint_ project. +.. _python-code-style: + +Python Code Style +----------------- + +Most of ESP-IDF's tooling — ``idf.py`` and its actions, the build system helpers, and the scripts under :idf:`tools` — is written in Python. To keep contributions portable, new Python code should run on every Python version ESP-IDF supports: from the minimum supported version stated in the :doc:`Get Started guide ` up to the latest released Python version. Avoid relying on syntax or standard-library features that are not available across this whole range. + +Linting and Formatting +^^^^^^^^^^^^^^^^^^^^^^^ + +Python code is linted and formatted by `Ruff `_ and type-checked by `mypy `_, configured in :project_file:`ruff.toml` and :project_file:`.mypy.ini`. You do not need to memorize the individual rules: install the :doc:`pre-commit hook ` before committing, and these tools run automatically on every commit, keeping your changes consistent with the rest of the codebase. + +Dependencies +^^^^^^^^^^^^ + +Python dependencies are declared in the requirement files under :idf:`tools/requirements`. List the package name only — do not pin versions there. Version constraints are maintained separately in constraint files that live outside the ESP-IDF repository, so hard-coding a version in a requirements file is usually a mistake. + +Reusing Shared Code (esp-pylib) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ESP-IDF ships `esp-pylib `_ as a core requirement. It collects utilities that are shared across Espressif's Python tools so that they behave consistently. When adding or modifying Python tooling, prefer these helpers over rolling your own — for example, emit output through its shared logger instead of calling ``print()`` yourself, and reuse its common error-handling and command-line building blocks rather than re-implementing them. Refer to the `esp-pylib README `_ for what is available and how to use it. + Configuring the Code Style for a Project Using EditorConfig ----------------------------------------------------------- diff --git a/docs/zh_CN/contribute/index.rst b/docs/zh_CN/contribute/index.rst index d1c9b8eae90..68599d97d39 100644 --- a/docs/zh_CN/contribute/index.rst +++ b/docs/zh_CN/contribute/index.rst @@ -19,6 +19,8 @@ * 要提交的代码是否符合 ESP-IDF :doc:`style-guide`？ +* 如果贡献内容新增或修改了 Python 工具，是否遵循 :ref:`Python 代码风格 `，并在适用时复用 ``esp-pylib`` 提供的共享辅助代码？ + * 是否安装了 ESP-IDF :doc:`pre-commit 钩子 `？ * 代码文档是否符合 :doc:`documenting-code` 的要求？ diff --git a/docs/zh_CN/contribute/style-guide.rst b/docs/zh_CN/contribute/style-guide.rst index 4a44578a440..e35908a1f07 100644 --- a/docs/zh_CN/contribute/style-guide.rst +++ b/docs/zh_CN/contribute/style-guide.rst @@ -487,6 +487,28 @@ CMake 代码风格 - 对于全局变量，使用大写 (``WITH_UNDERSCORES``)。 - 其他方面遵循 cmake-lint_ 项目的默认设置。 +.. _python-code-style: + +Python 代码风格 +--------------- + +ESP-IDF 的大部分工具——``idf.py`` 及其子命令、构建系统辅助脚本，以及 :idf:`tools` 目录下的脚本——均使用 Python 编写。为保证贡献内容的可移植性，新增的 Python 代码应能在 ESP-IDF 支持的所有 Python 版本上运行：从 :doc:`快速入门 ` 中所述的最低支持版本，到最新发布的 Python 版本。请避免使用在该版本范围内并非普遍可用的语法或标准库特性。 + +代码检查与格式化 +^^^^^^^^^^^^^^^^ + +Python 代码由 `Ruff `_ 进行检查和格式化，并由 `mypy `_ 进行类型检查，相关配置位于 :project_file:`ruff.toml` 和 :project_file:`.mypy.ini`。你无需记住每一条具体规则：只需在提交前安装 :doc:`pre-commit 钩子 `，这些工具便会在每次提交时自动运行，使你的改动与代码库的其余部分保持一致。 + +依赖项 +^^^^^^^^ + +Python 依赖项在 :idf:`tools/requirements` 目录下的 requirements 文件中声明。其中只需列出软件包名称——请勿在这些文件中固定版本号。版本约束由位于 ESP-IDF 仓库之外的独立约束 (constraint) 文件单独维护，因此在 requirements 文件中写死版本通常是错误的做法。 + +复用共享代码 (esp-pylib) +^^^^^^^^^^^^^^^^^^^^^^^^ + +ESP-IDF 将 `esp-pylib `_ 作为核心依赖项一同提供。它汇集了在乐鑫各 Python 工具间共享的实用工具，使这些工具的行为保持一致。在新增或修改 Python 工具时，应优先使用这些辅助代码，而非自行实现——例如，应通过其共享的日志记录器输出信息，而不要自己调用 ``print()``，并复用其通用的错误处理与命令行构建模块，而非重新实现。关于可用功能及其用法，请参阅 `esp-pylib README `_。 + 使用 EditorConfig 配置项目代码风格 ----------------------------------