2021 年發布 Python 軟件包的正確姿勢

作者：Anton 2021-04-20 22:27:22

如果您像我一樣，偶爾編寫一個有用的python實用小程序，并希望與您的同事共享。做到這一點的最好方法是制作一個Python軟件包：它易于安裝，并且可以避免進行拷貝操作。

本文轉載自微信公眾號「Python中文社區」，作者Anton 。轉載本文請聯系Python中文社區公眾號。

您可能會認為創建軟件包很麻煩。其實現在已經不會這樣了。我將通過此分步指南進行說明。只需執行三個主要步驟(以及一系列可選步驟)，并輔以幾個GitHub鏈接即可。

1.初始化

我們將創建podsearch - 一種在iTunes中搜索播客的實用程序。讓我們創建一個目錄和一個虛擬環境：

$ mkdir podsearch 
$ cd podsearch 
$ python3 -m venv env 
$ . env/bin/activate

定義一個最小的包結構：

. 
├── .gitignore 
└── podsearch 
    └── __init__.py 
"""Let's find some podcasts!""" 
 
 __version__ = "0.1.0" 
 
 
 def search(name, count=5): 
     """Search podcast by name.""" 
     raise NotImplementedError()

2.測試包

用Python創建一個包曾經是一個麻煩的任務。幸運的是，如今有一個很棒的 flit (https://flit.readthedocs.io/en/latest/)小程序可以簡化所有操作。讓我們安裝它：

pip install flit

并創建軟件包描述：

$ flit init 
Module name [podsearch]: 
Author [Anton Zhiyanov]: 
Author email [m@antonz.org]: 
Home page [https://github.com/nalgeon/podsearch-py]: 
Choose a license (see http://choosealicense.com/ for more info) 
1. MIT - simple and permissive 
2. Apache - explicitly grants patent rights 
3. GPL - ensures that code based on this is shared with the same terms 
4. Skip - choose a license later 
Enter 1-4 [1]: 1 
 
Written pyproject.toml; edit that file to add optional extra info.

pyproject.toml

Flit已創建pyproject.toml - 項目元數據文件。它已經具有將程序包發布到公共存儲庫-PyPI所需的一切。

注冊TestPyPi(測試存儲庫)和PyPI(主要存儲庫)。它們是完全獨立的，因此您將需要兩個帳戶。

在~/ .pypirc中設置對存儲庫的訪問權限：

[distutils] 
index-servers = 
  pypi 
  pypitest 
 
[pypi] 
username: nalgeon  # replace with your PyPI username 
 
[pypitest] 
repository: https://test.pypi.org/legacy/ 
username: nalgeon  # replace with your TestPyPI username

并將軟件包發布到測試存儲庫：

$ flit publish --repository pypitest 
Found 4 files tracked in git 
... 
Package is at https://test.pypi.org/project/podsearch/

完畢!該軟件包可在TestPyPi上獲得。

3.公開軟件包

讓我們改進代碼，以便它能夠實際搜索播客：

# ... 
 
SEARCH_URL = "https://itunes.apple.com/search" 
 
@dataclass 
class Podcast: 
    """Podcast metadata.""" 
 
    id: str 
    name: str 
    author: str 
    url: str 
    feed: Optional[str] = None 
    category: Optional[str] = None 
    image: Optional[str] = None 
 
 
def search(name: str, limit: int = 5) -> List[Podcast]: 
    """Search podcast by name.""" 
    params = {"term": name, "limit": limit, "media": "podcast"} 
    response = _get(url=SEARCH_URL, params=params) 
    return _parse(response)

并發布到主存儲庫-PyPI。僅在您的程序包中包含有用的代碼后，才執行此步驟。不要發布無效的程序包和存根。

flit publish

發布完畢!是時候與同事分享了。為了使軟件包易于使用，我建議您再執行以下幾個步驟。

A.自述文件Readme和變更日志changelog

沒人喜歡寫文檔。但是，如果沒有文檔，人們不太可能會想要安裝您的軟件包，因此我們需要添加README.md和CHANGELOG.md。

README.md
CHANGELOG.md

將README添加到pyproject.toml，以便PyPI在軟件包頁面上顯示它：

description-file = "README.md"

還要指定受支持的最低Python版本：

requires-python = ">=3.7"

更新__init__.py中的版本，并通過flit publish發布軟件包：

B.Linters和tests

我們來考慮一下格式設置(black)，測試覆蓋率(coverage)，代碼質量(flake8，pylint，mccabe)和靜態分析(mypy)。我們將通過tox處理一切。

$ pip install black coverage flake8 mccabe mypy pylint pytest tox

在tox.ini中創建tox配置：

[tox] 
isolated_build = True 
envlist = py37,py38,py39 
 
[testenv] 
deps = 
    black 
    coverage 
    flake8 
    mccabe 
    mypy 
    pylint 
    pytest 
commands = 
    black podsearch 
    flake8 podsearch 
    pylint podsearch 
    mypy podsearch 
    coverage erase 
    coverage run --include=podsearch/* -m pytest -ra 
    coverage report -m

tox.ini

并運行所有檢查：

$ tox -e py39 
... 
py39 run-test: commands[0] | black podsearch 
All done!  
... 
py39 run-test: commands[2] | pylint podsearch 
Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00) 
... 
py39 run-test: commands[6] | coverage report -m 
TOTAL 100% 
... 
py39: commands succeeded 
congratulations :)

linters檢測通過，測試也通過了，覆蓋率是100%。

C.云構建

每個可靠的開源項目在每次提交后都會進行云測試，因此我們也將這樣做。一個很好的附加效果是自述文件中有漂亮的徽章。

讓我們使用GitHub Actions構建項目，使用Codecov檢查測試覆蓋率，并使用Code Climate檢查代碼質量。

您將必須注冊Codecov和Code Climate(均支持GitHub登錄)并在設置中啟用軟件包存儲庫。

之后，將GitHub Actions構建配置添加到.github / workflows / build.yml：

# ... 
jobs: 
    build: 
        runs-on: ubuntu-latest 
        strategy: 
            matrix: 
                python-version: [3.7, 3.8, 3.9] 
 
        env: 
            USING_COVERAGE: "3.9" 
 
        steps: 
            - name: Checkout sources 
              uses: actions/checkout@v2 
 
            - name: Set up Python 
              uses: actions/setup-python@v2 
              with: 
                  python-version: $ 
 
            - name: Install dependencies 
              run: | 
                  python -m pip install --upgrade pip 
                  python -m pip install black coverage flake8 flit mccabe mypy pylint pytest tox tox-gh-actions 
 
            - name: Run tox 
              run: | 
                  python -m tox 
 
            - name: Upload coverage to Codecov 
              uses: codecov/codecov-action@v1 
              if: contains(env.USING_COVERAGE, matrix.python-version) 
              with: 
                  fail_ci_if_error: true

build.yml

就像我們前面一樣，GitHub通過tox進行測試。tox-gh-actions軟件包和USING_COVERAGE設置可確保tox使用與strategy.matrix所需的 GitHub Actions 相同的 Python 版本。

最后一步將測試覆蓋率發送給Codecov。Code Climate不需要單獨的步驟-它會自動發現存儲庫更改。

現在，一分鐘內提交，推送并享受結果。并且讓每個人也喜歡向README.md添加徽章：

[![PyPI Version][pypi-image]][pypi-url] 
[![Build Status][build-image]][build-url] 
[![Code Coverage][coverage-image]][coverage-url] 
[![Code Quality][quality-image]][quality-url] 
 
... 
 
<!-- Badges --> 
 
[pypi-image]: https://img.shields.io/pypi/v/podsearch 
[pypi-url]: https://pypi.org/project/podsearch/ 
[build-image]: https://github.com/nalgeon/podsearch-py/actions/workflows/build.yml/badge.svg 
[build-url]: https://github.com/nalgeon/podsearch-py/actions/workflows/build.yml 
[coverage-image]: https://codecov.io/gh/nalgeon/podsearch-py/branch/main/graph/badge.svg 
[coverage-url]: https://codecov.io/gh/nalgeon/podsearch-py 
[quality-image]: https://api.codeclimate.com/v1/badges/3130fa0ba3b7993fbf0a/maintainability 
[quality-url]: https://codeclimate.com/github/nalgeon/podsearch-py

是不是很酷?

D.任務自動化

tox很好，但對于開發來說不是很方便。運行單個命令(例如pylint，coverage等)的速度更快。但是它們非常冗長，因此我們將一些無意義的操作進行自動化處理。

讓我們為Makefile的頻繁操作創建簡短的別名：

.DEFAULT_GOAL := help 
.PHONY: coverage deps help lint push test 
 
coverage:  ## Run tests with coverage 
 coverage erase 
 coverage run --include=podsearch/* -m pytest -ra 
 coverage report -m 
 
deps:  ## Install dependencies 
 pip install black coverage flake8 mccabe mypy pylint pytest tox 
 
lint:  ## Lint and static-check 
 flake8 podsearch 
 pylint podsearch 
 mypy podsearch 
 
push:  ## Push code with tags 
 git push && git push --tags 
 
test:  ## Run tests 
 pytest -ra

Makefile

這是我們的任務：

$ make help 
Usage: make [task] 
 
task                 help 
------               ---- 
coverage             Run tests with coverage 
deps                 Install dependencies 
lint                 Lint and static-check 
push                 Push code with tags 
test                 Run tests 
help                 Show help message

為了使代碼更簡潔，請使用make調用替換原始的build.yml步驟：

- name: Install dependencies 
  run: | 
      make deps 
 
- name: Run tox 
  run: | 
      make tox

E.云發布

GitHub有能力為我們運行flit publish。讓我們創建一個單獨的工作流程：

name: publish 
 
on: 
    release: 
        types: [created] 
 
jobs: 
    publish: 
        runs-on: ubuntu-latest 
        steps: 
            - name: Checkout sources 
              uses: actions/checkout@v2 
 
            - name: Set up Python 
              uses: actions/setup-python@v2 
              with: 
                  python-version: "3.9" 
 
            - name: Install dependencies 
              run: | 
                  make deps 
 
            - name: Publish to PyPi 
              env: 
                  FLIT_USERNAME: ${{ secrets.PYPI_USERNAME }} 
                  FLIT_PASSWORD: ${{ secrets.PYPI_PASSWORD }} 
              run: | 
                  make publish

publish.yml

在存儲庫設置(Settings > Secrets > New repository secret)中設置了PYPI_USERNAME和PYPI_PASSWORD。使用您的PyPi用戶名和密碼，甚至更好的-API令牌。

現在，一旦創建新版本，GitHub將自動發布該軟件包。

您的軟件包已準備就緒!它具有人們夢寐以求的一切：干凈的代碼，清晰的文檔，測試和云構建。是時候告訴你的同事和朋友了。

這些設置將使您的 Python 軟件包變得AWESOME：

pyproject.toml
tox.ini
Makefile
build.yml
publish.yml

責任編輯：武曉燕來源： Python中文社區