13. 附录
13.1. 安装 Python
示例和案例研究需要 [Python] 3.12 或更高版本([Django] 6.1 要求如此)。它们已在 3.13 版本上测试过。
在 [Windows] 下,从 python.org/downloads 页面下载安装程序(“Download Python 3.13.x”按钮,或更新的版本)。在安装程序的第一个界面中,勾选“Add python.exe to PATH”复选框,这样就可以在任何控制台中输入 [python] ,然后点击“Install Now”。安装程序还会安装 [pip]、[venv] 模块以及 [py] 启动器(安装了多个版本时,[py -3.13] 可启动指定版本)。在 [Windows] 10 和 11 中,如果尚未安装就输入 [python] ,会打开 Microsoft Store:这是一个可以禁用的系统快捷方式(设置 / 应用 / 高级应用设置 / 应用执行别名)。
在 [macOS] 上,使用 python.org 的安装程序或 [Homebrew] 包管理器:[brew install python@3.13]。在 [Linux] 下,[Python] 通常已经存在,但模块 [venv] 和 [pip] 往往是单独的软件包。在 [Ubuntu] 24.04 下(其 [Python] 版本为 3.12):
在 [macOS] 和 [Linux] 下,命令名为 [python3] 和 [pip3];在已激活的虚拟环境中,直接用 [python] 和 [pip] 即可。在新的控制台中验证安装:
第一条命令应显示大于或等于 3.12 的版本号(例如 [Python 3.13.7])。
13.2. pip 与虚拟环境
[pip] 是 [Python] 的库管理器。它从 [PyPI] (pypi.org)仓库下载库:安装期间需要连接互联网。如果你处于公司代理之后,请通过环境变量 [HTTP_PROXY] 和 [HTTPS_PROXY],或使用 [--proxy] 选项来指定代理,该选项属于 [pip]。
虚拟环境是一个文件夹,其中包含 [Python] 解释器的轻量级副本及其自己的库:每个项目都有自己的虚拟环境,使用它所需的版本,而不会影响 [Python] 的安装或其他项目。在项目文件夹(包含 [requirements.txt] 的文件夹)中的常用命令:
在 [Windows] 下,[PowerShell] 有时会拒绝运行激活脚本(“script execution is disabled on this system”):命令 [Set-ExecutionPolicy -Scope CurrentUser RemoteSigned] 可为当前用户启用它。你也可以绕过激活,直接调用该环境的解释器:[.venv\Scripts\python manage.py runserver]。
名为 [.venv] 的文件夹不能从一台机器复制到另一台机器(它包含绝对路径和特定于系统的程序):必须使用上述命令重新创建。这就是它不包含在课程材料中的原因。[examples] 文件夹有自己的环境,由全部 28 个示例共享;案例研究有它自己的环境。
[mysqlclient] 库和 [MySQL] 驱动(示例 28 和案例研究)是用 C 编写的。在 [Windows] 下,[pip] 会下载预编译版本:无需任何操作。在 [Linux] 和 [macOS] 下,[pip] 会对其进行编译,为此需要 [MySQL] 的开发文件和一个编译器:
如果没有它们,[pip install -r requirements.txt] 会在 [mysqlclient] 上失败,错误消息中会提到 [pkg-config] 或 [mysql_config]。
13.3. 安装 Visual Studio Code
[Visual Studio Code] 可从 code.visualstudio.com 下载。添加三个扩展(“查看”菜单 / 扩展):
- Python(由 Microsoft 提供):用于运行和调试 [Python] 代码以及管理虚拟环境。它会同时安装 Python Debugger 扩展;
- Pylance(由 Microsoft 提供,也随 Python 扩展一并安装):代码补全、代码导航(包括 [Django] 的代码,位于 [.venv] 文件夹中)、错误报告和类型注解检查;
- Django(作者 Baptiste Darthenay):为 [Django] 模板([.html] 文件,位于 [templates] 文件夹中)提供语法高亮和快捷方式。
打开 [examples] 文件夹或案例研究文件夹(“文件”菜单 / 打开文件夹),然后选择该文件夹虚拟环境的解释器(命令面板,Ctrl+Shift+P,Python: Select Interpreter,然后选择 [.venv] 中的那个)。内置终端(“终端”菜单 / 新建终端)随后会自动激活该环境,使你无需离开编辑器即可运行应用程序和 [python manage.py ...] 命令。
要分步运行应用程序,请创建一个调试配置(“运行”菜单 / 添加配置,然后选择 Python Debugger 和 Django):编辑器会在调试器的控制下启动 [manage.py runserver] ,并在视图中设置的断点处暂停。
13.4. 使用 Laragon 安装 MySQL
[Laragon] 可安装即用的 [MySQL] 服务器,适用于 [Windows],并附带 [HeidiSQL] 管理工具(参见引言中的“安装 Laragon”)。安装之后:
- “Start All”按钮会在 3306 端口上启动 [MySQL] 服务器;
- 用户 [root] 没有密码:这些就是示例 28 中 [DATABASES] 设置([config/settings.py])的值,以及案例研究中 [DB_USER] 和 [DB_PASSWORD] 变量(来自 [.env] 文件)的值;
- “Database”按钮会打开 [HeidiSQL],其中的“文件 / 运行文件 (SQL)”菜单项用于运行脚本 [dbpersons.sql] (示例 28)和 [dbrdvmedecins2.sql] (案例研究)。
在 [Linux] 或 [macOS] 上,使用系统的包管理器安装 [MySQL] 或 [MariaDB] ,并使用命令行客户端 [mysql] ([mysql -u root < database/dbrdvmedecins2.sql])运行脚本。[mysqlclient] 驱动和 [MySQL] 引擎(来自 [Django] )与两者都能配合,无需任何配置。在 [Linux] 下,[MariaDB] 的 [root] 账户常被配置为只能通过系统账户 [root] 登录([sudo mysql]):此时需要为应用程序创建一个用户:
然后将其告知应用程序:示例 28 对应 [DATABASES] 设置中的键 [USER] 和 [PASSWORD];案例研究对应文件 [.env] 中的行 [DB_USER=course] 和 [DB_PASSWORD=course]。
13.5. Installing curl
[curl] 已包含在 [Windows] 10 和 11、[macOS]、以及大多数 [Linux] 发行版中。在 [PowerShell] 中,必须输入 [curl.exe],而不是 [curl]:在旧版本的 [PowerShell] 中,[curl] 是另一个命令([Invoke-WebRequest])的别名,其选项不同。在 [Windows] 的命令提示符([cmd])中,JSON 字符串的引号要写成 [\"] (示例 11),而包含 [&] 的 URL 字符串必须用双引号括起来。
13.6. django-admin 工具
[Django] 会安装一个命令 [django-admin],学习本文档并不需要它(示例已提供,开箱即用),但它用于启动新项目。每个项目的 [manage.py] 文件是一个 [django-admin] 文件,同时它还了解该项目的设置:在项目内部,你输入 [python manage.py] 而不是 [django-admin]。最有用的命令:
命令 [startproject] 末尾的句点会在当前文件夹中创建项目(没有它,项目会创建在名为 [config] 的新文件夹中)。由 [startapp] 创建的应用必须添加到 [INSTALLED_APPS] 设置列表中。[inspectdb] 命令对于现有数据库(例如案例研究中的数据库)是一个宝贵的工具:它读取各个表,并使用 [managed = False] 生成模型的初稿;剩下的工作就是为关系命名、选择类型并添加方法。命令 [makemigrations] 和 [migrate] 根据模型创建和更新表,本文档中没有使用它们:其数据库由 SQL 脚本创建,这些脚本与应用程序的其他版本共享。