發布 Python 模組
****************

電子郵件:
   distutils-sig@python.org

作為一個普及的開源開發專案，Python 有一個活躍的支持社群，由其貢獻者及
使用者組成，而他們也讓他們的軟體可被其他 Python 開發者在開源授權條款下
使用。

這樣可以讓 Python 使用者們有效地共享和合作，並受益於其他人對常見（有時
甚至是罕見）的問題已經建立的解決方案，更可以在公開社群中潛在地貢獻他們
自己的解決方案。

這份指南涵蓋了上述過程中的發布部分。如果是要安裝其他的 Python 專案，請
參考安裝 Python 模組指南。

備註:

  對於企業和其他機構的使用者，要注意到，許多組織對於使用和貢獻開源軟體
  都有自己的政策。在開始使用配備 Python 的發布及安裝工具時，請將那些政
  策納入考量。


關鍵術語
========

* Python 套件索引 (Python Package Index) 是開源授權套件的一個公共儲存
  庫，其中的套件皆可被其他 Python 使用者所使用。

* Python 封裝管理站 (Python Packaging Authority) 是一個由開發者和說明
  文件作者組成的團隊，負責維護及改進標準封裝工具，以及相關的元資料
  (metadata) 和檔案格式標準。他們在 GitHub 和 Bitbucket 這兩個平台上維
  護各種工具、說明文件及問題追蹤系統。

* "distutils" 是最早的建置和發布系統，於 1998 年首次被加入 Python 標準
  函式庫。雖然直接使用 "distutils" 的方式已經被逐步淘汰，它仍然是現今
  封裝和發布的基礎結構根基，而且它不僅仍然是標準函式庫的一部分，它的名
  稱也以其他的方式存活著（例如：用於協調 Python 封裝標準開發的郵寄清單
  就是以它命名）。

* setuptools 是 "distutils" 的一個（主要的）偶然出現的替代品，它於
  2004 年首次被發布。相較於未修改的 "distutils" 工具，它最值得注意的新
  功能，是能夠宣告對其他套件的依賴性 (dependency)。它目前被推薦為
  "distutils" 的一個替代方案，因其更新較為頻繁，且能在各個廣泛的
  Python 版本之間，為較新的封裝標準提供一致性的支援。

* wheel（在此文中）是一個將 "bdist_wheel" 指令附加到
  "distutils"/setuptools 的專案。這會產生一個跨平台的二進制封裝格式（
  稱為「wheels」或「wheel 檔案」，並於 **PEP 427** 中被定義），它可讓
  Python 函式庫，甚至那些包含二進制擴充的函式庫，可以在系統中被安裝，
  但不需要在本機進行建置。


開源授權與協同合作
==================

在世界上多數地方，軟體會自動受版權所保護。這代表著其他開發人員需要明確
的許可，才能複製、使用、修改和重新發布軟體。

開源授權是一種以相對一致的方式，明確地授予此類許可的方法，它允許開發人
員透過為各種問題提供免費可用的共通解決方案，來達到高效率的共享和協作。
這使得許多開發人員可以自由地將更多時間專注於處理他們在特定情況中遇到的
相對獨特的問題。

Python 所提供的發布工具，被設計為讓開發人員能夠以合理的直觀方式，對該
公用軟體庫回饋他們自己的貢獻，前提是他們願意這樣做。

同一個發布工具也可用於在組織內發布軟體，不論該軟體是否有作為開源軟體被
發布。


安裝工具
========

標準函式庫並不包含那些支援現代 Python 封裝標準的建置工具，因為核心開發
團隊發現，提供始終可運作的標準工具是很重要的，即使它們是在舊版的
Python 上運作。

當今被推薦的建置及發布工具，可以透過在命令列中呼叫 "pip" 模組來安裝它
們：

   python -m pip install setuptools wheel twine

備註:

  對於 POSIX 使用者（包括 Mac OS X 和 Linux 使用者），這些教學皆假設有
  使用 *virtual environment*。對於 Windows 使用者，這些教學皆假設在安
  裝 Python 時，「可調整系統 PATH 環境變數」的選項已被選取。

Python 封裝使用者指南包含了關於當今推薦工具的更多細節。


閱讀 Python 封裝使用者指南
==========================

Python 封裝使用者指南涵蓋了關於建立和發布一個專案的各項關鍵步驟和元素
：

* 專案結構

* 專案建置與封裝

* 上傳專案至 Python 套件索引 (Python Package Index)

* .pypirc 檔案


我該如何...？
=============

接下來是關於一些常見任務的快速解答或連結。


...為我的專案選擇一個名稱？
---------------------------

這不是一個簡單的題目，但這裡有一些提示：

* 檢查 Python 套件索引，看看該名稱是否已被使用

* 檢查常用的代管網站，像是 GitHub、Bitbucket 等，看看是否已經有一個使
  用該名稱的專案

* 檢查您正在考慮的名稱在網路搜尋中會出現的內容

* 避免使用特別常見的單字，尤其是那些有多重含義的單字，因為它們會讓使用
  者在搜尋你的軟體時時很難找到它


...建立和發布二進制擴充？
-------------------------

實際上這是一個非常複雜的題目，因為有各式各樣的替代方案可使用，取決於您
確實想要達成的目標。更多的資訊和建議，請參閱 Python 封裝使用者指南。

也參考: Python 封裝使用者指南：二進制擴充
