我如何在 https://foss.heptapod.net/openpyxl/ 上为 openpyxl 做出贡献

Question

我最近为 openpyxl 做出了贡献，这是一个非常有趣的库。

但是，至少对我来说，有些方面减缓了我最初的进步，因为我必须学习一些新的工具和概念等。当然，如果你有动力做出贡献，你会解决这些问题，但是如果有人整理了一份提示/说明/常见问题等列表，我本可以更快地做出贡献。

因此，我决定在 issue 1530 下的 openpyxl 上为此打开一个问题（在我通过贡献 - MR 384 提交后，地址 issue 1003）。当我在计划写什么和以什么格式写时，我也认为在 stackoverflow 上也解决这个问题会很好，原因有几个。首先，当我遇到与编程相关的问题时，我总是搜索stackoverflow，所以其他人可能也会这样做。其次，在将其提交给 heptapod/openpyxl 之前，这是一个试水并了解人们对此 Q&A 的看法的好方法。最后，它可能会给一些人带来动力，不仅要使用开源和 stackoverflow，还要为它们做出贡献:)

这是我设置提交到openpyxl的分步指南

stackoverflow 的美妙之处在于，如果有不清楚的地方，很容易发表评论并让我知道，我应该可以直接在这里解决。因此，随着时间的推移，答案应该会变得更好，并提供一个简单的替代渠道来询问有关openpyxl 贡献的问题。

Answer 1

循序渐进（下面每个方面的详细信息）：

• 在https://foss.heptapod.net/ 上创建一个帐户
• 下载并安装 mercurial https://www.mercurial-scm.org/wiki/Download 和 hg-evolve https://pypi.org/project/hg-evolve/（我注意到 mercurial 客户端 [TortoiseHg]，似乎默认使用 python27。这意味着当我在我的 python39 上安装 hg-evolve 时它没有似乎可以工作，但是当我也将它安装在我的 python27 上时，扩展程序开始与 mercurial 一起工作）
  • 确保同时注册 hg-evolve 扩展：

  $ hg config --edit # add these three lines:
  [extensions]
  evolve =
  topic = 
  

• 克隆 openpyxl 存储库
• 请求开发者访问权限
• 阅读 Python Cookbook 3rd Edition 的第 8.13 节（类型检查类、mixin 等）
• 阅读代码库，尝试从open_workbook() 等初始方法开始，并通过代码库跟踪/跟踪它们以了解它们是如何连接的。
• 在https://foss.heptapod.net/openpyxl/openpyxl/-/issues 上选择一个问题，最好是有一些赞成/积极的 cmets，然后自己发表评论，表示您希望实施/修复此问题。
• 阅读您要处理的部分的 OOMXL 规范（对于文档的某些功能/错误/改进可能不需要）
• 与您当地的 hg (hg topic topic-name) 为该问题创建一个主题
• 代码 - 实现功能/修复错误/更新文档等。
• 编写测试（如果是新功能）
• 编写文档（如果是新功能）
• hg addremove 和 hg 提交所有更改
• 推送到 foss（这将触发 PR/MR）
• 等待维护者的审核，回答任何问题并解决任何请求（例如：请添加测试以覆盖 xyz，尝试使文档中的演示更真实，确保符合 PEP-8风格等）
• 进行任何进一步的更改，hg addremove，hg commit，hg push
• MR 被接受 - 恭喜！

---

更多细节：

源代码控制相关：

