Django 包含一个由已安装应用组成的注册表,它保存应用的配置并提供自省。它还维护一个可用 models 的列表。
这个注册表叫做 django.apps
,位于 apps
中:
>>> from django.apps import apps
>>> apps.get_app_config('admin').verbose_name
'Admin'
历史上,Django 使用 项目 这个词来描述Django的一个web应用。现在项目主要通过一个设置模块定义。
例如,当你运行 django-admin startproject mysite
时,将会创建一个 mysite
的项目目录,目录包含一个名为 mysite
的Python
包,包含文件 settings.py
、 urls.py
和 wsgi.py
。 项目包通常被扩展成一个包括fixture、CSS和模板的特定应用程序模板。
项目的 根目录 (包含 manage.py
的目录)通常是项目里所有应用程序的容器,这些应用程序并不是单独存在的。
应用 这个词表示一个Python包,它提供某些功能的集合。应用可以在各种项目中 重用。
应用包含模型、视图、模板、模板标签、静态文件、URL、中间件等等。它们一般通过 INSTALLED_APPS
设置和
其它例如URLconf、MIDDLEWARE
设置以及模板继承等机制接入到项目中。
Django 的应用只是一个代码集,它与框架的其它部分进行交互,理解这点很重要。并没有应用程序对象之类的东西。
然而,有一些地方Django 需要与安装的应用交互,主要用于配置和自省。这是为什么应用注册表要在 AppConfig
实例中维持每个安装的应用的元数据。
也没有规定项目不能被认为是包含模型的应用。(这就需要将其添加到 INSTALLED_APPS
中)
配置应用首先要创建 AppConfig
的子类,并且将子类路径加入 INSTALLED_APPS
。
当 INSTALLED_APPS
包含某个应用模块的路径后,Django 将在这个模块中检查一个 default_app_config
变量。
如果这个变量有定义,它应该是这个应用的 AppConfig
子类的路径。
如果没有 default_app_config
, Django将使用 AppConfig
类。
新的应用最好不要使用 default_app_config
. 应该在 INSTALLED_APPS
中显式地配置适当的 AppConfig
子类的路径。
如果你正在创建一个名叫“Rock ’n’ roll”的可插式应用,下面展示了如何给admin提供一个合适的名字:
# rock_n_roll/apps.py
from django.apps import AppConfig
class RockNRollConfig(AppConfig):
name = 'rock_n_roll'
verbose_name = "Rock ’n’ roll"
可以让你的应用像下面一样以默认方式加载这个 AppConfig
的子类:
# rock_n_roll/__init__.py
default_app_config = 'rock_n_roll.apps.RockNRollConfig'
这将使得 INSTALLED_APPS
只包含 'rock_n_roll'
时将使用 RockNRollConfig
这允许你使用 AppConfig
功能而不用要求用户更新他们的 INSTALLED_APPS
设置
当然,你也可以将 'rock_n_roll.apps.RockNRollConfig'
放在 INSTALLED_APPS
设置中。
你甚至可以提供几个具有不同行为的 AppConfig
子类,并让使用者通过他们的
INSTALLED_APPS
设置选择。
建议的做法是将配置类放在应用的 apps
子模块中。但是,Django 不强制这一点。
你必须包含 name
属性来让Django 决定该配置适用的应用。
你可以定义 AppConfig
API 参考中记录的任何属性。
注解
如果你的代码在应用的 __init__.py
中导入应用程序注册表,
名称 apps
将与 pps
子模块发生冲突。最佳做法是将这些代码移到子模块,并将其导入。
一种解决方法是以一个不同的名称导入注册表:
from django.apps import apps as django_apps
如果你在 anthology
项目中使用”Rock ’n’ rol”,但您希望显示成 "Gypsy jazz"
,你可以修改你自己的配置︰:
# anthology/apps.py
from rock_n_roll.apps import RockNRollConfig
class JazzManoucheConfig(RockNRollConfig):
verbose_name = "Jazz Manouche"
# anthology/settings.py
INSTALLED_APPS = [
'anthology.apps.JazzManoucheConfig',
# ...
]
再说一次,在 apps
子模块定义特定于项目的配置类是一种习惯,并不强制要求。
AppConfig.
name
¶完整的Python路径, e.g. 'django.contrib.admin'
.
他的属性定义了该配置适用于哪个applications. 而且必须所有的 AppConfig
的子类都要设置。
在整个Django项目中必须是唯一的。
AppConfig.
label
¶application的缩写名, e.g. 'admin'
此属性可以重新标记应用,当两个应用程序有冲突的标签。它默认为 name
的最后一部分。它是一个有效的 Python 标识符。
在整个Django项目中必须是唯一的。
AppConfig.
verbose_name
¶应用的适合阅读的名称, e.g. “Administration”.
默认是 label.title()
.
AppConfig.
path
¶应用目录的文件系统路径, e.g.
'/usr/lib/python3.4/dist-packages/django/contrib/admin'
.
在大多数情况下,Django 可以自动检测并设置它,你也可以在 AppConfig
子类上提供一个显式的类属性以覆盖它 。
在有些情况下是需要这样的;例如,如果应用的包是一个具有多个路径的 namespace package 。
AppConfig.
module
¶应用的根模块, e.g. <module 'django.contrib.admin' from
'django/contrib/admin/__init__.pyc'>
.
AppConfig.
models_module
¶包含 models
的模块, e.g. <module 'django.contrib.admin.models'
from 'django/contrib/admin/models.pyc'>
.
如果应用不包含 models
模块,它可能为 None
。
注意与数据库相关的信号,如 pre_migrate
和
post_migrate
只有在应用具有 models
模块时才发出。
AppConfig.
get_model
(model_name)¶根据 model_name
返回对应 Model
.
如果模型不存在,则抛出一个 LookupError
异常, model_name
不区分大小写。
AppConfig.
ready
()¶子类可以重写此方法以执行初始化任务,如注册信号。它在注册表填充完之后立即调用。
虽然不能在定义 AppConfig
类的模块级别导入模型,
但是可以使用 import
语句或 get_model()
将它们导入到 ready()
中。
如果您注册的是 model signals
,
您可以通过它的字符串标签来引用发送方,而不是使用模型类本身。
例如:
from django.db.models.signals import pre_save
def ready(self):
# importing model classes
from .models import MyModel # or...
MyModel = self.get_model('MyModel')
# registering signals with the model's string label
pre_save.connect(receiver, sender='app_label.MyModel')
警告
尽管可以像上面描述的那样访问模型类,但要避免在 ready()
中实现与数据库交互。
包括执行查询( save()
、
delete()
、manager方法等)的模型方法,
以及通过 django.db.connection
的原始SQL查询。
您的 ready()
方法将在任意管理命令启动时运行。例如:
即使测试数据库配置与生产环境设置是分离的, manage.py test
仍会执行一些针对您的 生产环境 数据库的查询!
注解
在常规的初始化过程中,ready
方法只由Django 调用一次。但在一些极端情况下,
特别是在那些摆弄安装应用程序的测试中,ready
可能被调用不止一次。在这种情况下,编写幂等方法,
或者在 AppConfig
类上放置一个标识来防止应该执行一次的代码重复运行。
Python3.3以及更高版本支持不包含
__init__.py
文件的Python包。 这些包分布在 sys.path
(see PEP 420)上的不同位置的多个目录中。
Django应用程序需要一个单一的基本文件系统路径,其中Django(取决于配置)将搜索模板、静态资源。 因此,如果符合以下条件,则名称空间包可能只是Django应用程序。
如果这些条件都不满足,Django将抛出 ImproperlyConfigured
异常。
apps
¶应用程序注册中心提供以下公共API。以下未列出的方法被认为是私有的,可能会在没有通知的情况下发生变化。
apps.
ready
¶布尔属性,在注册中心完全填充后或所有 AppConfig.ready()
方法被调用后设置为 True
。
apps.
get_app_config
(app_label)¶根据 app_label
返回对应的 AppConfig
,如果没有对应的应用,则抛出一个 LookupError
异常。
apps.
is_installed
(app_name)¶检查注册表中是否存在具有给定名称的应用。
app_name
是应用的完整名称, e.g. 'django.contrib.admin'
.
apps.
get_model
(app_label, model_name)¶返回给定 app_label
和 model_name
对应的 Model
作为快捷方式,此方法还接受 app_label.model_name
形式的一个单一参数。model_name
不区分大小写。
如果没有这种模型存在,抛出 LookupError
。使用不包含点号的单个参数调用时将引发 ValueError
异常。
当Django 启动时,django.setup()
负责填充应用注册表。
setup
(set_prefix=True)¶配置Django:
set_prefix
为 True, 那么将URL解析器脚本前缀设置为 FORCE_SCRIPT_NAME
(如果定义),
或者为 /
。设置URL解析器脚本前缀的功能是1.10中新加的。
此函数在这些情况自动调用:
在其他情况下,必须显式地调用它,例如在普通的Python脚本中。
应用程序注册表初始化分为三个阶段。在每一个阶段,Django都按照 INSTALLED_APPS
中的顺序处理所有应用程序。
首先Django先导入 INSTALLED_APPS
中的每个应用程序。
如果它是一个应用配置类,Django 导入应用的root包,通过其 name
属性。
如果它是一个Python 包,Django 创建应用的一个默认配置。
在这个阶段,你的代码不应该将任何模型导入!
换句话说,您的应用程序的根包和定义您的应用程序配置类的模块不应该导入任何模型,甚至是间接的。
严格地讲,Django 允许应用配置加载后导入模型。然而,为了避免 INSTALLED_APPS
的顺序带来不必要的约束,
强烈推荐在这一阶段不导入任何模型
这一阶段完成后,操作应用配置的API 开始变得可以使用了,例如 get_app_config()
。
然后 Django 将导入每个应用的models 子模块(如果存在的话)。
你必须在应用的 models.py
或 models/__init__.py
中定义或导入所有模型。否则,
应用注册表在此时可能不会完全填充,这可能导致ORM 出现故障
一旦完成该步骤, get_model()
之类的 model API 可以使用了。
最后,Django 运行每个应用程序配置的 ready()
方法。
下面是在初始化过程中可能遇到的一些常见问题:
AppRegistryNotReady
: 导致这种情况是由于导入应用程序配置或模型模块触发了依赖应用程序注册表的代码。
例如, ugettext()
使用应用注册表来查找应用中的翻译目录。
若要在导入时翻译,你需要 ugettext_lazy()
(使用 ugettext()
would be a bug,
将是一个bug,因为翻译发生在导入的时候,而不是取决于每个请求的当前语言。)
模型模块中在导入时使用ORM 执行数据库查询也会引发此异常。ORM 要直到所有的模型都可用时才能正常工作。
另一个常见的罪魁祸首 django.contrib.auth.get_user_model()
。
请在导入时使用 AUTH_USER_MODEL
设置来引用用户模型。
如果在一个独立的 Python 脚本中你忘了调用 django.setup()
也会发生此异常。
ImportError: cannot import name ...
如果出现循环导入,就会反正这种情况。
要消除这种问题,应尽量减少模型模块之间的依赖项,并在导入时尽可能少做工作。 为了避免在导入时执行代码,你可以移动它到一个函数和缓存其结果。当你第一次需要其结果时, 将执行该代码。这一概念被称为”惰性求值”。
django.contrib.admin
在安装的应用中自动发现 admin
,
要阻止它,请更改你的
INSTALLED_APPS
以包含
'django.contrib.admin.apps.SimpleAdminConfig'
而不是
'django.contrib.admin'
.
10月 29, 2021