从源码到应用：python-mss开发者贡献指南

【免费下载链接】python-mss An ultra fast cross-platform multiple screenshots module in pure Python using ctypes. 项目地址: https://gitcode.com/gh_mirrors/py/python-mss

一、为什么选择贡献python-mss？

python-mss是一个超快速的跨平台多截图模块，完全使用纯Python和ctypes实现。作为开发者，参与这个项目不仅能提升自己的技术能力，还能为开源社区贡献一份力量。无论你是Python新手还是有经验的开发者，都可以通过贡献代码、修复bug或完善文档等方式参与进来。

二、开发环境搭建

2.1 准备工作

首先，你需要对项目仓库进行fork操作。然后创建自己的分支，确保在分支上进行开发工作。

2.2 安装依赖

你需要安装pytest来进行测试工作。可以按照以下步骤创建虚拟环境并安装依赖：

$ python -m venv venv
$ . venv/bin/activate
$ python -m pip install -U pip
$ python -m pip install -e '.[tests]'

三、测试流程

3.1 运行测试套件

完成环境搭建后，可以通过以下命令启动测试套件：

$ python -m pytest

3.2 代码质量检查

为确保代码质量，需要安装开发相关依赖并运行检查脚本：

$ python -m pip install -e '.[dev]'
$ ./check.sh  # Linux/macOS
$ .\check.ps1  # Windows (PowerShell)

四、文档构建

要构建项目文档，只需执行以下命令：

$ python -m pip install -e '.[docs]'
$ sphinx-build -d docs docs/source docs_out --color -W -bhtml

五、XCB代码生成器使用

5.1 概述

GNU/Linux XCB后端依赖于生成的ctypes绑定。如果需要添加新的XCB请求或类型，不要手动编辑src/mss/linux/xcbgen.py。src/xcbproto目录包含用于生成Python绑定的工具和协议定义。其中gen_xcb_to_py.py是代码生成器，可从XCB协议XML文件生成Python/ctypes绑定；*.xml是从上游xcbproto仓库获取的协议定义文件。

5.2 工作流程

生成器是维护者工具，不属于正常构建过程：

1. 当项目需要新的XCB请求或类型时，维护者编辑gen_xcb_to_py.py中的配置（查看顶部附近的TYPES和REQUESTS字典）。
2. 维护者运行生成器：

python src/xcbproto/gen_xcb_to_py.py

3. 生成器读取XML协议定义并生成xcbgen.py。
4. 维护者确保生成工作正常，并对生成的文件运行ruff check --fix和ruff format。
5. 维护者将文件移动到src/mss/linux/xcbgen.py。
6. 生成的xcbgen.py会提交到版本控制并随包分发，因此最终用户无需运行生成器。

5.3 协议XML文件

*.xml文件是上游xcbproto项目的未修改副本，定义了libxcb使用的有线协议和数据结构，不要编辑这些文件。

5.4 为什么生成代码

XCB C库公开了数千个协议元素。我们自动生成实际使用的子集，而不是手动为每个结构和请求编写ctypes绑定，这样可以保持代码库精简，同时确保绑定与上游协议定义完全匹配。

5.5 依赖

• lxml：解析XML协议定义所需。
• Python 3.12+：生成器使用现代Python特性。

注意，最终用户不需要lxml，仅在重新生成绑定时才需要。

六、贡献注意事项

在贡献过程中，要确保添加或更新补丁中的测试和文档。遵循项目的代码规范和最佳实践，保证代码的可维护性和可读性。如果你有任何疑问，可以参考项目中的相关文档或与其他开发者交流。

希望这份指南能帮助你顺利参与到python-mss项目的开发中，期待你的贡献！ 🚀

【免费下载链接】python-mss An ultra fast cross-platform multiple screenshots module in pure Python using ctypes. 项目地址: https://gitcode.com/gh_mirrors/py/python-mss