• openpyxl 托管在 https://foss.heptapod.net/ 而不是 github
• openpyxl 使用 Mercurial 而不是 Git，并且需要使用 pip 安装 hg-evolve
• Mercurial/hg 使用“主题”而不是分支（但它们本质上是相同的）并且您不能分叉存储库，您必须在本地克隆存储库，然后为您的工作创建一个主题并将所有代码添加并提交到那个话题。
• Mercurial/hg 使用一些与 git 不同的命令，这是一个常见的工作流程（示例来自我的贡献）：

  $ hg clone https://foss.heptapod.net/openpyxl/openpyxl openpyxl
  $ cd openpyxl
  $ hg pull # not needed
  $ hg up 3.1 # because it's a new feature
  $ hg topic workbook-customDocProps
  # write your code...
  $ hg pull # pull remote changes (seems to behave like git fetch)
  $ hg merge -r 3.1 # merge changes from the remote into your topic branch
  $ hg addremove # add any new files, and remove any you deleted
  $ hg forget TempScripts/** # because I added some temp scripts during investigation, not to be committed
  $ hg commit -m ":heavy_plus_sign: implemented wb.custom_doc_props, with tests and docs"
  $ hg push https://{username}:{accessToken}@foss.heptapod.net/openpyxl/openpyxl
  

  • 注意：hg up 是 hg update 或 hg checkout 的别名
• 有一些很好的帮助资源，例如：
  • https://heptapod.net/pages/quick-start-guide.html
  • https://www.mercurial-scm.org/doc/evolution/tutorials/topic-tutorial.html
  • https://www.selenic.com/mercurial/hg.1.html#addremove
  • https://heptapod.net/pages/faq.html
• 你需要创建一个访问令牌来推送到仓库（你需要使用我上面显示的格式推送，例如https://{username}:{accessToken}@foss.heptapod.net/openpyxl/openpyxl）https://heptapod.net/pages/tuto-repo-http-access-token.html

与库本身有关：

• 这是一个相当大的库，有很多相互关联的部分，所以你需要一段时间才能弄清楚。
• 如果不阅读 Python Cookbook 第 3 版的第 8.13 节，可能很难理解所有类、继承和混入等为了序列化和反序列化 XML 所实现的目标。
• 因此，为了尝试解决前面的 2 个要点，我尝试从我使用的部分内容中尽我所能解释该库：

  • descriptors 文件夹包含启用类型系统的类（使用诸如 Typed 之类的类）并启用与 XML 和 XML 字符串表示的序列化和反序列化（使用诸如 Serlializable 之类的类）方法to_tree() 和from_tree()）。类型系统很重要，因为 OOXML 规范相当严格，而且由于 python 是一种动态语言，我们需要一种以可扩展的方式强制执行类型的方法。此外，由于 .xlsx 或 .xlsm（2007 年后）工作簿本质上只是一个包含 XML 文件的 Zip 文件，因此 XML 序列化和反序列化当然是至关重要的。

  • workbook 文件夹包含 Workbook 类，它是工作簿的 Python 表示形式。该类的属性，对应真实工作簿的属性

  • packaging 文件夹包含用于存储工作簿文档属性（如作者、创建时间等）的类

  • reader 文件夹包含用于将工作簿从磁盘读取到内存中的类（到 Workbook 类中）

  • writer 文件夹包含用于将内存工作簿（在 Workbook 类中）写入磁盘的类

  • 还有更多的文件夹和类，但在我研究这些领域之前，我不会讨论它们。但是，一旦我这样做了，我会回来更新这个。

    本地克隆后库的文件夹结构：

与 Excel 文件本身相关：

（仅谈论 2007/10 之后的 .xlsx 和 .xlsm 变体）

• Open XML 文件格式的规范非常枯燥：http://www.ecma-international.org/news/TC45_current_work/Office%20Open%20XML%20Part%201%20-%20Fundamentals_final.docx 但根据规范正确实现新功能非常重要和必要（而不是通过您拥有的逆向工程示例 Excel 文件 - 尽管这可以有时会帮助您指出规范的正确部分等）
• 您需要了解清单、rels、uuid、命名空间等如何协同工作以将 excel 工作簿（及其所有工作表、图像、图表等）存储为 XML，在某些情况下为二进制格式。
• 因此，为了尝试解决前面的 2 个要点，我已尝试从我使用的部分内容中尽我所能解释 OOXML 格式：

  • 工作簿结构如下，是一个相当简单的工作簿。通常，根文件夹只包含一个文件[Content_Types].xml，这也称为“清单”。这包含默认类型和覆盖类型的列表。本质上，随着您向工作簿添加越来越多的功能，此类型列表会扩展。例如，我实现了对 Workbook.CustomDocumentProperties 的支持，这些都保存在docProps/custom.xml 中，一旦添加了一个 CustomDocumentProperty，Excel 就会添加这个文件，而且还会在清单中添加一个类型覆盖，让 Excel 知道，什么这是 XML 文件的类型：

    <?xml version="1.0"?>
    <Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
      <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
      <Default Extension="xml" ContentType="application/xml"/>
      <Default Extension="bin" ContentType="application/vnd.ms-office.vbaProject"/>
      <Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>
      <Override PartName="/xl/theme/theme1.xml" ContentType="application/vnd.openxmlformats-officedocument.theme+xml"/>
      <Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>
      <Override PartName="/docProps/app.xml" ContentType="application/vnd.openxmlformats-officedocument.extended-properties+xml"/>
      <Override PartName="docProps/custom.xml" ContentType="application/vnd.openxmlformats-officedocument.custom-properties+xml"/>
      <Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
      <Override PartName="/xl/workbook.xml" ContentType="application/vnd.ms-excel.sheet.macroEnabled.main+xml"/>
    </Types>
    

  • 另外，在根文件夹中，通常有3个子文件夹，_rels、docProps和xl。文件夹_rels 通常称为“根关系”或“根关系”。此文件夹包含一个文件_rels/.rels，它是整个文档的 XML 关系文件。这些“rels”文件（或关系文件）贯穿 OOXML 格式，简而言之，它们解释了如何将一个 XML 文件链接到另一个 XML 文件或二进制文件。例如，在这个简单的 .xslm 文件中，我们有一些 CustomDocumentProperties（可选）以及默认属性（“docProps/core.xml”和“docProps/app.xml”）和根 rels，如下所示：

    <?xml version="1.0"?>
    <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
      <Relationship Target="xl/workbook.xml" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Id="rId1"/>
      <Relationship Target="docProps/core.xml" Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" Id="rId2"/>
      <Relationship Target="docProps/app.xml" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties" Id="rId3"/>
      <Relationship Target="docProps/custom.xml" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties" Id="rId4"/>
    </Relationships>
    

  • 您在上面的 XML 中看到，工作簿本身存储在“xl/workbook.xml”中，因此您可以从层次结构的角度考虑诸如Document > Workbook > Worksheets 之类的 Excel 文件。每个工作簿都需要至少一个工作表，就像我们在这里一样。另请注意，主题也适合层次结构，例如Document > Workbook > Themes，如下面的文件夹结构所示。

  • 同样，您可以推断出Document > Styles 和Document > vbaProject 等层次结构，这意味着它们与Workbook 处于同一层次结构级别。

  • 深入了解该结构，您再次看到 _rels 文件夹，这次更深一层为 xl/_rels/workbook.xml.rels，这意味着它是 Workbook.xml 文件的关系：

    <?xml version="1.0"?>
    <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
      <Relationship Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="/xl/worksheets/sheet1.xml" Id="rId1"/>
      <Relationship Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml" Id="rId2"/>
      <Relationship Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme" Target="theme/theme1.xml" Id="rId3"/>
      <Relationship Type="http://schemas.microsoft.com/office/2006/relationships/vbaProject" Target="vbaProject.bin" Id="rId4"/>
    </Relationships>
    

  • xl/workbook.xml 文件本身就是这样（尽管这里没有列出样式、主题和 vbaProject，但上面显示的关系很重要，以便 Excel 知道这些文件存在）：

    <?xml version="1.0"?>
    <workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
      <workbookPr codeName="ThisWorkbook"/>
      <bookViews>
        <workbookView visibility="visible" minimized="0" showHorizontalScroll="1" showVerticalScroll="1" showSheetTabs="1" xWindow="-120" yWindow="-120" windowWidth="29040" windowHeight="15840" tabRatio="600" firstSheet="0" activeTab="0" autoFilterDateGrouping="1"/>
      </bookViews>
      <sheets>
        <sheet xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" name="Sheet1" sheetId="1" state="visible" r:id="rId1"/>
      </sheets>
      <definedNames/>
      <calcPr calcId="191029" fullCalcOnLoad="1"/>
    </workbook>
    

  • 最后，查看xl/worksheets/sheet1.xml，我们会看到工作表数据是如何保存的。这里我们只在单元格 B1 中保存了单词“test”：

    <?xml version="1.0"?>
    <worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
      <sheetPr codeName="Sheet1">
        <outlinePr summaryBelow="1" summaryRight="1"/>
        <pageSetUpPr/>
      </sheetPr>
      <dimension ref="B1:B1"/>
      <sheetViews>
        <sheetView tabSelected="1" workbookViewId="0">
          <selection activeCell="B3" sqref="B3"/>
        </sheetView>
      </sheetViews>
      <sheetFormatPr baseColWidth="8" defaultRowHeight="15"/>
      <sheetData>
        <row r="1">
          <c r="B1" s="1" t="inlineStr"><is><t>Test</t></is></c>
        </row>
      </sheetData>
      <pageMargins left="0.7" right="0.7" top="0.75" bottom="0.75" header="0.3" footer="0.3"/>
    </worksheet>
    

  • 目前，Sheet1 没有关系，但随着我们向工作表中添加更多功能，此关系文件将在 xl/worksheets/_rels/sheet1.xml.rels 创建并通知我们，与哪些额外数据（如 XML 文件或有时 .bin 文件）相关sheet1.

    如果你将一个excel文件如outfile.xlsm重命名为outfile.zip，那么你可以提取所有文件并查看OOXML文档的结构：