开发¶

如果您发现OpenPYXL项目很有趣，并且想要提供一个新的令人敬畏的特性，请修复一个讨厌的bug或改进文档，本节将指导您设置开发环境。

我们将研究所使用的编码标准和版本控制系统工作流，以及将OpenPYXL代码克隆到本地计算机、设置虚拟的Python环境、运行测试和构建文档。

正在获取源¶

OpenPYXL的源代码托管在 Heptapod 作为一个Mercurial项目，您可以使用例如GUI客户端下载 SourceTree 亚特兰西人。如果您喜欢使用命令行，可以使用以下命令行：

$ hg clone https://bitbucket.org/openpyxl/openpyxl
$ hg up 3.0

请注意，默认分支不应用于开发工作。对于错误修复和小补丁，您应该将工作建立在当前版本的分支上，例如 3.0 . 新特性通常应基于 next 次要版本。如果有疑问，请联系OpenPYXL开发团队。

值得添加对原始存储库的上游远程引用，以便通过添加到 ./hg/hgrc 归档以下内容：

[paths]
default = ...
openpyxl-master = https://foss.heptapod.net/openpyxl/openpyxl

然后，您可以使用以下命令获取任何新更改：

$ hg pull openpyxl-master

之后，您应该使用 virtualenv 安装项目要求和项目本身：

$ cd openpyxl
$ virtualenv openpyxl-env

使用以下方式激活环境：

$ source bin/activate  # or ./openpyxl-env/Scripts/activate on Windows

使用以下方式安装dev和prod依赖项以及包本身：

(openpyxl-env) $ pip install -U -r requirements.txt
(openpyxl-env) $ pip install -e .

运行试验¶

注意，未经测试对项目的贡献将 not 被接受。

我们使用 pytest 作为测试运行者 pytest-cov 覆盖范围信息和 pytest-flakes 用于静态代码分析。

要运行所有需要执行的测试，请执行：

(openpxyl-env) $ pytest -xrf openpyxl  # the flags will stop testing at the first error

或使用 tox 要在不同的Python版本和配置上运行测试，请执行以下操作：

$ tox openpyxl

新闻报道¶

目标是100%覆盖单元测试-数据类型和实用功能。覆盖率信息可通过以下方式获得：

py.test --cov openpyxl

组织¶

测试最好在包/模块级别进行，例如 openpyxl/cell . 这使得测试和获取正在开发的代码的统计信息更加容易：

py.test --cov openpyxl/cell openpyxl/cell

检查XML¶

使用 openpyxl.tests.helper.compare_xml 函数比较生成的和预期的XML片段。

架构验证¶

在处理代码以生成XML时，可以验证生成的XML是否符合发布的规范。注意，这不一定保证一切都是好的，但比逆向工程更好！

微软工具¶

除了SDK，微软还拥有 "Productivity Tool" 用于使用Office OpenXML。

这允许您快速检查或比较整个Excel文件。不幸的是，验证错误包含许多误报。该工具还包含到规范和实现者注释的链接。

文件支持和规范¶

OpenPYXL的主要目标是支持读写Microsoft Excel 2010文件。这些是由指定的压缩ooxml文件 ECMA 376 和 ISO 29500 .

在可能的情况下，我们试图支持由其他库或程序生成的文件，但不能保证，因为这些文件通常不严格遵循上述格式。

支持python版本¶

支持Python3.6及更高版本

编码风格¶

对于编码样式，我们将自己定位在PEP-8，除了实现往返的属性。尽管如此，我们还是鼓励您使用Python数据约定（布尔值、无等）。注意docstring中此转换的异常。

贡献¶

欢迎以拉式请求的形式作出贡献。别忘了把自己加入作者名单！

分支命名约定¶

我们使用“major.minor.patch”编号系统，即 3.0.5 . 开发分支以“major.minor”版本命名。一般来说，API更改只会发生在主要版本上，但也会有例外。在对邮件列表进行更改之前，请始终将API更改与邮件列表进行通信。如果要更改API，请尝试为旧行为实现一个回退（带有拒绝警告）。

“默认分支”用于发布，并且始终具有合并的开发分支的更改。它不应该是请求拉取的目标。

拉动请求¶

请求请求应提交给当前未发布的开发分支。如果当前版本是 3.0.5 ，应向 3.0 分支机构。例外情况是对已发布版本的错误修复，应将其提交给相关的发布分支，并在上游合并到开发中。

请使用 tox 测试不同提交的代码之前提出请求。这对于跨Python版本处理问题特别重要。

文档¶

在添加或更改功能时，请记住更新文档。检查文档的语法是否正确。：：

tox -e doc

标杆管理¶

基准测试和分析是正在进行的任务。我们知道有很多事情要做，所以我们非常欢迎为这些作出贡献。

内存使用¶

使用 memory_utils 包裹。：：

tox -e memory

珀莫勒¶

由于openpyxl不包含任何内部内存基准测试工具，所以python 珀莫勒 在测试样式期间使用了包来分析 openpyxl.reader.excel.read_style_table() ：：

# in openpyxl/reader/style.py
from pympler import muppy, summary

def read_style_table(xml_source):
  ...
  if cell_xfs is not None:  # ~ line 47
      initialState = summary.summarize(muppy.get_objects())  # Capture the initial state
      for index, cell_xfs_node in enumerate(cell_xfs_nodes):
         ...
         table[index] = new_style
      finalState = summary.summarize(muppy.get_objects())  # Capture the final state
      diff = summary.get_diff(initialState, finalState)  # Compare
      summary.print_(diff)

pympler.summary.print_() 将对象内存使用情况的报告打印到控制台，允许比较不同的方法和检查内存使用情况。一个有用的未来发展将是构建一个基准测试包来衡量不同组件的性能。

开发¶