pyscaffoldext-django 0.2

快速入门

此扩展可以直接通过pip安装

pip install pyscaffoldext-django

或者，如果您更喜欢pipx

pipx install pyscaffold  # if you haven't installed pyscaffold yet
pipx inject pyscaffold pyscaffoldext-django

请注意，安装完成后，使用 putup -h 将显示一个新选项 --django。使用此选项来指示您正在尝试创建 django 应用。例如

putup --django myapp

请参阅 django-admin 文档以获取更多详细信息。

替代方案

在 PyScaffold 中使用 Django 扩展大致相当于首先使用 django-admin 创建一个应用，然后将它转换为 PyScaffold。以下手动程序可以用作替代 pyscaffoldext-django

django-admin startproject myapp
mkdir myapp/src
mv myapp/myapp myapp/src
mv myapp/manage.py myapp/src/myapp/__main__.py

# edit the location of the database in myapp/src/myapp/setttings.py
# to point to one directory up, similar to:
#
#   PROJECT_DIR = os.path.dirname(BASE_DIR)
#   DATABASES = {'default': { ..., 'NAME': os.path.join(PROJECT_DIR, 'db.sqlite3')}}

putup myapp --force

我们将 manage.py 文件移动/重命名为 myapp/src/myapp/__main__.py。这使得在作为包安装（而不是 python manage.py）时，可以使用 python -m myapp 来管理应用程序。所有参数保持不变。请参阅下一节以获取更多信息。

使用 python -m 运行脚本需要您的包已安装（简单的 pip install -e . 就足够了），但我们还生成了一个指向 __main__.py 的简单占位符 manage.py 文件，它无需显式安装即可工作。

对于复杂的使用案例，可能更好的选择是手动进行转换。如果您在用 --django 运行 PyScaffold 时遇到问题，请尝试执行此程序。

可分发 Django 包

Django 是用于创建 Web 应用的框架，PyScaffold 是一个帮助构建可重用、可分发包的工具——这通常对应于库或命令行工具。

虽然这两个定义并不相互排斥，但使用 PyScaffold 创建一个服务于 Django 应用的包有些棘手。第一个原因是应用程序通常需要具体的依赖关系（固定的版本号），而库则更加宽松，倾向于使用抽象依赖关系（版本号的范围）。您可以在 PyScaffold 的文档 中阅读关于这两种方法之间差异的所有内容，但主要观点是：在创建 Web 应用的包时，您有两个选择

使用具体依赖关系：:

固定依赖关系的确切版本号以避免错误（在我的机器上它工作），但向用户说明该包应安装在 专用 的 虚拟环境 中，以避免依赖关系冲突；或者

使用抽象依赖关系：:

偏好宽松的依赖关系范围（例如，依赖于使用 semver 的稳定 API 的依赖项），但广泛测试您的模块针对不同安装版本，以确保一切正常（tox 和 nox 是很好的工具）。

第二个原因是 Django 期望您的应用程序用户能够控制源代码的位置，而这与 pip 安装在文件系统深处的位置（例如 /home/username/my-venvs/web-app/lib/python3.6/site-packages/my-web-app）并不相容……

例如，在启动 Django 应用程序服务器之前，您应该运行迁移来在数据库中准备接收数据的正确结构。这通常通过在目录根目录中运行 python manage.py migrate 来实现，然而，如果某人正在使用 pip 安装您的应用程序，这个人如何知道在哪里找到 manage.py 文件呢？

为了解决这个问题，pyscaffoldext-django 将 manage.py 重命名为 __main__.py 并将其移动到您的Web应用程序包内部。由于它成为您包的一部分，脚本将可以通过 python -m YOUR_PACKAGE_NAME <commands> 在系统中的任何地方访问，因此使用pip安装它的人无需知道其位置。

相同行为的另一个例子是Django创建的默认SQLite数据库。如果您将未使用PyScaffold创建的Django应用程序转换为包，然后安装并运行迁移，Django将在您的磁盘的任意位置生成一个SQLite文件。PyScaffold无法自动为您解决这个问题。相反，您可以采取以下几种方法：

1. (不推荐) 将您的SQLite数据库放在包内部，并以 package data 的形式分发，通过 importlib.resources 访问它。请注意，资源应该是不可变的，不应写入磁盘。

2. 允许安装您包的人通过环境变量指定不同的配置。根据 Mozilla的教程，库 dj-database-url 很适合此目的。

3. 将您的SQLite数据库放在 用户主目录中的某个位置。

为了实用主义，PyScaffold将重新配置 settings.py，在开发环境中将数据库放在项目根目录中，但您负责在进入生产环境时更改此设置。

最后，重要的是要注意，虽然创建独立的顶级文件夹来存放独立的应用程序在Django社区中很流行，但这与Python包的概念或多或少是不兼容的……PyPI中的一个条目应在您的机器上安装单个包。理想情况下，如果您使用 多个应用程序，您应该为每个应用程序部署不同的包，并将它们声明为主项目的依赖项。或者您也可以在主项目包（由PyScaffold/django-admin startproject生成的）内部部署新的应用程序。因此，当使用 python manage.py startapp 时需要谨慎（您应该提供可选的 directory 参数，使其位于主包内部，或者完全跳过它）。一个使用嵌套应用程序的示例是

putup --django website
cd website
# … do some coding
mkdir src/website/subapp
python manage.py startapp subapp src/website/subapp
# OR python -m website startapp subapp src/website/subapp
#    if you have the package installed in the dev environment
# … then you can add "website.subapp" to INSTALLED_APPS in src/website/settings.py
# … remeber to use relative imports or the full package name "website.subapp" when needed

技巧

1. 查看 Django的指南，但请记住，PyScaffold已经为您做了大部分工作（无需从头编写包装配置），并且我们使用的是 基于src的布局

2. 不要假设包将安装到的文件系统。

3. 如果您确实需要将内容写入磁盘，可以遵循 XDG标准 并写入 $XDG_DATA_HOME（包 appdirs 可能会很有帮助）。

4. 通过环境变量接受配置，并在提供不正确时抛出有意义的错误。即使您更喜欢从文件中读取配置，也可以让安装您包的人指定该文件的存储位置作为环境变量。

5. 使用环境变量作为标志/开关来启用/禁用功能或选择替代实现。

6. 务必小心，不要在源代码库中存储机密信息和保密信息。

7. 在一般情况下，务必小心处理机密信息和保密信息。如果确实需要存储，请使用已知的加密技术，并在操作系统中对文件/文件夹权限进行调整（例如，使用命令 chmod og-rwx，这是一个好帮手，您也可以考虑使用 400 权限）。指导安装您的软件包的人员创建一个独立的系统账户来以有限权限运行您的网络应用程序也是一个好主意。

8. 提供详细的文档，说明用户应该如何安装和运行您的应用程序（例如，虚拟环境安装说明、ngnix/apache/systemd 配置示例等…）

修改和贡献

本项目使用 pre-commit，请在进行任何修改之前确保已安装。

pip install pre-commit
cd pyscaffoldext-django
pre-commit install

更新钩子到最新版本是个好主意。

pre-commit autoupdate

请查阅 PyScaffold 的贡献指南，

注意

本项目使用 PyScaffold 4.0a2 设置。有关 PyScaffold 的详细信息和使用信息，请参阅 https://pyscaffold.org/。