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

Question

我最近向openpyxl投稿，这是一个非常有趣的图书馆

然而，至少对我来说，有一些方面减缓了我最初的进度，因为我必须学习一些新的工具和概念等。当然，如果你有动力做出贡献，你会发现这些事情，但如果有人策划了一系列提示/说明/常见问题解答等，我本可以更快地做出贡献

因此，我决定在openpyxl上为这个问题打开一个话题（在我通过贡献提交-MR 384，以解决issue 1003）在issue 1530下。当我在计划写什么以及以什么格式时，我也认为在stackoverflow上解决这个问题会很好，因为有几个不同的原因。首先，当我陷入与编程相关的问题时，我总是搜索stackoverflow，所以其他人可能也会这样做。第二，这是一个很好的方式来测试水，看看人们对这个问题的看法；A、 在提交给heptapod/openpyxl之前。最后，它可能会激励一些人不仅消费开源和stackoverflow，而且也为他们做出贡献：）

下面是我的逐步指南，介绍如何设置提交openpyxl

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

Answer 1

一步一步（以下各方面的详细信息）：

• 在https://foss.heptapod.net/上开户
• 下载及；安装mercurialhttps://www.mercurial-scm.org/wiki/Download和hg evolvehttps://pypi.org/project/hg-evolve/（我注意到mercurial客户端[TortoiseHg]似乎默认使用python27。这意味着当我在python39上安装hg evolve时，它似乎不起作用，但当我在python27上安装hg evolve时，扩展开始与mercurial一起工作）
  • 确保在注册hg evolve扩展时也这样做：

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

• 克隆openpyxl repo
• 请求开发人员访问
• 阅读PythonCookbook第3版的第8.13节（类型检查类、混合等）
• 阅读代码库，试着从像open_workbook()这样的初始方法开始，通过代码库跟踪它们，了解它们是如何连接的
• 在https://foss.heptapod.net/openpyxl/openpyxl/-/issues上选择一个问题，最好是有一些赞成票/正面评论的问题，然后自己发表评论，表示希望实现/修复此问题
• 请阅读您希望使用的部件的OOMXL规范（某些特性/缺陷/文档改进可能不需要）
• 与您当地的hg一起为该问题创建一个主题（hg topic topic-name）
• 代码-实现功能/修复错误/更新文档等
• 编写测试（如果是新功能）
• 编写文档（如果是新功能）
• hg addremove和hg commit所有更改
• 推送至自由和开放源码软件（这将触发PR/MR）
• 等待维护人员的审查，回答任何问题并解决任何请求（例如：请添加测试以涵盖xyz，尝试使文档中的演示更真实，确保符合PEP-8风格，等等）
• 进行任何进一步的更改，hg addremove、hg commit、hg push
• 先生被录取了，祝贺你

---

更多详情：

与源代码管理相关：

• openpyxl托管在https://foss.heptapod.net/上，而不是github上
• openpyxl使用Mercurial代替Git，并要求HGEvolve与pip一起安装
• Mercurial/hg使用“主题”而不是分支（但它们本质上是相同的），并且您不能分叉repo，您必须在本地克隆repo，然后为您的工作创建一个主题，并向该主题添加和提交所有代码
• 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
• 您需要创建一个访问令牌来推送到repo（并且您需要使用上面显示的格式，例如https://{username}:{accessToken}@foss.heptapod.net/openpyxl/openpyxl）https://heptapod.net/pages/tuto-repo-http-access-token.html

与库本身相关：

• 这是一个相当大的库，有很多相互关联的部分，所以需要一段时间才能自己弄清楚
• 如果不阅读Python Cookbook第3版的第8.13节，就很难理解所有类、继承和混合等在序列化和反序列化XML时实现了什么
• 因此，为了解决前面的两个要点，我试着尽我所能解释这个库，从我使用的部分：

  • descriptors文件夹包含启用类型系统的类（使用Typed等类）以及启用XML与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品种）

• 开放式XML文件格式的规范非常枯燥：http://www.ecma-international.org/news/TC45_current_work/Office%20Open%20XML%20Part%201%20-%20Fundamentals_final.docx但根据规范正确实现新功能是非常重要和必要的（而不是通过您拥有的反向工程示例Excel文件-尽管这有时可以帮助您找到规范的正确部分等）
• 您需要了解清单、REL、UUID、名称空间等如何协同工作，将excel工作簿（及其所有工作表、图像、图表等）存储为XML格式，有时还包括二进制格式
• 因此，为了解决前面的两个要点，我尝试从我使用的部分尽可能地解释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/.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”中，因此您可以从层次结构的角度考虑Excel文件，如Document > Workbook > Worksheets。每个工作簿至少需要一个工作表，正如我们在这里所做的那样。还请注意，主题也适合层次结构，如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中：

    <?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创建此关系文件，并通知我们与Sheet1相关的额外数据（如XML文件或.bin文件）

    如果将excel文件（如outfile.xlsm）重命名为outfile.zip，则可以提取所有文件并查看OOXML文档的结构：