Skip to content

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):

sudo apt install python3 python3-venv python3-pip

在 [macOS] 和 [Linux] 下,命令名为 [python3] 和 [pip3];在已激活的虚拟环境中,直接用 [python] 和 [pip] 即可。在新的控制台中验证安装:

python --version
python -m pip --version

第一条命令应显示大于或等于 3.12 的版本号(例如 [Python 3.13.7])。

13.2. pip 与虚拟环境

[pip] 是 [Python] 的库管理器。它从 [PyPI] (pypi.org)仓库下载库:安装期间需要连接互联网。如果你处于公司代理之后,请通过环境变量 [HTTP_PROXY] 和 [HTTPS_PROXY],或使用 [--proxy] 选项来指定代理,该选项属于 [pip]。

虚拟环境是一个文件夹,其中包含 [Python] 解释器的轻量级副本及其自己的库:每个项目都有自己的虚拟环境,使用它所需的版本,而不会影响 [Python] 的安装或其他项目。在项目文件夹(包含 [requirements.txt] 的文件夹)中的常用命令:

1
2
3
4
5
6
7
python -m venv .venv                 # 创建虚拟环境(.venv 文件夹)
.venv\Scripts\activate               # 激活它(Windows)
source .venv/bin/activate            # 激活它(Linux、macOS)
pip install -r requirements.txt      # 安装项目的库
pip list                             # 已安装的库
pip freeze                           # 同一份列表,采用 requirements.txt 格式
deactivate                           # 退出环境

在 [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] 的开发文件和一个编译器:

1
2
3
sudo apt install python3-dev default-libmysqlclient-dev build-essential pkg-config     # Ubuntu、Debian
brew install mysql-client pkg-config                                                    # macOS
export PKG_CONFIG_PATH="$(brew --prefix)/opt/mysql-client/lib/pkgconfig"                # macOS,在 pip install 之前

如果没有它们,[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]):此时需要为应用程序创建一个用户:

sudo mysql -e "CREATE USER 'course'@'localhost' IDENTIFIED BY 'course'; GRANT ALL ON dbpersons.* TO 'course'@'localhost'; GRANT ALL ON dbrdvmedecins2.* TO 'course'@'localhost';"

然后将其告知应用程序:示例 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]。最有用的命令:

django-admin startproject config .        # 新建项目,其配置为 config 包
python manage.py startapp pages           # 新建应用,pages 文件夹
python manage.py runserver 8000           # 开发服务器
python manage.py check                    # 检查项目(设置、路由、模型等)
python manage.py check --deploy           # 检查生产环境的安全设置
python manage.py shell                    # 加载了 Django 的 Python 控制台
python manage.py dbshell                  # 数据库客户端,使用项目的设置
python manage.py inspectdb                # 为现有数据库编写模型(需要审阅并修正)
python manage.py makemessages -l fr       # 收集需要翻译的文本(.po 文件)
python manage.py compilemessages          # 编译字典(.mo 文件)
python manage.py collectstatic            # 为生产环境收集静态文件
python manage.py diffsettings             # 与默认值不同的设置

命令 [startproject] 末尾的句点会在当前文件夹中创建项目(没有它,项目会创建在名为 [config] 的新文件夹中)。由 [startapp] 创建的应用必须添加到 [INSTALLED_APPS] 设置列表中。[inspectdb] 命令对于现有数据库(例如案例研究中的数据库)是一个宝贵的工具:它读取各个表,并使用 [managed = False] 生成模型的初稿;剩下的工作就是为关系命名、选择类型并添加方法。命令 [makemigrations] 和 [migrate] 根据模型创建和更新表,本文档中没有使用它们:其数据库由 SQL 脚本创建,这些脚本与应用程序的其他版本共享。