高级教程:如何编写可重用应用程序¶
本高级教程从教程 8结束的地方开始。我们将把我们的网络投票变成一个独立的 Python 包,你可以在新项目中重用它并与其他人共享。
如果你最近没有完成教程 1-7,我们建议你回顾一下这些教程,以便你的示例项目与下面描述的项目相匹配。
可重用性很重要¶
设计、构建、测试和维护 Web 应用程序需要大量工作。许多 Python 和 Django 项目都面临着共同的问题。如果我们可以节省一些重复的工作,那不是很好吗?
可重用性是 Python 的生活方式。Python 包索引 (PyPI) 提供了大量你可以在自己的 Python 程序中使用的包。查看Django 包,了解你可以合并到项目中的现有可重用应用程序。Django 本身也是一个普通的 Python 包。这意味着你可以使用现有的 Python 包或 Django 应用程序,并将它们组合到自己的 Web 项目中。你只需要编写使你的项目独一无二的部分。
假设你正在启动一个新项目,该项目需要一个类似于我们一直在使用的投票应用程序。如何使这个应用程序可重用?幸运的是,你已经走在了正确的道路上。在教程 1中,我们看到了如何使用include
将投票与项目级 URLconf 解耦。在本教程中,我们将采取进一步的措施,使应用程序易于在新项目中使用,并准备好发布,以便其他人可以安装和使用。
包?应用?
Python 包 提供了一种将相关 Python 代码分组以方便重用的方法。一个包包含一个或多个 Python 代码文件(也称为“模块”)。
可以使用 import foo.bar
或 from foo import bar
导入包。对于要形成包的目录(如 polls
),它必须包含一个特殊文件 __init__.py
,即使此文件为空。
Django 应用 是一个专门用于 Django 项目的 Python 包。应用可以使用常见的 Django 约定,例如具有 models
、tests
、urls
和 views
子模块。
稍后我们将使用术语打包来描述使 Python 包易于他人安装的过程。我们知道,这可能有点令人困惑。
您的项目和可重用应用¶
在之前的教程之后,我们的项目应该如下所示
mysite/
manage.py
mysite/
__init__.py
settings.py
urls.py
asgi.py
wsgi.py
polls/
__init__.py
admin.py
apps.py
migrations/
__init__.py
0001_initial.py
models.py
static/
polls/
images/
background.png
style.css
templates/
polls/
detail.html
index.html
results.html
tests.py
urls.py
views.py
templates/
admin/
base_site.html
您在 教程 7 中创建了 mysite/templates
,并在 教程 3 中创建了 polls/templates
。现在,也许更清楚为什么我们选择为项目和应用创建单独的模板目录:所有属于 polls 应用的部分都在 polls
中。这使得应用自包含,并且更容易放入新项目中。
现在可以将 polls
目录复制到新的 Django 项目中并立即重用。但它还没有准备好发布。为此,我们需要打包应用,以便其他人更容易安装。
安装一些先决条件¶
目前 Python 包的管理工具比较混乱。在本教程中,我们将使用 setuptools 来构建我们的包。它是推荐的打包工具(与 distribute
分支合并)。我们还将使用 pip 来安装和卸载它。您现在应该安装这两个包。如果您需要帮助,可以参考 如何使用 pip 安装 Django。您可以用相同的方式安装 setuptools
。
打包您的应用程序¶
Python 的打包是指将您的应用程序准备成一种特定的格式,以便于安装和使用。Django 本身也是以这种方式打包的。对于像 polls 这样的小型应用程序,这个过程并不难。
首先,在您的 Django 项目之外创建一个包的父目录。将此目录命名为
django-polls
。选择应用程序的名称
在选择包的名称时,请检查 PyPI 以避免与现有包发生命名冲突。我们建议使用
django-
前缀作为包名,以标识您的包是特定于 Django 的,并使用相应的django_
前缀作为模块名。例如,django-ratelimit
包包含django_ratelimit
模块。应用程序标签(即应用程序包的点分路径的最后一部分)必须在
INSTALLED_APPS
中是唯一的。避免使用与任何 Django contrib 包 相同的标签,例如auth
、admin
或messages
。将
polls
目录移动到django-polls
目录中,并将其重命名为django_polls
。编辑
django_polls/apps.py
,使name
指向新的模块名称,并添加label
为应用程序提供一个简短的名称。from django.apps import AppConfig class PollsConfig(AppConfig): default_auto_field = "django.db.models.BigAutoField" name = "django_polls" label = "polls"
创建一个名为
django-polls/README.rst
的文件,内容如下:============ django-polls ============ django-polls is a Django app to conduct web-based polls. For each question, visitors can choose between a fixed number of answers. Detailed documentation is in the "docs" directory. Quick start ----------- 1. Add "polls" to your INSTALLED_APPS setting like this:: INSTALLED_APPS = [ ..., "django_polls", ] 2. Include the polls URLconf in your project urls.py like this:: path("polls/", include("django_polls.urls")), 3. Run ``python manage.py migrate`` to create the models. 4. Start the development server and visit the admin to create a poll. 5. Visit the ``/polls/`` URL to participate in the poll.
创建一个名为
django-polls/LICENSE
的文件。选择许可证超出了本教程的范围,但可以肯定地说,公开发布的没有许可证的代码是无用的。Django 和许多与 Django 兼容的应用程序都在 BSD 许可证下发布;但是,您可以自由选择自己的许可证。请注意,您的许可证选择将影响谁能够使用您的代码。接下来,我们将创建
pyproject.toml
、setup.cfg
和setup.py
文件,这些文件详细说明了如何构建和安装应用程序。对这些文件的完整解释超出了本教程的范围,但 setuptools 文档 提供了很好的解释。创建django-polls/pyproject.toml
、django-polls/setup.cfg
和django-polls/setup.py
文件,内容如下:[build-system] requires = ['setuptools>=40.8.0'] build-backend = 'setuptools.build_meta'
[metadata] name = django-polls version = 0.1 description = A Django app to conduct web-based polls. long_description = file: README.rst url = https://www.example.com/ author = Your Name author_email = [email protected] license = BSD-3-Clause # Example license classifiers = Environment :: Web Environment Framework :: Django Framework :: Django :: X.Y # Replace "X.Y" as appropriate Intended Audience :: Developers License :: OSI Approved :: BSD License Operating System :: OS Independent Programming Language :: Python Programming Language :: Python :: 3 Programming Language :: Python :: 3 :: Only Programming Language :: Python :: 3.10 Programming Language :: Python :: 3.11 Programming Language :: Python :: 3.12 Topic :: Internet :: WWW/HTTP Topic :: Internet :: WWW/HTTP :: Dynamic Content [options] include_package_data = true packages = find: python_requires = >=3.10 install_requires = Django >= X.Y # Replace "X.Y" as appropriate
from setuptools import setup setup()
默认情况下,包中只包含 Python 模块和包。要包含其他文件,我们需要创建一个
MANIFEST.in
文件。上一步骤中提到的setuptools
文档对该文件进行了更详细的讨论。要包含模板、README.rst
和我们的LICENSE
文件,请创建一个名为django-polls/MANIFEST.in
的文件,内容如下:include LICENSE include README.rst recursive-include django_polls/static * recursive-include django_polls/templates *
包含详细的文档是可选的,但建议这样做。为将来的文档创建一个空目录
django-polls/docs
。在django-polls/MANIFEST.in
中添加一行:recursive-include docs *
请注意,除非您在该目录中添加一些文件,否则
docs
目录不会包含在您的包中。许多 Django 应用程序还通过 readthedocs.org 等网站在线提供文档。尝试通过在
django-polls
中运行python setup.py sdist
来构建您的包。这将创建一个名为dist
的目录,并构建您的新包django-polls-0.1.tar.gz
。
有关打包的更多信息,请参阅 Python 的 打包和分发项目的教程。
使用您自己的包¶
自从我们将 polls
目录移出项目后,它就不再起作用了。现在我们将通过安装新的 django-polls
包来解决这个问题。
作为用户库安装
以下步骤将 django-polls
安装为用户库。与系统范围安装相比,针对用户的安装有很多优点,例如,在您没有管理员权限的系统上可以使用,并且可以防止包影响系统服务和机器的其他用户。
请注意,针对用户的安装仍然会影响以该用户身份运行的系统工具的行为,因此使用虚拟环境是一个更强大的解决方案(见下文)。
要安装包,请使用 pip(您已经 安装了它,对吧?)。
python -m pip install --user django-polls/dist/django-polls-0.1.tar.gz
更新
mysite/settings.py
以指向新的模块名称。INSTALLED_APPS = [ "django_polls.apps.PollsConfig", ..., ]
更新
mysite/urls.py
以指向新的模块名称。urlpatterns = [ path("polls/", include("django_polls.urls")), ..., ]
运行开发服务器以确认项目继续工作。
发布您的应用程序¶
现在我们已经打包并测试了 django-polls
,它已经可以与世界分享了!如果这不仅仅是一个例子,您现在可以
- 将包发送给朋友。
- 将包上传到您的网站。
- 将包发布到公共存储库,例如 Python 包索引 (PyPI)。 packaging.python.org 有 一个很好的教程 来完成此操作。