「譯」Python 專案應該都有什麼?

z正小歪發表於2017-01-30

原文地址

Python 語言在過去的幾年有著突飛猛進的發展,社群也在快速發展。在發展過程中,社群中出現了許多工具保持著資源的結構性和可獲取性。在這篇文章中,我將提供一個簡短列表,讓每個 Python 專案中都具有可訪問性和可維護性。

requirements.txt

首先, requirements.txt 在安裝專案時候是十分重要的,通常是一個純文字檔案,通過 pip 安裝,每行一個專案的依賴。

真是簡單又實用。

你也可以有多個用於不同目的 requirements.txt。例如,requirements.txt 是讓專案正常啟動的依賴,requirements_dev.txt 是用於開發模式的依賴,requirements_docs.txt 是生成文件的依賴(像 Sphinx 需要的主題)

setup.py

setup.py 檔案在通過 pip 安裝時候時候是十分重要的。編寫容易,很好的可配置性並且可以處理很多事情,例如匯入,專案後設資料,更新源,安裝依賴項等等。

可以檢視 setuptools 文件獲取更多的資訊。

正確的專案結構

專案結構至關重要。有了一個組織良好的結構,它會更容易組織的東西,找到某些原始檔,並鼓勵其他人貢獻。

一個專案目錄應具有類似的結構

root/
        docs/
        tests/
        mymodule/
        scripts/
        requirements.txt
        setup.py
        README
        LICENSE複製程式碼

當然,這不是組織專案的唯一方法,但這肯定是最常用的模板。

測試

單元測試對專案十分重要,可以保證程式碼的穩定性。我推薦 unittest 模組,因為它是內建的,並且足夠靈活,完成正確工作。

還有其他可用於測試專案的庫,例如 test.pynose

文件

如果你開發一個專案,我確信你不只是為你自己寫。其他人也要必須知道如何使用你的專案。即使你只是為自己編寫的專案(雖然是開源的目的),但是一段時間後不開發後,你一定不會記得你的程式碼中發生的任何事情(或API)。

因此,為了實現可重用的程式碼,你應該:

  • 設計一個簡單的API,易於使用和記憶
  • API應該足夠靈活,容易配置
  • 記錄相關使用例子
  • 例子不要追求 100% ,最合適的是覆蓋 80% 。

為了充分的記錄你的程式碼,你應該使用特殊的工具開完成文件工作,例如 Sphinx 或者 mkdocs ,所以你可以使用一個流行的標記語言(rst或markdown)來生成具有適當引用連結的漂亮的文件。

結論

在熟悉上述話題之後,一定能夠生成符合社群標準的漂亮的結構化專案和庫。不要忘記總是使用PEP-8!

相關文章