创建成功的Python项目

创建成功的Python项目

• 前端开发工具技巧介绍—Sublime篇
• SEO在网页制作中的应用
• 观察者模式
• 使用D3制作图表

英文原文：Create successful Python projects，编译：Elaine.Ye

创建一个成功的开源Python项目所涉及的并不仅仅是编写有用的代码，与其相关的还有社区的参与、越来越多的合作机会、技艺以及支持等。探索最佳的做法有助于你创建出自己的成功项目。

开源Python项目的生态系统丰富多样，这使得您能够站在巨人的肩膀上来开发下一个开源项目。此外，这意味着存在一系列的社区规范和最佳做法，通过遵守这些约定并把这些做法应用到项目中，你可以为自己的软件赢得更广范围的采用。

本文涵盖了一些在构建大型和小型的项目时都运作得很好的实践做法，这些项目都已经赢得了广泛的用户群体。这里给出的这些建议的都是合理的、有其意义的，不过，因为结果可能会有所不同，所以不必把它们当成严格的教条来遵守。

首先我们来讨论一下，解耦的过程如何能够带来一个更强健的社区，在编写、维护和支持开源软件等各方面都带来更大的生产能力。

合作（collaboration）和互助（cooperation）的对比

在DjangoCon 2011大会期间，David Eaves作了基调发言，雄辩地表达了这样的想法，即尽管合作（collaboration）和互助（cooperation）有着类似的定义，但还是有着细微的差别：

“我认为，和作（collaboration）不同于互助（cooperation），其需要项目涉及到的各方通力来解决问题。”

Eaves接着又给出了一整篇文章，专门说明GitHub如何成为革新开源的运作方式——特别是在社区管理方面的运作方式的推动力。在“How GitHub Saved OpenSource”这篇文章（参见参考资料）中，Eaves说到：

“我相信，当捐献者能够以低交易成本的互助方式来参与，并且高交易成本的合作尽可能的少时， 开源项目的运作能达到最好。开源的高明之处就在于其不需要一个工作组来共同讨论每个问题以及解决问题，而是恰恰相反。”

他接着谈到了分支（forking）的价值所在，以及其如何通过在参与者之间启用低成本的互助来降低合作的高成本，这些参与者能够在无需批准的情况下推进项目。这种分支把需要的合作搁置起来，直到解决方案已经做好了合并的准备为止，如此来支持更快速的动态的实验。

你可以以类似的方式来打造自己的项目，目标是相同的：在编写、管理和支持项目的整个期间，增加低成本的互助，同时尽可能减少代价高昂的合作。

编写

从一张白纸开始，创建一些新鲜的东西，制造一些有创意的东西——或仅仅是一些与现有的略不同的东西，没有什么事情比得上启动一个新的项目并和全世界分享你的努力成果让人感觉更好的了。

与维护不同，在编写代码时，你是在创造新的东西而不是在修改或是修正已有的东西。编写和构思一个项目除了是一门科学之外还是一种艺术形式，其他人会看到实现的情况并会对代码的质量作出判断，而你的名字将会永远和它连在一起。

因此。了解工匠的心态以及据此来编写软件的方法是很重要的。编写新的项目不仅仅是意味着生成代码：项目的创建和构思包括了编写有着精美风格的让人乐于阅读的代码、在适当的时候为验证项目中的功能创建测试代码，以及制作详尽的有帮助的文档。

技艺

工艺（craft）一般是指艺术行业或是职业需要特殊的技能来手工制作一些东西，通常是小规模生产的物理器件。就软件工匠关注的更多的是质量而非数量这一意义而言，你可以延伸这一定义，把它应用在软件上。

对于工匠来说，产品具有吸引力而非只是功用是很重要的。具体来说，在软件中，工匠要努力确保代码的干净和美观、应用编程接口（API）的悦目，以及文档和测试用例能够给用户带来是在使用坚实的产品进行工作的这种感受。

