diff --git a/docs/guidelines/advanced/configuration.md b/docs/guidelines/advanced/configuration.md index d6cfc67..ee156e5 100644 --- a/docs/guidelines/advanced/configuration.md +++ b/docs/guidelines/advanced/configuration.md @@ -221,7 +221,7 @@ Dynaconf 支持加载环境变量,也可以使用 .env 文件。 在使用环境变量时,同样和配置文件一样,支持完全覆盖,和自动合并。 -需要额外强调一点的是, Dynaconf 初始化的时,使用了 `envvar_prefix=BLOG` 。 Dynaconf 会自动加载以 `BLOG_` 开头的 +需要额外强调一点的是, Dynaconf 初始化的时候,使用了 `envvar_prefix=BLOG` 。 Dynaconf 会自动加载以 `BLOG_` 开头的 环境变量。包括 `ENVVAR_FOR_DYNACONF='BLOG_SETTINGS'` 配置的 Dynaconf 加载配置文件的环境变量 `BLOG_SETTINGS` 。 所以在使用环境变量的时候,不要错误的将 `BLOG_SETTINGS` 环境变量指定其他内容,而造成不必要的错误。 diff --git a/docs/guidelines/advanced/exception.md b/docs/guidelines/advanced/exception.md index 6a981c9..0a50e91 100644 --- a/docs/guidelines/advanced/exception.md +++ b/docs/guidelines/advanced/exception.md @@ -5,11 +5,11 @@ ## 介绍 -Python 中的异常分为两类,一是句法错误,一类是异常。 +Python 中的异常分为两类,一是语法错误,一类是异常。 ### 句法错误 -句法错误是用来指示 Python 编码不符合句法规范的: +语法错误是用来指示 Python 编码不符合语法规范的: ```python >>> while True print('Hello world') @@ -266,7 +266,7 @@ def divide(x, y): 开发实践中,异常信息对诊断程序非常重要。所以在使用和处理异常时,请遵循如下几点: - 需要处理异常时使用 `try...except...finally` 捕获 -- 处理异常时,如果没有继续抛出异常,需要输入日志信息。除非你知道不输出任何信息不会造成拍错困难。 +- 处理异常时,如果没有继续抛出异常,需要输入日志信息。除非你知道不输出任何信息不会造成排错困难。 - 项目级别,一定要定义一个项目的基类异常。项目中其他自定义异常必须继承该基类异常。这么做的目的是可以在外层逻辑通过捕获基类 异常来只捕获抛出的自定义异常。 - 项目异常要以 `ERROR` 结尾。和标准异常命名类似。 diff --git a/docs/guidelines/advanced/logging.md b/docs/guidelines/advanced/logging.md index d7516aa..399e157 100644 --- a/docs/guidelines/advanced/logging.md +++ b/docs/guidelines/advanced/logging.md @@ -7,18 +7,18 @@ 一个事件通过一些包含变量数据的描述信息来描述(比如:每个事件发生时的数据都是不同的)。开发者还会区分事件的重要性, 重要性也被称为 **等级** 或 **严重性**。有一个好的日志实践,能让开发调试流程更顺畅,出现问题能更快速精准定位。 -本文不会以最基础的方式讲述 Python logging 的使用,而是以当前总结的实践方式结合实际操作案例展示 Logging 的使用,所以在阅读文章钱, +本文不会以最基础的方式讲述 Python logging 的使用,而是以当前总结的实践方式结合实际操作案例展示 Logging 的使用,所以在阅读文章前, 你应该提前了解 [日志 HOWTO](https://docs.python.org/zh-cn/3/howto/logging.html) 和 [Python 的日志记录工具](https://docs.python.org/zh-cn/3/library/logging.html) 两篇文档。 ## 1. 简单使用 在一般开发中,对于临时开发的项目,可能为了快速完成任务,项目中大量使用了 `print` 将调试信息输出到控制台。 -项目后期就会出现调试困难等问题。本节会提供在简单环境下快速使用日志方式。 +项目后期就会出现调试困难等问题。本节会提供在简单环境下快速使用日志的方式。 ### 1.1 单文件使用 -对于单文件的使用,直接使用根日志对象即可。由于默认的日志级别为 `WARNING` ,所以需要使用更低级别的日志是无法显示的。 +对于单文件的使用,直接使用根日志对象即可。由于默认的日志级别为 `WARNING` ,所以使用更低级别的日志是无法显示的。 ```python """Simple logging""" @@ -27,7 +27,7 @@ import logging logging.warning('I love you ~') ``` -如果后续开发有要控制日志级别的需求,直接在开始初始化日志配置就可以了; +如果后续开发有要控制日志级别的需求,直接在开始的时候初始化日志配置就可以了。 ```python """Simple logging""" @@ -40,7 +40,7 @@ logging.warning('I love you ~') logging.debug('I love you too ~') ``` -当需要输出更详细的日志信息,如执行时间 、 日志级别 、 线程或进程信息,都可以很方便的控制。 +当需要输出更详细的日志信息,如执行时间、日志级别、线程或进程信息等,都可以很方便的控制。 ```python """Simple logging""" @@ -59,7 +59,7 @@ logging.debug('I love you too ~') ``` -虽然使用 `print` 能更快速的在控制太输出想要看到的内容,但从上面的示例来看,直接使用默认的日志输出也是很方便的,唯一的区别可能 +虽然使用 `print` 能更快速的在控制台输出想要看到的内容,但从上面的示例来看,直接使用默认的日志输出也是很方便的,唯一的区别可能 就是需要导入了。而使用日志的话,想要在后续增加输出更精确的信息就显得比较灵活。 日志格式所支持的字段请参考 [LogRecord 属性](https://docs.python.org/zh-cn/3/library/logging.html#logrecord-attributes) 。 diff --git a/docs/guidelines/project_management/distribution.md b/docs/guidelines/project_management/distribution.md index fff8409..f9d5f14 100644 --- a/docs/guidelines/project_management/distribution.md +++ b/docs/guidelines/project_management/distribution.md @@ -17,9 +17,9 @@ ### 2.1 打包工具 -由于历史原因, Python 的打包走了很长一段路了,但和其他语言的打包工具相比,为了还是有很长一段路要走。 +由于历史原因, Python 的打包走了很长一段路了,但和其他语言的打包工具相比,未来还是有很长一段路要走。 -在 [PEP-517](https://www.python.org/dev/peps/pep-0517/) 中,提到了当前 Python 构建系统的不足和响应的解决方案。 +在 [PEP-517](https://www.python.org/dev/peps/pep-0517/) 中,提到了当前 Python 构建系统的不足和相应的解决方案。 其主要就是解决让 Python 支持更加灵活的构建系统。 [PEP-518](https://www.python.org/dev/peps/pep-0518/) 则提出为项目指定一个最小的构建系统。 @@ -313,7 +313,7 @@ build-backend = "poetry.core.masonry.api" - `tool.poetry.scripts` : 安装包时将安装的脚本或可执行文件 - `tool.poetry.extras` :可选依赖项,增强包,但不是必需的,可选依赖项的集群。 - `tool.poetry.plugins` : 插件,可通过 `importlib.metadata`导入 -- `tool.poetry.urls` : 自定义 url,发布pypi后展示 +- `tool.poetry.urls` : 自定义 url,发布 pypi 后展示 - `build-system` : 构建系统引用部分 ##### 2.2.2.1 入口点 EntryPoints diff --git a/docs/guidelines/project_management/project_structure.md b/docs/guidelines/project_management/project_structure.md index 92cf2db..9c7aaa6 100644 --- a/docs/guidelines/project_management/project_structure.md +++ b/docs/guidelines/project_management/project_structure.md @@ -66,7 +66,7 @@ sampleproject └── tests ``` -六年前的这篇文章 [Packaging a python library](https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure) 就详细阐述了使用 `src` 结构比简单结构的诸多有点。而现在也逐渐被社区作为一个标准遵循。虽然社区中有大量老的项目依然采用简单布局,但新项目推荐使用 `src` 结构。 +六年前的这篇文章 [Packaging a python library](https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure) 就详细阐述了使用 `src` 结构比简单结构的诸多优点。而现在也逐渐被社区作为一个标准遵循。虽然社区中有大量老的项目依然采用简单布局,但新项目推荐使用 `src` 结构。 如下面这个示例项目结构: diff --git a/docs/guidelines/tutorial/init_project.md b/docs/guidelines/tutorial/init_project.md index 30c299b..bd82b1f 100644 --- a/docs/guidelines/tutorial/init_project.md +++ b/docs/guidelines/tutorial/init_project.md @@ -45,7 +45,6 @@ init_skeleton [n]: y ``` - 然后使用 vscode 打开项目: ```bash @@ -279,7 +278,7 @@ def init_log() -> None: - `/etc/example_etl/settings.yml` :操作系统外部配置文件。默认这个配置文件和项目默认配置文件的内容一致。 - 使用 `EXAMPLE_ETL_=` 环境变量传递 -优先级从从上倒下依次增大,优先级高的会覆盖优先级低的配置。 +优先级从从上到下依次增大,优先级高的会覆盖优先级低的配置。 ```python """ diff --git a/docs/guidelines/tutorial/publish.md b/docs/guidelines/tutorial/publish.md index 195ab2d..587376f 100644 --- a/docs/guidelines/tutorial/publish.md +++ b/docs/guidelines/tutorial/publish.md @@ -43,7 +43,7 @@ poetry config repositories.testpypi https://test.pypi.org/legacy/ poetry publish --repository=testpypi --username=USERNAME --password=PASSWORD ``` -> 注意:不建议将测试项目发布都 [https://pypi.org/](https://pypi.org/) 上。在 [https://pypi.org/](https://pypi.org/) 上的项目名称是全局唯一的, +> 注意:不建议将测试项目发布到 [https://pypi.org/](https://pypi.org/) 上。在 [https://pypi.org/](https://pypi.org/) 上的项目名称是全局唯一的, > 所以如果你考虑到将项目发布到 [https://pypi.org/](https://pypi.org/) 上前,应定一个不存在名称。 ## 安装测试 diff --git a/docs/guidelines/tutorial/test.md b/docs/guidelines/tutorial/test.md index e67bd97..d3bf524 100644 --- a/docs/guidelines/tutorial/test.md +++ b/docs/guidelines/tutorial/test.md @@ -9,7 +9,7 @@ 测试是保障安全上线一个重要的步骤,编写良好的测试,可以在发布之前尽可能避免 BUG 出现。 在修改功能后,也可以通过回归测试,检查现有功能的稳定性。 -编写单元测试过程,和开发顺序一直,现测试三个模块,再测试 `manage` 模块,最后测试调用逻辑。 +编写单元测试过程,和开发顺序一样,先测试三个模块,再测试 `manage` 模块,最后测试调用逻辑。 测试时,使用的是 `pytest` 工具,而不是使用 `unittest` 。 diff --git a/docs/index.md b/docs/index.md index f6235e9..045961d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -50,7 +50,7 @@ - [ ] Scrapy - [ ] aiohttp - [ ] 数据库 - - [ ] SQLALchemy + - [ ] SQLAlchemy - [x] 数据开发实践 - [x] 初级教程 diff --git a/docs/introduction/install.md b/docs/introduction/install.md index 125821a..62a1244 100644 --- a/docs/introduction/install.md +++ b/docs/introduction/install.md @@ -45,7 +45,7 @@ ![windows-install-optional-features](../assets/images/install/windows-install-optional-features.png) -此时可以选择可选的特性,不过还不是你不知道它们是做什么的,或者不清楚你是否需要它们,那么保持默认即可。 +此时可以选择可选的特性,不过如果你不知道它们是做什么的,或者不清楚你是否需要它们,那么保持默认即可。 然后点击 `Next` : ![windows-install-advanced-options](../assets/images/install/windows-install-advanced-options.png)