feat: 同步项目模板示例，更新过时内容

docs/guidelines/tutorial/publish.md

@@ -1,47 +1,83 @@
 # 打包发布
 
+本章节，你可以学到：
+
+- 使用 poetry 构建项目
+- 使用 poetry 将项目发布到 pypi
+- 安装并使用你发布到 pypi 的项目
+
 项目开发测试完成后，可以将项目发布到 Pypi 仓库中，然后在其他地方通过 Pip 命令即可
 安装使用。对于一些工具包比较方便。
 
 ## 打包
 
 根据 PEP 517 规范，新的打包机制可通过 `poetry` 工具来操作。
 
-安装打包工具：
+执行构建命令：
 
 ```bash
-pip install poetry
+$ poetry build
+Building example_etl (0.1.0)
+ - Building sdist
+ - Built example_etl-0.1.0.tar.gz
+ - Building wheel
+ - Built example_etl-0.1.0-py3-none-any.whl
+
 ```
 
-然后运行打包命令：
+## 发布
+
+本项目为测试项目，以下操作可以将项目发布到 [https://test.pypi.org/](https://test.pypi.org/) 。
+
+首先在 [https://test.pypi.org/](https://test.pypi.org/) 注册账号。
+
+然后配置 poetry 发布的仓库：
 
 ```bash
-poetry build
+poetry config repositories.testpypi https://test.pypi.org/legacy/
 ```
 
-## 发布
+然后填写根据你的用户名密码修改如下命令后，将项目发布到 testpypi 上。
 
 ```bash
-poetry publish
+poetry publish --repository=testpypi --username=USERNAME --password=PASSWORD
 ```
 
-输入账号密码后，即可将项目发布到 Pypi
-
-> 注意：由于 Pypi 上的项目名称是唯一的， `example_etl` 名称已经被使用，所以你在测试时，需要使用其他项目名称。
+> 注意：不建议将测试项目发布都 [https://pypi.org/](https://pypi.org/) 上。在 [https://pypi.org/](https://pypi.org/) 上的项目名称是全局唯一的，
+> 所以如果你考虑到将项目发布到 [https://pypi.org/](https://pypi.org/) 上前，应定一个不存在名称。
 
 ## 安装测试
 
 项目正常发布后，可以通过 pip 安装到本地使用：
 
 ```bash
-pip install example-etl
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple example-etl
 ```
 
+由于我们使用的是测试仓库，所以需要指定 `--index-url https://test.pypi.org/simple/` 参数，用来安装发布到 [https://test.pypi.org/](https://test.pypi.org/) 的包
+同时使用 `--extra-index-url https://pypi.org/simple` 参数，来安装 `example-etl` 依赖的包。
+
 输出结果如下：
 
 ```text
-❯ pip install example-etl
+❯ pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple example-etl
+Looking in indexes: https://test.pypi.org/simple/, https://pypi.org/simple
 Collecting example-etl
+ Downloading https://test-files.pythonhosted.org/packages/f3/51/8cea9e34ae2f0e48abb6a0aa58cdf29d4d2900bdd97e45b8d4ee24b357f0/example_etl-0.1.0-py3-none-any.whl (9.5 kB)
+Collecting stevedore<6.0.0,>=5.1.0
+ Downloading stevedore-5.1.0-py3-none-any.whl (49 kB)
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 49.6/49.6 kB 195.3 kB/s eta 0:00:00
+Collecting click<9.0.0,>=8.1.3
+ Downloading click-8.1.3-py3-none-any.whl (96 kB)
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 96.6/96.6 kB 389.6 kB/s eta 0:00:00
+Collecting dynaconf<4.0.0,>=3.1.12
+ Downloading dynaconf-3.1.12-py2.py3-none-any.whl (211 kB)
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 211.8/211.8 kB 878.8 kB/s eta 0:00:00
+Collecting pbr!=2.1.0,>=2.0.0
+ Downloading pbr-5.11.1-py2.py3-none-any.whl (112 kB)
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 112.7/112.7 kB 1.7 MB/s eta 0:00:00
+Installing collected packages: pbr, dynaconf, click, stevedore, example-etl
+Successfully installed click-8.1.3 dynaconf-3.1.12 example-etl-0.1.0 pbr-5.11.1 stevedore-5.1.0
  Downloading example_etl-0.0.1.dev0-py3-none-any.whl (14 kB)
 Collecting dynaconf==3.1.7
  Downloading dynaconf-3.1.7-py2.py3-none-any.whl (200 kB)

docs/guidelines/tutorial/test.md

@@ -1,12 +1,54 @@
 # 测试
 
+在本章节，你将学到如下内容：
+
+- 使用 pytest 编写单元测试
+- 使用 pytest-mock 模拟单元测试中的依赖逻辑
+- 使用 tox 自动化测试流程
+
 测试是保障安全上线一个重要的步骤，编写良好的测试，可以在发布之前尽可能避免 BUG 出现。
 在修改功能后，也可以通过回归测试，检查现有功能的稳定性。
 
 编写单元测试过程，和开发顺序一直，现测试三个模块，再测试 `manage` 模块，最后测试调用逻辑。
 
 测试时，使用的是 `pytest` 工具，而不是使用 `unittest` 。
 
+## 调整测试代码
+
+```py hl_lines="18" linenums="1"
+"""Test cmdline"""
+from __future__ import annotations # PEP 585
+
+import pytest
+from click.testing import CliRunner
+
+from example_etl import __version__
+from example_etl.cmdline import main
+
+
+@pytest.mark.parametrize(
+ ['invoke_args', 'exit_code', 'output_keyword'],
+ [
+ ([], 0, 'help'),
+ (['--help'], 0, 'help'),
+ (['--version'], 0, __version__),
+ (['-V'], 0, __version__),
+
+ ]
+)
+def test_main(
+ clicker: CliRunner,
+ invoke_args: list[str],
+ exit_code: int,
+ output_keyword: str,
+):
+ """Test main cmdline"""
+ result = clicker.invoke(main, invoke_args)
+ assert result.exit_code == exit_code
+ assert output_keyword in result.output
+
+```
+
 ## 测试 extractor
 
 在 `tests` 包中新建 `test_extractor.py` 内容如下：
@@ -45,7 +87,7 @@ def test_file_source(mocker, foo_file):
 安装 `pytest-mock` ：
 
 ```bash
-poetry add -D pytest-mock
+poetry add --group dev pytest-mock
 ```
 
 > 这里使用了 `poetry add -D` ，意思是将 `pytest-mock` 安装到开发环境依赖中。
@@ -79,24 +121,43 @@ def foo_file():
 
 然后在命令行中运行 `pytest` ，测试刚刚编写的测试代码。可以看到如下输出：
 
+<!-- markdownlint-disable MD013 MD033-->
+
 ```text
 ❯ pytest
-================================================================= test session starts =================================================================
-platform linux -- Python 3.10.0, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
-rootdir: /tmp/test/example_etl, configfile: setup.cfg, testpaths: tests
-plugins: cov-3.0.0, mock-3.6.1
-collected 12 items 
-
-tests/test_cmdline.py ..... [ 41%]
-tests/test_extcator.py .. [ 58%]
-tests/test_log.py .... [ 91%]
-tests/tests.py . [100%]
-
-================================================================= 12 passed in 0.18s ==================================================================
+================================================================================================================================= test session starts =================================================================================================================================
+platform darwin -- Python 3.10.11, pytest-7.3.1, pluggy-1.0.0
+rootdir: /private/tmp/example_etl
+configfile: pyproject.toml
+testpaths: tests
+plugins: pylint-0.19.0, mock-3.10.0
+collected 12 items 
+
+tests/test_cmdline.py ..... [ 35%]
+tests/test_exceptions.py . [ 42%]
+tests/test_extractor.py .. [ 57%]
+tests/test_log.py ..... [ 92%]
+tests/test_version.py . [100%]
+
+
+
+================================================================================================================================== warnings summary ===================================================================================================================================
+../../../Users/kevin/Library/Caches/pypoetry/virtualenvs/example-etl-B-7RVLBy-py3.10/lib/python3.10/site-packages/pkg_resources/__init__.py:121
+ /Users/kevin/Library/Caches/pypoetry/virtualenvs/example-etl-B-7RVLBy-py3.10/lib/python3.10/site-packages/pkg_resources/__init__.py:121: DeprecationWarning: pkg_resources is deprecated as an API
+ warnings.warn("pkg_resources is deprecated as an API", DeprecationWarning)
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+============================================================================================================================ 12 passed, 1 warning in 0.04s ============================================================================================================================
+
 ```
 
+<!-- markdownlint-restore -->
+
 测试成功。
 
+**说明：** 上面测试结果中有 `pkg_resources` 的警告，这是由于当前版本的 `dynaocnf` 中的一个逻辑在 python3.10 下被提示出 API 弃用的警告造成的。这个问题在 `dynaconf` 的下一个版本中已经修复了。当
+`dynaconf` 的下一个版本发布后，可以将 `dynaconf` 的版本升级到下一个版本，这个警告就会消失。当前 `dynaconf` 版本为 `3.1.12` 。
+
 ## 测试 transformer
 
 在 `tests` 包中创建 `test_transformer.py` 内容如下：
@@ -229,45 +290,52 @@ def test_manage_transform(mocker):
 
 在测试时，需要保证配置文件中存在之前在代码中使用的变量。
 
-在 `src/example_etl/config/settings.yml` 文件中加入如下内容：
-
-```yaml
-extractor_name: file
-transformer_name: strip
-loader_name: file
-```
-
-配置程序默认使用三个已经实现的逻辑。
-
 再次运行 `pytest` 检查测试结果。
 
 ## 检查测试覆盖率
 
 测试覆盖率指示编写的单元测试，覆盖了多少源代码。能够通过测试覆盖率查看还有哪些内容没有被测试到。
 
+增加 `pytest-cov` 依赖：
+
+```bash
+poetry add --group dev pytest-cov
+```
+
 运行 `pytest --cov` 查看测试覆盖率。
 
+<!-- markdownlint-disable MD013 MD033-->
+
 ```text
 ❯ pytest --cov
-================================================================= test session starts =================================================================
-platform linux -- Python 3.10.0, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
-rootdir: /tmp/test/example_etl, configfile: pyproject.toml, testpaths: tests
-plugins: cov-3.0.0, mock-3.6.1
-collected 24 items 
-
-tests/test_cmdline.py ..... [ 20%]
-tests/test_extcator.py .. [ 29%]
-tests/test_loader.py .. [ 37%]
-tests/test_log.py ...... [ 62%]
-tests/test_manage.py .... [ 79%]
-tests/test_transformer.py .... [ 95%]
-tests/tests.py . [100%]
-
----------- coverage: platform linux, python 3.10.0-final-0 -----------
+================================================================================================================================= test session starts =================================================================================================================================
+platform darwin -- Python 3.10.11, pytest-7.3.1, pluggy-1.0.0
+rootdir: /private/tmp/example_etl
+configfile: pyproject.toml
+testpaths: tests
+plugins: pylint-0.19.0, mock-3.10.0, cov-4.1.0
+collected 23 items 
+
+tests/test_cmdline.py ..... [ 21%]
+tests/test_extractor.py .. [ 30%]
+tests/test_loader.py .. [ 39%]
+tests/test_log.py ..... [ 60%]
+tests/test_manage.py .... [ 78%]
+tests/test_transformer.py .... [ 95%]
+tests/test_version.py . [100%]
+
+================================================================================================================================== warnings summary ===================================================================================================================================
+../../../Users/kevin/Library/Caches/pypoetry/virtualenvs/example-etl-B-7RVLBy-py3.10/lib/python3.10/site-packages/pkg_resources/__init__.py:121
+ /Users/kevin/Library/Caches/pypoetry/virtualenvs/example-etl-B-7RVLBy-py3.10/lib/python3.10/site-packages/pkg_resources/__init__.py:121: DeprecationWarning: pkg_resources is deprecated as an API
+ warnings.warn("pkg_resources is deprecated as an API", DeprecationWarning)
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+
+--------- coverage: platform darwin, python 3.10.11-final-0 ----------
 Name Stmts Miss Cover
 -------------------------------------------------------------
 src/example_etl/__init__.py 1 0 100%
-src/example_etl/cmdline.py 23 0 100%
+src/example_etl/cmdline.py 26 0 100%
 src/example_etl/config/__init__.py 8 0 100%
 src/example_etl/constants.py 1 0 100%
 src/example_etl/exceptions.py 10 2 80%
@@ -282,24 +350,24 @@ src/example_etl/manage.py 33 0 100%
 src/example_etl/transformer/__init__.py 0 0 100%
 src/example_etl/transformer/base.py 5 0 100%
 src/example_etl/transformer/strip.py 7 0 100%
-tests/__init__.py 0 0 100%
+tests/__init__.py 7 0 100%
 tests/conftest.py 12 0 100%
 tests/test_cmdline.py 10 0 100%
-tests/test_exceptions.py 0 0 100%
-tests/test_extcator.py 14 0 100%
+tests/test_extractor.py 14 0 100%
 tests/test_loader.py 20 0 100%
-tests/test_log.py 10 0 100%
+tests/test_log.py  9 0 100%
 tests/test_manage.py 25 0 100%
 tests/test_transformer.py 12 0 100%
-tests/tests.py  3 0 100%
+tests/test_version.py 3 0 100%
 -------------------------------------------------------------
-TOTAL 265 2 99%
+TOTAL 274 2 99%
 
-
-================================================================= 24 passed in 0.41s ==================================================================
+============================================================================================================================ 23 passed, 1 warning in 0.08s ============================================================================================================================
 
 ```
 
+<!-- markdownlint-restore -->
+
 通过覆盖率可以看到 `src/example_etl/exceptions.py` 的逻辑还有没测试的。
 
 ## 完善其他测试