django-cogwheels 0.3

对应用开发者大有裨益！

• 实现可覆盖的应用特定设置的稳定、文档化、标准化方法。

• 明确定义和传达应用程序设置废弃状态，为您在项目生命周期内提供灵活地重命名、替换或标记设置以进行删除的能力。使用旧设置名称定义的用户覆盖仍然可用，使您能够在废弃期间继续支持它们。

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

• 为模型、模块和其他可导入的Python对象缓存导入，以实现快速访问。

• 与Django的测试框架良好兼容（订阅Django的setting_changed信号，因此当使用override_settings时，会清除缓存值）。

对应用程序用户大有裨益！

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

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

快速入门指南

1. 使用pip安装此包

   pip install django-cogwheels

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

   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模型的设置，您可以使用设置辅助工具的特殊models属性来访问模型类本身，而不仅仅是字符串值。例如

   >>> 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模块的设置，您可以使用设置辅助工具的特殊modules属性来访问模块本身，而不是导入路径字符串

   >>> 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对象的设置，您可以使用设置辅助工具的特殊objects属性来访问这些对象，而不是导入路径字符串

   >>> 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_'

    您可以通过在设置辅助工具类上设置prefix属性来将此前缀更改为您想要的任何内容

    # 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