在这种心态下工作，对于心灵来说是一种奖赏，也是在制作开源软件时能感受到诸多享受的原因：你不再受困于回应最后期限、客户以及其他的外部需求，而是按照自己的时间来，享受制作一些美好事物的乐趣。

代码风格和规范检查

Python的增强建议（Python Enhancement Proposal，PEP）8（参见参考资料）是一个详细的Python风格指南，你应该基于该指南来建立自己的Python项目（或至少是基于你的项目 的风格指南）。不是非要教条地采用PEP 8，不过你的工作成果越接近PEP 8规范，其他的Python开发者就越容易提交以标准的Python社区风格实现的整洁的补丁包。

除了风格的一致性之外，在捕捉诸如缺失导入和未定义变量一类的错误方面，代码规范（linting）的概念也是很有作用的。除了风格检查器会帮助你 进行检查，找出违背了默认规则或是自定义规则的代码之外，现还有一些规范器（linter）或是一些工具，最常用到的一些实用程序是：

1. pyflakes
2. pylint
3. pep8

请参阅参考资料获得到这些工具的链接。

无论你选择遵从的是哪一种约定，如果这些约定偏离了PEP 8的话，我建议文档化它们，以便让那些想要为你的项目做贡献的人了解你所采用的编码风格，显式的说明要好于隐含不语。

pyflakes是一个特别有用的规范器，它很好地平衡了有用的功能、捕捉和标出错误这两方面，不会过度地揪住微小的古怪做法不放。下面是一个在某个Python项目上使用pyflakes的示例会话：

1 2 3 4

$ pyflakes kaleo kaleo/forms.py:1: 'form' imported but unused kaleo/forms.py:4: undefined name 'forms' kaleo/forms.py:6: undefined name 'forms'

立刻，该工具告诉了我有一个import的输入错误，查看文件kaleo/forms.py，我发现：

1 2 3 4

1: from django import form 2: 3: class InviteForm(forms.Form): 4: email_address = forms.EmailField()

从内容中可看出来，要把第1行改为from django import forms。

测试

在项目中提供验证代码有效性的测试始终是一件好事，以此来防止回归被忽视，以及在某些情况下作为一种文档形式，通过阅读其中的测试代码可以让其他人知道你的库API是如何工作的。

话虽如此，但我不会根据项目是否包括测试用例或是完成这些测试的方式
来判断项目的完整性或可行性。测试用例的存在并不能保证代码的质量，这可能是一个有争议的观点，但我相信，完全没有测试比去测一些错误的东西要来得好一
些。在编写测试代码时，考虑为每个测试单元给出各种输入是一件很重要的事情。

文档

不过，与测试不同的是，你可以根据项目文档的质量和广博性来判断项目的质量和技艺水平。用与创作和维护代码相同的方式来创作和维护稳定，编写良好的并且是有深度的文档会鼓励捐献者效仿你的做法，使你的项目变得更易于为用户接受。

使用诸如Sphinx和Read the Docs一类的工具（参见参考资料），你可以发布及时更新的、外观极为不错的文档。使用这些工具是一件简单的事情，也就是写一些文字内容并并推送提交。习惯于尽可能地使用commit来提交文档的变更是很适当的一种做法。

维护

在Python Package
Index（PyPI）上发布了第一个版本，并通过各种Tweet消息和博客文章公布该版本的消息，开始有了一些使用者之后，你就需要在任何后续的创作活
动中加入维护方面的考虑了。用户会报告错误、要求添加功能、提一些文档中没有明显涉及到问题，诸如此类等等。

有些事情你会选择不去处理，给出一些权变措施；但其他的一些问题，你会打算或是修正文档或是修正代码。使用诸如git一类的分布式版本控制系统
（distributed version control
system，DVCS）并常常发布开发者包，这种做法可以大大简化维护工作，使之变成一件不再是烦人的事情。

源控制

有许多可用的DVCS，其中就包括了git和mercurial（参见参考资料），无论你选择的是哪一个控制系统，请确保它提供了源控制功能，这种功能赋予你这样的能力，可以让用户分支你的项目，然后自己来解决其中的错误。

