django-cogwheels 0.3

应用开发者的福音！

• 一种稳定的、记录在案的、标准化的方法，用于实施可覆盖的特定于应用程序的设置。

• 清楚地定义和传达应用设置的弃用状态，让您可以灵活地重命名、替换或标记设置以在项目的生命周期中移除。使用旧设置名称定义的用户覆盖仍然可供您使用，允许您在弃用期间继续支持它们。

• 当为模型、模块或其他可覆盖对象设置提供的默认值无效时，有用、一致的错误消息。

• 缓存导入以快速访问模型、模块和其他可导入的 python 对象。

• 与 Django 的测试框架配合得很好（订阅 Django 的setting_changed信号，以便在使用override_settings时清除缓存的值）。

对应用程序用户有好处！

• 当它们的模型、类、方法或模块覆盖设置格式不正确或无法导入时，有用、一致的错误消息。

• 当它们覆盖已重命名、替换或标记为删除的设置时，会发出有用、一致的弃用警告。

快速入门指南

1. 使用 pip 安装包：

   pip install django-cogwheels

2. cd进入项目的根应用程序目录：

   cd your-django-project/yourproject/

3. 使用 cogwheels Django 应用模板创建一个conf应用：

   django-admin.py startapp conf --template=https://github.com/ababic/cogwheels-conf-app/zipball/master

4. 打开yourproject/conf/defaults.py，并添加您的设置值，如下所示：

   # You can add settings for any type of value
   MAX_ITEMS_PER_ORDER = 5
   
   # For settings that refer to models, use a string in the format 'app_name.Model'
   ORDER_ITEM_MODEL = 'yourproject.SimpleOrderItem'
   
   # For settings that refer to a python module, use an 'import path' string, like so:
   DISCOUNTS_BACKEND = 'yourproject.discount_backends.simple'
   
   # For settings that refer to classes, methods, or other python objects from a
   # python module, use an 'object import path' string, like so:
   ORDER_FORM_CLASS = 'yourproject.forms.OrderForm'

5. 要在您的应用程序中使用设置值，只需导入设置助手，并将相关设置作为属性引用，如下所示：

   >>> from yourproject.conf import settings
   
   >>> settings.MAX_ITEMS_PER_ORDER
   5
   
   >>> settings.ORDER_ITEM_MODEL
   'yourproject.SimpleOrderItem'
   
   >>> settings.DISCOUNTS_BACKEND
   'yourproject.discount_backends.simple'
   
   >>> settings.ORDER_FORM_CLASS
   'yourproject.forms.OrderForm'

6. 对于引用 Django 模型的设置，您可以使用设置助手的特殊模型属性来访问模型类本身，而不仅仅是字符串值。例如：

   >>> from yourproject.conf import settings
   
   >>> model = settings.models.ORDER_ITEM_MODEL
   yourproject.models.SimpleOrderItem
   
   >>> obj = model(id=1, product='test product', quantity=15)
   >>> obj.save()
   
   >>> print(model.objects.all())
   <QuerySet [<SimpleOrderItem: SimpleOrderItem object (1)>]>

   在幕后，调用 Django 的django.apps.apps.get_model()方法，并将结果缓存起来，以便快速有效地处理对同一模型的重复请求。

7. 对于引用 python 模块的设置，您可以使用设置助手的特殊模块属性来访问模块本身，而不是导入路径字符串：

   >>> from yourproject.conf import settings
   
   >>> module = settings.modules.DISCOUNTS_BACKEND
   <module 'yourproject.discount_backends.simple' from '/system/path/to/your-django-project/yourproject/discount_backends/simple.py'>

   在后台，python 的importlib.import_module()方法被调用，结果被缓存，以便快速有效地处理对同一模块的重复请求。

8. 对于引用类、函数或其他可导入 python 对象的设置，您可以使用设置助手的特殊对象属性来访问这些对象，而不是导入路径字符串：

   >>> from yourproject.conf import settings
   
   >>> form_class = settings.objects.ORDER_FORM_CLASS
   yourproject.formsOrderForm
   
   >>> form = form_class(data={})
   >>> form.is_valid()
   False

   在后台，python 的importlib.import_module()方法被调用，结果被缓存，以便快速有效地处理对同一对象的重复请求。

9. 您的应用程序的用户现在可以通过向其项目的 Django 设置模块添加替代值来覆盖任何默认值。例如：

   # userproject/settings/base.py
   
   YOURAPP_MAX_ITEMS_PER_ORDER = 2
   
   YOURAPP_ORDER_ITEM_MODEL = 'userproject_orders.CustomOrderItem'
   
   YOURAPP_DISCOUNTS_BACKEND = 'userproject.discounts.custom_discount_backend'
   
   YOURAPP_ORDER_FORM_CLASS = 'userproject.orders.forms.CustomOrderForm'

10. 你可能注意到上面的变量名都以YOURAPP_为前缀。此前缀因您的应用程序而异，具体取决于包名称。

    这种设置的“命名空间”很重要。它不仅可以帮助您的应用用户记住他们的覆盖设置适用于哪个应用，而且还有助于防止应用之间的设置名称冲突。

    您可以通过执行以下操作找出您的应用程序的前缀是什么：

    >>> from yourproject.conf import settings
    >>> settings.get_prefix()
    'YOURPROJECT_'

    您可以通过在设置助手类上设置前缀属性来将此前缀更改为您喜欢的任何内容，如下所示：

    # yourapp/conf/settings.py
    
    class MyAppSettingsHelper(BaseAppSettingsHelper):
        prefix = 'CUSTOM'  # No need for a trailing underscore here

    >>> from yourproject.conf import settings
    >>> settings.get_prefix()
    'CUSTOM_'

经常问的问题

# yourapp/some_directory/settings.py

class MyAppSettingsHelper(BaseAppSettingsHelper):
    defaults_path = 'yourapp.some_other_place.defaults'

兼容性

当前版本已通过以下兼容性测试：

• Django 版本 1.11 到 2.2

• Python 版本 3.4 到 3.8