创建成功的 Python 项目
Patrick Altman
2012 年 3 月 14 日发布
Python 开源项目的生态系统丰富多样。您可以在这一雄厚的基础上完成下一个开源项目的生产。此外,这也意味着,有相应的一套社区规范和最佳实践。通过遵守这些规范并在项目中应用这些实践,可以使您的软件获得更广泛的采用。
本文介绍了拥有广泛用户群体的大小型项目构建实践。本文在此提供的建议合理有效。但是,结果可能有所不同,因此请不要将此建议看作是金科玉律。
首先,我们将讨论解耦流程如何带来一个更加强大的社区,在开源软件的编写、维护和支持方面拥有更高的生产率。
协作与合作
在 2011 年的 DjangoCon 会议上,David Eaves 发表了相关的主题演讲,清楚地说明了虽然协作与合作定义相似但却有细微的差别:“我认为协作与合作不同,它需要项目的各参与方共同参与来解决问题。"
Eaves 还撰写了一整篇文章,详细介绍 GitHub 如何成为开源工作方式创新的驱动力—特别是在社区参与方面。在 "How GitHub Saved OpenSource"(参阅 参考资料)一文中,Eaves 表示:“我认为,只有当参与者能够参与到低交易成本合作中,并且最大限度地减少高交易成本合作的时候,开源项目才能发挥最大的作用。开源的精神在于它并不需要一个团队相互协作来讨论并处理每个问题,而是正好相反。”
接着,他还谈论了派生 (forking) 的价值,以及如何在人群中支持低成本合作,使之能够在无需许可的情况下推进项目,从而降低高额的协作成本。该派生可推迟对于协作的需求,直到有解决方案合并到其中,这样能使实验过程更为快速、更具动态。
您可以用相同的方式分享项目,并实现相似的目标:增加低成本合作,同时最大程度地减少项目编写、维护和支持方面的昂贵协作。
编写
从零开始,创建新的、有创意的—或与现存有所不同的东西。没有什么可以比得上启动一个项目,并与全世界的人们一起分享您所努力的成果而让人更加兴奋。
与维护不同,当您进行编写时,您是在创建新东西,而不是修改或修订某些已存在的东西。编写和精心创作项目是一种艺术也是一种科学。其他人将会看到这个实现,并对此代码的质量进行评判,您的名字将永远与这个项目联系在一起。
因此,相应地了解工匠的思维模式以及编写软件的方法至关重要。编写新项目不仅仅意味着生成代码:项目的创作与完善包括编写易于阅读且样式美观的代码,创建可验证项目功能的测试,以及生成全面且有用的文档。
技艺
工艺 通常是指手工制造并具有专业技术要求的艺术行为或职业,通常指小规模生产的物品。您可以将其定义延伸到软件中,就此意义而言,软件工匠关注的是软件的质量而非数量。
对于工匠来说,重要的是,该产品不仅要功能实用,还必须吸引人。具体地讲,软件工匠要确保代码简洁且赏心悦目,应用程序编程界面 (API) 美观,文档和测试让用户感觉这是一种可靠的产品。
以这种思维进行工作得到的奖励是能够在生产开源软件中获得乐趣源泉:您不用理会截止日期、客户端以及其他一些外部需求。您可以慢慢地享受创造美丽事物的过程。
为您的项目获取一个 Twitter 帐户,在其中人们可以公开与您讨论您的。Twitter 帐号可以作为发表项目公告的一个很好的地方。
代码样式和 linting
Python Enhancement Proposal (PEP) 8(参阅 参考资料)是关于 Python 样式的详细指南,您应基于此指南(或至少您项目的样式指南)构建 Python 项目。遵守 PEP 8 教条并不是那么重要,但是如果更接近 PEP 8,那么对于其他 Python 开发人员以标准的 Python 社区样式提交简洁补丁会更加容易。
除了样式一致性外,代码 linting 的概念在错误捕捉(比如缺失导入和未定义变量)中非常有用。除了样式检查程序,还有许多 linter(或工具),可帮助检查代码以查找与默认规则集或已配置规则的偏差。最受欢迎的实用工具是:pyflakes
pylint
pep8
请参阅 参考资料 以获得这些工具的链接。
不管您遵守哪一套规则,如果它们与 PEP 8 有出入,那么我建议提供相关文档使那些参与您项目的人了解您所使用的代码样式。最好是显式表达,而不是隐式表达。
pyflakes 是一款非常有用的 linter 工具。它能很好地实现功能、捕捉与高亮显示错误之间的平衡,而无需过多奇怪操作。下面是一个在 Python 项目上使用 pyflakes 的示例会话:$ pyflakes kaleo
kaleo/forms.py:1: 'form' imported but unused
kaleo/forms.py:4: undefined name 'forms'
kaleo/forms.py:6: undefined name 'forms'
该工具会立刻告诉我有一个输入拼写错误。查看 kaleo/forms.py,我看到:1: from django import form
2:
3: class InviteForm(forms.Form):
4: email_address = forms.EmailField()
...告诉我将第 1 行更改为 from django import forms。
测试
对项目进行测试以验证代码的运行情况总是很有帮助的,这样可预防忽略回归 (regressions),并在某些情况下它可作为一种文档格式,在其中阅读测试代码可以告知其他人库中的 API 工作情况。
也就是说,我不会根据项目是否包括测试或这些测试的完整程度来判断一个项目的完整性和可行性。测试的存在并不能保证代码的质量。这也许是一个具有争议的观点,但是我个人认为完全不进行测试总比测试不当要好。在编写测试程序时,将各种输入放置到测试中的每个单元非常重要。
文档
但是,与测试不同,您可以 根据项目文档的质量和范围来判断一个项目的质量和工艺。编写和维护文档的方法与您编写和维护代码的方法相似。文档写得出色并具有深度,可吸引更多的参与者加入,使用户更接近您的项目。
使用 Sphinx 和 Read the Docs(参阅 参考资料)等工具,您可以拥有已发布的最新文档,这些文档看起来非常棒。使用这些工具与编写词组并按提交一样简单。在合适时养成尽可能使用提交键来提交文档更改的习惯。
维护
发布了 Python Package Index
(PyPI) 第一个版本,在各个 Tweet 和博客文章中宣布,并开始拥有一些用户后,您就需要对所有持续活动添加维护操作。用户将会报告 bug,请求特性,询问在文档中不明显的问题等。
有些事情您可以选择不做,并提出解决方法;但是对于其他一些事情,您可能想要在文档或代码中进行修改。使用 Git 等分布式版本控制系统 (DVCS) 并发布常用的开发人员软件包,可以简化有关维护的繁琐工作。
源代码控制
有多款分布式版本控制系统可用,其中包括 Git 和 Mercurial(参阅 参考资料)。不管您选择哪一版本的控制系统,请确保该系统提供源代码控制,可以让用户分享您的项目并自己修订 bug。
Pull 请求
pull 请求 是发送到某个储存库的其他分支(比如典型的父型分叉)的消息,请求存储库拉出一批更改或提交。因为 pull 请求流程会增加合作,同时降低协作成本,可加快创新周期。
执行更改的速度取决于许多因素,其关键因素之一是目标受众(例如,其他开发人员和非技术性最终用户)。如果您正在为开发人员编写代码,那么鼓励在 pull 请求中提供 bug 报告或特性请求可以真正地减轻维护人员的负担。同时,它还能增强社区感,因为人们可以参与到未来发行版的构建中。
开发版本
您希望在每次发布其他补丁集后尽早且频繁地多次发布开发版本。这样可以使其他在工作中使用您项目的开发人员更加轻松地运行项目的最新更改。在不同场景中使用代码的人越来越多,在发布新稳定版本时质量就越好。
支持
维护随之而来的是支持。参与并构建一个由用户和参与者组成的社区至关重要。授权其他人帮助您提供支持,可提高项目的总体合作因素,使项目规模获得更好的扩展性并自然地加强解决用户问题的观点。
因此,确保提供多个通道以提高普及率并使用户能够更加轻松地参与您以及项目。通道选项包括 IRC、邮件列表和社交媒体(比如 Twitter)。
IRC
在 freenode 等 IRC 上建立通道是一个好想法。我就为自己的项目 nashvegas 建立了这样一个通道;虽然除了我没有别的用户,但是我的 IRC 客户端能在后台运行。当临时用户有问题时,我能够以很低的事务处理成本且更加动态的方式来回应此问题,而不是通过电子邮件。
邮件列表
大多数开源项目均支持邮件列表并且在参与者之间讨论开发流程,这是一种标准实践。我推荐将它保存到一个邮件列表中,并且在人员数量不断增加而导致麻烦时将其列表分成“用户”和“开发人员”列表。
为您的项目获取一个 Twitter 帐户,在其中人们可以公开与您讨论您的作品。Twitter 帐户也可以作为发布项目公告的一个好地方。
结束语
在 Python 社区中编写和参与开源软件也非常有趣。本文侧重于降低高成本协作,同时提高低成本合作机遇,可帮助您的项目与活动参与者一起成长。在开源中,当提到自己的项目时,您有成为一名工匠的自由:充分利用它并享受其中。关注一致的代码样式、可靠的测试和编写良好的文档,以提高用户和其他开发人员采用您项目的比率。此外,请使用 DVCS,留意 pull 请求并发布常用的开发版本。最后,您可以通过提供多通道支持并充许社区帮助提供支持,从而进一步提高您项目的采用率和增长率。
相关主题阅读 Mark Pilgrim 撰写的 Dive into Python 了解有关于该语言的简介。
有关打包 Python 项目的更多信息,请查看 Python 打包指南(Patrick Altman,developerWorks,2011 年 10 月)。
在深入研究您的下一个 Python 项目之前,确保您熟悉 PEP 8,这是关于 Python 代码的“官方”样式指南。
查看我的项目 nashvegas 的 GitHub 页面,获取在您自己的 Python 项目中使用 DVCS 的示例。
有许多 linter 工具可供使用。受欢迎的选项包括 pyflakes、pylint 和 Python 样式指南检查器 pep8。
在您准备为项目添加文档时,有几款在线工具可以使此工作更加简单。其中两个选项是 Sphinx 和 Read the Docs。
在 使用 sphinx 制作简洁而又美观的文档(Alfredo Deza,developerWorks,2011 年 11 月)中浏览关于 Sphinx 的更多信息。
Git 和 Mercurial 均能实现杰出的 DVCS。