【譯】Python 發(fā)布包

《翻譯-Python 發(fā)布包》斗躏，原文地址：https://packaging.python.org/tutorials/packaging-projects/

這篇指南向您介紹如何打包一個簡單的 python 工程蹄胰，內(nèi)容包含包的目錄結(jié)構(gòu)以及需要添加哪些必要的文件具帮。怎樣編譯包柿究？以及怎樣將包上傳到 pypi 公共倉庫斑司。

一個簡單的項目

現(xiàn)有一個叫做 example_pkg的包需要發(fā)布绽媒。如果您已經(jīng)擁有一個需要打包的工程妙蔗，我們建議向如下的目錄結(jié)構(gòu)去規(guī)整您的工程傲霸。

packaging_tutorial
└── example_pkg
    └── __init__.py

一旦按照如上的目錄結(jié)構(gòu)創(chuàng)建項目，接下來所有在命令行運行的指令只需切換到根目錄下即可眉反，即——$ cd packaging_tutorial

創(chuàng)建包文件

現(xiàn)在你需要創(chuàng)建一些文件昙啄，為發(fā)布包做準(zhǔn)備。你需要將它們放在根目錄下寸五，暫時可以創(chuàng)建空文件梳凛，內(nèi)容待會填充。

packaging_tutorial
├── LICENSE
├── README.md
├── example_pkg
│   └── __init__.py
├── setup.py
└── tests

創(chuàng)建測試文件夾

tests/ 目錄用于單元測試梳杏，暫時先讓它空著吧韧拒。

創(chuàng)建 setup.py 文件

setup.py是 setuptools 工具的構(gòu)件腳本，它會告訴 setuptools 包的一些基礎(chǔ)信息以及包含哪些文件十性。

打開 setup.py 文件然后寫入如下內(nèi)容叛溢。您需要替換一些信息，主要是包名烁试，確保不會和 Pypi 公共倉庫現(xiàn)有的包名沖突雇初。

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="example-pkg-YOUR-USERNAME-HERE", # 替換成您的包名，由字母减响、數(shù)字靖诗、-郭怪、_組成
    version="0.0.1",
    author="Example Author",
    author_email="author@example.com",
    description="A small example package",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/pypa/sampleproject",
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
)

創(chuàng)建 README.md 文件

打開 README.md 文件，寫入如下內(nèi)容：

# Example Package

