建立成功的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的樣本會話：

1234	$ pyflakes kaleokaleo/forms.py:1: ‘form‘ imported but unusedkaleo/forms.py:4: undefined name ‘forms‘kaleo/forms.py:6: undefined name ‘forms‘

立刻，該工具告訴了我有一個import的輸入錯誤，查看檔案kaleo/forms.py，我發現：

1234	1: from django import form2: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的內容。

建立成功的Python項目