Update Lab 5
This commit is contained in:
parent
632cb25ef6
commit
cae8ed0b7a
|
|
@ -1 +1,95 @@
|
|||
敬请期待
|
||||
# Lab 5：Python开源软件包安装/管理/打包/上载（10分）
|
||||
|
||||
**截止日期：2022.11.23 11:59am**
|
||||
|
||||
## 实践目的
|
||||
|
||||
* 以Python为例，了解对软件项目进行依赖管理、打包、和发布的基本流程
|
||||
|
||||
## 初始文件
|
||||
|
||||
请基于你的Lab 4，继续完成本次Lab
|
||||
|
||||
## 实践流程
|
||||
|
||||
1. 在`pyproject.toml`中修改`tool.poetry.name`为`pygraph-{姓名拼音}`（例如，`pygraph-hehao`），这将是上传到TestPyPI的包名，不能与已有包冲突。
|
||||
|
||||
2. 在`pyproject.toml`中配置需要打包的文件为`pygraph.py`，这需要用到[tool.poetry.packages](https://python-poetry.org/docs/pyproject/#packages)选项。
|
||||
|
||||
3. 修改后，使用`poetry update`更新项目配置。
|
||||
|
||||
4. 使用Poetry打包`pygraph-xxxx`：
|
||||
|
||||
```shell script
|
||||
poetry build
|
||||
```
|
||||
|
||||
上述命令会在`dist/`文件夹中生成wheel文件和源代码tar包，这些是在PyPI上发布所必须的文件。
|
||||
|
||||
5. 在[TestPyPI](https://test.pypi.org/)注册一个账号，请注意不要在[PyPI](https://pypi.org)上直接注册。
|
||||
|
||||
> [TestPyPI](https://test.pypi.org)是与PyPI分离的Python包发布平台，主要用于学习和测试，不影响真正的Python生态。
|
||||
|
||||
6. 在`pyproject.toml`中添加[Twine](https://twine.readthedocs.io/en/stable/)作为开发依赖，并使用`poetry install`安装Twine。
|
||||
|
||||
> [Python官方文档](https://packaging.python.org/en/latest/key_projects/#twine): Twine is the primary tool developers use to upload packages to the Python Package Index or other Python package indexes. It is a command-line program that passes program files and metadata to a web API. Developers use it because it’s the official PyPI upload tool, it’s fast and secure, it’s maintained, and it reliably works.
|
||||
|
||||
7. 使用Twine在TestPyPI上手动发布`pygraph-xxxx`：
|
||||
|
||||
```shell script
|
||||
twine upload --repository testpypi dist/*
|
||||
```
|
||||
|
||||
此时就可以在TestPyPI上查看你的软件包了（例如[pygraph-hehao](https://test.pypi.org/project/pygraph-hehao/0.1.0/)）。
|
||||
|
||||
可以尝试退出poetry shell，在一个新的Python环境中运行类似如下命令以安装你的软件包：
|
||||
|
||||
```shell script
|
||||
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ pygraph-hehao
|
||||
```
|
||||
|
||||
这里`--extra-index-url`是为了确保pygraph可以安装从PyPI上来的间接依赖。
|
||||
|
||||
然后，在Python解释器中可以尝试导入pygraph包，类似如下：
|
||||
|
||||
```
|
||||
PS D:\GitHub\OSSDevelopment> pip install --index-url https://test.pypi.org/simple/ -extra-index-url https://pypi.org/simple/ pygraph-hehao
|
||||
Looking in indexes: https://test.pypi.org/simple/, https://pypi.org/simple/
|
||||
Collecting pygraph-hehao
|
||||
Downloading https://test-files.pythonhosted.org/packages/f5/98/4ee92fd154f44ec9c3093b82240a21689893c3227a0965b4784c701f6214/pygraph_hehao-0.1.0-py3-none-any.whl (1.7 kB)
|
||||
Installing collected packages: pygraph-hehao
|
||||
Successfully installed pygraph-hehao-0.1.0
|
||||
PS D:\GitHub\OSSDevelopment> python
|
||||
Python 3.9.13 (tags/v3.9.13:6de2ca5, May 17 2022, 16:36:42) [MSC v.1929 64 bit (AMD64)] on win32
|
||||
Type "help", "copyright", "credits" or "license" for more information.
|
||||
>>> import pygraph
|
||||
>>> g = pygraph.Graph([(1,2),(3,4)])
|
||||
>>> g
|
||||
Graph({1: {2}, 2: {1}, 3: {4}, 4: {3}})
|
||||
```
|
||||
|
||||
但是，像这样在本地手动发布Python包对于团队协作开发的开源项目而言，不是最佳实践。比较好的做法是在GitHub上配置CD流水线，在master分支上达成特定条件（例如使用tag标记的版本）时，自动发布到PyPI。接下来的操作将会达成这一点。
|
||||
|
||||
8. 借助[networkx](https://networkx.org/documentation/stable/index.html)（可以使用[`poetry add`](https://python-poetry.org/docs/cli/#add)命令添加新依赖），为pygraph实现计算最短路径的功能，并添加测试样例确保功能正确。在开发完成后，将`pyproject.toml`中的版本号修改为`0.2.0`。
|
||||
|
||||
> 也许这里封装networkx显得很蠢，不过在实际编程中，由于图数据结构无处不在（常常蕴含在其他复杂结构化数据里），经常会有将当前的数据转换格式并应用已有图算法的情况。
|
||||
|
||||
9. 你的GitHub仓库内[配置PyPI账户名和密码为Secret](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)。
|
||||
|
||||
10. 添加一个新的GitHub Action流水线，使得若你的仓库[在GitHub上创建了一个新release](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#release)，流水线将会构建、测试、打包pygraph并发布到TestPyPI。
|
||||
|
||||
11. 将所有更改完成后，push到GitHub，在GitHub上创建一个新的Release，检查自动发布是否生效。
|
||||
|
||||
> 如果配置错误，可修改后重新发布release，测试流水线是否有效
|
||||
|
||||
12. 可以尝试仿照步骤7，在TestPyPI安装你的包并调用代码，测试发布是否有效。
|
||||
|
||||
## 评分标准
|
||||
|
||||
- （3分）TestPyPI上有通过步骤1-7发布的Python包。
|
||||
- （3分）pygraoh实现了计算最短路径的功能并包含可通过的测试样例。
|
||||
- （4分）配置了能够自动发布Python包的GitHub Action流水线。
|
||||
|
||||
## 提交方式
|
||||
|
||||
Lab 5无需特意提交任何内容，助教会在DDL后检查[OSS-Dev-Course-PKU](https://github.com/OSS-Dev-Course-PKU)中检查相应仓库，以及所对应的TestPyPI包，做出最终评分。
|
||||
10
Syllabus.md
10
Syllabus.md
|
|
@ -94,7 +94,7 @@ See the Mulan PSL v2 for more details.
|
|||
|
||||
> **Lab 4：CI/CD流水线搭建（10分）**
|
||||
>
|
||||
> 了解三种CI流程管理工具Travis CI、GitHub Actions、Gitee Go, 知道如何使用这些工具编写简单的CI流水线，并且在实践项目上完成符合要求的成功构建
|
||||
> 了解CI/CD流程管理工具GitHub Action，知道如何编写简单的CI/CD流水线，并且在实践项目上完成符合要求的成功构建
|
||||
>
|
||||
> Lab 4详细要求参见[WriteUp](Assignments/Lab4.md)，**截止日期：2022.11.02 11:59am**
|
||||
>
|
||||
|
|
@ -109,10 +109,10 @@ See the Mulan PSL v2 for more details.
|
|||
|
||||
> **Lab 5：Python开源软件包安装/管理/打包/上载（10分）**
|
||||
>
|
||||
> - 使用pip进行python包的管理；
|
||||
> - 使用poetry进行python包的管理；
|
||||
> - 配置自己的python包，包括配置setup.py、setup.cfg和pyproject.toml；
|
||||
> - 熟悉Python包生态系统平台PyPI，并且通过setuptools、wheel和build三种方式将自己的python包发布到testpypi平台上（注意，不是pypi平台。Testpypi https://test.pypi.org 是与PyPI分离的python包发布平台，使练习时发布的python包不会影响到真正的生态）
|
||||
> - 使用Poetry进行Python包的安装、管理与打包；
|
||||
> - 利用依赖对Python包实现新功能；
|
||||
> - 将自己的Python包手动发布到TestPyPI；
|
||||
> - 配置自动化的CI/CD流水线实现从GitHub直接发布Python包到TestPyPI（注意，不是PyPI平台。[TestPyPI](https://test.pypi.org)是与PyPI分离的Python包发布平台，使练习时发布的Python包不会影响到真正的生态）
|
||||
>
|
||||
> Lab 5详细要求参见[WriteUp](Assignments/Lab5.md)，**截止日期：2022.11.23 11:59am**
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue