| Name | linlei04-pdemo JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | |
| Summary | My package description |
| upload_time | 2023-11-03 05:35:05 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://pypi.org/project/linlei04-pdemo/)
[](https://pypi.org/project/linlei04-pdemo/)
[](https://pypi.org/project/linlei04-pdemo/)
[](https://pypi.org/project/linlei04-pdemo/)
[](https://github.com/xmlclone/pdemo/blob/main/LICENSE)
[](hhttps://github.com/xmlclone/pdemo/graphs/contributors)
# 说明
本文包含了python的打包、分发、构建、测试等，比如包含了`tox`、`mypy`等。
# 目录结构说明
默认情况下，需要打包的工程需要放置到一个目录下，这个目录下创建配置文件，比如`pyproject.toml`、`MANIFEST.in`等文件。
# setuptools
[setuptools](https://setuptools.pypa.io/en/latest/)支持`pyproject.toml`、`setup.cfg`和`setup.py`几种方式，目前推荐使用`pyproject.toml`的方式，本文也以此为例进行说明，详细的请参考`pyproject.toml`文件内的注释。
## 打包命令
> 需要提前使用`pip install build`安装`build`工具
```shell
# 配置完成后，使用下面命令进行打包
# 命令执行完成后，会在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](https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html)
## 自动版本识别
```shell
# 依赖于setuptools_scm，当然还有很多其它的插件可以使用
pip install setuptools_scm
```
> 项目目录下需要有版本工具的配置信息，比如git就需要有`.git`目录
```toml
[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生成版本号
## 开发模式
```shell
# 如果已经安装到了site-packages下，先卸载
pip uninstall mypkg1
# 需要先python -m build后才可以使用，命令执行目录和python -m build在同一级，否则需要更改 .参数
# 不用重复使用下面命令，使用一次即可
pip install -e .
```
# 发布包
## 发布到pypi
```shell
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`为如下配置，即可以不在命令行使用用户名和密码
```ini
[pypi]
username = __token__
password = pypi-xxxx
```
# tox
```shell
# 查看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官方链接](https://shields.io/badges/py-pi-python-version)
# readthedocs
# sphinx
```shell
# 安装
pip install sphinx
# 快速生成一个基础的目录
sphinx-quickstart
# 编译
sphinx-build -M html source build
# 如果有自动生成makefile，也可以使用下面的make命令
make html
```
> rst语法请参考: [GettingStarted](https://www.sphinx-doc.org/en/master/tutorial/getting-started.html)
# 本项目总结
```shell
# 测试代码
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](https://setuptools.pypa.io/en/latest/)
2. [MANIFEST.in](https://packaging.python.org/en/latest/guides/using-manifest-in/#manifest-in-commands)
3. [pyproject.toml](https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html)
4. [twine](https://twine.readthedocs.io/en/stable/index.html)
5. [packaging-projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
6. [setuptools-scm](https://pypi.org/project/setuptools-scm/)
7. [tox](https://tox.wiki/en/latest/index.html)
8. [shields.io](https://shields.io/badges/py-pi-python-version)
9. [sphinx](https://www.sphinx-doc.org/en/master/)
10. [readthedocs](https://about.readthedocs.com/)
11. [readthedocs-tutorial](https://docs.readthedocs.io/en/stable/tutorial/index.html)
> 其它:
1. [Why you shouldn’t invoke setup.py directly](https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html)
2. [setuptools-scm配置项](https://setuptools-scm.readthedocs.io/en/latest/config/)
3. [RST-Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-directives)
4. [RST-Builders](https://www.sphinx-doc.org/en/master/usage/builders/index.html#builders)
Raw data
{
"_id": null,
"home_page": "",
"name": "linlei04-pdemo",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "xmlclone <xmlclone@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e4/68/58e5fa8c9254ebf4da5e6314497b3013555a89a6b0d804c9345a1892b4a1/linlei04-pdemo-1.0.1.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/linlei04-pdemo/)\n[](https://pypi.org/project/linlei04-pdemo/)\n[](https://pypi.org/project/linlei04-pdemo/)\n[](https://pypi.org/project/linlei04-pdemo/)\n[](https://github.com/xmlclone/pdemo/blob/main/LICENSE)\n[](hhttps://github.com/xmlclone/pdemo/graphs/contributors)\n\n# \u8bf4\u660e\n\n\u672c\u6587\u5305\u542b\u4e86python\u7684\u6253\u5305\u3001\u5206\u53d1\u3001\u6784\u5efa\u3001\u6d4b\u8bd5\u7b49\uff0c\u6bd4\u5982\u5305\u542b\u4e86`tox`\u3001`mypy`\u7b49\u3002\n\n# \u76ee\u5f55\u7ed3\u6784\u8bf4\u660e\n\n\u9ed8\u8ba4\u60c5\u51b5\u4e0b\uff0c\u9700\u8981\u6253\u5305\u7684\u5de5\u7a0b\u9700\u8981\u653e\u7f6e\u5230\u4e00\u4e2a\u76ee\u5f55\u4e0b\uff0c\u8fd9\u4e2a\u76ee\u5f55\u4e0b\u521b\u5efa\u914d\u7f6e\u6587\u4ef6\uff0c\u6bd4\u5982`pyproject.toml`\u3001`MANIFEST.in`\u7b49\u6587\u4ef6\u3002\n\n# setuptools\n\n[setuptools](https://setuptools.pypa.io/en/latest/)\u652f\u6301`pyproject.toml`\u3001`setup.cfg`\u548c`setup.py`\u51e0\u79cd\u65b9\u5f0f\uff0c\u76ee\u524d\u63a8\u8350\u4f7f\u7528`pyproject.toml`\u7684\u65b9\u5f0f\uff0c\u672c\u6587\u4e5f\u4ee5\u6b64\u4e3a\u4f8b\u8fdb\u884c\u8bf4\u660e\uff0c\u8be6\u7ec6\u7684\u8bf7\u53c2\u8003`pyproject.toml`\u6587\u4ef6\u5185\u7684\u6ce8\u91ca\u3002\n\n## \u6253\u5305\u547d\u4ee4\n\n> \u9700\u8981\u63d0\u524d\u4f7f\u7528`pip install build`\u5b89\u88c5`build`\u5de5\u5177\n\n```shell\n# \u914d\u7f6e\u5b8c\u6210\u540e\uff0c\u4f7f\u7528\u4e0b\u9762\u547d\u4ee4\u8fdb\u884c\u6253\u5305\n# \u547d\u4ee4\u6267\u884c\u5b8c\u6210\u540e\uff0c\u4f1a\u5728dist\u76ee\u5f55\u4e0b\u751f\u6210whl\u548ctar.gz\u6587\u4ef6\n# \u8fd9\u4e24\u4e2a\u6587\u4ef6\u5c31\u53ef\u4ee5\u901a\u8fc7 pip install \u8fdb\u884c\u5b89\u88c5\u4e86\uff0c\u6b64\u65f6\u4f1a\u5b89\u88c5\u5230site-packages\u4e0b\uff0c\u9879\u76ee\u4ee3\u7801\u5c31\u53ef\u4ee5\u50cf\u5f15\u7528\u5176\u5b83\u6a21\u5757\u4e00\u6837\u8fdb\u884c\u5f15\u7528\u4e86\npython -m build\n\n# \u67e5\u770b\u5e2e\u52a9\npython -m build --help\n\n# \u53ea\u6253\u5305sdist\uff0c\u4e5f\u5c31\u662ftar.gz\u6587\u4ef6(\u9ed8\u8ba4\u6253\u5305\u4e3atar.gz\u548cwhl\u4e24\u4e2a\u6587\u4ef6)\npython -m build -s\n\n# \u53ea\u6253\u5305whl\npython -m build -w\n\n# \u52a0\u5feb\u6253\u5305\u901f\u5ea6(\u4e0d\u5b89\u88c5\u865a\u62df\u73af\u5883)\npython -m build --no-isolation -s\n```\n\n> \u4e0d\u5efa\u8bae\u4f7f\u7528`setup.py`\uff0c\u8bf7\u53c2\u8003: [Why you shouldn\u2019t invoke setup.py directly](https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html)\n\n## \u81ea\u52a8\u7248\u672c\u8bc6\u522b\n\n```shell\n# \u4f9d\u8d56\u4e8esetuptools_scm\uff0c\u5f53\u7136\u8fd8\u6709\u5f88\u591a\u5176\u5b83\u7684\u63d2\u4ef6\u53ef\u4ee5\u4f7f\u7528\npip install setuptools_scm\n```\n\n> \u9879\u76ee\u76ee\u5f55\u4e0b\u9700\u8981\u6709\u7248\u672c\u5de5\u5177\u7684\u914d\u7f6e\u4fe1\u606f\uff0c\u6bd4\u5982git\u5c31\u9700\u8981\u6709`.git`\u76ee\u5f55\n\n```toml\n[project]\n# version = \"0.0.1\" # Remove any existing version parameter.\ndynamic = [\"version\"]\n\n[tool.setuptools_scm]\nversion_file = \"pkg/_version.py\"\n# write_to\u5df2\u7ecf\u5728\u65b0\u7248\u672c\u5f03\u7528\uff0c\u4f7f\u7528\u4e0a\u9762\u7684version_file\u4ee3\u66ff\nwrite_to = \"mypkg1/_version.py\"\nlocal_scheme = \"no-local-version\"\n```\n\n### \u751f\u6210\u89c4\u5219\n\n1. \u6839\u636egit\u7684\u6700\u65b0tag\u751f\u6210\u7248\u672c\u53f7\n\n## \u5f00\u53d1\u6a21\u5f0f\n\n```shell\n# \u5982\u679c\u5df2\u7ecf\u5b89\u88c5\u5230\u4e86site-packages\u4e0b\uff0c\u5148\u5378\u8f7d\npip uninstall mypkg1\n# \u9700\u8981\u5148python -m build\u540e\u624d\u53ef\u4ee5\u4f7f\u7528\uff0c\u547d\u4ee4\u6267\u884c\u76ee\u5f55\u548cpython -m build\u5728\u540c\u4e00\u7ea7\uff0c\u5426\u5219\u9700\u8981\u66f4\u6539 .\u53c2\u6570\n# \u4e0d\u7528\u91cd\u590d\u4f7f\u7528\u4e0b\u9762\u547d\u4ee4\uff0c\u4f7f\u7528\u4e00\u6b21\u5373\u53ef\npip install -e .\n```\n\n# \u53d1\u5e03\u5305\n\n## \u53d1\u5e03\u5230pypi\n\n```shell\npip install twine\n# \u6d4b\u8bd5\u53d1\u5e03(\u9700\u8981\u63d0\u524d\u5728pypi\u6ce8\u518c\u8d26\u53f7) https://test.pypi.org\ntwine upload -r testpypi dist/*\n# \u6b63\u5f0f\u53d1\u5e03 https://pypi.org/\ntwine upload dist/*\n\n# \u9ed8\u8ba4\u53d1\u5e03\u5230pypi,\u53ef\u4ee5\u901a\u8fc7\u53c2\u6570\u53d1\u5e03\u5230\u6307\u5b9a\u7684repo\n# \u6ce8\u610f\u9700\u8981\u5230pypi\u589e\u52a0\u81ea\u5df1\u7684api token,\u4f7f\u7528api token\u5904\u7406username\u548cpassword\ntwine upload --repository-url https://xxx -u username -p password dist/*\n```\n\n> \u6ce8\u610f: api token\u53ea\u4f1a\u51fa\u73b0\u4e00\u6b21\uff0c\u540e\u7eed\u65e0\u6cd5\u83b7\u53d6\uff0c\u6545\u9700\u8981\u53ca\u65f6\u4fdd\u5b58\uff0c\u800c\u4e14\u4f7f\u7528\u65f6\u7684\u7528\u6237\u540d\u4e00\u5f8b\u4e3a: `__token__`\n> \u53e6\u5916\uff1a\u53ef\u4ee5\u914d\u7f6e`$HOME/.pypirc`\u4e3a\u5982\u4e0b\u914d\u7f6e\uff0c\u5373\u53ef\u4ee5\u4e0d\u5728\u547d\u4ee4\u884c\u4f7f\u7528\u7528\u6237\u540d\u548c\u5bc6\u7801\n\n```ini\n[pypi]\n username = __token__\n password = pypi-xxxx\n```\n\n# tox\n\n```shell\n# \u67e5\u770benv\u5217\u8868\ntox list\n\n# \u6267\u884c\ntox\ntox run\n\n# \u6307\u5b9a\u6267\u884c\u73af\u5883\ntox run -e py310\n\n# \u5982\u679c\u547d\u4ee4\u884c\u6709{}\u66ff\u6362\u7b26\u53f7\uff0c\u53ef\u4ee5\u901a\u8fc7--\u7684\u65b9\u5f0f\u66ff\u6362{}\ntox run -e py310 -- -v\n```\n\n# make\n\n\u5982\u679c\u5728windows\u4e0b\u6267\u884c\uff0c\u5efa\u8bae\u4f7f\u7528WSL\uff0c\u5b89\u88c5\u5e76\u542f\u52a8\n\n> windows\u4e0b\u8bbf\u95eewsl\u76ee\u5f55\uff0c\u76f4\u63a5\u5728\u8d44\u6e90\u7ba1\u7406\u5668\u8f93\u5165`\\\\wsl$`\u5c31\u53ef\u4ee5\u67e5\u770b\uff1blinux\u4e0b\u8bbf\u95eewindows\uff0c\u53ef\u4ee5\u76f4\u63a5`cd /mnt`\u5373\u53ef\n> wsl\u91cc\u9762\uff0c\u8fdb\u5165\u5230\u6307\u5b9a\u76ee\u5f55\u540e\uff0c\u5982\u679c\u60f3\u901a\u8fc7vscode\u7f16\u8f91\u4ee3\u7801\uff0c\u53ef\u4ee5\u901a\u8fc7`code .`\u547d\u4ee4\u542f\u52a8vscode\n\n`Makefile`\u91cc\u9762\u5b9a\u4e49\u4e86\u5404\u9879\u52a8\u4f5c\uff0c\u6bd4\u5982\u8981\u6267\u884c`tox`\uff0c\u53ea\u9700\u8981\u6267\u884c`make test`\u547d\u4ee4\u5373\u53ef\n\n# shields.io\u751f\u6210badges\n\n\u53c2\u8003demo0\u5185\u90e8README.md\u6587\u4ef6\u548c[shields.io\u5b98\u65b9\u94fe\u63a5](https://shields.io/badges/py-pi-python-version)\n\n# readthedocs\n\n# sphinx\n\n```shell\n# \u5b89\u88c5\npip install sphinx\n\n# \u5feb\u901f\u751f\u6210\u4e00\u4e2a\u57fa\u7840\u7684\u76ee\u5f55\nsphinx-quickstart\n\n# \u7f16\u8bd1\nsphinx-build -M html source build\n# \u5982\u679c\u6709\u81ea\u52a8\u751f\u6210makefile\uff0c\u4e5f\u53ef\u4ee5\u4f7f\u7528\u4e0b\u9762\u7684make\u547d\u4ee4\nmake html\n```\n\n> rst\u8bed\u6cd5\u8bf7\u53c2\u8003: [GettingStarted](https://www.sphinx-doc.org/en/master/tutorial/getting-started.html)\n\n\n# \u672c\u9879\u76ee\u603b\u7ed3\n\n```shell\n# \u6d4b\u8bd5\u4ee3\u7801\nmake test\n\n# \u6253\u5305\u4ee3\u7801\u5e76\u53d1\u5e03\u5230pypi (https://pypi.org/project/linlei04-pdemo/)\nmake release\n\n# \u751f\u6210\u6587\u6863\u5e76\u53d1\u5e03\u5230read the doc\n# \u76f4\u63a5\u8fdb\u5165: https://readthedocs.org/projects/pdemo/ \u5bfc\u5165github\u9879\u76ee\u81ea\u52a8\u6784\u5efa\u5373\u53ef\n# https://pdemo.readthedocs.io/en/latest/\n```\n\n# \u53c2\u8003\u94fe\u63a5\n\n1. [setuptools](https://setuptools.pypa.io/en/latest/)\n2. [MANIFEST.in](https://packaging.python.org/en/latest/guides/using-manifest-in/#manifest-in-commands)\n3. [pyproject.toml](https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html)\n4. [twine](https://twine.readthedocs.io/en/stable/index.html)\n5. [packaging-projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/)\n6. [setuptools-scm](https://pypi.org/project/setuptools-scm/)\n7. [tox](https://tox.wiki/en/latest/index.html)\n8. [shields.io](https://shields.io/badges/py-pi-python-version)\n9. [sphinx](https://www.sphinx-doc.org/en/master/)\n10. [readthedocs](https://about.readthedocs.com/)\n11. [readthedocs-tutorial](https://docs.readthedocs.io/en/stable/tutorial/index.html)\n\n\n> \u5176\u5b83:\n1. [Why you shouldn\u2019t invoke setup.py directly](https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html)\n2. [setuptools-scm\u914d\u7f6e\u9879](https://setuptools-scm.readthedocs.io/en/latest/config/)\n3. [RST-Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-directives)\n4. [RST-Builders](https://www.sphinx-doc.org/en/master/usage/builders/index.html#builders)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "My package description",
"version": "1.0.1",
"project_urls": {
"Code": "https://github.com/xmlclone/pdemo",
"Documentation": "https://github.com/xmlclone/pdemo",
"Help/Questions": "https://github.com/xmlclone/pdemo",
"Homepage": "https://github.com/xmlclone/pdemo",
"Issue tracker": "https://github.com/xmlclone/pdemo"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "88c31ed3bd7a9d575be273d4c5573e85df9ba6c34ace26d512e8076d5b3e95d5",
"md5": "8649b4a51dae72ef993c5eec15698595",
"sha256": "5014da1befb4b245da4dfdce75dde93364d5830b9117bc1f1115ddca991bd77d"
},
"downloads": -1,
"filename": "linlei04_pdemo-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8649b4a51dae72ef993c5eec15698595",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 17890,
"upload_time": "2023-11-03T05:35:03",
"upload_time_iso_8601": "2023-11-03T05:35:03.204949Z",
"url": "https://files.pythonhosted.org/packages/88/c3/1ed3bd7a9d575be273d4c5573e85df9ba6c34ace26d512e8076d5b3e95d5/linlei04_pdemo-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e46858e5fa8c9254ebf4da5e6314497b3013555a89a6b0d804c9345a1892b4a1",
"md5": "e8a7afce17bfa242a465395fa8362863",
"sha256": "0e3618e280be11852dc30377b71d26f396b69393290befd5909b81b0df842568"
},
"downloads": -1,
"filename": "linlei04-pdemo-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "e8a7afce17bfa242a465395fa8362863",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 23702,
"upload_time": "2023-11-03T05:35:05",
"upload_time_iso_8601": "2023-11-03T05:35:05.106040Z",
"url": "https://files.pythonhosted.org/packages/e4/68/58e5fa8c9254ebf4da5e6314497b3013555a89a6b0d804c9345a1892b4a1/linlei04-pdemo-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-03 05:35:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xmlclone",
"github_project": "pdemo",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"tox": true,
"lcname": "linlei04-pdemo"
}
