usage.rst 3.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101
  1. Usage
  2. =====
  3. It's strongly recommended to use the usual ``from django.conf import settings``
  4. in your own code to access the configured settings.
  5. But you can also **OPTIONALLY** use your app's own settings object directly,
  6. by instantiating it in place::
  7. from myapp.models import MyAppConf
  8. myapp_settings = MyAppConf()
  9. print myapp_settings.SETTING_1
  10. Note that accessing the settings that way means they don't have a prefix.
  11. ``AppConf`` instances don't automatically work as proxies for the global
  12. settings. But you can enable this if you want by setting the ``proxy``
  13. attribute of the inner ``Meta`` class to ``True``::
  14. from appconf import AppConf
  15. class MyAppConf(AppConf):
  16. SETTING_1 = "one"
  17. SETTING_2 = (
  18. "two",
  19. )
  20. class Meta:
  21. proxy = True
  22. myapp_settings = MyAppConf()
  23. if "myapp" in myapp_settings.INSTALLED_APPS:
  24. print "yay, myapp is installed!"
  25. In case you want to override some settings programmatically, you can
  26. simply pass the value when instantiating the ``AppConf`` class::
  27. from myapp.models import MyAppConf
  28. myapp_settings = MyAppConf(SETTING_1='something completely different')
  29. if 'different' in myapp_settings.SETTING_1:
  30. print "yay, I'm different!"
  31. Custom configuration
  32. --------------------
  33. Each of the settings can be individually configured with callbacks.
  34. For example, in case a value of a setting depends on other settings
  35. or other dependencies. The following example sets one setting to a
  36. different value depending on a global setting::
  37. from django.conf import settings
  38. from appconf import AppConf
  39. class MyCustomAppConf(AppConf):
  40. ENABLED = True
  41. def configure_enabled(self, value):
  42. return value and not settings.DEBUG
  43. The value of ``MYAPP_ENABLED`` will vary depending on the
  44. value of the global ``DEBUG`` setting.
  45. Each of the app settings can be customized by providing
  46. a method ``configure_<lower_setting_name>`` that takes the default
  47. value as defined in the class attributes of the ``AppConf`` subclass
  48. or the override value from the global settings as the only parameter.
  49. The method **must return** the value to be use for the setting in
  50. question.
  51. After each of the ``configure_*`` methods has been called, the ``AppConf``
  52. class will additionally call a main ``configure`` method, which can
  53. be used to do any further custom configuration handling, e.g. if multiple
  54. settings depend on each other. For that a ``configured_data`` dictionary
  55. is provided in the setting instance::
  56. from django.conf import settings
  57. from appconf import AppConf
  58. class MyCustomAppConf(AppConf):
  59. ENABLED = True
  60. MODE = 'development'
  61. def configure_enabled(self, value):
  62. return value and not settings.DEBUG
  63. def configure(self):
  64. mode = self.configured_data['MODE']
  65. enabled = self.configured_data['ENABLED']
  66. if not enabled and mode != 'development':
  67. print "WARNING: app not enabled in %s mode!" % mode
  68. return self.configured_data
  69. .. note::
  70. Don't forget to return the configured data in your custom ``configure``
  71. method if you edit it.