进行变更的速率取决于许多因素，一个关键的因素是目标受众（例如，其他开发者、非技术型的最终用户）。如果你的项目是针对开发者来编写的，那么鼓励
通过拉请求（pull
request）来报告错误或是请求功能之类的做法可以真正地做到降低维护者的负担。这种做法还提升了社区的归属感，因为大家都把他们的捐献合并到了将来
的版本中。

开发构建

你会希望尽早地以及经常性地发布开发版本，在每次有一组附加的补丁包出来之后都会发布版本，如此多次。这会让其他在工作中使用你的项目的开发者能够
更容易地针对项目中的最新更改来运行。越多的人在不同的情况下使用这些代码，那么一旦到发布一个新的稳定版本的时候，该版本就会有越高的质量。

支持

支持是和维护相随的，参与并构建一个由用户和捐献者组成的社区至关重要。赋予其他人通过支持来帮助你的权利，你就是在增强项目的全面合作因素，在项目的规模方面提供更好的伸缩性，以及自然而然地增加了解决用户问题的做法。

为了达到该目的，请确保提供多种渠道来增加接触的机会，让用户更加容易地与你接洽以及参与到项目中。可选的沟通渠道包括IRC、邮件列表以及诸如Twitter一类的社交媒体汇聚点。

IRC

在诸如freenode一类的IRC平台上设置一个沟通频道是一个好主意，我就为自己的项目设置了一个：nashvegas；除了我之外只有一个用
户，虽然这种情况很少有，但我的IRC客户端还是悄无声息地运行在后台。当偶尔有用户提问时，我能够只花很少的交易成本就以一种比通过邮件要动态得多的方
式来做出响应。

邮件列表

对于大多数的开源项目来说，有一个用于支持的邮件列表并在捐献者之间讨论开发进程是一种标准的做法。我的建议是，把支持放在一个邮件列表中，只有在内容已经变得太多，彼此影响到了各小组的讨论的时候，才把它分成“用户”列表和“开发”列表。

Twitter

为项目开设一个Twitter帐户，大家可以在这里与你快速地讨论工作。Twitter帐户还是一个可以作为发布项目消息的好地方。

结束语

给Python社区中的开源软件编写并捐献代码是一种有趣且有益的体验。在增加低成本互助机会的同时侧重于减少高成本的合作，这种做法有助于项目与
活跃的捐献者一起成长。在开源领域，就你的项目来说，你有大把的*来成为一个能工巧匠，充分利用这一点并享受它。把关注的重点放在一致的代码风格、坚实
的测试和编写良好的文档上，以此来提高项目被用户和其他开发者采用的几率。此外，要利用DVCS，关注拉请求，经常性地发布开发版本。最后还有一点就是，
你可以提供多种支持渠道，以及允许社区协助你提供这种支持，通过这些做法来进一步提升项目的采用率并促进项目的成长。

参考资料

1. 阅读Mark Pilgrim的Dive into Python，获取关于该语言的一个介绍。

2. 欲了解更多关于打包Python项目方面的信息，可以读一下 A guide to Python packaging（Patrick Altman，developerWorks，2011年10月）这篇文章。

3. 阅读更多David Eaves的博客文章： Wikis and Open Source: Collaborative or Cooperative? 和How GitHub Saved OpenSource.

4. 在潜心进行下一个Python项目之前，请确保已了解PEP 8，Python代码的这一“官方”风格指南。

5. 浏览一下我的项目nashvegas的GitHub页面，以此来做为一个使用DVCS的Python项目的例子。

6. 看一看PyPI。

7. 了解更多关于分布式Python模块方面的内容。

8. developerWorks开源专区提供了丰富的关于开源工具和使用开源技术方面的信息。

9.在Twitter上关注developerWorks。

10. 在Easy and beautiful documentation with Sphinx (Alfredo Deza，developerWorks，2011年11月)一文中了解更多关于Sphinx的内容。