This is a simple example package. You can use
[Github-flavored Markdown](https://guides.github.com/features/mastering-markdown/)
to write your content.

創(chuàng)建 LICENSE 文件

每一個上傳到 Pypi 的包都需要證書刊橘，這將告訴那些安裝您包的用戶鄙才，應(yīng)當(dāng)在什么樣的情況下可以正常使用您的包。

您可以在 https://choosealicense.com/ 網(wǎng)站上選擇合適的證書促绵，一旦你確定了哪種證書攒庵，打開 LICENSE 文件然后寫入內(nèi)容。

這里假設(shè)您選擇的 MIT 證書败晴，寫入如下內(nèi)容：

Copyright (c) 2018 The Python Packaging Authority

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

打包

接下來就是生成打包產(chǎn)物了浓冒，打包產(chǎn)物將會被上傳到 Pypi 公共倉庫，并可以通過 pip 安裝到本地尖坤。

確保您已經(jīng)安裝了最新版本的 setuptools 和 wheel稳懒，如果沒有，執(zhí)行以下命令：

$ python3 -m pip install --user --upgrade setuptools wheel

運行命令進(jìn)行打包：

$ python3 setup.py sdist bdist_wheel

這條命令會在終端輸入一些內(nèi)容以及在根目錄下生成 dist 目錄：

dist/
  example_pkg_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
  example_pkg_YOUR_USERNAME_HERE-0.0.1.tar.gz

上傳打包產(chǎn)物

最后慢味，您需要將打包產(chǎn)物上傳到 Pypi 公共倉庫场梆。

您需要做的第一件事就是在 Test PyPI網(wǎng)站注冊一個賬號，Test PyPI 和 PyPI 是兩個獨立的網(wǎng)站纯路，它主要用于測試和實驗或油，并不會將包上傳到正式的 Pypi 倉庫。

前往 https://test.pypi.org/account/register/ 網(wǎng)頁驰唬，注冊一個賬號顶岸，您需要填寫一些基礎(chǔ)信息，并驗證郵箱定嗓。

當(dāng)您注冊完成后蜕琴，前往 https://test.pypi.org/manage/account/#api-tokens 網(wǎng)頁創(chuàng)建 API TOKEN ，這用于上傳包時的身份校驗宵溅。在上傳包整個流程完成之前不要關(guān)閉創(chuàng)建 token 頁面凌简。

確保您已經(jīng)安裝了最新版本的 twine ，如果沒有的話恃逻，執(zhí)行以下命令：

$ python3 -m pip install --user --upgrade twine

使用 twine命令上傳你的包：

$ python3 -m twine upload --repository testpypi dist/*

終端會讓您輸入 usernmae 和 password雏搂。username 請輸入 __token__ 字符串，password 請粘貼剛才的 token 值

（您粘貼過密碼后可能會發(fā)現(xiàn) password 后面是空的寇损，不用擔(dān)心凸郑，這出于安全考慮，密碼一般不顯示矛市，但已經(jīng)粘貼上了芙沥，回車即可）。

Uploading distributions to https://test.pypi.org/legacy/
Enter your username: [your username]
Enter your password:
Uploading example_pkg_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
100%|█████████████████████| 4.65k/4.65k [00:01<00:00, 2.88kB/s]
Uploading example_pkg_YOUR_USERNAME_HERE-0.0.1.tar.gz
100%|█████████████████████| 4.25k/4.25k [00:01<00:00, 3.05kB/s]

上面的步驟執(zhí)行完成后，您可以訪問 https://test.pypi.org/project/example-pkg-YOUR-USERNAME-HERE 查看上傳到測試倉庫的包而昨。

安裝上傳的包

現(xiàn)在救氯，使用 pip 安裝剛剛上傳的包，在本地測試下它是否功能正常吧歌憨。

創(chuàng)建虛擬環(huán)境：

$ mkdir test-pkg                                # 創(chuàng)建測試目錄
$ cd test-pkg
$ $ python -m venv .venv        # 創(chuàng)建虛擬環(huán)境     
$ source .venv/bin/acticate         # 激活虛擬環(huán)境

將下面這條命令中 example-pkg-YOUR-USERNAME-HERE 替換為你的包名着憨。

python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps example-pkg-YOUR-USERNAME-HERE

pip 會自動安裝包，終端會輸出如下信息：

Collecting example-pkg-YOUR-USERNAME-HERE
  Downloading https://test-files.pythonhosted.org/packages/.../example-pkg-YOUR-USERNAME-HERE-0.0.1-py3-none-any.whl
Installing collected packages: example-pkg-YOUR-USERNAME-HERE
Successfully installed example-pkg-YOUR-USERNAME-HERE-0.0.1

您可以在 python 解釋器或其它方式測試包的功能是否正常务嫡。

$ python
>>> import example_pkg

上傳到 PyPI 正式環(huán)境

恭喜甲抖！您已經(jīng)完成了打包以及發(fā)布到倉庫整個流程。

不要忘記心铃，這份指南只是教你將包發(fā)布到了 Test PyPI 測試倉庫准谚，而不是 PyPI 公共倉庫。當(dāng)您測試完成于个，確保包的功能性無誤后可以將包上傳到正式倉庫氛魁，可以參考本指南暮顺，僅有幾點需要注意：

選擇一個易記且獨一無二的包名厅篓。
去 https://pypi.org 網(wǎng)站注冊用戶。
使用 twine upload dist/* 上傳包到公共倉庫時捶码，輸入 pypi.org 網(wǎng)站的用戶名和密碼羽氮，并且不需要指定 --repository 參數(shù)，包將會被上傳到 PyPI 正式倉庫惫恼。
安裝包將變得更加簡單档押，只需要 $ pip install [your-package] 。