linlei04-pdemo 1.0.1

My package description

说明

本文包含了python的打包、分发、构建、测试等，比如包含了tox、mypy等。

目录结构说明

默认情况下，需要打包的工程需要放置到一个目录下，这个目录下创建配置文件，比如pyproject.toml、MANIFEST.in等文件。

setuptools

setuptools支持pyproject.toml、setup.cfg和setup.py几种方式，目前推荐使用pyproject.toml的方式，本文也以此为例进行说明，详细的请参考pyproject.toml文件内的注释。

打包命令

需要提前使用pip install build安装build工具

# 配置完成后，使用下面命令进行打包
# 命令执行完成后，会在dist目录下生成whl和tar.gz文件
# 这两个文件就可以通过 pip install 进行安装了，此时会安装到site-packages下，项目代码就可以像引用其它模块一样进行引用了
python -m build

# 查看帮助
python -m build --help

# 只打包sdist，也就是tar.gz文件(默认打包为tar.gz和whl两个文件)
python -m build -s

# 只打包whl
python -m build -w

# 加快打包速度(不安装虚拟环境)
python -m build --no-isolation -s

不建议使用setup.py，请参考: Why you shouldn’t invoke setup.py directly

自动版本识别

# 依赖于setuptools_scm，当然还有很多其它的插件可以使用
pip install setuptools_scm

项目目录下需要有版本工具的配置信息，比如git就需要有.git目录

[project]
# version = "0.0.1"  # Remove any existing version parameter.
dynamic = ["version"]

[tool.setuptools_scm]
version_file = "pkg/_version.py"
# write_to已经在新版本弃用，使用上面的version_file代替
write_to = "mypkg1/_version.py"
local_scheme = "no-local-version"

生成规则

1. 根据git的最新tag生成版本号

开发模式

# 如果已经安装到了site-packages下，先卸载
pip uninstall mypkg1
# 需要先python -m build后才可以使用，命令执行目录和python -m build在同一级，否则需要更改 .参数
# 不用重复使用下面命令，使用一次即可
pip install -e .

发布包

发布到pypi

pip install twine
# 测试发布(需要提前在pypi注册账号) https://test.pypi.org
twine upload -r testpypi dist/*
# 正式发布 https://pypi.org/
twine upload dist/*

# 默认发布到pypi,可以通过参数发布到指定的repo
# 注意需要到pypi增加自己的api token,使用api token处理username和password
twine upload --repository-url https://xxx -u username -p password dist/*

注意: api token只会出现一次，后续无法获取，故需要及时保存，而且使用时的用户名一律为: __token__ 另外：可以配置$HOME/.pypirc为如下配置，即可以不在命令行使用用户名和密码

[pypi]
  username = __token__
  password = pypi-xxxx

tox

# 查看env列表
tox list

# 执行
tox
tox run

# 指定执行环境
tox run -e py310

# 如果命令行有{}替换符号，可以通过--的方式替换{}
tox run -e py310 -- -v

make

如果在windows下执行，建议使用WSL，安装并启动

windows下访问wsl目录，直接在资源管理器输入\\wsl$就可以查看；linux下访问windows，可以直接cd /mnt即可 wsl里面，进入到指定目录后，如果想通过vscode编辑代码，可以通过code .命令启动vscode

Makefile里面定义了各项动作，比如要执行tox，只需要执行make test命令即可

shields.io生成badges

参考demo0内部README.md文件和shields.io官方链接

readthedocs

sphinx

# 安装
pip install sphinx

# 快速生成一个基础的目录
sphinx-quickstart

# 编译
sphinx-build -M html source build
# 如果有自动生成makefile，也可以使用下面的make命令
make html

rst语法请参考: GettingStarted

本项目总结

# 测试代码
make test

# 打包代码并发布到pypi (https://pypi.org/project/linlei04-pdemo/)
make release

# 生成文档并发布到read the doc
# 直接进入: https://readthedocs.org/projects/pdemo/ 导入github项目自动构建即可
# https://pdemo.readthedocs.io/en/latest/

参考链接

1. setuptools
2. MANIFEST.in
3. pyproject.toml
4. twine
5. packaging-projects
6. setuptools-scm
7. tox
8. shields.io
9. sphinx
10. readthedocs
11. readthedocs-tutorial

其它:

1. Why you shouldn’t invoke setup.py directly
2. setuptools-scm配置项
3. RST-Directives
4. RST-Builders