README.rst 3.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124
  1. django-appconf
  2. ==============
  3. .. image:: http://codecov.io/github/django-compressor/django-appconf/coverage.svg?branch=develop
  4. :alt: Code Coverage
  5. :target: http://codecov.io/github/django-compressor/django-appconf?branch=develop
  6. .. image:: https://secure.travis-ci.org/django-compressor/django-appconf.svg?branch=develop
  7. :alt: Build Status
  8. :target: http://travis-ci.org/django-compressor/django-appconf
  9. A helper class for handling configuration defaults of packaged Django
  10. apps gracefully.
  11. .. note::
  12. This app precedes Django's own AppConfig_ classes that act as
  13. "objects [to] store metadata for an application" inside Django's
  14. app loading mechanism. In other words, they solve a related but
  15. different use case than django-appconf and can't easily be used
  16. as a replacement. The similarity in name is purely coincidental.
  17. .. _AppConfig: https://docs.djangoproject.com/en/stable/ref/applications/#django.apps.AppConfig
  18. Overview
  19. --------
  20. Say you have an app called ``myapp`` with a few defaults, which you want
  21. to refer to in the app's code without repeating yourself all the time.
  22. ``appconf`` provides a simple class to implement those defaults. Simply add
  23. something like the following code somewhere in your app files:
  24. .. code-block:: python
  25. from appconf import AppConf
  26. class MyAppConf(AppConf):
  27. SETTING_1 = "one"
  28. SETTING_2 = (
  29. "two",
  30. )
  31. .. note::
  32. ``AppConf`` classes depend on being imported during startup of the Django
  33. process. Even though there are multiple modules loaded automatically,
  34. only the ``models`` modules (usually the ``models.py`` file of your
  35. app) are guaranteed to be loaded at startup. Therefore it's recommended
  36. to put your ``AppConf`` subclass(es) there, too.
  37. The settings are initialized with the capitalized app label of where the
  38. setting is located at. E.g. if your ``models.py`` with the ``AppConf`` class
  39. is in the ``myapp`` package, the prefix of the settings will be ``MYAPP``.
  40. You can override the default prefix by specifying a ``prefix`` attribute of
  41. an inner ``Meta`` class:
  42. .. code-block:: python
  43. from appconf import AppConf
  44. class AcmeAppConf(AppConf):
  45. SETTING_1 = "one"
  46. SETTING_2 = (
  47. "two",
  48. )
  49. class Meta:
  50. prefix = 'acme'
  51. The ``MyAppConf`` class will automatically look at Django's global settings
  52. to determine if you've overridden it. For example, adding this to your site's
  53. ``settings.py`` would override ``SETTING_1`` of the above ``MyAppConf``:
  54. .. code-block:: python
  55. ACME_SETTING_1 = "uno"
  56. In case you want to use a different settings object instead of the default
  57. ``'django.conf.settings'``, set the ``holder`` attribute of the inner
  58. ``Meta`` class to a dotted import path:
  59. .. code-block:: python
  60. from appconf import AppConf
  61. class MyAppConf(AppConf):
  62. SETTING_1 = "one"
  63. SETTING_2 = (
  64. "two",
  65. )
  66. class Meta:
  67. prefix = 'acme'
  68. holder = 'acme.conf.settings'
  69. If you ship an ``AppConf`` class with your reusable Django app, it's
  70. recommended to put it in a ``conf.py`` file of your app package and
  71. import ``django.conf.settings`` in it, too:
  72. .. code-block:: python
  73. from django.conf import settings
  74. from appconf import AppConf
  75. class MyAppConf(AppConf):
  76. SETTING_1 = "one"
  77. SETTING_2 = (
  78. "two",
  79. )
  80. In the other files of your app you can easily make sure the settings
  81. are correctly loaded if you import Django's settings object from that
  82. module, e.g. in your app's ``views.py``:
  83. .. code-block:: python
  84. from django.http import HttpResponse
  85. from myapp.conf import settings
  86. def index(request):
  87. text = 'Setting 1 is: %s' % settings.MYAPP_SETTING_1
  88. return HttpResponse(text)