贡献¶

开发¶

如果你已经克隆了 sqlmodel 仓库并且想深入研究代码，这里有一些设置环境的指南。

虚拟环境¶

按照说明为 sqlmodel 的内部代码创建并激活虚拟环境。

使用 `pip` 安装依赖¶

激活环境后，安装所需的包

$ pip install -r requirements.txt

---> 100%

它将在你的本地环境中安装所有依赖项和你的本地 SQLModel。

使用你的本地 SQLModel¶

如果你创建一个导入并使用 SQLModel 的 Python 文件，并使用你本地环境中的 Python 运行它，它将使用你克隆的本地 SQLModel 源代码。

如果你更新了本地 SQLModel 源代码，当你再次运行该 Python 文件时，它将使用你刚刚编辑的最新版 SQLModel。

这样，你就不必“安装”你的本地版本就能测试每次更改。

"技术细节"

这只有当你使用这个包含的 requirements.txt 安装，而不是直接运行 pip install sqlmodel 时才会发生。

那是因为在 requirements.txt 文件中，本地版本的 SQLModel 被标记为以“可编辑”模式安装，带有 -e 选项。

格式化¶

你可以运行一个脚本，它将格式化并清理你的所有代码

$ bash scripts/format.sh

它还会自动排序你的所有导入。

测试¶

你可以本地运行一个脚本来测试所有代码并生成 HTML 格式的覆盖率报告

$ bash scripts/test.sh

此命令会生成一个目录 ./htmlcov/，如果你在浏览器中打开文件 ./htmlcov/index.html，你可以交互式地探索代码中被测试覆盖的区域，并注意是否有任何区域缺失。

文档¶

首先，请确保你按照上述说明设置了环境，这将安装所有依赖项。

文档实时预览¶

在本地开发期间，有一个脚本可以构建网站并检查任何更改，实现实时重新加载

$ python ./scripts/docs.py live

<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes

它将在 http://127.0.0.1:8008 上提供文档服务。

这样，你可以编辑文档/源文件并实时查看更改。

提示

或者，你可以手动执行脚本所做的相同步骤。

进入 docs/ 目录

$ cd docs/

然后在该目录中运行 mkdocs

$ mkdocs serve --dev-addr 8008

Typer CLI (可选)¶

这里的说明向你展示了如何直接使用 python 程序运行 ./scripts/docs.py 脚本。

但你也可以使用 Typer CLI，安装补全后，你将在终端中获得命令的自动补全。

如果你安装了 Typer CLI，你可以通过以下方式安装补全

$ typer --install-completion

zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.

文档结构¶

文档使用 MkDocs。

在 ./scripts/docs.py 中还有额外的工具/脚本。

提示

你不需要查看 ./scripts/docs.py 中的代码，你只需在命令行中使用它。

所有文档都以 Markdown 格式存储在 ./docs 目录中。

许多教程都有代码块。

在大多数情况下，这些代码块都是可以原样运行的完整应用程序。

事实上，这些代码块不是写在 Markdown 内部的，它们是 ./docs_src/ 目录中的 Python 文件。

在生成网站时，这些 Python 文件会被包含/注入到文档中。

文档测试¶

大多数测试实际上都是针对文档中的示例源文件运行的。

这有助于确保

文档是最新的。
文档示例可以原样运行。
大多数功能都包含在文档中，并通过测试覆盖率确保。

贡献¶

开发¶